Tutorial: How to port a radio module driver to RIOT OS
tobhe edited this page Jul 22, 2017
·
24 revisions
Attention: Work in progress (content is coming step by step / feel free and make corrections and add your experience)
The intention for this page is just to give RIOT newbies a guide to develop or port a driver for their prefered radio module. In fact there are actually many boards supported by RIOT OS but only a few radio modules. Maybe this page can help to change the situation.
- First: You need two pieces of hardware - at least one microcontroller board (well known to work with RIOT) and the Radio Module for which you want to write the software driver. Blind programming (without having the hardware) maybe interesting, but doesn't really make sense....
- Be sure you have all the documents of the module (which provides you information about connecting the module to the big wide world) and also from the silicon (chip datasheet, manual, application notes which can provide you information about protocols, timings, register-sets and so on...)
- You need a working toolchain and a working programming environment / IDE (e.g. Eclipse)
- You need a hardware emulation probe which provides you the possibility to program your firmware onto the microcontroller-board and which provides you the possibility to trace through the code....
- A connection to the microcontroller's serial port will be helpful. Sometimes it is very helpful to direct debug messages from inside of the running firmware to a serial port which could then be display on a terminal software on your development computer (workstation/PC). A helpful piece of hardware could be a TTL-USB-UART, which connects the microcontrollers TTL-Serial Port to the PC.
- A well known working "base-station"/border-router/receiver is needed. Look at the Wiki Article about the Raspberry-Pi 6LoWPAN bringup
- Finally, you probably need an oscilloscope to inspect traffic flowing between the microcontroller board and the radio module.
- Take a look into the code of software-drivers which could be used as a blue-print for your own driver. In the case of a **netdev2-radio-driver** this could be the code for the Atmel at86rf2xx family. The datasheet for this silicon would be also helpful to understand what's going in in this driver - if not all parts are described in this tutorial ;-)
- Stick together your hardware parts (microcontroller-board and radio-module). Most of the radio modules use an SPI-Interface as the communication pipeline between the microcontroller and the radio-module. But don't forget the other necessary signals (chip-select(s), reset-line, interrupt-line(s), wake/sleep e.g.) and the power-supply (VCC, GND).
We have to create a directory under the /drivers path which has the name of the later create driver and under this an include directory
mkdir ~/RIOT/drivers/<driver-name> mkdir ~/RIOT/drivers/<driver-name>/include
touch ~/RIOT/sys/auto_init/netif/auto_init_<driver-name>.c
The following file have to be created or copied from another driver
~/RIOT/drivers/<driver-name>/Makefile
~/RIOT/drivers/<driver-name>/<driver-name>.c
~/RIOT/drivers/<driver-name>/<driver-name>_internal.c
~/RIOT/drivers/<driver-name>/<driver-name>_getset.c
~/RIOT/drivers/<driver-name>/<driver-name>_netdev.c
~/RIOT/drivers/<driver-name>/include/<driver-name>_registers.h
~/RIOT/drivers/<driver-name>/include/<driver-name>_params.h
~/RIOT/drivers/<driver-name>/include/<driver-name>_internal.c
- in this file, we implement the low-level / hardware-related functions,
that is, all routines which have to do with direct access to the
registers of the radio module.
~/RIOT/drivers/<driver-name>/include/<driver-name>_netdev.h
~/RIOT/drivers/include/<driver-name>.h
~/RIOT/boards/<board-name>/include/board.h
~/RIOT/drivers/Makefile.dep ~/RIOT/drivers/Makefile.include
- if you want to invoke the usage of the driver automatically together with a special board you have to add the following lines to the dependency-makefile of the board:
ifneq (,$(filter netdev_default gnrc_netdev_default,$(USEMODULE))) USEMODULE += <driver-name> endif
- Most IEEE802154 radio modules are connected to a microcontroller using an SPI interface
- In the board.h file (RIOT/boards/include/board.h) you can tell the system which SPI interface of the microcontroller will be used and also which additional GPIOs are used for the control signals of the radio module
- An example of the paragraph which defines the connectivity is shown here (example micro-controller is a STM32)
somewhere in the RIOT/boards/<board-name>/include/board.h file.......
#define <driver-name>_PARAMS_BOARD {.spi = SPI_1, \
.spi_speed = SPI_SPEED_5MHZ, \
.cs_pin = GPIO_PIN(PORT_B, 12), \
.int_pin = GPIO_PIN(PORT_A, 15), \
.sleep_pin = GPIO_PIN(PORT_B, 9), \
.reset_pin = GPIO_PIN(PORT_B, 8)}
Note: In this example we see that the module is connected to SPI_1. The chip-select signal is connected to Port_B/12 port pin, the interrupt is connected to Port_A/15 port pin, the sleep signal is connected to Port_B/9 pin, and the reset-input of the radio module is driven by the Port_B/8 port pin.
ATTENTION: Configuration for ALTERNATIVE microcontroller SPI-PIN-Configurations (e.g. due to the use of the microcontroller's pin-multiplexers) have to be configured otherwise.
The file
~/RIOT/drivers/<radio-chip-name>/<radio-chip-name>_internal.cprovides all the hardware related functions to access the registers inside of the radio chip.
The file
~/RIOT/drivers/<radio-chip-name>/include/<radio-chip-name>_registers.hprovides the addresses of the registers inside of the address-map/register-map.
One of the first things to check is the SPI interface to the microcontroller:
are all pins soldered correctly? is the SPI interface configured correctly? (protocol, speed etc.)Note 1: It might be a good idea to write a shell command to print out all the register values of the radio module. With this command, all changes of register values could be monitored and you can review if the register values after changes are set up correctly (write access check).
Note 2: Some radio modules provide a vendor identification register which could be used to identify the radio chip.