Allow board specific define, for boards without unique ARDUINO_BOARDNAME or no matching entry in boards.txt

[tyeth]

Some boards use the generic module FQBN or the ARDUINO_BOARD define for a generic module/devkit, when they have differing pinouts.

We need to be able to distinguish between them during compilation, which we do via ci-arduino build targets with FQBN.
It's possible to override the boards.txt entries for a single board, or even add new boards, using a boards.local.txt file installed into the platform folder (where boards.txt resides).

This issue was raised after a user added the DFRobot ESP32C3 which uses the same board define as the Espressif C3 devkit.

I've added an argument to build-platforms.py in ci-arduino, --boards-local-txt, with an optional file argument (or defaults to CWD\boards.local.txt).

• If the argument/flag is supplied, then the test-examples function also looks for an example specific boards.local.txt file, or preferably a board specific version .{PLATFORM}.boards.local.txt like the .skip files (and .generate which is for UF2)

ci-arduino PR
adafruit/ci-arduino#217

wipper PR
#784

I tested with a boards.local.txt at project root, and the updated CI task to use the flag, using a wippersnapper DFrobot C3 specific define (WS_UNIQUE_BOARD_ID) and the plain ESP32C3_DEV separated into two entries in Wippersnapper_Boards.h, one with a broken board ID, and watched them come online with the different id, then swapped the broken one.
Then restored to both being dfrobot c3, but now we can add the c3 devkit or other boards using the ESP32C3_DEV define.

Related:
espressif/arduino-esp32#6883
#771

[tyeth]

@brentru this is probably worth going over together, but you can see the test stages in the commit history.

Here are two assets (runnable on any C3) that cover the two situations I created in commit history, where I used the boards.local.txt to override the board defines for the DFRobot.

build-files-dfrobot_beetle_esp32c3.1.0.0-beta.109-9-ga7d554ca-bad-robot-if-boards-txt-worked.zip
build-files-dfrobot_beetle_esp32c3.1.0.0-beta.109-8-g452f3d33-correct-robot-if-local-boards-file-worked.zip

Adafruit_Wippersnapper_Arduino/boards.local.txt

Lines 1 to 17 in 8afd334

	# This is to allow providing extra defines like WS_MY_BOARD_NAME for any boards using generic module board definitions.
	# Instead of the MY_BOARD_NAME suffix, it should match the unique Board ID in Wippersnapper_Boards.h, but
	# uppercase with underscores for dashes. e.g. "dfrobot-beetle-esp32c3" becomes WS_DFROBOT_BEETLE_ESP32C3 with -D for define.
	#
	# See if the board.txt already has extra board.defines= in any menu entries, or only the basic empty board.defines=
	# so for example this existing one dfrobot_romeo_esp32s3.menu.PSRAM.enabled.build.defines=-DBOARD_HAS_PSRAM
	# then you would add a replacement entry with the existing plus additionally the new -DWS_UNIQUE_BOARD_NAME define:
	# dfrobot_romeo_esp32s3.menu.PSRAM.enabled.build.defines=-DBOARD_HAS_PSRAM -DWS_DFROBOT_UNIQUE_BOARD_ID
	#
	# Do the same for the board entry in the platformio.ini file: build_flags = -DWS_YOUR_UNIQUE_BOARD_ID
	#
	# Note: If needed we can do a version of this file for each board build target in case boards don't have a
	# unique definition in boards.txt to add an override. Then in CI pass filename with --boards-local-txt file
	# DF Robot ESP32-C3 shares define with Espressif ESP32_C3 Devkit/Module, so needs unique define:
	dfrobot_beetle_esp32c3.build.defines=-DWS_DFROBOT_BEETLE_ESP32C3

[tyeth]

Tagging @ladyada as mentioned in the meeting. For now the CI-Arduino PR does not take the change into main branch, but will happily afterwards if it's desired (which it sounds like it is).

[ladyada]

yep understood!

[brentru]

@tyeth Ping me in slack when you're back from holiday and we'll go over this