For the internet of plants, we have decided to use the Atmel SAM R21, a Cortex M0 based platform with an on-board IEEE 802.15.4 wireless module, to monitor our green friends. This post explains the general process of setting up a development environment for RIOT applications on Ubuntu 14.10, taking into account the peculiarities of the SAM R21 board.
The following packages are needed to build the necessary tools and the RIOT application:
- General: git, pkg-config, autoconf, libtool, unzip
- OpenOCD: libudev-dev, libusb-1.0-0-dev
They can be installed through apt by running
sudo apt-get install git pkg-config autoconf \ libudev-dev libusb-1.0-0-dev libtool unzip \ valgrind
In addition it is recommendable to update Ubuntu to the latest version after installing, by invoking
sudo apt-get update && sudo apt-get dist-upgrade
Warning: Running a
dist-upgrade is a potentially destructive operation, so it is NOT recommended if you don’t have a dedicated installation of Ubuntu 14.10 for this excercise.
The Open On-Chip-Debugger (OpenOCD) is used by the RIOT build system for flashing the application onto the board and to debug it. The current release (v0.8.0) of OpenOCD, however, does not contain configuration files for the SAM R21 board, so it has to be built from source. OpenOCD also requires hidapi, which is not available as a package on Ubuntu 14.10. The following script will clone, build and install hidapi if all goes well:
TMP=$(mktemp) && rm -r $TMP && mkdir -p $TMP && cd $TMP && git clone http://github.com/signal11/hidapi.git && cd hidapi && ./bootstrap && ./configure && make && sudo make install && sudo ln -s /usr/local/lib/libhidapi-hidraw.so.0 \ /usr/lib/libhidapi-hidraw.so.0
Now that all requirements are installed, OpenOCD can be built:
TMP=$(mktemp) && rm -r $TMP && mkdir -p $TMP && cd $TMP && git clone https://github.com/watr-li/OpenOCD.git openocd && cd openocd && ./bootstrap && ./configure --enable-maintainer-mode \ --enable-cmsis-dap \ --enable-hidapi-libusb && make && sudo make install
Installing the toolchain
sudo apt-get remove binutils-arm-none-eabi gcc-arm-none-eabi && sudo add-apt-repository ppa:terry.guo/gcc-arm-embedded && sudo apt-get update && sudo apt-get install gcc-arm-none-eabi=188.8.131.525q1-0utopic14
Note: A warning could be displayed that there are conflicting package names with the Debian apt repositories. That warning is already taken into consideration here and you can safely proceed by pressing enter.
Building a RIOT example application
Now that all the requirements are set up, a RIOT-based application can be built. Cloning RIOT (via github.com/RIOT), switching to the directory of the example hello world application and building it is performed by the following script:
git clone https://github.com/RIOT-OS/RIOT.git && cd RIOT/examples/hello-world && export BOARD=samr21-xpro && make
The only non-standard line here is the definition of the
BOARD environment variable which tells the RIOT build system which hardware we are targeting.
Preparations for flashing
In order to be able to flash the application onto the board without root privileges, a couple of additional customizations are necessary. First we need to add our user do the
dialout group by running the following command:
sudo usermod --append --groups dialout <our username>
This is required in order to capture the output from the board’s serial console, which is mounted as
/dev/ttyACM[0-9]+ and belongs to the
dialout group by default.
Note: You need to re-login after adding the user to the group.
Secondly we need to instruct udev, the device manager, to allow access to the kernel devices created by the hidapi. We do this by creating a new file
99-hidraw-permissions.rules in the
/etc/udev/rules.d directory with the following content:
KERNEL=="hidraw*", SUBSYSTEM=="hidraw", MODE="0664", GROUP="plugdev"
Note: After adding the
udev permission you have to re-connect the board for the changes to take effect.
Flashing and running the application
The next step is to get the application onto the board, run it and see the output it produces. The RIOT build system is already configured to do all of this for the SAMR board, under the assumption that OpenOCD is installed. For this we need two separate terminals: one where the command to flash the board is invoked and the other where the output from the board is displayed.
Setting up the output terminal
In this terminal we start a pyterm instance, a serial port terminal emulator written in Python, listening to the output of the board:
export BOARD=samr21-xpro && make term
This should result in the following being printed, after which pyterm waits for output from the board:
INFO # Connect to serial port /dev/ttyACM0 Welcome to pyterm! Type '/exit' to exit.
Running the flash command
Now we can switch to the other terminal window in which we will invoke the commands to flash the application onto the board:
export BOARD=samr21-xpro && make flash
The CMSIS-DAP interface for flashing and debugging is quite slow (should be around 2KiB/s). So when flashing, you might need to wait a little longer. You can also apply an OpenOCD patch that increases flashing speed by 50-100%.
make flash flashes and subsequently resets the board, causing the application to run. For our hello world example it should result in the following output being shown in the terminal window in which
make term was executed:
INFO # kernel_init(): This is RIOT! (Version: 2014.12-285-gfe295) INFO # kernel_init(): jumping into first task... INFO # Hello World! INFO # You are running RIOT on a(n) samr21-xpro board. INFO # This board features a(n) samd21 MCU.
Bonus: RIOT native mode
In addition to running the application directly on the target hardware, RIOT also features a target called
native, which runs the application inside the host operating system. This is especially useful when flashing the devices is comparatively slow, as is the case for the SAM R21 board.
If you want to use native mode, the only thing required is a 32-bit version of libc installed on the system:
sudo apt-get install libc6-dev-i386
After installing this dependency you can then return to the directory of the example hello world application and invoke
export BOARD=native && make && make term
For native mode, the build system creates a 32-bit binary in the
bin/native directory. The only thing
make term then has to do is running that binary. You should see the same output as when running the application on the board, except for the board’s name and the MCU.
That’s all, folks!
Now that the development environment for RIOT has been set up and applications can be flashed onto the board, you’re ready to develop your first RIOT-based IoT application!
For more information about RIOT on the SAM R21, please visit the wiki page for the board in the RIOT repository. If you have any questions on the setup procedure or if anything is not working quite right, please leave a comment!
This article is based on a great post by David Karibe on setting up an open-source development toolchain for the Freescale FRDM-KL25Z board.