143 lines
5.9 KiB
ReStructuredText
143 lines
5.9 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 (or ath10k) based WLAN adapter is highly recommended,
|
|
although other chipsets may also work. VAP (multiple SSID) support
|
|
is a requirement. At the moment, Gluon's scripts can't handle devices
|
|
without WLAN adapters (although such environments may also be interesting,
|
|
e.g. for automated testing in virtual machines).
|
|
|
|
|
|
.. _hardware-adding-profiles:
|
|
|
|
Adding profiles
|
|
---------------
|
|
The vast majority of devices with ath9k WLAN uses the ar71xx target of LEDE.
|
|
If the hardware you want to add support for is also ar71xx, adding a new profile
|
|
is enough.
|
|
|
|
Profiles are defined in ``targets/*`` in a shell-based DSL (so common shell
|
|
commands 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())'
|
|
|
|
The second parameter defines the name of the image files generated by LEDE. Usually,
|
|
it is also the LEDE profile name; for devices that still use the old image build
|
|
code, a third parameter with the LEDE profile name can be passed. The profile names
|
|
can be found in the image Makefiles in ``lede/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 LEDE 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 LEDE 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 LEDE, 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 LEDE 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 LEDE. 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 arbitary target-specific LEDE 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 LEDE 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 three arguments:
|
|
the target name, the Gluon subtarget name (if the target has subtargets), and the
|
|
LEDE subtarget name (if it differs from the Gluon subtarget). The third argument
|
|
can be used to define multiple Gluon targets with different configuration for the
|
|
same LEDE target, like it is done for the ``ar71xx-tiny`` target.
|
|
|
|
After this, is should be sufficient to call ``make GLUON_TARGET=<target>`` to build the images for the new target.
|