1.. _arduino_due:
2
3Arduino Due
4###########
5
6Overview
7********
8
9The arduino_due board configuration is used by Zephyr applications
10that run on the Arduino Due board. It provides support for the Atmel
11SAM3X8E ARM Cortex-M3 CPU and the following devices:
12
13* Nested Vectored Interrupt Controller (NVIC)
14
15* System Tick System Clock (SYSTICK)
16
17* Serial Port over USB (ATMEL_SAM3)
18
19More information about the board can be found at the `Arduino Due website`_.
20The `Atmel SAM3X8E Datasheet`_ has the information and the datasheet about
21the processor.
22
23.. note::
24   This configuration is not supported by Arduino.
25
26.. image:: img/arduino_due.jpg
27     :align: center
28     :alt: Arduino Due
29
30Hardware
31********
32Supported Features
33==================
34
35The arduino_due board configuration supports the following hardware features:
36
37+-----------+------------+----------------------+
38| Interface | Controller | Driver/Component     |
39+===========+============+======================+
40| NVIC      | on-chip    | nested vectored      |
41|           |            | interrupt controller |
42+-----------+------------+----------------------+
43| SYSTICK   | on-chip    | system clock         |
44+-----------+------------+----------------------+
45| UART      | on-chip    | serial port          |
46+-----------+------------+----------------------+
47| GPIO      | on-chip    | gpio                 |
48+-----------+------------+----------------------+
49| I2C       | on-chip    | i2c                  |
50+-----------+------------+----------------------+
51| Watchdog  | on-chip    | watchdog             |
52+-----------+------------+----------------------+
53
54Other hardware features are not currently supported by the Zephyr kernel.
55See `Arduino Due website`_ and `Atmel SAM3X8E Datasheet`_ for a complete
56list of Arduino Due board hardware features.
57
58The default configuration can be found in the Kconfig
59:zephyr_file:`boards/arduino/due/arduino_due_defconfig`.
60
61.. note::
62   For I2C, pull-up resistors are required for using SCL1 and SDA1 (near IO13).
63
64Interrupt Controller
65====================
66
67There are 15 fixed exceptions including exceptions 12 (debug monitor) and 15
68(SYSTICK) that behave more as interrupts than exceptions. In addition, there can
69be a variable number of IRQs. Exceptions 7-10 and 13 are reserved. They don't
70need handlers.
71
72A Cortex-M3/4-based board uses vectored exceptions. This means each exception
73calls a handler directly from the vector table.
74
75Handlers are provided for exceptions 1-6, 11-12, and 14-15.  The table here
76identifies the handlers used for each exception.
77
78+------+------------+----------------+-----------------------+
79| Exc# | Name       | Remarks        | Used by Zephyr Kernel |
80+======+============+================+=======================+
81| 1    | Reset      |                | system initialization |
82+------+------------+----------------+-----------------------+
83| 2    | NMI        |                | system fatal error    |
84+------+------------+----------------+-----------------------+
85| 3    | Hard fault |                | system fatal error    |
86+------+------------+----------------+-----------------------+
87| 4    | MemManage  | MPU fault      | system fatal error    |
88+------+------------+----------------+-----------------------+
89| 5    | Bus        |                | system fatal error    |
90+------+------------+----------------+-----------------------+
91| 6    | Usage      | undefined      | system fatal error    |
92|      | fault      | instruction,   |                       |
93|      |            | or switch      |                       |
94|      |            | attempt to ARM |                       |
95|      |            | mode           |                       |
96+------+------------+----------------+-----------------------+
97| 11   | SVC        |                | system calls, kernel  |
98|      |            |                | run-time exceptions,  |
99|      |            |                | and IRQ offloading    |
100+------+------------+----------------+-----------------------+
101| 12   | Debug      |                | system fatal error    |
102|      | monitor    |                |                       |
103+------+------------+----------------+-----------------------+
104| 14   | PendSV     |                | context switch        |
105+------+------------+----------------+-----------------------+
106| 15   | SYSTICK    |                | system clock          |
107+------+------------+----------------+-----------------------+
108
109.. note::
110   After a reset, all exceptions have a priority of 0. Interrupts cannot run
111   at priority 0 for the interrupt locking mechanism and exception handling
112   to function properly.
113
114System Clock
115============
116
117Arduino Due has two external oscillators/resonators. The slow clock is
11832.768 kHz, and the main clock is 12 MHz. The processor can set up PLL to drive
119the master clock, which can be set as high as 84 MHz.
120
121Serial Port
122===========
123
124The Atmel SAM3X8E processor has a single UART that is used by the SAM-BA
125bootloader. This UART has only two wires for RX/TX and does not have flow
126control (CTS/RTS) or FIFO. The RX/TX pins are connected to the ATmega16U2,
127which provides USB-to-TTL serial function. The Zephyr console output, by
128default, is utilizing this controller.
129
130
131Programming and Debugging
132*************************
133
134Flashing
135========
136
137BOSSA Tool
138----------
139
140Flashing the Zephyr kernel onto Arduino Due requires the `bossa tool`_.
141
142There are GUI and command line versions of the bossa tool. The following
143section provides the steps to build the command line version. Please
144refer to the bossa tool's README file on how to build the GUI version.
145
146To build the bossa tool, follow these steps:
147
148#. Checkout the bossa tool's code from the repository.
149
150   .. code-block:: console
151
152     $ git clone https://github.com/shumatech/BOSSA.git
153     $ cd BOSSA
154
155#. Checkout the arduino branch. The code on the master branch does not
156   work with Arduino Due.
157
158   .. code-block:: console
159
160     $ git checkout arduino
161
162#. Build the command line version of the bossa tool.
163
164   .. code-block:: console
165
166     $ make bin/bossac
167
168#. The resulting binary is available at :file:`bin/bossac`.
169
170
171Flashing an Application to Arduino Due
172--------------------------------------
173
174Applications for the ``arduino_due`` board configuration can be built
175and flashed in the usual way (see :ref:`build_an_application` and
176:ref:`application_run` for more details).
177
178Here is an example for the :zephyr:code-sample:`hello_world` application. After
179building the application, press the Reset button before running the
180flash command, so the board will boot into the SAM-BA bootloader and
181be prepared to receive the new program.
182
183.. zephyr-app-commands::
184   :zephyr-app: samples/hello_world
185   :board: arduino_due
186   :goals: build flash
187
188After flashing the application, run your favorite terminal program to
189listen for output. For example, under Linux, the terminal should be
190:code:`/dev/ttyACM0`. For example:
191
192.. code-block:: console
193
194   $ sudo minicom -D /dev/ttyACM0 -o
195
196The -o option tells minicom not to send the modem initialization
197string.
198
199Now press the Reset button and you should see "Hello World! arduino_due" in your terminal.
200
201.. note::
202   Make sure your terminal program is closed before flashing the binary image,
203   or it will interfere with the flashing process.
204
205References
206**********
207
208.. target-notes::
209
210.. _Arduino Due website: https://www.arduino.cc/en/Main/ArduinoBoardDue
211
212.. _Atmel SAM3X8E Datasheet: http://ww1.microchip.com/downloads/en/DeviceDoc/Atmel-11057-32-bit-Cortex-M3-Microcontroller-SAM3X-SAM3A_Datasheet.pdf
213
214.. _bossa tool: https://github.com/shumatech/BOSSA
215
216.. _bossa arduino branch: https://github.com/shumatech/BOSSA/tree/arduino
217