[OpenWrt-Devel] [RFC] commit message in YAML format for new devices

[Paul Spooren]

Hi all,

some time ago I created a (now outdated) device overview[0] based on 
YAML meta data. This approach could simplify maintaining an device 
overview and device specific pages[1].

All commits adding new devices already include most relevant information 
for creating the overview. However it would be convenient if developers 
would format their commit messages in a generic format, therefore I'd 
propose the following:

Every commit message for newly added devices must contain a number of 
hardware information and steps for an initial installation.
The hardware information should contain at least the following 
information, maybe more:

SoC, flash, ram, wifi, LEDs, buttons, USB, serial, vendor, model, device 
tree ID, Ethernet ports

An illustrative commit therefore:

soc: Qualcomm IPQ4029
ram_mb: 512
flash:
   - size_mb: 128
     type: SPI-NAND (Macronix)
   - size_mb: 4
     type: SPI-NOR (Macronix MX25R3235F)
usb:
   - version: 2
     ports: 1
   - version: 3
     ports: 2
ethernet:
   - mbit: 100
     ports: 4
   - mbit: 1000
     ports: 1
led_count: 3
serial: false
vendor: Foobar
model: Lorem Ipsum
variant: v4
dt_id: foobar_lorem-ipsum_v4
target: ath79/generic

Additionally stuff like cpu_mhz, cpu_cores and such could also be added, the OpenWrt hwdata offers some additional information which should be added if relevant[2].

To write a multi-line text for the installation or comments, a "|" can be used as the following:

installation: |
   1. Get the OpenWrt initramfs image. Rename it to ipq40xx.ari and put it
      into the TFTP server root directory. Configure the TFTP server to
      be reachable at 192.168.1.75/24. Connect the machine running the TFTP
      server to the E0 (!) ethernet port of the access point, as it only
      tries to pull from the WAN port.
   
   2. Connect to the serial console. Interrupt autobooting by pressing
      Enter when prompted.
   ...

comments: |
   VCC - NC
    D+ - TX
    D- - RX
   GND - GND

Installation steps would be merged to templates as many devices share the same steps, only varying the TFTP binary name or IP. This could become part of the general information, like a variable called tftp_ip and tftp_bin.
  
All info would be added to a metadata repository like openwrt/devices.git, which can then be updated by the community.

To verify the YAML data a tool like yamllint[3] (Python) could be used.

The main motivation is to have an simple and appealing overview which allows searching/filtering for devices, seeing the support status, retrieve firmware and having an easily maintained, up to date documentation.

Please share your thoughts.

Sunshine,
Paul

[0]: https://aparcar.github.io/openwrt-devices/
[1]: https://aparcar.github.io/openwrt-devices/devices/tp-link_tl-wdr4300/
[2]: 
https://github.com/aparcar/openwrt-devices/blob/master/_data/devices/open-mesh_a62.yml
[3]: https://github.com/adrienverge/yamllint


_______________________________________________
openwrt-devel mailing list
openwrt-devel at lists.openwrt.org
https://lists.openwrt.org/mailman/listinfo/openwrt-devel