hardware.rst

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).

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). 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 packages gluon-core and gluon-mesh-batman-adv-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.