This is an automated email from the ASF dual-hosted git repository.
xiaoxiang781216 pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/nuttx.git
The following commit(s) were added to refs/heads/master by this push:
new 3e7d3100e1c docs/arduino-m0: Migrate README.txt to RST
3e7d3100e1c is described below
commit 3e7d3100e1c1715aa821e49f75789677b291abb7
Author: Swatantra Yadav <[email protected]>
AuthorDate: Mon Oct 12 01:38:41 2026 +0530
docs/arduino-m0: Migrate README.txt to RST
Migrate the legacy monospaced README.txt for the Arduino M0 board
(ATSAMD21G18A MCU) to standard Sphinx rST documentation format in
index.rst and remove the legacy README.txt include stub.
Details included in this guide:
- Hardware specifications and Cortex-M0+ @ 48 MHz architecture
- Board variants: Arduino M0, M0 Pro, Arduino Zero, and compatible clones
(Wemos SAMD21 M0, RobotDyn SAMD21 M0)
- Operating voltage warnings (3.3V logic)
- LED status indicators table (PA17) for CONFIG_ARCH_LEDS
- Serial console pinout and connection guide (SERCOM5 TX on PB22 / RX on
PB23)
- Native USB CDC/ACM NSH console
- Supported configurations (nsh, usbnsh) and build commands
- SWD flashing and debugging via OpenOCD (CMSIS-DAP, ST-Link, J-Link, GDB)
- Clarification on bootloader offset limitations
Addresses #11077
Part of #15737
Signed-off-by: Swatantra Kumar Gupta <[email protected]>
---
.../arm/samd2l2/boards/arduino-m0/README.txt | 149 -------------
.../arm/samd2l2/boards/arduino-m0/index.rst | 234 ++++++++++++++++++++-
2 files changed, 232 insertions(+), 151 deletions(-)
diff --git a/Documentation/platforms/arm/samd2l2/boards/arduino-m0/README.txt
b/Documentation/platforms/arm/samd2l2/boards/arduino-m0/README.txt
deleted file mode 100644
index 334e536ce7e..00000000000
--- a/Documentation/platforms/arm/samd2l2/boards/arduino-m0/README.txt
+++ /dev/null
@@ -1,149 +0,0 @@
-README
-======
-
-This README discusses issues unique to NuttX configurations for the
-Arduino M0. I used a compatible board called Wemos SAMD21 M0 board,
-but there are other equivalent boards, like the RobotDyn SAMD21 M0.
-
-Unfortunately because the Arduino.cc vs Arduino.org conflict in the past,
-we have three types of boards: Arduino Zero, Arduino M0 and Arduino M0 Pro.
-
-The Wemos SAMD21 M0 is compatible with Arduino M0, but not exactly a clone.
-
-You have two options to program it: using the SWD (EDBG) connector that
-comes in the board or the Arduino M0 bootloader that comes flashed on it.
-Currently only SWD programming is supported. Bootloader skip area should be
-implemented to avoid overwriting the bootloader area.
-
-The board uses the ATSAMD21G18A MCU and can work over the Native USB Port.
-
-Contents
-========
-
- - STATUS/ISSUES
- - LEDs
- - Serial Consoles
- - Configurations
-
-STATUS/ISSUES
-=============
-
- Because the Arduino M0 doesn't have a 12MHz crystal, it uses the internal
- RC oscillator.
-
-LEDs
-====
-
- There is one yellow LED available on the Arduino M0 and it can be turned
- on and off. The LED can be activated by driving the connected
- PA17 I/O line to high level.
-
- When CONFIG_ARCH_LEDS is defined in the NuttX configuration, NuttX will
- control the LED as follows:
-
- SYMBOL Meaning LED0
- ------------------- ----------------------- ------
- LED_STARTED NuttX has been started OFF
- LED_HEAPALLOCATE Heap has been allocated OFF
- LED_IRQSENABLED Interrupts enabled OFF
- LED_STACKCREATED Idle stack created ON
- LED_INIRQ In an interrupt N/C
- LED_SIGNAL In a signal handler N/C
- LED_ASSERTION An assertion failed N/C
- LED_PANIC The system has crashed FLASH
-
- Thus is LED is statically on, NuttX has successfully booted and is,
- apparently, running normally. If LED is flashing at approximately
- 2Hz, then a fatal error has been detected and the system has halted.
-
-Serial Consoles
-===============
-
- SERCOM5
- ------
-
- SERCOM5 is available on pins PB22 (TXD) and PB23 (RXD). You will need to
- solder a two pins header to RXD and TXD labels, near to ICSP pin header.
-
- PIN GPIO Function
- ---- ---- ------------------
- 37 PB22 SERCOM5 / USART RX
- 38 PB23 SERCOM5 / USART TX
-
- If you have a 3.3V USB/Serial adapter then this is the most convenient
- serial console to use (because you don't lose the console device each time
- you lose the USB connection). It is the default in all of these
- configurations. An option is to use the virtual COM port.
-
- Native USB Port
- ---------------
-
- You can access the NSH shell directly using the USB connector. All you need
- to do is use the "usbnsh" board profile.
-
-Configurations
-==============
-
- Each Arduino M0 configuration is maintained in a sub-directory and
- can be selected as follow:
-
- tools/configure.sh arduino-m0:<subdir>
-
- Before building, make sure the PATH environment variable include the
- correct path to the directory than holds your toolchain binaries.
-
- And then build NuttX by simply typing the following. At the conclusion of
- the make, the nuttx binary will reside in an ELF file called, simply, nuttx.
-
- make
-
- The <subdir> that is provided above as an argument to the tools/configure.sh
- must be is one of the following.
-
- NOTE: These configurations use the mconf-based configuration tool. To
- change any of these configurations using that tool, you should:
-
- a. Build and install the kconfig-mconf tool. See nuttx/README.txt
- see additional README.txt files in the NuttX tools repository.
-
- b. Execute 'make menuconfig' in nuttx/ in order to start the
- reconfiguration process.
-
- NOTES:
-
- 1. These configurations use the mconf-based configuration tool. To
- change any of these configurations using that tool, you should:
-
- a. Build and install the kconfig-mconf tool. See nuttx/README.txt
- see additional README.txt files in the NuttX tools repository.
-
- b. Execute 'make menuconfig' in nuttx/ in order to start the
- reconfiguration process.
-
-Configuration sub-directories
------------------------------
-
- nsh:
- This configuration directory will built the NuttShell. See NOTES above
- and below:
-
- NOTES:
-
- 1. This configuration is set up to build on Windows using the Cygwin
- environment using the ARM EABI toolchain. This can be easily
- changed as described above under "Configurations."
-
- 2. By default, this configuration provides a serial console on SERCOM5
- at 115200 8N1 via RXD/TXD pads:
-
- PIN EXT3 GPIO Function
- ---- ---- ------------------
- 37 PB22 SERCOM5 / USART RX
- 38 PB23 SERCOM5 / USART TX
-
- usbnsh:
- This configuration directory will build the NuttShell to work over USB.
- It uses the internal SAMD21 USB port working as CDC/ACM Serial/Modem.
-
- Using the configuration you don't need to solder the header pins RXD/TXD
- to get access the NSH terminal.
diff --git a/Documentation/platforms/arm/samd2l2/boards/arduino-m0/index.rst
b/Documentation/platforms/arm/samd2l2/boards/arduino-m0/index.rst
index 0650126b5be..6f606eba43d 100644
--- a/Documentation/platforms/arm/samd2l2/boards/arduino-m0/index.rst
+++ b/Documentation/platforms/arm/samd2l2/boards/arduino-m0/index.rst
@@ -4,6 +4,236 @@ arduino-m0
.. tags:: arch:arm, chip:samd2l2, vendor:microchip
-.. include:: README.txt
- :literal:
+The Arduino M0 is a development board featuring the Microchip (formerly Atmel)
+ATSAMD21G18A ARM Cortex-M0+ microcontroller. It is designed in the classic
Arduino
+Uno form factor, operating with 3.3V logic.
+This documentation applies to the **Arduino M0**, as well as closely related
+boards and compatible third-party variants:
+
+- **Arduino M0**: Features the ATSAMD21G18A MCU with native micro-USB connector
+ and a 6-pin SWD header (no onboard EDBG debugger chip).
+- **Arduino M0 Pro / Arduino Zero**: Includes an onboard Atmel Embedded
Debugger
+ (EDBG) chip providing a hardware programming/debugging port and virtual COM
port,
+ alongside the native USB port.
+- **Wemos SAMD21 M0 / RobotDyn SAMD21 M0**: Cost-effective compatible boards
+ utilizing the ATSAMD21G18A in the Arduino form factor.
+
+.. warning::
+ All I/O pins on the Arduino M0 operate at **3.3V**. Unlike 8-bit AVR Arduino
+ boards (such as Uno or Mega) which run at 5V, applying more than 3.3V to any
+ I/O pin will damage the microcontroller.
+
+Features
+========
+
+- **Microcontroller**: Microchip ATSAMD21G18A
+ - 32-bit ARM Cortex-M0+ running at up to 48 MHz
+ - 256 KB In-System Self-Programmable Flash memory
+ - 32 KB SRAM
+ - Hardware single-cycle (32x32) multiplier
+- **Clock Architecture**:
+ - Internal 8 MHz RC oscillator (OSC8M) driving GCLK1
+ - Digital Frequency Locked Loop (DFLL48M) generating the 48 MHz main system
clock (GCLK0)
+ - 32.768 kHz RTC oscillator footprint
+- **Operating Voltage**: 3.3V
+- **Digital I/O Pins**: 14 (with 12 PWM channels and UART)
+- **Analog Input Pins**: 6 (12-bit ADC channels)
+- **Analog Output**: 1 (10-bit DAC)
+- **USB**: Full-Speed (12 Mbps) USB 2.0 Device/Host port (Native USB)
+- **Interfaces**:
+ - Up to 6 SERCOM modules configurable as UART/USART, SPI, or I2C
+ - Real-Time Counter (RTC) and calendar
+
+LEDs
+====
+
+The Arduino M0 provides one user-controllable yellow LED (labeled ``L`` or
``STATUS``)
+connected to port pin **PA17**. Driving PA17 high illuminates the LED.
+
+When ``CONFIG_ARCH_LEDS`` is enabled in NuttX, the system controls
+the LED to indicate operational states:
+
+================== ======================= ======
+Symbol Meaning LED
+================== ======================= ======
+LED_STARTED NuttX has been started OFF
+LED_HEAPALLOCATE Heap has been allocated OFF
+LED_IRQSENABLED Interrupts enabled OFF
+LED_STACKCREATED Idle stack created ON
+LED_INIRQ In an interrupt N/C
+LED_SIGNAL In a signal handler N/C
+LED_ASSERTION An assertion failed N/C
+LED_PANIC The system has crashed FLASH
+================== ======================= ======
+
+When NuttX boots successfully, the LED stays statically **ON** (indicating
normal
+system execution). If the LED blinks rapidly at approximately 2 Hz, a fatal
error or
+panic has occurred.
+
+If ``CONFIG_ARCH_LEDS`` is disabled, the LED is accessible to user
+applications via the standard user LED driver (``/dev/userleds``).
+
+Serial Consoles
+===============
+
+SERCOM5 UART
+------------
+
+By default, the ``nsh`` configuration routes the serial console to **SERCOM5**
+at 115200 baud, 8 data bits, no parity, and 1 stop bit (8N1).
+
+SERCOM5 USART signals are exposed on two solder pads labeled **RXD** and
**TXD**
+near the ICSP pin header:
+
+==== ==== ==================
+Pin GPIO Function
+==== ==== ==================
+37 PB22 SERCOM5 / USART TX
+38 PB23 SERCOM5 / USART RX
+==== ==== ==================
+
+To use this console:
+
+1. Solder a 2-pin male header to the RXD and TXD pads.
+2. Connect a 3.3V USB-to-UART TTL adapter:
+ - Adapter **TX** -> Board **RXD** (PB23)
+ - Adapter **RX** -> Board **TXD** (PB22)
+ - Adapter **GND** -> Board **GND**
+
+.. note::
+ Using an external USB-to-UART adapter on SERCOM5 allows monitoring the
system
+ console without resetting the terminal session when the board or native USB
+ port resets.
+
+Native USB Port
+---------------
+
+The ATSAMD21 features an integrated Full-Speed USB controller. The ``usbnsh``
+configuration enables the USB CDC/ACM serial device class, mapping the
NuttShell
+(NSH) console directly to the native micro-USB connector.
+
+Using the ``usbnsh`` profile eliminates the need to solder external wires or
use a
+USB-to-serial converter. When connected to a host computer, the board appears
as:
+
+- **Linux**: ``/dev/ttyACM0``
+- **macOS**: ``/dev/cu.usbmodem*``
+- **Windows**: Virtual COM port (e.g., ``COM3``)
+
+Configurations
+==============
+
+The following board configurations are supported:
+
+nsh
+---
+
+Basic NuttShell (NSH) interactive shell over the SERCOM5 UART serial console
+(115200 8N1).
+
+usbnsh
+------
+
+NuttShell (NSH) console accessible directly over the native micro-USB port
+using USB CDC/ACM serial class emulation.
+
+Building NuttX
+==============
+
+To configure and build NuttX for the Arduino M0:
+
+1. Configure the build for your selected profile:
+
+ .. code-block:: console
+
+ $ ./tools/configure.sh arduino-m0:nsh
+
+ Or for the USB NSH console:
+
+ .. code-block:: console
+
+ $ ./tools/configure.sh arduino-m0:usbnsh
+
+2. (Optional) Customize settings using menuconfig:
+
+ .. code-block:: console
+
+ $ make menuconfig
+
+3. Build the NuttX binary:
+
+ .. code-block:: console
+
+ $ make
+
+Upon completion, the build produces:
+
+- ``nuttx``: ELF binary with debug symbols.
+- ``nuttx.bin``: Raw binary image for flashing.
+
+Flashing and Debugging
+======================
+
+SWD Programming with OpenOCD
+----------------------------
+
+Currently, only **SWD programming** is supported because the default board
+linker script (``scripts/flash.ld``) links NuttX starting at flash origin
+``0x00000000``. Flashing via SWD overwrites the flash starting from address
+zero, which replaces any pre-installed Arduino SAM-BA bootloader.
+
+.. note::
+ Flashing via USB bootloader utilities (such as BOSSA at offset ``0x2000``)
+ is not currently supported because the default binary is linked for origin
+ ``0x00000000``. Booting from an offset bootloader requires adjusting the
flash
+ origin and vector table offset in a custom linker script.
+
+The Arduino M0 exposes SWD pins on the 6-pin SWD connector or solder pads.
+Connect your SWD programmer (**SWCLK**, **SWDIO**, **RESET**, **GND**,
**3.3V**)
+and flash the ``nuttx.bin`` binary using OpenOCD:
+
+CMSIS-DAP / Atmel-ICE
+~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: console
+
+ $ openocd -f interface/cmsis-dap.cfg -f target/at91samdXX.cfg \
+ -c "program nuttx.bin 0x00000000 verify reset exit"
+
+ST-Link (ST-LINK/V2)
+~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: console
+
+ $ openocd -f interface/stlink.cfg -f target/at91samdXX.cfg \
+ -c "program nuttx.bin 0x00000000 verify reset exit"
+
+Segger J-Link
+~~~~~~~~~~~~~
+
+.. code-block:: console
+
+ $ openocd -f interface/jlink.cfg -c "transport select swd" \
+ -f target/at91samdXX.cfg \
+ -c "program nuttx.bin 0x00000000 verify reset exit"
+
+Debugging with GDB
+------------------
+
+To debug NuttX on target hardware:
+
+1. Start OpenOCD as a GDB server:
+
+ .. code-block:: console
+
+ $ openocd -f interface/cmsis-dap.cfg -f target/at91samdXX.cfg
+
+2. Connect GDB to the target:
+
+ .. code-block:: console
+
+ $ arm-none-eabi-gdb nuttx
+ (gdb) target extended-remote :3333
+ (gdb) monitor reset halt
+ (gdb) load
+ (gdb) continue
