Adding support for new hardware¶
This page will give a short overview on how to add support for new hardware to Gluon.
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.
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.
Gluon currently is aware of two device classes. Depending on the device class, different features can be installed onto the device.
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
The vast majority of devices with ath9k WLAN is based on the ar71xx target of OpenWrt. If the hardware you want to add support for is ar71xx, 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).
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
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
This can be changed using the
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.
Sometimes multiple models use the same OpenWrt images. In this case, the
command can be used to create symlinks and additional entries in the autoupdater
manifest for the alternative models.
On targets without per-device rootfs support in OpenWrt, the commands described above
can’t be used. Instead,
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 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.
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).
config command allows to add arbitrary target-specific OpenWrt configuration
to be emitted to
On devices with multiple WLAN adapters, care must also be taken that the primary MAC address is
/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,
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:
One package that may need adjustments for new targets is
libplatforminfo (to be found in
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
directory, or adding a new source file.
On many targets, Gluon’s network setup scripts (mainly in the package
won’t run correctly without some adjustments, so better double check that everything is fine there (and the files
/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
GluonTarget macro takes one to three arguments:
the target name, the Gluon subtarget name (if the target has subtargets), and the
OpenWrt 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 OpenWrt target, like it is done for the
After this, is should be sufficient to call
make GLUON_TARGET=<target> to build the images for the new target.