The missing indication of the actual board name in a doc page1 has
reminded me that I had a plan around some time ago to put some better
structure to the boards we have in terms of metadata and documentation.
Challenges and areas will be:
Which data can and do we want to express?
How is it best expressed in a maintainable way?
How is it made accessible without maintaining yet another
documentation ecosystem outside doxygen?
How to query this? Right now, we can’t even search for board names; in
the end, I’d like “Give me boards with USB charging and BLE support
that fit in a match box” to produce results.
Can we share that information with other embedded projects? Can we
mash it up with other data sources? What if different authorities have
different concepts of what’s the same board? (We might treat different
revisions of a board under the same name as the same board while
others might not.)
Bonus question:
If the metadata is really good, can we ditch some code and replace it
with a very small shell script?
While I’m pretty sure I can’t do any actual work on this until end of
January, it may be whorthwhile to gather some comments on this til then.
If the metadata is really good, can we ditch some code and replace it with a very small shell script?
There has been some talk of providing metadata on things like application, RIOT version, and board to the riotctrl wrapper and being able to use that for interacting with tests (replacing the basic shell and providing more features when writing the automated python tests).
To have some compatibility with other embedded projects we should look at standard solutions / formats. With @jia200x we have proposed some time ago to move to Kconfig and DeviceTree in RIOT. These formats are being used by other projects. We could express in DeviceTree hardware boot configuration, and its capabilities. Even handle revisions and / or shields or extension. Of course DeviceTree will provide the syntax and still the bindings would still need to be defined, but I see it as a potentially reusable option.
Absolutely: configuration header files could (should) be generated from that. That would allow checks and give the build system and the user more knowledge of the used hardware.
Still I think all these tools should only complement proper documentation, serving as a way of unifying certain aspects of interest on every platform.
+1 for device trees. I remember some people were asking about it. Should make it simple to generate a renode configuration from it as well. There are probably even more places where this comes in handy.
to me this sounds like a good opportunity to relate to work on configuration.
I don’t see how this is related to configuration. Board metadata is
something static, whereas configuration can change between applications
or even on a per-flashing base.
Sure, on the developed-to-the-end side, a board could be just a
configuration template (“pick that CPU, and set these two pins as
labelled ‘I2C 0’, and set that you have that flashing mechanisms
available, …”), but that’s a very big jump as opposed to more
structured documentation.
Mh, the device tree topic is certainly one aspect, but is just one
aspect of this.
The data I was thinking more about was:
What are physical properties of this board?
Are there schematics available?
Is there a pinout infographic? An annotated photo?
Is the board itself described under an Open Harware license?
What’s its board name in RIOT?
What’s the boards vendor and vendor part number? (Where) can it be
bought directly from the vendor?
Is the board breadboard-compatible? Is it an SMD module?
Does it have a radio interface? With external antenna?
Only the last of those could be answered from a device tree, and I’m not
even sure its latter part can be.
Still I think all these tools should only complement proper
documentation, serving as a way of unifying certain aspects of
interest on every platform.
I’d hope that proper documentation, at least in parts, can be generated
from the metadata. Right now, documentation is either almost empty or
contains textual descriptions of the above questions, in any order.
Looking through random samples of the documented boards, about half the
text in there could be autogenerated (in prose or infobox style), and
the documentation would not be worse for it.
And can we grab and cache a copy of it, since ((%#@$ manufacturer sites get
re-organized, and even just 1year SoCs still in production disappear…
While this problem is screaming for a structured wiki, I find that any wiki
that isn’t backed by git is a failure really quickly.
And we really need discussion too. That could evolve into github issues, but.
So, I want to suggest that we create a discussion forum for each board, and
some kind of template post. I think that this post is in the “Boards”
category, so maybe we already have what we need. (From email and the link to
the forum, I can’t tell how I’d find this category from the top…)
The fora should probably have some minimal moderation so that new threads do
not proliferate or attract query posts. People can reply to it freely.
I think that the forum supports uploaded things and attachments.
I think that device tree is a really good machine readable thing to explain
the device configuration. I don’t think that anyone is proposing to use that
at runtime, but I hear people talking about perhaps generating configuration
headers at compile time?
Zephyr keeps those information in a yaml file and also uses that to decide what to build on CI.
We have something similar with FEATURES_PROVIDED, maybe we can just extend on that (provide mtd, netdev_ieee802154, … as a feature)
But the YAML approach would also allow to model non-code features like schematic URL or physical proerties.
So, I want to suggest that we create a discussion forum for each board, and some kind of template post.
That would currently amount to 218 forums with a lot of overlap.
It would make more sense to have a sub-forum per MCU vendor (STM32, Atmel SAM, ESP32/8266, …) instead.
I don’t think that anyone is proposing to use that at runtime, but I hear people talking about perhaps generating configuration headers at compile time?
So, I want to suggest that we create a discussion forum for each
board, and some kind of template post.
> That would currently amount to 218 forums with a lot of overlap.
Sorry, I really said that wrong.
I mean one forum, with a thread for each board!
> It would make more sense to have a sub-forum per MCU vendor (STM32,
> Atmel SAM, ESP32/8266, …) instead.
You are suggesting a hierarchy(tree) rather than flat list.
I don’t care, but maybe we should start flat and add the sub-forum whenever
we see many similar items.
>> I don’t think that anyone is proposing to use that at runtime, but I
>> hear people talking about perhaps generating configuration headers at
>> compile time?
> That would be the idea.
Sorry, I really said that wrong.
I mean one forum, with a thread for each board!
I’m not sure whether that’d help get the data structured (as it
encourages per-board rather than over-arching discussion), but a link to
the forum thread about that board would be a good metadatum to have, as
might be a link into the issue tracker for open issues about this board.
Zephyr keeps those information in a yaml file and also uses that to
decide what to build on CI.
They use devicetree in parallel, right?
I like (having read up a bit on devicetree now that it’s come up here)
how that is building overlays. Maybe a final metadata result could be
the result of, in a sense, overlaying the device tree with the a YAML
(or similarly structured) information?
Although extra information like the vendor or license could be added to the DeviceTree (in the sense that AFAIK the syntax would allow it), it would not be following the original intention of the specification.
Regarding this, there is a PoC video of a VMA where it is shown how configuration and pinout diagrams are generated based on DeviceTree configuration. The idea was to have some templates and fill the pin assignments when building docs. You can see the final result in the video at 17:05.
Yes, they are using both. Overlays are pretty powerful and handy for things like expansion boards. The connections of a shield could be expressed in reference to a well known connector (e.g. an Arduino type pin header) and if the board presents the same connector the translation is handled.
I’d say an overlay of the information of both files sounds sensible. As I mentioned before, although not impossible adding some of the information you pointed out on a DeviceTree looks a bit far-fetched.
This information would be exactly what I am missing during my usage of the documentation.
Pinout and schematics can get very hard to find.
And while some boards/Mcu’s have certain interfaces, they might not be supported/defined in RIOT.
For example the nrf52840-dongle has an spi interface on board, but it is not enabled in RIOT.
I do like the discussion about device trees and other configuration strategies. But my main problem whenever I try to use RIOT right nog is that I have to dive into the sources to find board/peripheral information.
