Arduino/Genuino Zero (BBE)

Downstream Extension!

This board description is a copy from the Zephyr upstream board Arduino/Genuino Zero and will be used for further development, improvement and preparation of changes for Zephyr within Bridle. However, the original board description still lives within the Zephyr namespace.

Overview

The Arduino Zero is a maker-friendly development board with Atmel’s Embedded Debugger (EDBG [10]), which provides a full debug interface without the need for additional hardware.

Arduino Zero

List of extensions

This is a set of Bridle’s board extensions (BBE) to the original Zephyr upstream board Arduino/Genuino Zero with some adaptions and improvement on Twister, Kconfig and Devicetree level. Notes and details about these extensions can be found at various points within this documentation.

Hardware

  • ATSAMD21G18A [28] ARM Cortex-M0+ processor at 48 MHz

  • 32.768 kHz crystal oscillator

  • 256 KiB flash memory and 32 KiB of RAM

  • 3 user LEDs (L/Rx/Tx)

  • One reset button

  • On-board USB based EDBG unit with serial console

  • Native USB port

  • Arduino UNO R3 header

  • Arduino ICSP header

Supported Features

The arduino_zero//bbe board configuration supports the following hardware features:

Hardware Features Supported by Zephyr

Peripheral

Kconfig option

Devicetree compatible

Zephyr API

PINCTRL

CONFIG_PINCTRL

atmel,sam0-pinctrl

Pin Control API

GPIO

CONFIG_GPIO

atmel,sam0-gpio

General-Purpose Input/Output (GPIO)

UART

CONFIG_SERIAL

atmel,sam0-uart

Universal Asynchronous Receiver-Transmitter (UART)

UDC (USB Device Controller)

CONFIG_USB_DEVICE_STACK_NEXT

atmel,sam0-usb

USB device support APIs

I2C

CONFIG_I2C

atmel,sam0-i2c

Inter-Integrated Circuit (I2C) Bus

SPI

CONFIG_SPI

atmel,sam0-spi

Serial Peripheral Interface (SPI) Bus

PWM

CONFIG_PWM

atmel,sam0-tcc-pwm

Pulse Width Modulation (PWM)

DAC

CONFIG_DAC

atmel,sam0-dac

Digital-to-Analog Converter (DAC)

ADC

CONFIG_ADC

atmel,sam0-adc

Analog-to-Digital Converter (ADC)

RTC

CONFIG_RTC

atmel,sam0-rtc

Real-Time Clock (RTC)

Timer (Counter)

CONFIG_COUNTER

atmel,sam0-tcc

Counter

Watchdog Timer (WDT)

CONFIG_WATCHDOG

atmel,sam0-watchdog

Watchdog

Flash

CONFIG_FLASH

atmel,sam0-nvmctrl

Flash and Flash map

DMA

CONFIG_DMA

atmel,sam0-dmac

Direct Memory Access (DMA)

HWINFO

CONFIG_HWINFO

atmel,sam0-id

Hardware Information

CLOCK / PM

not supported

atmel,samd2x-gclk
atmel,samd2x-pm

Clock Control

NVIC

N/A

Nested Vector Interrupts Controller

SYSTICK

N/A

arm,armv6m-systick

Other hardware features are not currently supported by Zephyr.

The extended default configuration can be found in the downstream file boards/arduino/zero/arduino_zero_bbe_default. It is a extended copy of the original board default configuration in boards/arduino/zero/arduino_zero_defconfig.

Board Configurations

The arduino_zero//bbe board can be configured for the following different use cases.

west build -b arduino_zero//bbe -S usb-console

Use the native USB device port with CDC-ACM as Zephyr console and for the shell, see USB Console Snippet (usb-console).

west build -b arduino_zero//bbe

Use the serial port SERCOM5 over EDBG as Zephyr console and for the shell.

List of extensions

Board YAML

  • add the missing features that this board supports and that Twister tests might depends on:

    • arduino_gpio

    • arduino_i2c

    • arduino_spi

    • arduino_serial

    • i2c

Devicetree

  • set default entries for model and compatible of the boards:

    Arduino/Genuino Zero

    arduino_zero_bbe.dts
    / {
    	model = "Arduino Zero @ UART Concole (BBE)";
    	compatible = "arduino,zero",
    		     "arduino,zero-bbe",
    		     "arduino,zero-uartcons",
    		     "arduino,zero-uartcons-bbe",
    		     "atmel,samd21g18a",
    		     "atmel,samd21";
    
    };
    

Connections and IOs

The Arduino store [20] has detailed information about board connections. Download the Arduino Zero Schematic [22] or Arduino Zero Design Data [23] for more detail. There is also an Arduino Zero Pinout Diagram [21].

Devicetree

  • add the Arduino UNO R3 specific edge connector binding &arduino_header {...}; with additional labels:

    Arduino/Genuino Zero

    arduino_r3_connector.dtsi
    	arduino_header: connector {
    		compatible = "arduino-header-r3";
    		#gpio-cells = <2>;
    		gpio-map-mask = <0xffffffff 0xffffffc0>;
    		gpio-map-pass-thru = <0 0x3f>;
    		gpio-map = <ARDUINO_HEADER_R3_A0 0 &porta 2 0>,  /* DAC:VOUT */
    			   <ARDUINO_HEADER_R3_A1 0 &portb 8 0>,  /* ADC:AIN2 */
    			   <ARDUINO_HEADER_R3_A2 0 &portb 9 0>,  /* ADC:AIN3 */
    			   <ARDUINO_HEADER_R3_A3 0 &porta 4 0>,  /* ADC:AIN4 */
    			   <ARDUINO_HEADER_R3_A4 0 &porta 5 0>,  /* ADC:AIN5 */
    			   <ARDUINO_HEADER_R3_A5 0 &portb 2 0>,  /* ADC:AIN10 */
    								 /* AREF (ADC/DAC:VRFEA) */
    			   <ARDUINO_HEADER_R3_D0 0 &porta 11 0>, /* SERCOM0:UART:RX */
    			   <ARDUINO_HEADER_R3_D1 0 &porta 10 0>, /* SERCOM0:UART:TX */
    			   <ARDUINO_HEADER_R3_D2 0 &porta 14 0>,
    			   <ARDUINO_HEADER_R3_D3 0 &porta 9 0>,
    			   <ARDUINO_HEADER_R3_D4 0 &porta 8 0>,
    			   <ARDUINO_HEADER_R3_D5 0 &porta 15 0>,
    			   <ARDUINO_HEADER_R3_D6 0 &porta 20 0>,
    			   <ARDUINO_HEADER_R3_D7 0 &porta 21 0>,
    			   <ARDUINO_HEADER_R3_D8 0 &porta 6 0>,
    			   <ARDUINO_HEADER_R3_D9 0 &porta 7 0>,
    			   <ARDUINO_HEADER_R3_D10 0 &porta 18 0>, /* SERCOM1:SPI:SS */
    			   <ARDUINO_HEADER_R3_D11 0 &porta 16 0>, /* SERCOM1:SPI:COPI */
    			   <ARDUINO_HEADER_R3_D12 0 &porta 19 0>, /* SERCOM1:SPI:CIPO */
    			   <ARDUINO_HEADER_R3_D13 0 &porta 17 0>, /* SERCOM1:SPI:SCK */
    			   <ARDUINO_HEADER_R3_D14 0 &porta 22 0>, /* SERCOM3:I2C:SDA */
    			   <ARDUINO_HEADER_R3_D15 0 &porta 23 0>; /* SERCOM3:I2C:SCL */
    	};
    
    arduino_r3_connector.dtsi
    arduino_i2c: &sercom3 {};
    arduino_spi: &sercom1 {};
    arduino_serial: &sercom0 {};
    

System Clock

The SAMD21 MCU is configured to use the 32.768 kHz external crystal with the on-chip PLL generating the 48 MHz system clock. The internal APB and GCLK unit are set up in the same way as the upstream Arduino libraries.

GPIO (PWM) Ports

The SAMD21 MCU has 2 GPIO ports, 3 PWM able Timer/Capture-Counter (TCC) and 2 simple Timer/Counter (TC). On the Arduino Zero, TCC2 channel 1 is available on first user LED (L), all other user LEDs can be controlled as GPIO. Only if CONFIG_PWM_SAM0_TCC is enabled then the first user LED (L) is driven by TCC2 instead of by GPIO. All channels of TCC0 and TCC1 are available on the Arduino UNO R3 header.

ADC/DAC Ports

The SAMD21 MCU has 1 DAC and 1 ADC. On the Arduino Zero the DAC voltage output (VOUT) is available on A0 of the Arduino UNO R3 header. The ADC channels 2-5 and 10 are available on A1-A5 of the Arduino UNO R3 header.

The external voltage reference VREFA can be used optional for the DAC and ADC on same time and is available on AREF of the Arduino UNO R3 header.

SPI Port

Arduino Zero SPI on 6 pin ICSP connector

The SAMD21 MCU has 6 SERCOM based SPIs. On the Arduino Zero, SERCOM4 is available on the 6 pin ICSP connector at the edge of the board. To the Arduino UNO R3 header SERCOM1 is connect to external devices over D11 (MOSI), D12 (MISO), and D13 (SCK). All signals of both busses are connected in parallel to the Atmel EDBG.

Devicetree

  • provide the SPI Port at the Arduino UNO R3 specific edge connector:

    Arduino/Genuino Zero

    arduino_zero_bbe.dts
    &sercom1 {
    	status = "okay";
    	compatible = "atmel,sam0-spi";
    	dipo = <3>;
    	dopo = <0>;
    	#address-cells = <1>;
    	#size-cells = <0>;
    
    	// either: cs-gpios = <&arduino_header ARDUINO_HEADER_R3_D10 GPIO_ACTIVE_LOW>;
    	//     or: cs-gpios = <&porta 18 GPIO_ACTIVE_LOW>;
    	//     or: pinctrl-0 = <&sercom1_spi_hwss>;
    
    	pinctrl-0 = <&sercom1_spi_default>;
    	pinctrl-names = "default";
    };
    
    arduino_r3_connector.dtsi
    arduino_spi: &sercom1 {};
    

I2C Port

The SAMD21 MCU has 6 SERCOM based I2Cs. On the Arduino Zero, SERCOM3 is signals are connected in parallel to the Atmel EDBG.

Devicetree

  • provide the I2C Port at the Arduino UNO R3 specific edge connector:

    Arduino/Genuino Zero

    arduino_zero_bbe.dts
    &sercom3 {
    	status = "okay";
    	compatible = "atmel,sam0-i2c";
    	clock-frequency = <I2C_BITRATE_FAST>;
    	#address-cells = <1>;
    	#size-cells = <0>;
    
    	pinctrl-0 = <&sercom3_i2c_default>;
    	pinctrl-names = "default";
    };
    
    arduino_r3_connector.dtsi
    arduino_i2c: &sercom3 {};
    

Serial Port

The SAMD21 MCU has 6 SERCOM based USARTs. One of the USARTs (SERCOM5) is connected to the onboard Atmel Embedded Debugger (EDBG) and is the Zephyr console. This is captured by the standard board configuration. SERCOM0 is available on the D0 (RX) and D1 (TX) of the Arduino UNO R3 header.

USB Device Port

Arduino Zero Native and Programming USB Ports

The SAMD21 MCU has a (native) USB device port that can be used to communicate with a host PC. See Zephyr USB for more, such as the USB CDC ACM UART sample sample which sets up a virtual serial port that echos characters back to the host PC. As an alternative to the default Zephyr console on serial port the Bridle USB Console Snippet (usb-console) can be used to enable CDC ACM and switch the console to USB:

USB device idVendor=2341, idProduct=804d, bcdDevice= 4.05
USB device strings: Mfr=1, Product=2, SerialNumber=3
Product: Arduino Zero (CDC ACM)
Manufacturer: Arduino LLC
SerialNumber: 9CF503EE1D54A301

Kconfig

  • deactivate self powered USB explicitly and set the maximum of electrical current consumption to 500㎃:

    Arduino/Genuino Zero

    Kconfig.defconfig
    config CDC_ACM_SERIAL_SELF_POWERED
    	default n
    	depends on USB_DEVICE_STACK_NEXT && USBD_CDC_ACM_CLASS
    
    config CDC_ACM_SERIAL_MAX_POWER
    	default 250 if BOARD_ARDUINO_ZERO	# 500mA
    	depends on USB_DEVICE_STACK_NEXT && USBD_CDC_ACM_CLASS
    
  • change log level only in case of use the native USB device port atmel,sam0-usb with CDC-ACM UART zephyr,cdc-acm-uart as Zephyr console:

    Arduino/Genuino Zero

    Kconfig.defconfig
    # Workaround for not being able to have commas in macro arguments
    DT_CHOSEN_Z_CONSOLE := zephyr,console
    DT_COMPAT_Z_CDC_ACM_UART := zephyr,cdc-acm-uart
    DT_COMPAT_ATMEL_USB := atmel,sam0-usb
    
    # Macros to shorten Kconfig expressions
    DT_CHOSEN_CONSOLE_NODE := $(dt_chosen_path,$(DT_CHOSEN_Z_CONSOLE))
    DT_CHOSEN_CONSOLE_PARENT := $(dt_node_parent,$(DT_CHOSEN_CONSOLE_NODE))
    
    if BOARD_ARDUINO_ZERO && \
    	$(dt_chosen_enabled,$(DT_CHOSEN_Z_CONSOLE)) && \
    	$(dt_compat_on_bus,$(DT_COMPAT_Z_CDC_ACM_UART),usb) && \
    	$(dt_node_has_compat,$(DT_CHOSEN_CONSOLE_PARENT),$(DT_COMPAT_ATMEL_USB))
    
    # Logger cannot use itself to log
    choice USBD_CDC_ACM_LOG_LEVEL_CHOICE
    	default USBD_CDC_ACM_LOG_LEVEL_OFF
    	depends on LOG && USB_DEVICE_STACK_NEXT && USBD_CDC_ACM_CLASS
    endchoice
    
    # Set USB log level to error only
    choice USBD_LOG_LEVEL_CHOICE
    	default USBD_LOG_LEVEL_ERR
    	depends on LOG && USB_DEVICE_STACK_NEXT && USBD_CDC_ACM_CLASS
    endchoice
    
    # Set UDC driver log level to error only
    choice UDC_DRIVER_LOG_LEVEL_CHOICE
    	default UDC_DRIVER_LOG_LEVEL_ERR
    	depends on LOG && USB_DEVICE_STACK_NEXT && USBD_CDC_ACM_CLASS
    endchoice
    
    endif # zephyr,cdc-acm-uart
    

Programming and Debugging

The Arduino Zero ships the BOSSA compatible UF2 bootloader [13] also known as Arduino Zero Bootloader [24], a modern SAM-BA [12] (Boot Assistant) replacement. The bootloader can be entered by pressing the RST button twice:

USB device idVendor=2341, idProduct=004d, bcdDevice= 2.00
USB device strings: Mfr=1, Product=2, SerialNumber=0
Product: Arduino Zero
Manufacturer: Arduino LLC

Additionally, if CONFIG_USB_CDC_ACM is enabled then the bootloader will be entered automatically when you run west flash.

Kconfig

  • BOSSA bootloader device:

    Arduino/Genuino Zero

    Kconfig.defconfig
    config BOOTLOADER_BOSSA_DEVICE_NAME
    	default "$(dt_chosen_label,$(DT_CHOSEN_Z_CONSOLE))"
    	depends on USB_CDC_ACM
    

Tip

When ever you need to restore this original bootloader you should read and following the directions in Arduino Zero Advanced Features [25] and Update the Bootloader on the Arduino Zero [26]. There is also a backup copy of the original bootloader together with a ready to use Segger JFlash control file inside the Bridel project:

The Segger JFlash control file is only useful when the EDBG firmware was upgrade to the latest J-Link firmware for Atmel EDBG [6]. This was a special OEM firmware version for Atmel’s Xplained Platforms, based on the AT32UC3A4256S [29] 32-bit AVR microcontroller.

Danger

It is neither guaranteed nor tested that the J-Link firmware for Atmel EDBG will also work on the EDGB populated on the Arduino Zero! See also the warning to Atmel Studio 7 below. In doubt you should never touch the EDBG firmware on Arduino Zero.

So if that didn’t happen, OpenOCD or, even easier, the small tool edbg, the CMSIS-DAP programmer [14] by a Microchip employee, should be used:

$ srec_cat samd21_sam_ba.hex -Intel -Output samd21_sam_ba.bin -Binary
$ edbg --list    # convert HEX to BIN file and get <your_edbg_sn>

$ edbg --verbose --serial <your_edbg_sn> --target samd21 \
       --erase --program --verify --file samd21_sam_ba.bin

It is also possible to use Microchip’s own Python MCU programmer [15] together with the Python Kit information [16] utility and write the Intel HEX file directly back to flash without conversion to BIN file:

$ pykitinfo # get <your_edbg_sn>
$ pymcuprog --verbose info --tool edbg --serialnumber <your_edbg_sn> \
            --device atsamd21g18a --file samd21_sam_ba.hex \
            --erase --verify write

Atmel Embedded Debugger (EDBG)

The Arduino Zero also comes with an Atmel Embedded Debugger (EDBG [10]). That provides a debug interface to the SAMD21 chip and is supported by OpenOCD for bootloader restore or direct programming and debugging. The Atmel EDGB is connected to the debug USB port for programming:

USB device idVendor=03eb, idProduct=2157, bcdDevice= 1.01
USB device strings: Mfr=1, Product=2, SerialNumber=3
Product: EDBG CMSIS-DAP
Manufacturer: Atmel Corp.
SerialNumber: E8VRDGVEYNKJTF8LS45K
Atmel Embedded Debugger (EDBG) Block Diagram

Arduino Zero, Atmel EDBG, and Atmel Studio 7

Atmel Embedded Debugger (EDBG) Chip

The Arduino Zero was designed in partnership with Atmel (now Microchip) which dedicated to this board a special USB PID with the major purpose to make the board recognizable and differentiate it form other evaluation boards in Atmel Studio. The EDBG chip is used on several Atmel evaluation boards and programmers, you can find the list here [9]. You should consider the Arduino Zero dedicated USB PID (0x2157) as another USB PID to add to that list. During the manufacturing process Arduino upgrade the EDBG firmware and customize the USB descriptor fields.

—https://github.com/arduino/ArduinoCore-samd/issues/286#issuecomment-354807646

Upgrading the firmware with a new one provided by Atmel Studio 7 using the atfw.exe tool will erase all the factory “Arduino Zero” USB configurations and will set the USB PID to 0x2111. But consider that you couldn’t revert the Arduino USB descriptor settings!

Flashing

  1. Build the Zephyr kernel and the Hello World sample application:

    west build -b arduino_zero//bbe -p -d build/arduino_zero zephyr/samples/hello_world
    
  2. Connect the Arduino Zero to your host computer using the native USB port (before the USB debug port) to rech the bootloader.

  3. Connect the Arduino Zero to your host computer using the USB debug port (after the native USB port) to reach the virtual console of EDBG.

  4. Run your favorite terminal program to listen for output. Under Linux the terminal should be /dev/ttyACM0. For example:

    minicom -D /dev/ttyACM0 -o
    

    The -o option tells minicom not to send the modem initialization string. Connection should be configured as follows:

    • Speed: 115200

    • Data: 8 bits

    • Parity: None

    • Stop bits: 1

  5. Pressing the RST button twice quickly to enter bootloader mode.

  6. Flash the image:

    west flash -d build/arduino_zero
    

    You should see “Hello World! arduino_zero/samd21g18a/bbe” in your terminal.

Debugging

Debugging is only possible over SWD with the help of EDBG!

  1. Do the for the debug session necessary steps as before except enter the bootloader mode and the flashing.

  2. Flash the image and attach a debugger to your board:

    west build -b arduino_zero//bbe -p -d build/arduino_zero zephyr/samples/hello_world -- -DBOARD_FLASH_RUNNER=openocd
    west debug -d build/arduino_zero
    

    You should ends up in a debug console (e.g. a GDB session).

More Samples

LED Blinky

west build -b arduino_zero//bbe -p -d build/arduino_zero zephyr/samples/basic/blinky
west flash -d build/arduino_zero

LED Fade

west build -b arduino_zero//bbe -p -d build/arduino_zero zephyr/samples/basic/fade_led
west flash -d build/arduino_zero

Basic Threads

west build -b arduino_zero//bbe -p -d build/arduino_zero zephyr/samples/basic/threads
west flash -d build/arduino_zero

Hello Shell with USB-CDC/ACM Console

west build -b arduino_zero//bbe -p -S "usb-console" -d build/arduino_zero bridle/samples/helloshell
west flash -d build/arduino_zero

Simple test execution on target

(text in bold is a command input)

uart:~$ hello -h
hello - say hello
uart:~$ hello
Hello from shell.
uart:~$ hwinfo devid
Length: 16
ID: 0xde73d01ae52511ed9cf503ee1d54a301

uart:~$ kernel version
Zephyr version 4.5.0

uart:~$ bridle version
Bridle version 4.4.99

uart:~$ bridle version long
Bridle version 4.4.99.0

uart:~$ bridle info
Zephyr: 4.5.0
Bridle: 4.4.99
uart:~$ device list
devices:
- eic@40001800 (READY)
  DT node labels: eic
- gpio@41004480 (READY)
  DT node labels: portb
- gpio@41004400 (READY)
  DT node labels: porta
- snippet_cdc_acm_console_uart (READY)
  DT node labels: snippet_cdc_acm_console_uart
- sercom@42001c00 (READY)
  DT node labels: sercom5
- sercom@42000800 (READY)
  DT node labels: sercom0 arduino_serial
- usb@41005000 (READY)
  DT node labels: usb0 zephyr_udc0
- adc@42004000 (READY)
  DT node labels: adc
- dac@42004800 (READY)
  DT node labels: dac0
- nvmctrl@41004000 (READY)
  DT node labels: nvmctrl
- sercom@42001400 (READY)
  DT node labels: sercom3 arduino_i2c
- tcc@42002800 (READY)
  DT node labels: tcc2
- leds (READY)
uart:~$ history
[  0] history
[  1] device list
[  2] bridle info
[  3] bridle version long
[  4] bridle version
[  5] kernel version
[  6] hwinfo devid
[  7] hello
[  8] hello -h

References