LoRaWAN config files and pin maps

[jgromes]

Continued discussion from #1104

At the moment, we are defining pin maps for some modules in LoRaWAN config.h files. I like the idea of providing pin maps to the users, but I don't think this should be part of RadioLib, much like we moved persistent memory management elsewhere. My arguments are the following:

1. The current config files are copy-pasted in the LoRaWAN examples, so they are prone to getting out-of-sync with each other.
2. Pin maps are not applicable to just LoRaWAN, but all examples in here, especially the SX127x/SX126x ones since those modules are typically used by manufacturers like Heltec on their boards. However, it's not really a solution to copy the config files everywhere.
3. People will want to contribute their own pin maps, we cannot stop that. So even if we test the ones that we have added, others are bound to be added later, making it harder to keep everything in sync. And of course, new boards will keep being made.

I think that points 1 and 2 can be resolved by moving pin maps into their own repository. We can point to it from all the relevant examples, but leave it up to the user if/how they want to use it. In that repository, it's up to us how to implement the pin maps, whether it will be just documentation, some headers that the user must configure themselves, or an automated board resolution algorithm. It also has the added advantage of other projects being able to benefit from this. I also don't seem to be able to find a significant downside, RadioLib will not lose any functionality after this change.

Point 3 will not be resolved by this, but at least it will limit the number of commits/PRs and changes to the examples here.

Thoughts @StevenCellist @HeadBoffin?

[StevenCellist]

When I was digging around yesterday for the pinmaps, it struck me that GxEPD2 has a similar 'problem'. Here, each and every example comes with a bunch of extra files, like can be seen here.
It's quite a bit of a hassle as you have to search for everything yourself, but it is helpful to get the guidance as you get an idea for where to look and how to use.

I am happy with pinmaps in a separate repository, and would suggest two files: one for all the boards that have a radio soldered onto them, which would be approximately the list that I ended up with in #1104 (although there's also STM32WL). These are fixed, and should need only be tested once to be sure that they are OK. The other file would be 'user contributed' for boards that are frequently used but without an 'internal' radio, such as a Feather, ESP8266, Pico (the hat is debatable).

[jgromes]

I think we should only have a list of boards with "internal" radio - or rather those with fixed configuration that user cannot change without significant hardware modification. So in my point-of-view, Heltec boards are applicable (since the user would need to literally start cutting traces to change the pinout), and so is the Pico hat because it is explicitly intended just for RPi Pico. On the other hand, generic Arduino shield with some radio is out of scope since the pins to which it is connected change depending on what Arduino board you connect it to.

I'll put something together in the next couple of days and post a link here.

[jgromes]

I pushed the first draft into https://github.com/radiolib-org/RadioBoards. It currently only has two supported boards, a simple one (Heltec WiFi LoRa32) and a complex one (Wio WM1110 with custom SPI and RF switching).

I tried to stick to the following guidelines:

1. We allow the user to either select automated board recognition, or select a board manually. The automated selection process defines our own macros for each board, so it should be possible to use this in environments that handle this differently (e.g. Heltec boards that have macros capitalized in Arduino but lowercase in Platformio if memory serves).
2. Suported boards are split between maintained (which we have tested personally) and contributed (which were added by other people).
3. The minimum required board definition are its pins, however, it can also define SPI if a non-default one is used and also set RF switching.
4. When used with RadioLib, it creates Module constructors, RF switch maps and handles SPI init for the user. Without RadioLib, it just provides pin number in a predictable format.

Example usage with automated selection (using RadioLib):

#include <RadioLib.h>

#define RADIO_BOARD_AUTO // automate board selection ...
//#define RADIO_BOARD_WIFI_LORA32 // ... or define it manually
#include <RadioBoards.h>

SX1276 radio = new RadioModule();

Feedback will be greatly appreciated!

[StevenCellist]

I'll give it a shot somewhere in the next few days, but there's one thing I'd like to say already: I am not completely positive about still needing to put the radio type in (in this case SX1276). I (we) run the same sketch on a collection of boards, on purpose a range of radios. There's definitely something to say for that the user must know which radio is on board as that's useful knowledge, but I do think that it would be nice if we could hide the radio type in RadioBoards as well. That way, a sketch becomes completely agnostic of both platform and board.
Besides that, functionality looks cool on first sight, but will give it a shot this week.

[jgromes]

I was thinking the same thing, and ultimately decided against including the radio type exactly for that exact reason - the user should know which radio they are using. At the same time though, an argument could be made that it's pretty much the same case as for the pins: the user has no control over what radio did the manufacturer use. So I think I will go back to this decision and include the module type in the RadioLib support section.

[StevenCellist]

Great minds... 😉 although I wouldn't dare implying that I'm on your level.
As soon as the user enables automated board selection, they should know that they 'give up' the control and knowledge of their board, indeed for both pins and radio. Most users will use IO which means they must look at a pinmap - usually the radio type is listed on there as well. At least LilyGo does, for Heltec it depends on which image or page you select.
Ultimately it's your call, and if we think both have their value, we could even add a #define for inserting the radio yes or no... ;)

[jgromes]

we could even add a #define for inserting the radio yes or no... ;)

I don't think that's a good idea, jsut more configuration for the user to be aware of. And nobody is forcing them to use it :)
I added it to the repo, alongside examples.

[K4KDR]

Thanks for the continuing development!!

Since I don't have the expertise to 'comment', I have attempted to follow your example and created a Pull Request for one of the hardware combinations that I have working:

radiolib-org/RadioBoards#1

[StevenCellist]

Took some more time to get around to it, but I just gave it a shot by seeing if I could get my Heltec V3 boards to work. And yes, it works flawlessly!
One point worth mentioning is the pin naming 'problem': SX126x uses a different naming scheme than SX127x, currently the latter is used. Now most users shouldn't need looking at the internals, but it would be nice if the naming would be consistent with the radio used. I don't have an immediate suggestion how this would be done, maybe someone else has an idea.

One question to ask ourselves is if we are going to apply any de-duplication for similar boards - specifically looking at the Heltec V3 boards here. All V3 boards have equal pinout for the radio - are we going to duplicate files for each board just for clarity and completeness, or rather keep it easier for the compiler and combine these into one file with a possibly rather long #if defined() || defined() || defined()?

[jgromes]

SX126x uses a different naming scheme than SX127x, currently the latter is used

I tried to do this in a radio-agnostic way, so that one of the signals is called IRQ while the other one is GPIO. The logic is that at least one interrupt source is always needed, hence the IRQ. The other pin can be any general-purpose pin without explicit function, it can be interrupt on some pins, another signal elsewhere (likey SX126x/8x BUSY).

One question to ask ourselves is if we are going to apply any de-duplication for similar boards

I don't have a strong preference here, but for what it's worth my as of yet uncommited changes already contain some deduplication ;)

[StevenCellist]

Ah, sure, yeah I see! Go ahead then, great work :)

[jgromes]

Thanks - in that case I pushed most of the boards from LoRaWAN config.h (not the ones marked as "not verified") and will replace it by a link to that repository in the LoRaWAN examples.