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 (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).
The vast majority of devices with ath9k WLAN uses the ar71xx target of OpenWrt. If the hardware you want to add support for is also ar71xx, adding a new profile is enough.
Profiles are defined in targets/<target>-<subtarget>/profiles.mk. There are two macros used to define which images are generated: GluonProfile and GluonModel. The following examples are taken from profiles.mk of the ar71xx-generic target:
$(eval $(call GluonProfile,TLWR1043)) $(eval $(call GluonModel,TLWR1043,tl-wr1043nd-v1-squashfs,tp-link-tl-wr1043n-nd-v1)) $(eval $(call GluonModel,TLWR1043,tl-wr1043nd-v2-squashfs,tp-link-tl-wr1043n-nd-v2))
The GluonProfile macro takes at least one parameter, the profile name as it is defined in the Makefiles of OpenWrt (openwrt/target/linux/<target>/<subtarget>/profiles/* and openwrt/target/linux/<target>/image/Makefile). If the target you are on doesn’t define profiles (e.g. on x86), just add a single profile called Generic or similar.
It may optionally take a second parameter which defines additional packages to include for the profile (e.g. ath10k). The additional packages defined in openwrt/target/linux/<target>/<subtarget>/profiles/* aren’t used.
The GluonModel macro takes three parameters: The profile name, the suffix of the image file generated by OpenWrt (without the file extension), and the final image name of the Gluon image. The final image name must be the same that is returned by the following command.
lua -e 'print(require("platform_info").get_image_name())'
This is just for the autoupdater can work. The command has to be executed _on_ the target (eg. the hardware router with a flashed image). So you’ll first have to build an image with a guessed name, and afterwards build a new, correctly named image. On targets which aren’t supported by the autoupdater, require("platform_info").get_image_name() will just return nil and the final image name may be defined arbitrarily.
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/core/initial/001-sysconfig 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 an 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 definitely needs adjustments for every new target added is lua-platform-info. Just start with a copy of an existing platform info script, adjust it for the new target, and add the new target to the list of supported targets in the package Makefile.
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).
Add support to the build system¶
A directory for the new target must be created under targets, and it must be added to targets/targets.mk. In the new target directory, four files must be created:
The file config can be used to add additional, target-specific options to the OpenWrt config. If such options aren’t necessary, it can be left empty. For profiles.mk, see Adding profiles.
The files kernel-config and kernel-vermagic must have the correct content so kernel modules from the upstream repositories can be easily installed. The OpenWrt version a Gluon release is based on is defined by the upstream package repo URL in include/gluon.mk (in the variable CONFIG_VERSION_REPO); at the time this documentation was written, this was barrier_breaker/14.07-rc3; whenever the package repo is updated, all kernel-config and kernel-vermagic files must be updated as well.
The file kernel-vermagic just contains a hash which is part of the version number of the kernel package. So in the case of ar71xx-generic on barrier_breaker/14.07-rc3, we look in the directory https://downloads.openwrt.org/barrier_breaker/14.07-rc3/ar71xx/generic/packages/ and find that the kernel package is called kernel_3.10.49-1-94831e5bcf361d1c03e87a15e152b0e8_ar71xx.ipk. This makes the kernel-vermagic the string 94831e5bcf361d1c03e87a15e152b0e8.
For kernel-config, the OpenWrt image builder must be downloaded. Again, for ar71xx-generic on barrier_breaker/14.07-rc3, we download OpenWrt-SDK-ar71xx-for-linux-x86_64-gcc-4.8-linaro_uClibc-0.9.33.2.tar.bz2 from https://downloads.openwrt.org/barrier_breaker/14.07-rc3/ar71xx/generic/. After unpacking it, we use the file OpenWrt-ImageBuilder-ar71xx_generic-for-linux-x86_64/build_dir/target-mips_34kc_uClibc-0.9.33.2/linux-ar71xx_generic/linux-3.10.49/.config as our kernel-config.
After this, is should be sufficient to call make GLUON_TARGET=<target>-<subtarget> to build the images for the new target.