hardware.rst 5.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142
  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 LEDE.
  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/*`` in a shell-based DSL (so common shell
  19. commands syntax like ``if`` can be used.
  20. The ``device`` command is used to define an image build for a device. It takes
  21. two or three parameters.
  22. The first parameter defines the Gluon profile name, which is used to refer to the
  23. device and is part of the generated image name. The profile name must be same as
  24. the output of the following command (on the target device), so the autoupdater
  25. can work::
  26. lua -e 'print(require("platform_info").get_image_name())'
  27. The second parameter defines the name of the image files generated by LEDE. Usually,
  28. it is also the LEDE profile name; for devices that still use the old image build
  29. code, a third parameter with the LEDE profile name can be passed. The profile names
  30. can be found in the image Makefiles in ``lede/target/linux/<target>/image/Makefile``.
  31. Examples::
  32. device tp-link-tl-wr1043n-nd-v1 tl-wr1043nd-v1
  33. device alfa-network-hornet-ub hornet-ub HORNETUB
  34. Suffixes and extensions
  35. '''''''''''''''''''''''
  36. By default, image files are expected to have the extension ``.bin``. In addition,
  37. the images generated by LEDE have a suffix before the extension that defaults to
  38. ``-squashfs-factory`` and ``-squashfs-sysupgrade``.
  39. This can be changed using the ``factory`` and ``sysupgrade`` commands, either at
  40. the top of the file to set the defaults for all images, or for a single image. There
  41. are three forms with 0 to 2 arguments (all work with ``sysupgrade`` as well)::
  42. factory SUFFIX .EXT
  43. factory .EXT
  44. factory
  45. When only an extension is given, the default suffix is retained. When no arguments
  46. are given, this signals that no factory (or sysupgrade) image exists.
  47. Aliases
  48. '''''''
  49. Sometimes multiple models use the same LEDE images. In this case, the ``alias``
  50. command can be used to create symlinks and additional entries in the autoupdater
  51. manifest for the alternative models.
  52. Standalone images
  53. '''''''''''''''''
  54. On targets without *per-device rootfs* support in LEDE, the commands described above
  55. can't be used. Instead, ``factory_image`` and ``sysupgrade_image`` are used::
  56. factory_image PROFILE IMAGE .EXT
  57. sysupgrade_image PROFILE IMAGE .EXT
  58. Again, the profile name must match the value printed by the aforementioned Lua
  59. command. The image name must match the part between the target name and the extension
  60. as generated by LEDE and is to be omitted when no such part exists.
  61. Packages
  62. ''''''''
  63. The ``packages`` command takes an arbitrary number of arguments. Each argument
  64. defines an additional package to include in the images in addition to the default
  65. package sets defined by LEDE. When a package name is prefixed by a minus sign, the
  66. packages are excluded instead.
  67. The ``packages`` command may be used at the top of a target definition to modify
  68. the default package list for all images, or just for a single device (when the
  69. target supports *per-default rootfs*).
  70. Configuration
  71. '''''''''''''
  72. The ``config`` command allows to add arbitary target-specific LEDE configuration
  73. to be emitted to ``.config``.
  74. Notes
  75. '''''
  76. On devices with multiple WLAN adapters, care must also be taken that the primary MAC address is
  77. configured correctly. ``/lib/gluon/core/sysconfig/primary_mac`` should contain the MAC address which
  78. can be found on a label on most hardware; if it does not, ``/lib/gluon/upgrade/010-primary-mac``
  79. in ``gluon-core`` might need a fix. (There have also been cases in which the address was incorrect
  80. even on devices with only one WLAN adapter, in these cases a LEDE bug was the cause).
  81. Adding support for new hardware targets
  82. ---------------------------------------
  83. Adding a new target is much more complex than adding a new profile. There are two basic steps
  84. required for adding a new target:
  85. Package adjustments
  86. '''''''''''''''''''
  87. One package that may need adjustments for new targets is ``libplatforminfo`` (to be found in
  88. `packages/gluon/libs/libplatforminfo <https://github.com/freifunk-gluon/packages/tree/master/libs/libplatforminfo>`_).
  89. If the new platform works fine with the definitions found in ``default.c``, nothing needs to be done. Otherwise,
  90. create a definition for the added target or subtarget, either by symlinking one of the files in the ``templates``
  91. directory, or adding a new source file.
  92. On many targets, Gluon's network setup scripts (mainly in the packages ``gluon-core`` and ``gluon-mesh-batman-adv-core``)
  93. won't run correctly without some adjustments, so better double check that everything is fine there (and the files
  94. ``primary_mac``, ``lan_ifname`` and ``wan_ifname`` in ``/lib/gluon/core/sysconfig/`` contain sensible values).
  95. Build system support
  96. ''''''''''''''''''''
  97. A definition for the new target must be created under ``targets``, and it must be added
  98. to ``targets/targets.mk``. The ``GluonTarget`` macro takes one to three arguments:
  99. the target name, the Gluon subtarget name (if the target has subtargets), and the
  100. LEDE subtarget name (if it differs from the Gluon subtarget). The third argument
  101. can be used to define multiple Gluon targets with different configuration for the
  102. same LEDE target, like it is done for the ``ar71xx-tiny`` target.
  103. After this, is should be sufficient to call ``make GLUON_TARGET=<target>`` to build the images for the new target.