| .. _arduino_101: |
| |
| Arduino 101 |
| ########### |
| |
| Overview |
| ******** |
| |
| The Arduino 101 board is an Arduino product with an IntelĀ® Curieā¢ |
| module. Zephyr can be flashed to an Arduino 101 for experimentation |
| and testing purposes; keep in mind this is configuration is unsupported |
| by Arduino. |
| |
| The Intel Curie module contains both an ARC and an X86 core, so be sure to |
| flash an ARC and an X86 image if you wish to use both. Either |
| **arduino_101_factory** (for x86) or **arduino_101_sss_factory** (for ARC) |
| board configurations work to build a Zephyr Kernel that can be flashed to and |
| run on the Arduino 101 platform. The default configuration for Arduino 101 |
| boards can be found in |
| :file:`boards/arduino_101/arduino_101_factory_defconfig` for the X86 and |
| :file:`boards/arduino_101_sss/arduino_101_sss_factory_defconfig` for the ARC. |
| |
| This release removes the support for the alternate boot ROM. Thus, the original |
| boot ROM can be kept supporting the flashing of the board over DFU and flashing |
| the Bluetooth firmware. |
| |
| See the documentation for releases up to v1.3.0 for details on how to use an |
| alternate boot ROM. |
| |
| If you have previously installed a different boot ROM it is recommended to |
| restore the original boot ROM image as described in the |
| `Backup and Restore Factory Settings`_ section. |
| |
| Board Layout |
| ************ |
| |
| General information for the board can be found at the `Arduino website`_, |
| which also includes `schematics`_ and BRD files. |
| |
| 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. |
| |
| * :ref:`The Zephyr SDK <zephyr_sdk>` |
| |
| * If you wish to grab any data off the serial port, you will need a TTY-to-USB |
| adaptor. The following adapters require male-to-male jumper cables in order |
| to connect to the Arduino 101 board. |
| |
| #. `USB to TTL Serial Cable`_ |
| |
| #. FTDI USB to TTL Serial Part #TTL-232R-3V3 |
| http://www.ftdichip.com/Products/Cables/USBTTLSerial.htm |
| |
| To flash using the JTAG the following hardware is needed: |
| |
| * `FlySwatter2 JTAG debugger`_ |
| |
| * ARM Micro JTAG Connector, Model: `ARM-JTAG-20-10`_ |
| |
| |
| Connecting Serial Output |
| ************************ |
| |
| In the default configuration, Zephyr's Arduino 101 images support serial output |
| via the UART0 on the board. To read the output, you will need a USB to TTL |
| serial cable. To enable serial output: |
| |
| * Connect the Serial Cable RX pin to the Arduino 101's TX->1 pin. |
| |
| .. figure:: figures/arduino_101_03.png |
| :scale: 50 % |
| :alt: Image for pin positions and serial output |
| |
| * Connect the Serial Cable TX pin to the Arduino 101's RX<-0 pin. |
| |
| .. figure:: figures/arduino_101_04.png |
| :scale: 50 % |
| :alt: Image for pin positions and serial output |
| |
| * Connect the Serial Cable GND pin to the Arduino 101's GND pin. |
| |
| .. figure:: figures/arduino_101_05.png |
| :scale: 50 % |
| :alt: Image for pin positions and serial output |
| |
| 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 |
| :file:`/dev/ttyUSB0` |
| |
| * Set the communication details to: |
| |
| * Speed: 115200 |
| * Data: 8 bits |
| * Parity: None |
| * Stopbits: 1 |
| |
| |
| Building an Application |
| *********************** |
| |
| The Arduino 101 is powered by a Quark CPU and a sensor sub-system powered by an |
| ARC processor. When building applications, depending on the usage, two Zephyr |
| image need to be built and flashed. |
| |
| The Arduino 101 has a bootloader that supports flashing over USB using |
| the DFU protocol. Flashing over USB keeps the original bootloader intact and |
| does not require a JTAG adapter. Additionally, the factory installed bootloader |
| supports flashing of the firmware for the Bluetooth device of the Curie |
| module. |
| |
| Use the ``arduino_101_factory`` board definition to build a kernel for the Quark |
| core. Use the ``arduino_101_sss_facotry`` board definition when targeting the |
| sensor sub-system. |
| |
| To use an alternate boot ROM different board definitions are needed for both the |
| Quark and the sensor sub-system cores: For the Quark, use ``arduino_101`` |
| and for the sensor-subsystem, use ``arduino_101_sss``. |
| |
| When your application is targeting the Quark processor only, it is important to |
| disable the sensor sub-system processor. otherwise the board will appear to hang |
| waiting for the sensor sub-system processor to boot. |
| |
| See the `Debugging on Arduino 101`_ section for details on how to disable the |
| sensor sub-system. |
| |
| Flashing using USB DFU |
| ********************** |
| |
| |
| Flashing the Sensor Subsystem Core |
| ================================== |
| |
| #. Make sure the binary image has been built. Change directories to your local |
| checkout copy of Zephyr, and run: |
| |
| .. code-block:: console |
| |
| $ source ./zephyr-env.sh |
| $ cd $ZEPHYR_BASE/samples/hello_world/nanokernel |
| $ make pristine && make BOARD=arduino_101_sss_factory |
| |
| #. Verify the Arduino 101 has power. |
| |
| #. Once the image has been built, flash it with: |
| |
| .. code-block:: console |
| |
| $ dfu-util -a sensor_core -D outdir/zephyr.bin |
| |
| .. note:: |
| |
| When building for the ARC processor, the board type is listed as |
| arduino_101_sss_factory. |
| |
| |
| Congratulations, you have now flashed the hello_world image to the ARC |
| processor. |
| |
| Flashing the x86 Application Core |
| ================================= |
| |
| #. Make sure the binary image has been built. Change directories to your local |
| checkout copy of Zephyr, and run: |
| |
| .. code-block:: console |
| |
| $ source ./zephyr-env.sh |
| $ cd $ZEPHYR_BASE/samples/hello_world/nanokernel |
| $ make pristine |
| $ make BOARD=arduino_101_factory |
| |
| #. Verify the Arduino 101 has power. |
| |
| #. Once the image has been built, flash it with: |
| |
| .. code-block:: console |
| |
| $ dfu-util -a x86_app -D outdir/zephyr.bin |
| |
| .. note:: |
| |
| When building for the x86 processor, the board type is listed as |
| arduino_101_factory. |
| |
| Congratulations you have now flashed the hello_world image to the x86 |
| processor. |
| |
| 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 instructions for acquiring and |
| flashing the firmware are found :ref:`here <arduino_101_ble>` |
| |
| Flashing using JTAG Adapter |
| *************************** |
| |
| Use this method only for advanced development and debugging. |
| |
| #. Connect the ARM Micro JTAG Connector to the FlySwatter2. |
| |
| #. Locate the micro JTAG connector 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:: figures/arduino_101_01.png |
| :scale: 50 % |
| :alt: Highlight of the JTAG connector. |
| |
| #. Beside the micro JTAG header is a small white dot indicating the |
| location of pin 1 on the header. The orange arrow on the figure points to |
| the dot. |
| |
| .. figure:: figures/arduino_101_02.png |
| :scale: 50 % |
| :alt: Pointer to the pin 1 of the JTAG connector. |
| |
| #. Connect the FlySwatter2 to the Arduino 101 micro JTAG connector. |
| |
| #. 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 FlySwatter your user 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 useradd function: |
| |
| .. code-block:: console |
| |
| $ sudo useradd -G plugdev $USERNAME |
| |
| #. For Linux environments, verify that udev has the proper rules for giving |
| your user control of the FlySwatter device. Adding the following rule |
| to udev will give members of the plugdev group control of the FlySwatter. |
| |
| .. code-block:: console |
| |
| $ su - |
| # cat <<EOF > /etc/udev/rules.d/99-openocd.rules |
| # TinCanTools FlySwatter2 |
| ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6010", MODE="664", GROUP="plugdev" |
| EOF |
| |
| #. 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 |
| |
| |
| Backup and Restore Factory Settings |
| =================================== |
| |
| Before continuing, consider creating a backup image of the ROM device as |
| it stands today. This would be necessary if you wanted to run Arduino sketches |
| on the hardware again, as the Arduino IDE requires updating via a USB flashing |
| method that is not currently supported by Zephyr. |
| |
| Typically Arduino hardware can re-program the Bootloader by connecting |
| the ICSP header and issuing the "Burn Bootloader" option from the Arduino |
| IDE. On the Arduino 101, this option is not provided. |
| |
| #. Confirm the Zephyr SDK has been installed on your platform. |
| |
| #. Open a terminal window. |
| |
| #. Verify the JTAG debugger is properly attached to the Arduino 101 board and |
| to the host computer. |
| |
| #. Connect the Arduino 101 to a power source. |
| |
| #. Open a terminal window |
| |
| #. Change directories to :file:`$ZEPHYR_BASE`. |
| |
| #. Source the :file:`zephyr-env.sh` file. |
| |
| #. In the terminal window, enter: |
| |
| .. code-block:: console |
| |
| $ ./boards/arduino_101/support/arduino_101_backup.sh |
| |
| .. note:: |
| |
| This command tells the JTAG to dump two files in your :file:`$ZEPHYR_BASE`: |
| directory: :file:`A101_BOOT.bin` and :file:`A101_OS.bin`. These contain |
| copies of the original flash, which can be used to restore the state of the |
| board to factory conditions. |
| |
| Done! You have finished creating a backup for the Arduino 101. |
| |
| To restore the factory settings of the Arduino 101 device, use the provided script. |
| |
| #. In the terminal window, enter: |
| |
| .. code-block:: console |
| |
| $ ./boards/arduino_101/support/arduino_101_load.sh |
| |
| .. note:: |
| |
| This script expects two files in your :file:`$ZEPHYR_BASE` directory |
| named :file:`A101_OS.bin` and :file:`A101_BOOT.bin`. |
| |
| |
| Flashing the Sensor Subsystem Core |
| ================================== |
| |
| #. Make sure the binary image has been built. Change directories to your local |
| checkout copy of Zephyr, and run: |
| |
| .. code-block:: console |
| |
| $ source ./zephyr-env.sh |
| $ cd $ZEPHYR_BASE/samples/hello_world/nanokernel |
| $ make pristine |
| $ make BOARD=arduino_101_sss_factory |
| |
| |
| #. Verify the JTAG debugger is properly attached to the Arduino 101 board. |
| |
| #. Verify the Arduino 101 has power. |
| |
| #. Once the image has been built, flash it with: |
| |
| .. code-block:: console |
| |
| $ make BOARD=arduino_101_sss_factory flash |
| |
| .. note:: |
| |
| When building for the ARC processor, the board type is listed as |
| arduino_101_sss. |
| |
| |
| Congratulations, you have now flashed the hello_world image to the ARC |
| processor. |
| |
| Flashing the x86 Application Core |
| ================================= |
| |
| #. Make sure the binary image has been built. Change directories to your local |
| checkout copy of Zephyr, and run: |
| |
| .. code-block:: console |
| |
| $ source ./zephyr-env.sh |
| $ cd $ZEPHYR_BASE/samples/hello_world/nanokernel |
| $ make pristine |
| $ make BOARD=arduino_101_factory |
| |
| #. Verify the JTAG debugger is properly attached to the Arduino 101 board. |
| |
| #. Verify the Arduino 101 has power. |
| |
| #. Once the image has been built, flash it with: |
| |
| .. code-block:: console |
| |
| $ make BOARD=arduino_101_factory flash |
| |
| .. note:: |
| |
| When building for the x86 processor, the board type is listed as |
| arduino_101_factory. |
| |
| Congratulations you have now flashed the hello_world image to the x86 |
| processor. |
| |
| |
| |
| Debugging on Arduino 101 |
| ************************ |
| |
| The image file used for debugging must be built to the corresponding |
| core that you wish to debug. For example, the binary must be built |
| for BOARD=arduino_101_factory if you wish to debug on the quark core. |
| |
| #. Build the binary for your application on the architecture you wish to |
| debug. Alternatively, use the instructions above as template for testing. |
| |
| When debugging on ARC, you will need to enable the |
| :option:`CONFIG_ARC_GDB_ENABLE` configuration option in your local kernel |
| configuration file. Details of this flag can be found in |
| :file:`arch/x86/soc/quark_se/Kconfig`. Setting this variable will force the |
| ARC processor to halt on bootstrap, giving the debugger a chance at |
| connecting and controlling the hardware. |
| |
| This can be done by editing the file |
| :file:`samples/hello_world/nanokernel/prj.conf` to include: |
| |
| .. code-block:: console |
| |
| CONFIG_ARC_INIT=y |
| CONFIG_ARC_GDB_ENABLE=y |
| |
| .. note:: |
| |
| By enabling :option:`CONFIG_ARC_INIT`, you *MUST* flash both an ARC and |
| an X86 image to the hardware. If you do not, the X86 image will appear to |
| hang at boot while it is waiting for the ARC to finish initialization. |
| |
| #. Open two terminal windows. |
| |
| #. In terminal window 1, type: |
| |
| .. code-block:: console |
| |
| $ cd $ZEPHYR_BASE/samples/hello_world/nanokernel |
| $ make BOARD=arduino_101_factory debugserver |
| |
| These commands will start an ``openocd`` session with a local telnet |
| server (on port 4444 for direct openocd commands to be issued), and a |
| gdbserver (for gdb access). The command should not return to a command line |
| interface until you are done debugging, at which point you can press :kbd:`Ctrl+C` |
| to shutdown everything. |
| |
| #. Start GDB in terminal window 2: |
| |
| * To debug on x86: |
| |
| .. code-block:: console |
| |
| $ cd $ZEPHYR_BASE/samples/hello_world/nanokernel |
| $ gdb outdir/zephyr.elf |
| gdb$ target remote :3333 |
| |
| * To debug on ARC: |
| |
| ARC debugging will require some extra steps and a third terminal. It is |
| necessary to use a version of gdb that understands ARC binaries. |
| Thankfully one is provided with the Zephyr SDK at |
| :envvar:`$ZEPHYR_SDK_INSTALL_DIR` |
| :file:`/sysroots/i686-pokysdk-linux/usr/bin/arc-poky-elf/arc-poky-elf-gdb`. |
| |
| It is suggested to create an alias in your shell to run this command, |
| such as: |
| |
| .. code-block:: console |
| |
| alias arc_gdb= "$ZEPHYR_SDK_INSTALL_DIR/sysroots/i686-pokysdk- |
| linux/usr/bin/arc-poky-elf/arc-poky-elf-gdb" |
| |
| a) On Terminal 2: |
| |
| .. code-block:: console |
| |
| $ cd $ZEPHYR_BASE/samples/hello_world/nanokernel |
| $ arc_gdb outdir/zephyr.elf |
| gdb$ target remote :3334 |
| |
| At this point you may set the breakpoint needed in the code/function. |
| |
| b) On Terminal 3 connect to the X86 side: |
| |
| .. code-block:: console |
| |
| $ gdb |
| gdb$ target remote :3333 |
| gdb$ continue |
| |
| .. note:: |
| |
| In previous versions of the SDK, the gdbserver remote ports were reversed. |
| The gdb ARC server port was 3333 and the X86 port was 3334. As of SDK |
| v0.7.2, the gdb ARC server port is 3334, and the X86 port is 3333. |
| |
| The :code:`continue` on the X86 side is needed as the ARC_GDB_ENABLE flag has |
| been set and halts the X86 until the ARC core is ready. Ready in this case |
| is defined as openocd has had a chance to connect, setup registers, and any |
| breakpoints. Unfortunately, there exists no automated method for notifying |
| the X86 side that openocd has connected to the ARC at this time. |
| |
| Once you've started the X86 side again, and have configured any debug |
| stubs on the ARC side, you will need to have gdb issue the continue |
| command for the ARC processor to start. |
| |
| |
| 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/arduino_101/pinmux.c`. |
| |
| |
| +-------------+----------+------------+ |
| | 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. |
| |
| 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. |
| |
| .. _Arduino Website: https://www.arduino.cc/en/Main/ArduinoBoard101 |
| |
| .. _schematics: https://www.arduino.cc/en/uploads/Main/Arduino101Schematic.pdf |
| |
| .. _FlySwatter2 JTAG debugger: |
| http://www.tincantools.com/JTAG/Flyswatter2.html |
| |
| .. _Intel Datasheet: |
| http://www.intel.com/content/www/us/en/embedded/products/quark/mcu/se-soc/overview.html |
| |
| .. _ARM-JTAG-20-10: |
| http://www.amazon.com/gp/product/ |
| B009UEO9ZY/ref=oh_aui_detailpage_o04_s00?ie=UTF8&psc=1 |
| |
| .. _USB to TTL Serial Cable: https://www.adafruit.com/products/954 |