Introduction - Esp8266/NodeMCU platform

In this page we explain:

The main Esp customization is based on Terra NET flavor for the ESP8266 platform using UDP/IP via WIFI IEEE802.11 radio. Currently we tested Terra in the following ESP8266-12E 4MB boards:

You will find in this page detailed information about TerraEsp specific events and functions.

Installing TerraEsp in a Linux Box

Pre-requisites

Installation Steps

Note: The installation procedure for ESP SDK Toolchain was based on Paul Sokolovsky script: https://github.com/pfalcon/esp-open-sdk

Terra dependencies - Install, if necessary, the following packages.

Open a command terminal and execute the following commands.

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

ESP SDK dependencies - Install, if necessary, the following packages.

 sudo apt-get install make unrar-free autoconf automake libtool gcc g++ gperf \
    flex bison texinfo gawk ncurses-dev libexpat-dev python-dev python python-serial \
    sed git unzip bash help2man wget bzip2 libtool-bin

ESP SDK Toolchain installation.

Note: Be patient! This step needs some time!

cd ~
git clone --recursive https://github.com/pfalcon/esp-open-sdk.git
cd ~/esp-open-sdk/
make

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.

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 environment definitions

Open a command terminal and change to HOME directory

cd ~

Open the file .bashrc in the editor.

gedit .bashrc

Insert following lines at the end of the file.

# 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'

# Export xtensa tools path
export PATH=$HOME/esp-open-sdk/xtensa-lx106-elf/bin:$PATH

Open a new command terminal to get the new environment.

Compiling and flashing

After a successful software installation, you can generate a compiled file and flash it into an ESP 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 esp command with additional parameters. 

cd $HOME/Terra/TerraVM/src

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

make esp TYPE:BOTH VM:NET MOD:MSGQ USB:/dev/ttyUSB0 BS_BAUD:57600 install.2

Attention points

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

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 WIFI network is the number 2. The node address, considering the unique ID 1, will be (2*2048)+1 = 4097.

The USB:path identifies the USB connected to flash the ESP 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 ESP8266 board. The command make help esp will show an updated definition.

Warning about some Pre installed firmwares

Terra firmware may not work depending on the original firmware loaded into the board. Loading a specific firmware based on the same libraries used by Terra will solve this problem. The following commands will load the AT-Command firmware into your board. You need to do this only once. 

cd ~/esp-open-sdk/sdk/bin
esptool.py write_flash 0 boot_v1.2.bin 0x01000 at/1024+1024/user1.2048.new.5.bin \
         0x3fc000 esp_init_data_default.bin 0xfe000 blank.bin 0x3fe000 blank.bin

Compiling a Terra script

Terra scripts rely on a definition file targeting a specific customization. In the case of ESP, the TerraEsp.defs file is the the basic customization. This file must be referenced in the beginning of your script code as #include "TerraEsp.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 and baud is the baud rate indicated in the BS_BAUD parameter. 

sf -comm serial@/dev/ttyUSB0:57600