162 lines
6.5 KiB
ReStructuredText
162 lines
6.5 KiB
ReStructuredText
Adding support for new hardware
|
|
===============================
|
|
This page will give a short overview on how to add support
|
|
for new hardware to Gluon.
|
|
|
|
Hardware requirements
|
|
---------------------
|
|
Having an ath9k, ath10k or mt76 based WLAN adapter is highly recommended,
|
|
although other chipsets may also work. VAP (multiple SSID) support
|
|
is a requirement.
|
|
|
|
.. _device-class-definition:
|
|
|
|
Device checklist
|
|
----------------
|
|
Pull requests adding device support must have the device checklist
|
|
included in their description. The checklist assures core functionality
|
|
of Gluon is well supported on the device.
|
|
|
|
The checklist can be found in the `wiki <https://github.com/freifunk-gluon/gluon/wiki/Device-Integration-checklist>`_.
|
|
|
|
Device classes
|
|
--------------
|
|
Gluon currently is aware of two device classes. Depending on the device class, different
|
|
features can be installed onto the device.
|
|
|
|
The ``tiny`` device-class contains devices with the following limitations:
|
|
|
|
* All devices with less than 64 MB of system memory
|
|
* All devices with less than 7 MB of usable firmware space
|
|
* Devices using a single ath10k radio and less than 128MB of system memory
|
|
|
|
.. _hardware-adding-profiles:
|
|
|
|
Adding profiles
|
|
---------------
|
|
The vast majority of devices with ath9k WLAN are based on the ath79 target of OpenWrt.
|
|
If the hardware you want to add support for is ath79, adding a new profile
|
|
is sufficient.
|
|
|
|
Profiles are defined in ``targets/*`` in a shell-based DSL (so common shell
|
|
command syntax like ``if`` can be used).
|
|
|
|
The ``device`` command is used to define an image build for a device. It takes
|
|
two or three parameters.
|
|
|
|
The first parameter defines the Gluon profile name, which is used to refer to the
|
|
device and is part of the generated image name. The profile name must be same as
|
|
the output of the following command (on the target device), so the autoupdater
|
|
can work::
|
|
|
|
lua -e 'print(require("platform_info").get_image_name())'
|
|
|
|
While porting Gluon to a new device, it might happen that the profile name is
|
|
unknown. Best practise is to generate an image first by using an arbitrary value
|
|
and then executing the lua command on the device and use its output from then on.
|
|
|
|
The second parameter defines the name of the image files generated by OpenWrt. Usually,
|
|
it is also the OpenWrt profile name; for devices that still use the old image build
|
|
code, a third parameter with the OpenWrt profile name can be passed. The profile names
|
|
can be found in the image Makefiles in ``openwrt/target/linux/<target>/image/Makefile``.
|
|
|
|
Examples::
|
|
|
|
device tp-link-tl-wr1043n-nd-v1 tl-wr1043nd-v1
|
|
device alfa-network-hornet-ub hornet-ub HORNETUB
|
|
|
|
Suffixes and extensions
|
|
'''''''''''''''''''''''
|
|
|
|
By default, image files are expected to have the extension ``.bin``. In addition,
|
|
the images generated by OpenWrt have a suffix before the extension that defaults to
|
|
``-squashfs-factory`` and ``-squashfs-sysupgrade``.
|
|
|
|
This can be changed using the ``factory`` and ``sysupgrade`` commands, either at
|
|
the top of the file to set the defaults for all images, or for a single image. There
|
|
are three forms with 0 to 2 arguments (all work with ``sysupgrade`` as well)::
|
|
|
|
factory SUFFIX .EXT
|
|
factory .EXT
|
|
factory
|
|
|
|
When only an extension is given, the default suffix is retained. When no arguments
|
|
are given, this signals that no factory (or sysupgrade) image exists.
|
|
|
|
Aliases
|
|
'''''''
|
|
|
|
Sometimes multiple models use the same OpenWrt images. In this case, the ``alias``
|
|
command can be used to create symlinks and additional entries in the autoupdater
|
|
manifest for the alternative models.
|
|
|
|
Standalone images
|
|
'''''''''''''''''
|
|
|
|
On targets without *per-device rootfs* support in OpenWrt, the commands described above
|
|
can't be used. Instead, ``factory_image`` and ``sysupgrade_image`` are used::
|
|
|
|
factory_image PROFILE IMAGE .EXT
|
|
sysupgrade_image PROFILE IMAGE .EXT
|
|
|
|
Again, the profile name must match the value printed by the aforementioned Lua
|
|
command. The image name must match the part between the target name and the extension
|
|
as generated by OpenWrt and is to be omitted when no such part exists.
|
|
|
|
Packages
|
|
''''''''
|
|
|
|
The ``packages`` command takes an arbitrary number of arguments. Each argument
|
|
defines an additional package to include in the images in addition to the default
|
|
package sets defined by OpenWrt. When a package name is prefixed by a minus sign, the
|
|
packages are excluded instead.
|
|
|
|
The ``packages`` command may be used at the top of a target definition to modify
|
|
the default package list for all images, or just for a single device (when the
|
|
target supports *per-default rootfs*).
|
|
|
|
|
|
Configuration
|
|
'''''''''''''
|
|
|
|
The ``config`` command allows to add arbitrary target-specific OpenWrt configuration
|
|
to be emitted to ``.config``.
|
|
|
|
Notes
|
|
'''''
|
|
|
|
On devices with multiple WLAN adapters, care must also be taken that the primary MAC address is
|
|
configured correctly. ``/lib/gluon/core/sysconfig/primary_mac`` should contain the MAC address which
|
|
can be found on a label on most hardware; if it does not, ``/lib/gluon/upgrade/010-primary-mac``
|
|
in ``gluon-core`` might need a fix. (There have also been cases in which the address was incorrect
|
|
even on devices with only one WLAN adapter, in these cases a OpenWrt bug was the cause).
|
|
|
|
|
|
Adding support for new hardware targets
|
|
---------------------------------------
|
|
|
|
Adding a new target is much more complex than adding a new profile. There are two basic steps
|
|
required for adding a new target:
|
|
|
|
Package adjustments
|
|
'''''''''''''''''''
|
|
|
|
One package that may need adjustments for new targets is ``libplatforminfo`` (to be found in
|
|
`packages/gluon/libs/libplatforminfo <https://github.com/freifunk-gluon/packages/tree/master/libs/libplatforminfo>`_).
|
|
If the new platform works fine with the definitions found in ``default.c``, nothing needs to be done. Otherwise,
|
|
create a definition for the added target or subtarget, either by symlinking one of the files in the ``templates``
|
|
directory, or adding a new source file.
|
|
|
|
On many targets, Gluon's network setup scripts (mainly in the package ``gluon-core``)
|
|
won't run correctly without some adjustments, so better double check that everything is fine there (and the files
|
|
``primary_mac``, ``lan_ifname`` and ``wan_ifname`` in ``/lib/gluon/core/sysconfig/`` contain sensible values).
|
|
|
|
Build system support
|
|
''''''''''''''''''''
|
|
|
|
A definition for the new target must be created under ``targets``, and it must be added
|
|
to ``targets/targets.mk``. The ``GluonTarget`` macro takes one to two arguments:
|
|
the target name and the OpenWrt subtarget name.
|
|
|
|
After this, is should be sufficient to call ``make GLUON_TARGET=<target>`` to build the images for the new target.
|