hardware.rst 5.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596
  1. Adding support for new hardware
  2. ===============================
  3. This page will give a short overview on how to add support
  4. for new hardware to Gluon.
  5. Hardware requirements
  6. ---------------------
  7. Having an ath9k (or ath10k) based WLAN adapter is highly recommended,
  8. although other chipsets may also work. VAP (multiple SSID) support
  9. is a requirement. At the moment, Gluon's scripts can't handle devices
  10. without WLAN adapters (although such environments may also be interesting,
  11. e.g. for automated testing in virtual machines).
  12. .. _hardware-adding-profiles:
  13. Adding profiles
  14. ---------------
  15. The vast majority of devices with ath9k WLAN uses the ar71xx target of OpenWrt.
  16. If the hardware you want to add support for is also ar71xx, adding a new profile
  17. is enough.
  18. Profiles are defined in ``targets/<target>-<subtarget>/profiles.mk``. There are two macros
  19. used to define which images are generated: ``GluonProfile`` and ``GluonModel``. The following examples
  20. are taken from ``profiles.mk`` of the ``ar71xx-generic`` target::
  21. $(eval $(call GluonProfile,TLWR1043))
  22. $(eval $(call GluonModel,TLWR1043,tl-wr1043nd-v1-squashfs,tp-link-tl-wr1043n-nd-v1))
  23. $(eval $(call GluonModel,TLWR1043,tl-wr1043nd-v2-squashfs,tp-link-tl-wr1043n-nd-v2))
  24. The ``GluonProfile`` macro takes at least one parameter, the profile name as it is
  25. defined in the Makefiles of OpenWrt (``openwrt/target/linux/<target>/<subtarget>/profiles/*``
  26. and ``openwrt/target/linux/<target>/image/Makefile``). If the target you are on doesn't define
  27. profiles (e.g. on x86), just add a single profile called ``Generic`` or similar.
  28. It may optionally take a second parameter which defines additional packages to include for the profile
  29. (e.g. ath10k). The additional packages defined in ``openwrt/target/linux/<target>/<subtarget>/profiles/*``
  30. aren't used.
  31. The ``GluonModel`` macro takes three parameters: The profile name, the suffix of the image file
  32. generated by OpenWrt (without the file extension), and the final image name of the Gluon image.
  33. The final image name must be the same that is returned by the following command.
  34. ::
  35. lua -e 'print(require("platform_info").get_image_name())'
  36. This is just so 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,
  37. ``require("platform_info").get_image_name()`` will just return ``nil`` and the final image name
  38. may be defined arbitrarily.
  39. On devices with multiple WLAN adapters, care must also be taken that the primary MAC address is
  40. configured correctly. ``/lib/gluon/core/sysconfig/primary_mac`` should contain the MAC address which
  41. can be found on a label on most hardware; if it does not, ``/lib/gluon/upgrade/core/initial/001-sysconfig``
  42. in ``gluon-core`` might need a fix. (There have also been cases in which the address was incorrect
  43. even on devices with only one WLAN adapter, in these cases an OpenWrt bug was the cause).
  44. Adding support for new hardware targets
  45. ---------------------------------------
  46. Adding a new target is much more complex than adding a new profile. There are two basic steps
  47. required for adding a new target:
  48. Adjust packages
  49. '''''''''''''''
  50. One package that definitely needs adjustments for every new target added is ``lua-platform-info``. Just
  51. start with a copy of an existing platform info script, adjust it for the new target, and add the new target
  52. to the list of supported targets in the package Makefile.
  53. On many targets, Gluon's network setup scripts (mainly in the packages ``gluon-core`` and ``gluon-mesh-batman-adv-core``)
  54. won't run correctly without some adjustments, so better double check that everything is fine there (and the files
  55. ``primary_mac``, ``lan_ifname`` and ``wan_ifname`` in ``/lib/gluon/core/sysconfig/`` contain sensible values).
  56. Add support to the build system
  57. '''''''''''''''''''''''''''''''
  58. A directory for the new target must be created under ``targets``, and it must be added
  59. to ``targets/targets.mk``. In the new target directory, the following files must be created:
  60. * profiles.mk
  61. * vermagic
  62. * config (optional)
  63. For ``profiles.mk``, see :ref:`hardware-adding-profiles`.
  64. The file ``config`` can be used to add additional, target-specific options to the OpenWrt config.
  65. The files ``vermagic`` must have the correct content so kernel modules from the upstream repositories
  66. can be installed without dependency issues. The OpenWrt version a Gluon release is based on is defined by the upstream package repo URL in ``include/gluon.mk``
  67. (in the variable ``DEFAULT_OPKG_REPO``); at the time this documentation was written, this was ``barrier_breaker/14.07``; whenever
  68. the package repo is updated, all ``vermagic`` files must be updated as well. The command ``make update-vermagic`` can be used to get the correct
  69. vermagic, or update the values when ``DEFAULT_OPKG_REPO`` has changed.
  70. The content is a hash which is part of the version number of the kernel package. So in the case of ``ar71xx-generic`` on
  71. ``barrier_breaker``, we look for the kernel package in the directory ``https://downloads.openwrt.org/barrier_breaker/14.07/ar71xx/generic/packages/base/``.
  72. As the kernel package is called ``kernel_3.10.49-1-0114c71ed85677c9c1e4911437af4743_ar71xx.ipk``, the correct ``vermagic`` string
  73. is ``0114c71ed85677c9c1e4911437af4743``.
  74. After this, is should be sufficient to call ``make GLUON_TARGET=<target>`` to build the images for the new target.