Pin management, MODULEs and BOARDs

[mikee47]

General option editing now seems to be satisfied using Kconfig, but managing pin assignments needs some special consideration so I've opened a new issue to discuss.

Other than Host, Sming currently supports three different architectures with a total of five variants:

• Esp8266
• Esp32
  • esp32
  • esp32s2
  • esp32c3
• Rp2040

Note: To clarify, SMING_ARCH determines the SDK and core platform (the family) whilst ESP_VARIANT identifies which chip within the family.
Additional note: Using ESP_VARIANT is probably going to get confusing, should change it perhaps to CHIP_VARIANT or SOC_VARIANT.

Each pin can be configured to various functions and with various restrictions.
As an example, in the ESP32 UART driver we have this definition block at the top:

#ifdef SUBARCH_ESP32
#define UART0_PIN_DEFAULT UART_NUM_0_TXD_DIRECT_GPIO_NUM, UART_NUM_0_RXD_DIRECT_GPIO_NUM
#define UART1_PIN_DEFAULT 18, 19 // Defaults conflict with flash
#define UART2_PIN_DEFAULT UART_NUM_2_TXD_DIRECT_GPIO_NUM, UART_NUM_2_RXD_DIRECT_GPIO_NUM
#elif defined(SUBARCH_ESP32C3)
#define UART0_PIN_DEFAULT 21, 20
#define UART1_PIN_DEFAULT UART_NUM_1_TXD_DIRECT_GPIO_NUM, UART_NUM_1_RXD_DIRECT_GPIO_NUM
#elif defined(SUBARCH_ESP32S2)
#define UART0_PIN_DEFAULT 43, 44
#define UART1_PIN_DEFAULT UART_NUM_1_TXD_DIRECT_GPIO_NUM, UART_NUM_1_RXD_DIRECT_GPIO_NUM
#elif defined(SUBARCH_ESP32S3)
#define UART0_PIN_DEFAULT 43, 44
#define UART1_PIN_DEFAULT UART_NUM_1_TXD_DIRECT_GPIO_NUM, UART_NUM_1_RXD_DIRECT_GPIO_NUM
#define UART2_PIN_DEFAULT UART_NUM_2_TXD_DIRECT_GPIO_NUM, UART_NUM_2_RXD_DIRECT_GPIO_NUM
#else
static_assert(false, "Must define default UART pins for selected ESP_VARIANT");
#endif

Horrible. And there is no way to communicate that information to the user other than inspecting the source code.
Duplicating the same information in a README is a maintainability nightmare.

So we need a set of core definitions which the framework code can use to ensure consistent behaviour and to assist the user in project development.

Goal 1: Device layouts

For each arch/variant, create a file mapping pin numbers with available functions.
Each pin should have a default setting which the framework will honour.
The definition can also be used to provide a definitive list of available peripherals (such as the number of UARTs or SPI controllers).

UPDATE: Goal 2a MODULE definitions

Goal 2: Board definitions

Various development boards or modules will expose pins in a different way.
A board definition should identify default pins and their function (including NOT AVAILABLE).
Note that the board definition will contain additional information, such as the architecture and variant used.
This implies that setting the BOARD will replace use of SMING_ARCH and ESP_VARIANT.
(We may be able to import Arduino board definitions here.)

Goal 3: User definitions

A project will define the board being used (including CUSTOM).
There should be a consistent way to label up a project to keep track of which pins are used for what purpose.
The build system can then run sanity checks against the selected board at build time.

One thing to consider here is where a pin is multiplexed for different functions at runtime,
such as GPIO connected to an FPGA. These might be marked as CUSTOM.

IMPORTANT: This will not change peripheral defaults.

A header file can be generated from these definitions for the project to use, for example by using them
in device constructor calls.

Goal 4: Tools

Provide the user with tools to manage all this:

• List available boards with basic information (including arch, variant, flash size)
• List currently selected board with full details (arch, variant, flash size, features)
• List project pin mappings
• Edit pin mappings
• Show a picture of the device appropriately labelled

Implementation notes

Source data should probably be JSON as it is structured, fairly easy to edit and more flexible.

Kconfig is a good candidate for editing user configurations, but not as a source data format.
More likely then is to use some python to generate Kconfig files then we can use menuconfig for the editing.

[icodk]

Why is it important to have an ESP_VARIANT ?
Are you expecting the same variant in more then one architecture.
From a SMING user perspective, If I program for an esp32s I don't care that it has some architectural coincidences with other chips.
It is adding an extra dimension and confusion but might have a reasoning??

[mikee47]

Why is it important to have an ESP_VARIANT ? Are you expecting the same variant in more then one architecture. From a SMING user perspective, If I program for an esp32s I don't care that it has some architectural coincidences with other chips. It is adding an extra dimension and confusion but might have a reasoning??

ESP_VARIANT was introduced for the Esp32 architecture because it uses one SDK to support multiple entirely different SOCs with significant differences.
I agree that it shouldn't be necessary to bother with this at a project level, but the developer still needs to be aware of it.

With Arduino you just pick the development board being used and it has all the appropriate settings defined somewhere,
and we need something like that for Sming.

Note that I forgot to include above the MODULE level between SOC and BOARD which also needs consideration,
especially for custom board definitions.
For example, the ESP32-S2-WROVER is a MODULE using an ESP32-S2 SOC with PSRAM included,
and the ESP32-S2-Saola-1 is a BOARD which uses that module.

I agree that projects should not care about all this, and should instead specify the BOARD to be used.
I've summarised below the available SOCs which Sming should currently build for:

SOC	SMING_ARCH	ESP_VARIANT	Cores	Notes
ESP8266EX	Esp8266		1
ESP8285	Esp8266		1
ESP32-D0WD-V3	Esp32	esp32	2
ESP32-U4WDH	Esp32	esp32	2
ESP32-PICO-V3	Esp32	esp32	2
ESP32-PICO-V3-O2	Esp32	esp32	2
ESP32-PICO-D4	Esp32	esp32	2
ESP32-D0WD	Esp32	esp32	2
ESP32-D0WDQ6-V3	Esp32	esp32	2
ESP32-D0WDQ6	Esp32	esp32	2
ESP32-S0WD	Esp32	esp32	1
ESP32-S3	Esp32	esp32s3	2	In development
ESP32-S2	Esp32	esp32s2	1
ESP32-S2F	Esp32	esp32s2	1
ESP32-C3	Esp32	esp32c3	1	RISCV CPU
ESP8685	Esp32			No info
ESP32-H2	Esp32			In development
RP2040	Rp2040		2	ARM Cortex M0+

I'm not going to attempt a module or board list because those would be massive.
I'm proposing that (like Arduino and other frameworks) the project will define which BOARD it's using.

So yes, you make a good point in that the application should only be concerned with the SOC being used,
and Sming should sort out the rest internally.

[icodk]

Yes. Only chip ARCH, which is significant for the code produced by the compiler/linker. PSRAM is a peripheral and it is up to the programmer to find out what kind of peripherals the board/module supports. Boards/modules are nice to have aggregations that can tell the use which ARCH is being used and can make the framework more accessible for beginners.

[mikee47]

Not just beginners actually. It should help with maintainability for both the framework and user projects.

At present, if I build the Basic_Serial sample then I'd expect it to just work on all the available dev. boards I have just by recompiling. For most dev. boards (except RP2040) the default serial port is the same one used for programming via USB so not a problem. However, that sample uses a second serial port so I need to know how to connect that for each board.

Another more real-world example is developing and testing an SPI Graphics library against multiple boards. There are a lot more pins to connect there.

So the problem is one of documentation, and avoiding having the same information in multiple places.

What I'd like is to be able to run make pinmap for any sample in the framework and it tells me all the pins that sample uses and how to connect them. If I change the code (by editing my project config), the map changes. This also means we don't need to bother including this sort of information in the documentation.