You will need to choose names for the pin and devices your board defines in its board module. In this section you can find some guidelines for what names to use.
Note that the pin names do not have to correspond to the manufacturer's pin names. For instance, D5 may not correspond to a pin numbered 5 on the actual chip.
Copy from Similar Boards
If your board is similar to an existing board, you will probably copy the names from that board, and make small changes or additions as needed.
If you are adding a Feather board, see the Feather Specification for suggestions of which pins should not vary, and what are the typical pin names that are used. SCL, SDA, SCK, MOSI, MISO, TX, and RX, should be present and in the same locations.
The A0 through A5 pins should also generally be present. Then, if possible, use the same Dn names found on many Feathers.
Likewise, for Metro, ItsyBitsy, and Qt Py boards, take inspiration from pin names on existing boards.
Use the Board Silkscreen as a Guide
Try to make the names correspond closely enough to the board silkscreen that it is self-evident which pins correspond to which silkscreen markings. It's fine to expand abbreviations, such as LED for L. You don't have to match the silkscreen exactly, since the silkscreen names are often constrained by the space available.
Pin Aliases
It is perfectly fine for a pin to have multiple names. For instance, board.LED may also be board.D13. In the pins.c file for the board, group the names together and surround the group with blank lines to make it easy to see the pin has multiple names. Put the primary name first.
I2C Devices and Pins
Boards often have a defined board.I2C() singleton device, using pins SCL and SDA. If the board has a STEMMA QT / Qwiic connector, it should also have a board.STEMMA_I2C() device. This device may use the same pins as board.I2C(), or, if sufficient pins are available, board.STEMMA_I2C() can use separate pins and a separate I2C device. If it uses separate pins, in general, choose SCL1 and SDA1 for those pins.
Espressif Board Pins
For boards using Espressif chips, the style is not to remap GPIOn pins to possibly differently-numbered pins named Dm, where n != m. Instead, the Dn numbers correspond one for one to the GPIOn pin names of the Espressif chip, with the n numbers matching. This is because the Arduino Espressif board support package does not allow remapping of numeric pin numbers.
GPIOn pin names are typically abbreviated as IOn on Espressif boards.
You'll see this on the Feather ESP32-S2, which has non-typical pin numbers for a Feather. On the Feather ESP32-S3, the Dn pin numbers are more typical, but do correspond directly to the GPIOn pin numbers.
The A0-A5 analog-capable pins are remappable in Arduino Espressif, so these don't need to correspond directly to particular GPIO pins.
Raspberry Pi RP2040 Pins
On RP2040, the RP2040 GPIOn names are typically abbreviated as GPn, unlike Espressif boards.
LEDs and Buttons
Most boards have a single color LED, often on pin D13, which should have the name LED. If there are multiple colored LEDs, give them names like LED_RED and LED_BLUE (not RED_LED and BLUE_LED). Choose one of them as the primary LED and give it the name LED as well.
A single button can be BUTTON. Multiple buttons might be BUTTON_1, BUTTON_2, BUTTON_A, BUTTON_B, or whatever they are labelled on the board silkscreen. Prefer including the underscore: BUTTON_1 rather than BUTTON1.
Addressable RGB LEDs are typically NEOPIXEL or DOTSTAR. For RGB LEDs with multiple anodes or cathodes, RGB_LED_RED, RGB_LED_GREEN, RGB_LED_BLUE are typical.
Power Control and Enable Lines
Some pins may control on-board or off-board power, such as NEOPIXEL_POWER, or NEOPIXEL_I2C_POWER. If the control line is active low, rather than high, adding _INVERTED will help the user remember that, such as NEOPIXEL_POWER_INVERTED.
Page last edited April 09, 2024
Text editor powered by tinymce.
