RIOT/boards/iotlab-m3/doc.txt

/**
@defgroup    boards_iotlab-m3 IoT-LAB M3 open node
@ingroup     boards
@brief       Support for the iotlab-m3 board

## Components

| MCU               | [ST2M32F103REY](http://www.st.com/web/catalog/mmc/FM141/SC1169/SS1031/LN1565/PF164485) – 32-bits, 64KiB RAM                               |
|:----------------- |:----------------------------------------------------------------------------------------------------------------------------------------- |
|sensors            | Light ([ISL29020](https://www.renesas.com/kr/en/products/sensors/ambient-light-sensors/light-to-digital-sensors/device/ISL29020.html))    |
|                   | Pressure ([LPS331AP](http://www.st.com/web/catalog/sense_power/FM89/SC1316/PF251601))                                                     |
|                   | Tri-axis accelerometer/magnetometer ([LSM303DLHC](http://www.st.com/web/catalog/sense_power/FM89/SC1449/PF251940))                        |
|                   | Tri-axis gyrometer ([L3G4200D](http://www.st.com/web/catalog/sense_power/FM89/SC1288/PF250373))                                           |
| external memory   | 128 Mbits external Nor flash ([N25Q128A13E1240F](https://www.micron.com/-/media/client/global/documents/products/data-sheet/nor-flash/serial-nor/n25q/n25q_128mb_3v_65nm.pdf)) |
| power             | 3,7V LiPo battery – 650 mAh ([063040](http://www.gmbattery.com/Datasheet/LIPO/LIPO-063040.pdf))                                           |
| radio chipset     | [AT86RF231](http://www.atmel.com/images/doc8111.pdf)                                                                                      |
|                   | a IEEE802.15.4-compliant radio at 2.4 GHz                                                                                                 |

## Board HW overview

![IoT-LAB M3 Layout](https://www.iot-lab.info/wp-content/uploads/2013/10/m3opennode.png)

### Board Architecture

![IoT-LAB M3 Architecture](https://github.com/iot-lab/iot-lab/wiki/Images/archiopenm3.png)

### [Board schematics](http://github.com/iot-lab/iot-lab/wiki/Docs/openm3-schematics.pdf)
, wiring, pinouts, etc...

## Implementation Status

| Device            | ID            | Supported     | Comments              |
|:----------------- |:------------- |:------------- |:--------------------- |
| MCU               | [STM32F103REY](http://www.st.com/st-web-ui/static/active/en/resource/technical/document/reference_manual/CD00171190.pdf) | partly    | Energy saving modes not fully utilized |
| Low-level driver  | GPIO          | yes           |                       |
|                   | PWM           | no            | periph config missing |
|                   | UART          | yes           |                       |
|                   | I2C           | yes           |                       |
|                   | SPI           | yes           |                       |
|                   | USB           | no            |                       |
|                   | RTT           | yes           |                       |
|                   | Timer         | yes           |                       |
| Radio Chip        | AT86RF231     | yes           |                       |
| Accelerometer     | LSM303DLHC    | yes           |                       |
| Magnetometer      | LSM303DLHC    | yes           |                       |
| Gyroscope         | L3G4200D      | yes           |                       |
| Pressure Sensor   | LPS331AP      | yes           |                       |
| Light Sensor      | ISL29020      | yes           |                       |
| SPI Flash         | N25Q128       | yes           |                       |

## Toolchains

See [ARM Family](https://github.com/RIOT-OS/RIOT/wiki/Family:-ARM)

Working:
* [gcc-arm-embedded](https://github.com/RIOT-OS/RIOT/wiki/Family:-ARM#gcc-
arm-embedded-toolchain)
* [gcc-linaro](https://github.com/RIOT-OS/RIOT/wiki/Family:-ARM#linaro-
toolchain)

### Programming and Debugging

In order to program (flash) and debug the node you need
[OpenOCD](http://openocd.sourceforge.net/) and an ARM version of gdb (`arm-none-
eabi-gdb`), which provided by most toolchains. Most Linux distributions provide
also a package for OpenOCD. The required configuration files are provided by
RIOT.
When starting the debugger with `make debug BOARD=iotlab-m3` GDB connects to
openocd, loads the elf-file and puts the MCU into halt state. Before setting
breakpoints it is sometimes needed to use the following workflow
```
bash
monitor reset run
monitor reset halt
b <breakpoint>
c
```
For best debugging experience also change the `-Os` flag in
`Makefile.include`'s `CFLAGS` variable to `-O0`.

## Details
The M3 Open Node can reset, debug and program the STM32 on JTAG through the
FTDI2322H connected to the USB. This component allows also a UART link to the
STM32. The Open Node connector gives access to 3 STM32/GPIO and the STM32/I2C.
Two power lines are accessible on this connector:
* a + 5.0 volts for the board power supply
* a 3.3 volts for the consumption monitoring of the STM32, the RF component
and the sensors

The M3 Open Node can be used standalone without a gateway connected to the M3
Open node connector. The powering of the board is then assumed by a battery or
by the USB connector  The choice of the power input is done electronically
(power management).

![IoT-LAB M3 architecture](https://www.iot-lab.info/wp-
content/uploads/2013/10/archiopenm3.png)

## Debugging

For debugging you need to open a terminal. Here you simply have to call `make
debug` - assuming that the current directory is your application directory. It
establishes an openocd connection to the device and starts gdb connected to the
openocd instance. For example, it should look something like this
```
[user@host RIOT]$ cd examples/default/
[user@host default]$ BOARD=iotlab-m3 make
Building application default for iotlab-m3 w/ MCU stm32f1.
...
[user@hostdefault]$ BOARD=iotlab-m3 make debug
RIOT/boards/hikob-common/dist/debug.sh RIOT/boards/iotlab-m3/dist/gdb.conf
RIOT/examples/default/bin/iotlab-m3/default.elf
Open On-Chip Debugger 0.8.0 (2014-07-27-20:18)
Licensed under GNU GPL v2
For bug reports, read
 http://openocd.sourceforge.net/doc/doxygen/bugs.html
GNU gdb (GNU Tools for ARM Embedded Processors) 7.4.1.20140401-cvs
Copyright (C) 2012 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.  Type "show copying"
and "show warranty" for details.
This GDB was configured as "--host=x86_64-apple-darwin10 --target=arm-none-
eabi".
For bug reporting instructions, please see:
<http://www.gnu.org/software/gdb/bugs/>...
Reading symbols from RIOT/examples/default/bin/iotlab-m3/default.elf...done.
idle_thread (arg=<optimized out>) at RIOT/core/kernel_init.c:67
67               lpm_set(LPM_IDLE);
JTAG tap: stm32f1x.cpu tap/device found: 0x3ba00477 (mfg: 0x23b, part:
0xba00, ver: 0x3)
JTAG tap: stm32f1x.bs tap/device found: 0x06414041 (mfg: 0x020, part: 0x6414,
ver: 0x0)
target state: halted
target halted due to debug-request, current mode: Thread
xPSR: 0x01000000 pc: 0x0800027c msp: 0x20002200
Loading section .text, size 0x6df4 lma 0x8000000
Loading section .ARM.exidx, size 0x8 lma 0x8006df4
Loading section .relocate, size 0x120 lma 0x8006dfc
Start address 0x8000000, load size 28444
Transfer rate: 11 KB/sec, 7111 bytes/write.
(gdb) c
Continuing.
```

The node will reboot and you can continue to use `gdb` like you're used to.
In some cases it
seems necessary to prepend a `monitor reset run` before executing continue.
In general you can
use openocd commands prepended by `monitor`.
In the case the node crashes it can be reset with the following sequence
```
Bash
(gdb) monitor reset halt
(gdb) monitor reset run
```

## Troubleshooting

For terminal output on macOS (`make term`) you need to install a driver:
http://www.ftdichip.com/Drivers/VCP.htm
http://www.ftdichip.com/Drivers/VCP.htm
 */