9d403c9849
Replace most of the page to account for the changes that have happened in Gluon and OpenWrt in the last 4 years: - Switch from Shell-based target definition language to Lua - Removal of targets using legacy build code Closes #2360
239 lines
8.4 KiB
ReStructuredText
239 lines
8.4 KiB
ReStructuredText
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
|
|
<https://github.com/freifunk-gluon/gluon/wiki/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/<target>-<subtarget>`` (or just
|
|
``target/<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/<target>/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.
|