Adding hardware support ======================= 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 with simultaneous AP + Mesh Point (802.11s) operation is required. Device checklist ---------------- The description of pull requests adding device support must include the `device integration checklist `_. The checklist ensures that core functionality of Gluon is well supported on the device. .. _device-class-definition: Device classes -------------- All supported hardware is categorized into "device classes". This allows to adjust the feature set of Gluon to the different hardware's capabilities via ``site.mk`` without having to list individual devices. There are currently two devices classes defined: "standard" and "tiny". The "tiny" class contains all devices that do not meet the following requirements: - At least 7 MiB of usable firmware space - At least 64 MiB of RAM (128MiB for devices with ath10k radio) Target configuration -------------------- Gluon's hardware support is based on OpenWrt's. For each supported target, a configuration file exists at ``targets/-`` (or just ``target/`` for targets without subtargets) that contains all Gluon-specific settings for the target. The generic configuration ``targets/generic`` contains settings that affect all targets. All targets must be listed in ``target/targets.mk``. The target configuration language is based on Lua, so Lua's syntax for variables and control structures can be used. Device definitions ~~~~~~~~~~~~~~~~~~ To configure a device to be built for Gluon, the ``device`` function is used. In the simplest case, only two arguments are passed, for example: .. code-block:: lua device('tp-link-tl-wdr3600-v1', 'tplink_tl-wdr3600-v1') The first argument is the device name in Gluon, which is part of the output image filename, and must correspond to the model string looked up by the autoupdater. The second argument is the corresponding device profile name in OpenWrt, as found in ``openwrt/target/linux//image/*``. A table of additional settings can be passed as a third argument: .. code-block:: lua device('ubiquiti-edgerouter-x', 'ubnt_edgerouter-x', { factory = false, packages = {'-hostapd-mini'}, manifest_aliases = { 'ubnt-erx', }, }) The supported additional settings are described in the following sections. Suffixes and extensions ~~~~~~~~~~~~~~~~~~~~~~~ For many targets, OpenWrt generates images with the suffixes ``-squashfs-factory.bin`` and ``-squashfs-sysupgrade.bin``. For devices with different image names, is it possible to override the suffixes and extensions using the settings ``factory``, ``factory_ext``, ``sysupgrade`` and ``sysupgrade_ext``, for example: .. code-block:: lua { factory = '-squashfs-combined', factory_ext = '.img.gz', sysupgrade = '-squashfs-combined', sysupgrade_ext = '.img.gz', } Only settings that differ from the defaults need to be passed. ``factory`` and ``sysupgrade`` can be set to ``false`` when no such images exist. For some device types, there are multiple factory images with different extensions. ``factory_ext`` can be set to a table of strings to account for this case: .. code-block:: lua { factory_ext = {'.img.gz', '.vmdk', '.vdi'}, } TODO: Extra images Aliases and manifest aliases ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Sometimes multiple devices exist that use the same OpenWrt images. To make it easier to find these images, the ``aliases`` setting can be used to define additional device names. Gluon will create symlinks for these names in the image output directory. .. code-block:: lua device('aruba-ap-303', 'aruba_ap-303', { factory = false, aliases = {'aruba-instant-on-ap11'}, }) The aliased name will also be added to the autoupdate manifest, allowing upgrade images to be found under the different name on targets that perform model name detection at runtime. It is also possible to add alternative names to the autoupdater manifest without creating a symlink by using ``manifest_aliases`` instead of ``aliases``, which should be done when the alternative name does not refer to a separate device. This is particularly useful to allow the autoupdater to work when the model name changed between Gluon versions. Package lists ~~~~~~~~~~~~~ Gluon generates lists of packages that are installed in all images based on a default list and the features and packages specified in the site configuration. In addition, OpenWrt defines additional per-device package lists. These lists may be modified in Gluon's device definitions, for example to include additional drivers and firmware, or to remove unneeded software. Packages to remove are prefixed with a ``-`` character. For many ath10k-based devices, this is used to replace the "CT" variant of ath10k with the mainline-based version: .. code-block:: lua local ATH10K_PACKAGES_QCA9880 = { 'kmod-ath10k', '-kmod-ath10k-ct', '-kmod-ath10k-ct-smallbuffers', 'ath10k-firmware-qca988x', '-ath10k-firmware-qca988x-ct', } device('openmesh-a40', 'openmesh_a40', { packages = ATH10K_PACKAGES_QCA9880, factory = false, }) This example also shows how to define a local variable, allowing the package list to be reused for multiple devices. Device flags ~~~~~~~~~~~~ The settings ``class``, ``deprecated`` or ``broken`` should be set according to the device support status. The default values are as follows: .. code-block:: lua { class = 'standard', deprecated = false, broken = false, } - Device classes are described in :ref:`device-class-definition` - Broken devices are untested or do not meet our requirements as given by the device checklist - Deprecated devices are slated for removal in a future Gluon version due to hardware constraints Global settings ~~~~~~~~~~~~~~~ There is a number of directives that can be used outside of a ``device()`` definition: - ``include('filename')``: Include another file with global settings - ``config(key, value)``: Set a config symbol in OpenWrt's ``.config``. Value may be a string, number, boolean, or nil. Booleans and nil are used for tristate symbols, where nil sets the symbol to ``m``. - ``try_config(key, value)``: Like ``config()``, but do not fail if setting the symbol is not possible (usually because its dependencies are not met) - ``packages { 'package1', '-package2', ... }``: Define a list of packages to add or remove for all devices of a target. Package lists passed to multiple calls of ``packages`` will be aggregated. - ``defaults { key = value, ... }``: Set default values for any of the additional settings that can be passed to ``device()``. Helper functions ~~~~~~~~~~~~~~~~ The following helpers can be used in the target configuration: - ``env.KEY`` allows to access environment variables - ``istrue(value)`` returns true if the passed string is a positive number (often used with ``env``, for example ``if istrue(env.GLUON_DEBUG) then ...``) Hardware support in packages ---------------------------- In addition to the target configuration files, some device-specific changes may be required in packages. gluon-core ~~~~~~~~~~ - ``/lib/gluon/upgrade/010-primary-mac``: Override primary MAC address selection Usually, the primary (label) MAC address is defined in OpenWrt's Device Trees. For devices or targets where this is not the case, it is possible to specify what interface to take the primary MAC address from in ``010-primary-mac``. - ``/lib/gluon/upgrade/020-interfaces``: Override LAN/WAN interface assignment On PoE-powered devices, the PoE input port should be "WAN". - ``/usr/lib/lua/gluon/platform.lua``: Contains a list of outdoor devices gluon-setup-mode ~~~~~~~~~~~~~~~~ - ``/lib/gluon/upgrade/320-setup-ifname``: Contains a list of devices that use the WAN port for the config mode On PoE-powered devices, the PoE input port should be used for the config mode. This is handled correctly by default for outdoor devices listed in ``platform.lua``. libplatforminfo ~~~~~~~~~~~~~~~ When adding support for a new target to Gluon, it may be necessary to adjust libplatforminfo to define how autoupdater image names are derived from the model name.