Skip to content

Latest commit

 

History

History
123 lines (95 loc) · 5.53 KB

variants.md

File metadata and controls

123 lines (95 loc) · 5.53 KB

Adding custom boards/ variants

  • Boards already supported by Zephyr can be added to the variants folder as outlined in this documentation.
  • Custom boards can first by added by following the official Zephyr porting guide. Once completed, continue here by adding a variant for your custom board.

Suppored Boards/variants

  • Arduino Nano ble sense 33
  • Arduino Nano ble 33
  • Arduino Nano 33 iot

Planned Support: (TODO)

  • Particle Xenon
  • Arduino mkrzero
  • TI-CC3220SF LaunchXL
  • nrf52840dk_nrf52840

How to add board variants

This module uses the board name (supplied at build time by the -b arduino_nano_33_ble flag) to correctly map Arduino pin names/numbers to the target board. To add board support:

  1. This project is structured in a way so as to isolate the variants from the core API. Thus, whenever a new board needs to be added it needs to be done in the variants/ folder. Add a folder inside of the variants folder that matches the name of your board.
  2. Add an overlay file and a pinmap header file that match the name of the board.
  3. Add your new headerfile to an #ifdef statement in the variants.h file.

An example of this structure is shown below.

variants/
├── arduino_nano_33_ble
│   ├── arduino_nano_33_ble.overlay
│   └── arduino_nano_33_ble_pinmap.h
├── CMakeLists.txt
└── variants.h
  • The top level consists of CMakeLists.txt, variants.h and the <BOARD_NAME> folder. Each of these files have a specific role to play. - The Cmakelists help the compiler locate the proper directory to help find the proper header files that are board specific. You need to add the name using zephyr_include_directories(BOARD_NAME) to this file. Do note that this BOARD_NAME is the same as the name of your board's directory. - variants.h contains the necessary #includes inorder to tell the source code about your board's pinmap.
  • The <BOARD_NAME> folder is where the overlay and pinmap file resides. Inorder to understand how to write DT overlays, lookup Documentation/overlays.md. To understand the <boardname_pinmap.h> file, go through the existing variants/ARDUINO_NANO33BLE/arduino_nano_ble_sense_pinmap.h which shows how to use the overlay nodes inside our C programs using zephyr macros like GPIO_DT_SPEC_GET. The zephyr-project documentation on this is pretty extensive as well and worth reading.

Guide to Writing Overlays

DeviceTree Overlay files for Arduino boards

This module requires that your Arduino header pins be mapped in the DeviceTree to a zephyr,user node using the d0_gpios format for each pin. Follow the examples in the variants directory to create an overlay file and a header file for your board.

Overlays using previously-defined Arduino headers

When an Arduino header exists in a board's in-tree DTS file it can easily be used to create the necessary overlay file. Assign the relevant mapping using the Arduino header label (usually either &arduino_header or &arduino_nano_header and the gpio_map number. The second number is used to add GPIO flags and may safely be left as zero.

For example, creating an overlay file for the Nordic nRF52840 Development Kit uses the Arduino header definitions, beginning with the first digital pin:

/ {
	zephyr,user {
		d0_gpios = <&arduino_header 6 0>;			/* Digital */
		d1_gpios = <&arduino_header 7 0>;
		...
		d13_gpios = <&arduino_header 19 0>;
		d14_gpios = <&arduino_header 0 0>;			/* Analog */
		d15_gpios = <&arduino_header 1 0>;
		...
		d19_gpios = <&arduino_header 5 0>;
		d20_gpios = <&arduino_header 20 0>;			/* SDA */
		d21_gpios = <&arduino_header 21 0>;			/* SCL */
		d22_gpios = <&gpio0 13 GPIO_ACTIVE_LOW>;	/* LED0 */
	};
};

Overlays from scratch

You can see in the example above that there is no mapping for LED0 in the board's Arduino header definition so it has been added using the Zephyr gpios syntax (port, pin, flags). When creating an overlay file that doesn't have an Arduino header defined, you should follow this syntax for adding all pins

You control the pin mapping

Zephyr chooses to map Arduino headers beginning with the Analog pins, but the overlay file example above begins with the digital pins. This is to match user expectation that issuing pinMode(0,OUTPUT); should control digital pin 0 (and not pin 6). In the same way, the Analog 0 pin was mapped to D14 as this is likely what a shield made for the Arduino Uno R3 header would expect.

Ultimately the mapping is completely up to you and should match the needs of the sketch you will be compiling.

Creating the pinmap header file

It is recommended that you copy an existing pinmap file from one of the board folders inside of the variants folder. For the most part, this header file will not change from board to board.

One example of a change that you may find useful is mapping additional pins. For example, the LEDs on the nRF52840 are not connected to any of the Arduino header pins. To define a built-in LED for this board, a 22nd pin definition was added.

Your pinmap header file must be added to the variants.h file by adding three lines using this format:

#ifdef CONFIG_BOARD_NRF52840DK_NRF52840
#include "nrf52840dk_nrf52840.h"
#endif // CONFIG_BOARD_NRF52840DK_NRF52840