Terra IoT System

Introduction - TinyOS platforms

In this page we explain:

how to install TinyOS-2.1.2 environment in an Ubuntu16.04 64bits machine,
how to install Terra development environment,
how to compile the firmware for TinyOS version of TerraVM and flash it into a device,
how to compile your Terra Script,
how to load a Terra Script bytecode in the network, and
how to start the Terra grid simulator.

In theory it is possible to compile Terra for all platforms available for TinyOS. But currently Terra has been tested on the following boards:

TelosB
MicaZ
Iris
Mica2
Mica2Dot

You will find in TerraNet and TerraGrp detailed informations about TerraNet and TerraGrp specific events and functions.

Installing TinyOS 2.1.2

These steps will install the production version of TinyOS 2.1.2 and the corresponding tools for AVR (mica family) and MSP (TelosB/MoteSky). This was tested with Ubuntu 16.04 64bits. (Adapted from http://tinyprod.net/repos/debian/)

Installation Steps

Install TinyOS Tools and msp430/avr support

Open a command terminal and execute the following commands.

sudo wget -O - http://tinyprod.net/repos/debian/tinyprod.key | sudo apt-key add -
sudo -s

cd /etc/apt/sources.list.d
echo "deb http://tinyprod.net/repos/debian wheezy main" >> tinyprod-debian.list
echo "deb http://tinyprod.net/repos/debian msp430-46 main" >> tinyprod-debian.list

exit

sudo apt-get update
sudo apt-get install openjdk-8-jdk
sudo apt-get install nescc tinyos-tools msp430-46 gcc-avr binutils-avr avr-libc

** At the end, I got the error Errors were encountered while processing: /var/cache/apt/archives/nescc_1.3.5-1_amd64.deb, but this error looks like that does not affect the system installation.

Install python/serial and previous gcc/g++

Open a command terminal and execute the following commands.

sudo apt-get install python-dev python-serial python-pygame
sudo apt-get install gcc-4.8 g++-4.8

Dowload TinyOS 2.1.2 repository

Open a command terminal and execute the following commands.

wget http://github.com/tinyos/tinyos-release/archive/tinyos-2_1_2.tar.gz
tar xf tinyos-2_1_2.tar.gz 
sudo mv tinyos-release-tinyos-2_1_2 /opt/tinyos-2.1.2

Patch some TinyOS files

Open a command terminal and execute the following commands.

sudo sed -i 's/GCC=gcc/GCC=gcc-4.8/g' /opt/tinyos-2.1.2/support/make/sim.extra
sudo sed -i 's/GPP=g++/GPP=g++-4.8/g' /opt/tinyos-2.1.2/support/make/sim.extra
sudo sed -i 's/shell python --version/shell python2 --version/g' /opt/tinyos-2.1.2/support/make/sim.extra
sudo sed -i 's/+\\{0,1\\}/\*/g' /opt/tinyos-2.1.2/support/make/sim.extra

sudo sed -i 's/GCC=gcc/GCC=gcc-4.8/g' /opt/tinyos-2.1.2/support/make/sim-sf.extra
sudo sed -i 's/GPP=g++/GPP=g++-4.8/g' /opt/tinyos-2.1.2/support/make/sim-sf.extra
sudo sed -i 's/shell python --version/shell python2 --version/g' /opt/tinyos-2.1.2/support/make/sim-sf.extra
sudo sed -i 's/+\\{0,1\\}/\*/g' /opt/tinyos-2.1.2/support/make/sim-sf.extra

sudo sed -i '/-fnesc-no-debug/a -D__AVR_ATmega128__' /opt/tinyos-2.1.2/tos/platforms/micaz/.platform
sudo sed -i '/-fnesc-no-debug/a -D__AVR_ATmega128__' /opt/tinyos-2.1.2/tos/platforms/mica2/.platform
sudo sed -i '/-fnesc-no-debug/a -D__AVR_ATmega128__' /opt/tinyos-2.1.2/tos/platforms/mica2dot/.platform
sudo sed -i '/-fnesc-no-debug/a -D__AVR_ATmega128__' /opt/tinyos-2.1.2/tos/platforms/btnode3/.platform
sudo sed -i '/-fnesc-no-debug/a -D__AVR_ATmega1281__' /opt/tinyos-2.1.2/tos/platforms/iris/.platform
sudo sed -i '/-fnesc-no-debug/a -D__AVR_ATmega128RFA1__' /opt/tinyos-2.1.2/tos/platforms/ucmini/.platform

sudo sed -i 's/typedef/typedef const/g' /opt/tinyos-2.1.2/tos/chips/atm128/atm128const.h
sudo sed -i 's/resQ\[qTail\] = id/resQ[qTail\%size] = id/g' /opt/tinyos-2.1.2/tos/system/FcfsResourceQueueC.nc

.bashrc Environment symbols

Open a command terminal and execute the following commands as one command.

echo \
'#TinyOS 2.1.2
# Setup the environment variables needed by the TinyOS make system
export TOSROOT="/opt/tinyos-2.1.2"
echo "setting up TinyOS source path to $TOSROOT"
export TOSDIR="$TOSROOT/tos"
export CLASSPATH=$CLASSPATH:$TOSROOT/support/sdk/java/tinyos.jar:.
export MAKERULES="$TOSROOT/support/make/Makerules"
export PYTHONPATH=$PYTHONPATH:$TOSROOT/support/sdk/python
' >> ~/.bashrc

Adjust USB access permission for your user:

sudo usermod -a -G dialout $USER

Note: You must logout and login again to validate this new permission.

Installing Terra for TinyOS in a Linux Box

Pre-requisites

Linux machine. This procedure was tested with Ubuntu 16.04 64bits.
Internet access.
Execution of the above TinyOS installation procedure.

Installation Steps

Install Git and Lua packages.

Open a command terminal and execute the following commands.

sudo apt-get update
sudo apt-get install git lua5.1 lua-lpeg

Get Terra source code from the repository

Clone Terra repository into home directory.

Open a command terminal, change to home directory, and download Terra repository.

cd ~
git clone https://github.com/afbranco/Terra

The next time use the command git pull from the new Terra dir to get last update

Create Terra specific environment definitions

Open a command terminal and execute the following commands as one command.

echo \
'# Export Terra paths
export TERRADIR=$HOME/Terra
export CLASSPATH=$TERRADIR/TerraControl/tinyos.jar:.$CLASSPATH
# Tools alias
alias terrac="$TERRADIR/terrac/terrac -I$TERRADIR/TerraVM/src/TerraDefs"
alias ttool="java -jar $TERRADIR/TerraControl/TControl.jar"
alias sf="java net.tinyos.sf.SerialForwarder"
' >> ~/.bashrc

Open a new command terminal to get the new environment.

Compiling and flashing

After a successful installation, you can generate a compiled file and flash it into an compatible TinyOS board.

Terra development environment uses a Make system to build and install the firmware. You must change to the $HOME/Terra/TerraVM/src directory and execute make command with additional parameters.

The follow command is an example of Terra compilation for MicaZ board:

cd $HOME/Terra/TerraVM/src
make micaz TYPE:BOTH VM:NET MOD:MSGQ USB:/dev/ttyUSB0 BS_BAUD:57600

Attention points

We must pay attention for some details when compiling and installing Terra for TinyOS.

The TYPE:type parameter indicates if your node will communicate via USB interface (BOTH) or not (NOBS). Usually one node, acting as BaseStation or sink node, is connected to a computer via USB interface when the all nodes communicate via radio. Hybrid networks may create a bridge connecting two node with different radios via serial/USB interface.

The BS_BAUD:value configures the USB baud rate for Terra operation. (This does not change the firmware flashing baud rate that is configured internally in the system.)

The INSTAL.n parameter indicates to flash the compiled file. The n is the unique node identifier for its network.

The real node address is the combination of the Network ID and the unique node identifier. For example, the default Network Id for the cc2420 network is the number 1. The node address, considering the unique ID 2, will be (1*2048)+2 = 2050.

The USB:path identifies the USB connected to flash the board. This value is usually /dev/ttyUSB0, this depends on the FDDI chip used in the board. But its number may change if the previous connection is already allocated. Use the command ls /dev/ttyU* to find the correct port.

Terra compilation parameters

These are the allowed parameters when compiling for a TinyOS board. The command make help xxx, where xxx is the platform, will show an updated definition.

VM: Define the VM flavor: NET, GRP | default NET
MOD: Define additional modules: MSGQ | default ''
SENSOR: Configure sensorboard: MTS300CA or MTS300CB(wired) or MDA100 | default MDA100
QUEUE: Generate short or long queues | default SHORT
TYPE: Configure runtime type: NOBS or BOTH | default BOTH
MOTE_TYPE: Define mote type: 1..254 | Default 1
VERB: Verbose Compilation mode: Y or N | Default N
RFPOWER: RF Power: 0 1 2 3 4 5 6 7 | default 7
LPL: Low Power Listening mode: Y or N | default N
IFLASH: Internal Flash for prog storage: Y or N | default Y
NET_ID: Network identifier - 0..30 | default 0:cc1000, 1:cc2420, 2:wifi-udp, 3:esp, 4:nrf24, 5:xbee
install. - Install command + unique node identifier inside its network - 1..2047 | default 1
USB: USB dev path. | default /dev/ttyUSB0
BS_BAUD: BaseStation baudrate - 115200, 57600, 19200 | default platform specific or 19200
- Platform specific = telosb, tmote, eyes, intelmote2 => 115200; micaz,mica2, iris => 57600; mica2dot=>19200
- Do not change baudrate for mica2dot.

Compiling a Terra script

Terra scripts rely on a definition file targeting a specific customization. In the case of TerraNet or TerraGrp, the TerraNet.defs file is used for the the basic customization and the TerraGrp.defs file is used for the Group customization. One of these files must be referenced in the beginning of your script code as #include "TerraNet.defs".

Use the terrac command to compile your script. Assuming that the name of your script file is myScript.terra, type the following command:

terrac myScript.terra

This command will generate a bytecode file named myScript.vmx

Loading a Terra Script into network

Considering that you already have a script compiled with terrac compiler, you need to load the script bytecode into the Terra network nodes. Two tools must be started to that: The TinyOS SerialForwarder application and the Terra Control tool.

The use of the Terra Control tool was explained in the Terra tutorial at Terra Site. The tool can be started by the ttool command. After started, the tool waits for the SerialForwarder to connect to the USB.

The SerialForwarder is started by sf -comm serial@path:baud command, where path is the path to the USB interface (data port) and baud is the baud rate indicated in the BS_BAUD parameter or the platform name.

sf -comm serial@/dev/ttyUSB1:micaz

Note: The mica family boards open a second USB port to data communication. For example, a mib520 USB adapter will open the /dev/ttyUSB0 for firmware flashing and the /dev/ttyUSB1 for the data comunication used by Terra.

Simulating Terra with TOSSIM

The Terra project has a customized grid simulator that allows some tests and experiments. The TOSSIM simulator is used to run a Terra firmware and a simple visual interface was built to represent, as possible, the simulation execution.

The simulation is started using two scripts - TerraSim.py and TerraViewer.py. The first one executes a TOSSIM scripts and receives as arguments the grid size and execution time. The second executes a graphical network animation based on the output informattion from the TOSSIM execution. After started a simulation, the ttool command must be used to load a Terra script into the network. Note that the SerialForward tool is not used.

The following command syntax must be used: ./TerraSim.py lines columns 0 0 time | ./TerraViewer.py, where lines and columns are, respectivately, the number of lines and columns that define the network grid. These numbers can vary from 1 up to 9. The two 0 are constants used for advanced tests and the time is the execution time in seconds that the simulation will run.

For example, the command bellow will start a 5 minutes (300 seconds) simulation for a 2x3 grid.

./TerraSim.py 2 3 0 0 300 | ./TerraViewer.py

Note: More details how to use the simulation can be found in Terra Tutorial. But, considering the differete way to start the simulation.