mirror of
https://github.com/zephyrproject-rtos/zephyr
synced 2025-09-14 14:41:57 +00:00
93c23d810b
Unify documentation formatting and use zephyr-app-commands where applicable. Signed-off-by: Marti Bolivar <marti@opensourcefoundries.com>
481 lines
17 KiB
ReStructuredText
481 lines
17 KiB
ReStructuredText
.. _arduino_101:
|
|
|
|
Arduino/Genuino 101
|
|
###################
|
|
|
|
Overview
|
|
********
|
|
|
|
The Arduino/Genuino 101 is a learning and development board which contains an
|
|
Intel |reg| Curie |trade| Module. This board is designed to integrate the core's low
|
|
power-consumption and high performance with the Arduino's ease-of-use. The
|
|
Arduino 101 adds Bluetooth Low Energy capabilities and has an on-board 6-axis
|
|
accelerometer/gyroscope, providing exciting opportunities for building creative
|
|
projects in the connected world.
|
|
|
|
.. figure:: img/arduino_101.jpg
|
|
:width: 442px
|
|
:align: center
|
|
:alt: Arduino/Genuino 101
|
|
|
|
Arduino/Genuino 101 (Credit: Intel)
|
|
|
|
The Intel Quark* SE SoC in the Curie module contains a single core 32 MHz x86
|
|
(Intel Quark* processor) and the 32 MHz Argonaut RISC Core (ARC)* EM processor.
|
|
The two processors operate simultaneously and share memory. The ARC processor is
|
|
also referenced as the digital signal processor (DSP) sensor hub or a sensor
|
|
subsystem depending on what document you're looking at. In theory, the DSP can
|
|
run using a minimal amount of power, gathering and processing sensor data while
|
|
the x86 processor waits in a low power mode, which would be ideal for always-on
|
|
applications.
|
|
|
|
Zephyr can be flashed to an Arduino 101 for experimentation and testing
|
|
purposes; keep in mind that running the Zephyr OS on the Arduino 101 is not
|
|
supported by Arduino LLC.
|
|
|
|
Hardware
|
|
********
|
|
|
|
Board Layout
|
|
============
|
|
|
|
General information for the board can be found at the
|
|
`Arduino 101 website <https://www.arduino.cc/en/Main/ArduinoBoard101>`_,
|
|
which also includes schematics and BRD files
|
|
for the board.
|
|
|
|
Arduino 101 Pinout
|
|
==================
|
|
|
|
When using the Zephyr kernel, the pinout mapping for the Arduino 101 becomes a
|
|
little more complicated. The table below details which pins in Zephyr map to
|
|
those on the Arduino 101 board for control. Full details of the pinmux
|
|
implementation, what valid options can be configured, and where things map can
|
|
be found in the :file:`boards/x86/arduino_101/pinmux.c` file.
|
|
|
|
|
|
+-------------+----------+------------+
|
|
| Arduino Pin | Function | Zephyr Pin |
|
|
+=============+==========+============+
|
|
| IO-0 | UART1-RX | 17 |
|
|
+-------------+----------+------------+
|
|
| IO-1 | UART1-TX | 16 |
|
|
+-------------+----------+------------+
|
|
| IO-2 | GPIO | 52 |
|
|
+-------------+----------+------------+
|
|
| IO-3 | GPIO | 51 |
|
|
| | | 63 |
|
|
+-------------+----------+------------+
|
|
| IO-4 | GPIO | 53 |
|
|
+-------------+----------+------------+
|
|
| IO-5 | GPIO | 49 |
|
|
| | | 64 |
|
|
+-------------+----------+------------+
|
|
| IO-6 | PWM2 | 65 |
|
|
+-------------+----------+------------+
|
|
| IO-7 | GPIO | 54 |
|
|
+-------------+----------+------------+
|
|
| IO-8 | GPIO | 50 |
|
|
+-------------+----------+------------+
|
|
| IO-9 | PWM3 | 66 |
|
|
+-------------+----------+------------+
|
|
| IO-10 | AIN0 | 0 |
|
|
+-------------+----------+------------+
|
|
| IO-11 | AIN3 | 3 |
|
|
+-------------+----------+------------+
|
|
| IO-12 | AIN1 | 1 |
|
|
+-------------+----------+------------+
|
|
| IO-13 | AIN2 | 2 |
|
|
+-------------+----------+------------+
|
|
| ADC0 | GPIO SS | 10 |
|
|
+-------------+----------+------------+
|
|
| ADC1 | GPIO SS | 11 |
|
|
+-------------+----------+------------+
|
|
| ADC2 | GPIO SS | 12 |
|
|
+-------------+----------+------------+
|
|
| ADC3 | GPIO SS | 13 |
|
|
+-------------+----------+------------+
|
|
| ADC4 | AIN14 | 14 |
|
|
+-------------+----------+------------+
|
|
| ADC5 | AIN9 | 9 |
|
|
+-------------+----------+------------+
|
|
|
|
.. note::
|
|
|
|
IO-3 and IO-5 require both pins to be set for functionality changes.
|
|
|
|
Supported Features
|
|
==================
|
|
|
|
The Zephyr kernel supports multiple hardware features on the Arduino 101 through
|
|
the use of drivers. Some drivers are functional on the x86 side only, some on
|
|
the ARC side only, and a few are functional on both sides. The table below shows
|
|
which drivers and functionality can be found on which architectures:
|
|
|
|
+-----------+------------+-----+-----+-----------------------+
|
|
| Interface | Controller | ARC | x86 | Driver/Component |
|
|
+===========+============+=====+=====+=======================+
|
|
| APIC | on-chip | N | Y | interrupt_controller |
|
|
+-----------+------------+-----+-----+-----------------------+
|
|
| UART | on-chip | N | Y | serial port-polling; |
|
|
| | | | | serial port-interrupt |
|
|
+-----------+------------+-----+-----+-----------------------+
|
|
| SPI | on-chip | Y | Y | spi |
|
|
+-----------+------------+-----+-----+-----------------------+
|
|
| ADC | on-chip | Y | N | adc |
|
|
+-----------+------------+-----+-----+-----------------------+
|
|
| I2C | on-chip | Y | Y | i2c |
|
|
+-----------+------------+-----+-----+-----------------------+
|
|
| GPIO | on-chip | Y | Y | gpio |
|
|
+-----------+------------+-----+-----+-----------------------+
|
|
| PWM | on-chip | Y | Y | pwm |
|
|
+-----------+------------+-----+-----+-----------------------+
|
|
| mailbox | on-chip | Y | Y | ipm |
|
|
+-----------+------------+-----+-----+-----------------------+
|
|
|
|
Required Hardware and Software
|
|
==============================
|
|
|
|
Before flashing the Zephyr kernel onto an Arduino 101, a few additional pieces
|
|
of hardware are required.
|
|
|
|
* The USB port for power will work; however, we recommend the 7V-12V barrel
|
|
connector be used when working with the JTAG connector.
|
|
* If you wish to grab any data off the serial port, you will need a TTL-to-USB
|
|
adapter. The following adapters require male-to-male jumper cables in order to
|
|
connect to the Arduino 101 board.
|
|
|
|
* USB to 3.3V TTL Serial Cable
|
|
* FTDI USB to TTL Serial Part #TTL-232R-3V3 http://www.ftdichip.com/Products/Cables/USBTTLSerial.htm
|
|
|
|
We recommend using the ``dfu-util`` tool to flash the Arduino 101 board.
|
|
For Linux environments, verify that ``udev`` has the proper rules for granting
|
|
you access to the Arduino 101 board in DFU mode. You can easily add the required
|
|
rules, using the ``create_dfu_udev_rule`` script provided with the
|
|
`Intel Curie Boards package`_ for the Arduino Desktop IDE. You can get and run
|
|
this script standalone with the following commands:
|
|
|
|
.. code-block:: console
|
|
|
|
$ wget https://github.com/01org/intel-arduino-tools/raw/linux64/scripts/create_dfu_udev_rule
|
|
$ chmod +x create_dfu_udev_rule
|
|
$ sudo ./create_dfu_udev_rule
|
|
$ rm create_dfu_udev_rule
|
|
|
|
If you'd like to flash using JTAG, the following additional hardware is needed:
|
|
|
|
* Flyswatter2 JTAG debugger
|
|
* ARM Micro JTAG Connector, Model: ARM-JTAG-20-10
|
|
|
|
Connecting Serial Output
|
|
========================
|
|
|
|
The default configuration defined in the Zephyr kernel supports serial output
|
|
via the UART1 on the board. To read the output, you will need a USB to 3.3V TTL
|
|
serial cable. To enable serial output:
|
|
|
|
* Connect the Serial Cable RX pin to the Arduino 101's TX->1 pin.
|
|
* Connect the Serial Cable TX pin to the Arduino 101's RX<-0 pin.
|
|
* Connect the Serial Cable GND pin to the Arduino 101's GND pin.
|
|
|
|
Once connected, on your development environment, you will need to:
|
|
|
|
* Open a serial port emulator (i.e. on Linux minicom, screen, etc)
|
|
* Attach to the USB to TTL Serial cable, for example, on Linux this may be
|
|
/dev/ttyUSB0
|
|
* Set the communication details to:
|
|
|
|
* Speed: 115200
|
|
* Data: 8 bits
|
|
* Parity: None
|
|
* Stopbits: 1
|
|
|
|
Programming and Debugging
|
|
*************************
|
|
|
|
The Arduino 101 is powered by a Quark CPU and a sensor subsystem powered by an
|
|
ARC processor. When building applications, depending on the usage, two Zephyr
|
|
images need to be built and flashed.
|
|
|
|
The Arduino 101 has a bootloader that supports flashing over USB using the DFU
|
|
protocol. Additionally, the factory installed bootloader supports flashing of
|
|
the firmware for the Bluetooth device of the Curie module.
|
|
|
|
Use the ``arduino_101`` board definition to build a kernel for the Quark core. Use
|
|
the ``arduino_101_sss`` board definition when targeting the sensor subsystem.
|
|
|
|
When your application is targeting the Quark processor only, it is important to
|
|
disable the sensor subsystem processor using the ``CONFIG_ARC_INIT=n`` option,
|
|
otherwise the board will appear to hang waiting for the sensor subsystem
|
|
processor to boot.
|
|
|
|
|
|
Bootloader (Boot ROM)
|
|
=====================
|
|
|
|
Support for the `QMSI Bootloader`_ has been removed starting from Zephyr 1.4.0.
|
|
Thus, the factory boot ROM can be kept supporting the flashing of the board over
|
|
DFU and flashing the Bluetooth firmware.
|
|
|
|
If you have previously installed a different boot ROM it is recommended to
|
|
restore the factory boot ROM image using the `Flashpack Utility`_. Consult
|
|
the README available in the `Flashpack Utility`_ package and follow the
|
|
instructions for your environment.
|
|
|
|
Flashing
|
|
========
|
|
|
|
The ``dfu-util`` flashing application will only recognize the Arduino 101 as a
|
|
DFU-capable device within five seconds after the Master Reset button is pressed
|
|
on the board. You can run this application with the help of the Zephyr build
|
|
system by defining the environment variable ``ZEPHYR_FLASH_OVER_DFU=y`` before
|
|
flashing Zephyr applications (as described in :ref:`application_run`).
|
|
|
|
If you regularly use this method, you can add the following line into your
|
|
``~/.zephyrrc`` file:
|
|
|
|
.. code-block:: console
|
|
|
|
export ZEPHYR_FLASH_OVER_DFU=y
|
|
|
|
Flashing the Sensor Subsystem Core
|
|
----------------------------------
|
|
When building for the ARC processor, the board type is listed as
|
|
``arduino_101_sss``.
|
|
|
|
The sample application :ref:`hello_world` is used for this tutorial. To build
|
|
and flash this application using ``dfu-util``, first set
|
|
``ZEPHYR_FLASH_OVER_DFU=y`` in the environment as described above, then run:
|
|
|
|
.. zephyr-app-commands::
|
|
:zephyr-app: samples/hello_world
|
|
:board: arduino_101_sss
|
|
:build-dir: arduino_101_sss
|
|
:goals: build flash
|
|
|
|
Flashing the x86 Application Core
|
|
---------------------------------
|
|
|
|
When building for the x86 processor, the board type is listed as
|
|
``arduino_101``. To build and flash the :ref:`hello_world` application to this
|
|
board using ``dfu-util``, first set ``ZEPHYR_FLASH_OVER_DFU=y`` in the
|
|
environment as described above, then run:
|
|
|
|
.. zephyr-app-commands::
|
|
:zephyr-app: samples/hello_world
|
|
:board: arduino_101
|
|
:build-dir: arduino_101
|
|
:goals: build flash
|
|
|
|
.. _bluetooth_firmware_arduino_101:
|
|
|
|
Flashing the Bluetooth Core
|
|
---------------------------
|
|
|
|
To be interoperable with the Zephyr Bluetooth stack the Bluetooth controller of
|
|
the Arduino 101 (Nordic Semiconductor nRF51) needs to be flashed with a
|
|
compatible firmware.
|
|
|
|
The Arduino 101 factory-installed firmware on this controller is not supported
|
|
by the Zephyr project, so you need to flash a new one onto it.
|
|
|
|
Luckily, starting with Zephyr 1.6, Zephyr itself is able to act as the firmware
|
|
for the controller. The application you need is ``samples/bluetooth/hci_uart`` and
|
|
the target board is called ``arduino_101_ble``.
|
|
|
|
To build the Bluetooth controller image and flash it using ``dfu-util``, first
|
|
set ``ZEPHYR_FLASH_OVER_DFU=y`` in the environment as described above, then
|
|
run:
|
|
|
|
.. zephyr-app-commands::
|
|
:zephyr-app: samples/bluetooth/hci_uart
|
|
:board: arduino_101_ble
|
|
:goals: build flash
|
|
|
|
After successfully completing these steps your Arduino 101 should now have a HCI
|
|
compatible BLE firmware.
|
|
|
|
|
|
Flashing using JTAG Adapter
|
|
---------------------------
|
|
|
|
We recommend using the ``dfu-util`` tool to flash the Arduino 101 board for typical
|
|
development work. JTAG is intended for advanced development and debugging.
|
|
|
|
* Connect the ARM Micro JTAG Connector to the Flyswatter2.
|
|
|
|
* Locate the micro JTAG header on the Arduino 101 board. It is adjacent to the
|
|
SCL and SDA pins in the Arduino headers, highlighted as the red square in the
|
|
figure below.
|
|
|
|
.. figure:: img/arduino_101_flat.jpg
|
|
:width: 442px
|
|
:align: center
|
|
:alt: Arduino/Genuino 101 JTAG
|
|
|
|
* Beside the micro JTAG header is a small white dot indicating the location of
|
|
pin 1 on the header. The green arrow on the figure points to the dot.
|
|
|
|
* Connect the ARM Micro JTAG Connector to the Arduino 101 micro JTAG header.
|
|
|
|
Ensure that both the cable and header pin 1 locations line up. The cable from
|
|
the ARM Micro JTAG Connector uses a red wire on the cable to denote which end on
|
|
the cable has the pin 1.
|
|
|
|
For Linux environments, to control the Flyswatter2 your Linux account needs to be
|
|
granted HAL layer interaction permissions. This is done through the group
|
|
'plugdev'. Verifying the group exists and adding your username can be
|
|
accomplished with the usermod command:
|
|
|
|
.. code-block:: console
|
|
|
|
$ sudo usermod -a -G plugdev $LOGNAME
|
|
|
|
If the group does not exist, you can add it by running the following command:
|
|
|
|
|
|
.. code-block:: console
|
|
|
|
$ sudo groupadd -r plugdev
|
|
|
|
For Linux environments, verify that ``udev`` has the proper rules for giving your
|
|
user control of the Flyswatter2 device. Adding the following rule to udev will
|
|
give members of the plugdev group control of the Flyswatter2.
|
|
|
|
.. code-block:: console
|
|
|
|
$ sudo su
|
|
$ cat <<EOF > /etc/udev/rules.d/99-openocd.rules
|
|
# TinCanTools Flyswatter2
|
|
ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6010", MODE="664", GROUP="plugdev"
|
|
EOF
|
|
$ exit
|
|
|
|
Once your udev rules are setup, you will need to reload the rules:
|
|
|
|
.. code-block:: console
|
|
|
|
$ sudo udevadm control --reload-rules
|
|
|
|
Plug the USB Type B cable into the Flyswatter2 and your computer. On Linux, you
|
|
should see something similar to the following in your dmesg:
|
|
|
|
.. code-block:: console
|
|
|
|
usb 1-2.1.1: new high-speed USB device number 13 using xhci_hcd
|
|
usb 1-2.1.1: New USB device found, idVendor=0403, idProduct=6010
|
|
usb 1-2.1.1: New USB device strings: Mfr=1, Product=2, SerialNumber=3
|
|
usb 1-2.1.1: Product: Flyswatter2
|
|
usb 1-2.1.1: Manufacturer: TinCanTools
|
|
usb 1-2.1.1: SerialNumber: FS20000
|
|
ftdi_sio 1-2.1.1:1.0: FTDI USB Serial Device converter detected
|
|
usb 1-2.1.1: Detected FT2232H
|
|
usb 1-2.1.1: FTDI USB Serial Device converter now attached to ttyUSB0
|
|
ftdi_sio 1-2.1.1:1.1: FTDI USB Serial Device converter detected
|
|
usb 1-2.1.1: Detected FT2232H
|
|
usb 1-2.1.1: FTDI USB Serial Device converter now attached to ttyUSB1
|
|
|
|
|
|
Debugging
|
|
=========
|
|
|
|
The instructions below will help you debug the Arduino 101 on the x86 core or
|
|
the ARC core, respectively.
|
|
|
|
Application Core (x86)
|
|
----------------------
|
|
|
|
Build and flash an x86 application, then launch a debugging server with the
|
|
following commands:
|
|
|
|
.. zephyr-app-commands::
|
|
:app: <my x86 app>
|
|
:board: arduino_101
|
|
:goals: build flash debugserver
|
|
|
|
Connect to the debug server at the x86 core from a second console:
|
|
|
|
.. code-block:: console
|
|
|
|
$ cd <my x86 app>
|
|
$ $ZEPHYR_SDK_INSTALL_DIR/sysroots/x86_64-pokysdk-linux/usr/bin/i586-zephyr-elfiamcu/i586-zephyr-elfiamcu-gdb build/zephyr/zephyr.elf
|
|
(gdb) target remote localhost:3333
|
|
(gdb) b main
|
|
(gdb) c
|
|
|
|
Sensor Subsystem Core (ARC)
|
|
---------------------------
|
|
|
|
Enable ARC INIT from the x86 core. This can be done by flashing an x86
|
|
application that sets the ``CONFIG_ARC_INIT=y`` option, such as the booting stub
|
|
provided with the Zephyr Test Framework, like so:
|
|
|
|
.. zephyr-app-commands::
|
|
:zephyr-app: tests/booting/stub
|
|
:board: arduino_101
|
|
:goals: flash
|
|
|
|
Then build the ARC application, flash it, and launch a debug server with the
|
|
following commands:
|
|
|
|
.. zephyr-app-commands::
|
|
:app: <my arc app>
|
|
:board: arduino_101_sss
|
|
:goals: flash debugserver
|
|
|
|
Connect to the debug server at the ARC core from a second console:
|
|
|
|
.. code-block:: console
|
|
|
|
$ cd <my arc app>
|
|
$ $ZEPHYR_SDK_INSTALL_DIR/sysroots/x86_64-pokysdk-linux/usr/bin/arc-zephyr-elf/arc-zephyr-elf-gdb build/zephyr/zephyr.elf
|
|
(gdb) target remote localhost:3334
|
|
(gdb) b main
|
|
(gdb) c
|
|
|
|
|
|
Bluetooth Firmware
|
|
------------------
|
|
|
|
You will only see normal log messages on the console, by default, without any
|
|
way of accessing the HCI traffic between Zephyr and the nRF51 controller.
|
|
However, there is a special Bluetooth logging mode that converts the console to
|
|
use a binary protocol that interleaves both normal log messages as well as the
|
|
HCI traffic. Set the following Kconfig options to enable this protocol before
|
|
building your application:
|
|
|
|
.. code-block:: console
|
|
|
|
CONFIG_BT_DEBUG_MONITOR=y
|
|
CONFIG_UART_CONSOLE=n
|
|
CONFIG_UART_QMSI_1_BAUDRATE=1000000
|
|
|
|
The first item replaces the BT_DEBUG_LOG option, the second one
|
|
disables the default printk/printf hooks, and the third one matches the console
|
|
baudrate with what's used to communicate with the nRF51, in order not to create
|
|
a bottleneck.
|
|
|
|
To decode the binary protocol that will now be sent to the console UART you need
|
|
to use the btmon tool from BlueZ 5.40 or later:
|
|
|
|
|
|
.. code-block:: console
|
|
|
|
$ btmon --tty <console TTY> --tty-speed 1000000
|
|
|
|
Release Notes
|
|
*************
|
|
When debugging on ARC, it is important that the x86 core be started and running
|
|
BEFORE attempting to debug on ARC. This is because the IPM console calls will
|
|
hang waiting for the x86 core to clear the communication.
|
|
|
|
|
|
References
|
|
**********
|
|
|
|
.. _QMSI Bootloader: https://github.com/quark-mcu/qm-bootloader
|
|
|
|
.. _Flashpack Utility: https://downloadcenter.intel.com/downloads/eula/25470/Arduino-101-software-package?httpDown=https%3A%2F%2Fdownloadmirror.intel.com%2F25470%2Feng%2Farduino101-factory_recovery-flashpack.tar.bz2
|
|
|
|
.. _Intel Curie Boards package: https://www.arduino.cc/en/Guide/Arduino101#toc2
|