Difference between revisions of "Embedded Radios Quick Start Guide"

From CityLab Testbed
Jump to navigation Jump to search
(Created page with "== Prerequisites == This quick start guide assumes you already have access to the Citylab Testbed and that you are familiar with the steps required to start experiments. If t...")
 
 
(19 intermediate revisions by the same user not shown)
Line 1: Line 1:
 +
This quick start guide will explain how to get started with the "LoRa" (EFM32GG+RFM95W) an the OpenUSB modules of the Citylab testbed nodes.
 
== Prerequisites ==
 
== Prerequisites ==
  
 
This quick start guide assumes you already have access to the Citylab Testbed and that you are familiar with the steps required to start experiments. If that is not the case then please follow the [[Getting Started]] guide first.
 
This quick start guide assumes you already have access to the Citylab Testbed and that you are familiar with the steps required to start experiments. If that is not the case then please follow the [[Getting Started]] guide first.
 +
 +
 +
== Experiment Setup ==
 +
 +
* Open the JFed GUI, create a new experiment and drag in two wireless nodes.
 +
[[File:jfed_embedded_setup_01.png|Experiment Setup|480px]]
 +
* Configure the nodes. Make sure that you:
 +
** Set the correct testbed for the node (defaults to w-iLab.2, needs to be set to Citylab)
 +
** Set Disk image to <code>Ubuntu 20.04 LTS 64-bit (CoT) with ARM gcc compiler</code>. This is important as we'll need the ARM gcc toolchain to compile the images for the devices.
 +
** Explicitly set the specific node to use. '''Make sure that the nodes you select are within range of each other!'''. You can use the [https://doc.lab.cityofthings.eu/nodemap/ Node Map] to help you with this.
 +
** name one of the nodes <code>nodeTX</code> and the other one <nodeRX>. You can use other node names but those are the node names that will be used throughout this guide.
 +
[[File:jfed_embedded_setup_02.png|Experiment Setup|600px]]
 +
 +
* Click "Run" to start the experiment and wait the the nodes to finish initialising. ''Important'': It'll take a bit longer than usual to start the experiment as the <code>Ubuntu 20.04 LTS 64-bit (CoT) with ARM gcc compiler</code> image we're using in this experiment is quite large so it'll take some time to load it onto the nodes.
 +
 +
== Getting started with the EFM32GG+RFM95W (LoRa) module ==
 +
 +
To help you get started with the "EFM32GG+RFM95W" module, we've ported the [https://github.com/Lora-net/LoRaMac-node LoraWAN network stack] to the "EFM32GG+RFM95W". This port can be found in the following Github repository:
 +
* https://github.com/imec-idlab/LoRaMac-node
 +
 +
In this guide, we'll use that repository to set up a basic broadcast tx/rx between two nodes but the stack has many other capabilities as well.
 +
 +
=== Preparing the receiver node ===
 +
 +
1) SSH into the <code>nodeRX</code> and clone the <code>LoRaMac-node</code> repository
 +
<pre>
 +
git clone https://github.com/imec-idlab/LoRaMac-node
 +
</pre>
 +
2) Change to the root dir of the repository
 +
<pre>
 +
cd LoraMac-node
 +
</pre>
 +
3) Edit the file <code>Makefile.local</code> and make sure it has the following contents:
 +
<pre>
 +
TARGET = beacon_rx
 +
CFLAGS += -DUSE_BAND_868=1
 +
CFLAGS += -DUSE_MODEM_LORA=1
 +
</pre>
 +
The <code>TARGET</code> line tells the compiler which application to build. The other lines tell the application to use the LoRa radio in the 868MHz band
 +
4) Compile the binary using the <code>make</code> command:
 +
<pre>
 +
make -j4
 +
</pre>
 +
If all went well you should now have a file named <code>beacon_rx.bin</code> in the local directory. If you get a complaint that no compiler could be found then, most likely you are not using the correct disk image.
 +
5) Flash the binary onto the EFM32GG device using the <code>flash_lora</code> script:
 +
<pre>
 +
flash_lora ./beacon_rx.bin
 +
</pre>
 +
 +
6) Use <code>picocom</code> to listen to the serial port of the 'Lora' device
 +
<pre>
 +
sudo picocom -b 115200 /dev/ttyLORA
 +
</pre>
 +
In the above command:
 +
* <code>115200</code> is the baud rate to use
 +
* <code>/dev/ttyLORA </code> is the path to the serial port of the Lora device. (This is a symlink to the actual 'ttyUSB' device that auto-generated via udev-rules present in all 'CoT' disk images)
 +
 +
At this point you won't see anything yet, but once the transmitter node has also been prepared you'll see text appearing here
 +
 +
=== Preparing the transmitter node ===
 +
 +
The steps needed to prepare the transmitter node are almost identical to the steps needed to prepare the receiver node.
 +
 +
1) Open a new terminal, SSH into the <code>nodeTX</code> and clone the <code>LoRaMac-node</code> repository
 +
 +
2) Change to the root dir of the repository
 +
 +
3) Edit the file <code>Makefile.local</code> and make sure it has the following contents:
 +
<pre>
 +
TARGET = beacon_tx
 +
CFLAGS += -DUSE_BAND_868=1
 +
CFLAGS += -DUSE_MODEM_LORA=1
 +
</pre>
 +
The only difference between the <code>Makefile.local</code> used here and the one used for the receiver is that we are now building the <code>beacon_tx</code> rather than the <code>beacon_rx</code> app.
 +
The <code>TARGET</code> line tells the compiler which application to build. The other lines tell the application to use the LoRa radio in the 868MHz band
 +
 +
4) Compile the binary using the <code>make</code> command.
 +
 +
5) Flash the binary onto the EFM32GG device using the <code>flash_lora</code> script:
 +
<pre>
 +
flash_lora ./beacon_tx.bin
 +
</pre>
 +
 +
6) Use <code>picocom</code> to listen to the serial port of the 'Lora' device
 +
<pre>
 +
sudo picocom -b 115200 /dev/ttyLORA
 +
</pre>
 +
You should now see lines similar to the ones below appearing:
 +
<pre>
 +
Sent Packet using LORA. size=16, counter=3 TimeOnAir(us)=52
 +
Sent Packet using LORA. size=16, counter=4 TimeOnAir(us)=52
 +
Sent Packet using LORA. size=16, counter=5 TimeOnAir(us)=52
 +
</pre>
 +
 +
7) Switch back to the terminal of the <code>nodeRX</code> testbed node. You should see lines similar to the ones below appearing
 +
<pre>
 +
0x520B4614248AB601,10,-33,25
 +
0x520B4614248AB601,11,-35,25
 +
0x520B4614248AB601,12,-34,26
 +
0x520B4614248AB601,13,-33,24
 +
</pre>
 +
In the reported lines, the first field is the UUID of the node sending the beacons, the second field is the sequence number of the packet and the 3rd & 4th fields are the RSSI & LQI of the received beacon packet.
 +
 +
=== Experiment Cleanup ===
 +
 +
In both the <code>nodeTX</code> and <code>nodeTX</code> terminals, perform the following actions to clean up the experiment:
 +
 +
1) Press the 'Control' key and then press the 'A' and 'X' one after the other while holding the 'Control' key pressed down. This control-sequence stops the running <code>picocom</code> program
 +
 +
2) Run the <code>erase_lora</code> program to wipe the LoRa devices.
 +
<pre>
 +
erase_lora
 +
</pre>
 +
It is important you do this since otherwise the transmitter node will keep sending beacons.
 +
 +
== Running Contiki-NG on the OpenUSB Radios ==
 +
 +
For this guide we re-use the same JFed experiment setup as for the 'LoRa device' (discussed above). In this section we'll flash two OpenUSB devices and ping from one to the other. The guide in this section is based on the [https://docs.contiki-ng.org/en/develop/doc/tutorials/Hello%2C-World%21.html Hello World], [https://docs.contiki-ng.org/en/develop/doc/tutorials/Shell.html Shell] and [https://docs.contiki-ng.org/en/develop/doc/tutorials/IPv6-ping.html IPv6 Ping] tutorials on the Contiki-NG documentation website, but focusses specifically on the OpenMote platform.
 +
 +
For more information on how to use Contiki-NG consult the Contiki-NG documentation at:
 +
* https://docs.contiki-ng.org/en/develop/doc/tutorials/
 +
* https://github.com/contiki-ng/contiki-ng/wiki
 +
 +
=== Cloning, Compiling & Flashing the nodes ===
 +
 +
1) SSH into both the <code>nodeTX</code> and <code>nodeRX</code> experiment nodes in two separate terminals. Then perform the steps below '''on both experiment nodes'''
 +
 +
2) Clone the contiki-ng git repository
 +
<pre>
 +
git clone https://github.com/contiki-ng/contiki-ng/
 +
</pre>
 +
 +
3) Change to the root of the source tree
 +
<pre>
 +
cd contiki-ng
 +
</pre>
 +
 +
4) Pull in all submodules (please note: this will take a while)
 +
<pre>
 +
git submodule update --init --recursive
 +
</pre>
 +
 +
4) move to the 'app' directory of the <code>hello-world</code> example application
 +
<pre>
 +
cd examples/hello-world
 +
</pre>
 +
 +
5) Edit the file <code>hello-world.c</code> and change the following line:
 +
<pre>
 +
  etimer_set(&timer, CLOCK_SECOND * 10);
 +
</pre>
 +
Into the following one:
 +
<pre>
 +
  etimer_set(&timer, CLOCK_SECOND * 120);
 +
</pre>
 +
The reason we do this is because we'll be opening a 'shell' to the device later on and having the "''Hello World''" prompt interrupting the shell session every 10 seconds is annoying.
 +
 +
6) Edit the <code>Makefile</code> and add the line <code>MODULES += os/services/shell</code> just below the <code>all: $(CONTIKI_PROJECT)</code> line. The end result should look like this:
 +
<pre>
 +
CONTIKI_PROJECT = hello-world
 +
all: $(CONTIKI_PROJECT)
 +
 +
MODULES += os/services/shell
 +
 +
CONTIKI = ../..
 +
include $(CONTIKI)/Makefile.include
 +
</pre>
 +
 +
7) Run <code>make distclean</code> to ensure the build environment is clean
 +
 +
8) Compile the hello-world application for the Openmote platform using the following command
 +
<pre>
 +
make TARGET=openmote BOARD=openmote-cc2538
 +
</pre>
 +
 +
9) Flash the hello-world application on the device using the following command:
 +
<pre>
 +
sudo make TARGET=openmote BOARD=openmote-cc2538 PORT=/dev/ttyOPENUSB hello-world.upload
 +
</pre>
 +
 +
10) Connect with <code>picocom</code> to the serial port of the openmote:
 +
<pre>
 +
sudo picocom -c -b 115200 --imap lfcrlf /dev/ttyOPENUSB
 +
</pre>
 +
In the above command:
 +
* <code>115200</code> is the baudrate
 +
* <code>-c</code> turns on local echo (so you can see what you type)
 +
* <code>--imap lfcrlf</code> automaticall converts the "\n" printed by the Openmote into "\r\n" so the terminal behaves as you expect it to
 +
 +
11) Type <code>help</code> and press enter to see a list of all commands available
 +
 +
=== Pinging from one node to another ===
 +
 +
If you've followed the steps above you should now have two 'terminal' windows open. One where you are logged in to the serial console of the OpenUSB devices of <code>nodeTX</code> and one where you are logged in to the console of the OpenUSB device connected to <code>nodeRX</code>.
 +
 +
 +
12) In the <code>nodeRX</code> terminal, enter <code>ip-addr</code> and press enter to retrieve the link-local address of the Openmote. The result should be similar to this:
 +
<pre>
 +
#0012.4b00.0YYY.XXXX> ip-addr
 +
Node IPv6 addresses:
 +
-- fe80::212:4b00:YYY:XXXX
 +
#0012.4b00.0YYY.XXXX>
 +
</pre>
 +
 +
13) In the <code>nodeTX</code> terminal, enter the following command:
 +
<pre>ping <ip>
 +
</pre>
 +
Where <code><ip></code> is the ''ip-address'' of the <code>nodeRX</code>. The result should be similar to this:
 +
<pre>
 +
#0012.4b00.0YYY.ZZZZ> ping fe80::212:4b00:YYY:XXXX
 +
Pinging fe80::212:4b00:613:1506
 +
Received ping reply from fe80::212:4b00:YYY:XXXX, len 4, ttl 64, delay 78 ms
 +
</pre>
 +
 +
=== Experiment Cleanup ===
 +
 +
In both the <code>nodeTX</code> and <code>nodeTX</code> terminals, perform the following actions to clean up the experiment:
 +
 +
1) Press the 'Control' key and then press the 'A' and 'X' one after the other while holding the 'Control' key pressed down. This control-sequence stops the running <code>picocom</code> program
 +
 +
2) From the <code>examples/hello-world</code> directory in the contiki-ng source tree, run the following command to wipe the flash on the OpenUSB device:
 +
<pre>
 +
../../tools/cc2538-bsl/cc2538-bsl.py -e -p /dev/ttyOPENUSB --bootloader-invert-lines
 +
</pre>
 +
It is important you do this since otherwise the OpenUSB devices will remain accessible over the wireless interface.

Latest revision as of 14:30, 5 April 2023

This quick start guide will explain how to get started with the "LoRa" (EFM32GG+RFM95W) an the OpenUSB modules of the Citylab testbed nodes.

Prerequisites

This quick start guide assumes you already have access to the Citylab Testbed and that you are familiar with the steps required to start experiments. If that is not the case then please follow the Getting Started guide first.


Experiment Setup

  • Open the JFed GUI, create a new experiment and drag in two wireless nodes.

Experiment Setup

  • Configure the nodes. Make sure that you:
    • Set the correct testbed for the node (defaults to w-iLab.2, needs to be set to Citylab)
    • Set Disk image to Ubuntu 20.04 LTS 64-bit (CoT) with ARM gcc compiler. This is important as we'll need the ARM gcc toolchain to compile the images for the devices.
    • Explicitly set the specific node to use. Make sure that the nodes you select are within range of each other!. You can use the Node Map to help you with this.
    • name one of the nodes nodeTX and the other one <nodeRX>. You can use other node names but those are the node names that will be used throughout this guide.

Experiment Setup

  • Click "Run" to start the experiment and wait the the nodes to finish initialising. Important: It'll take a bit longer than usual to start the experiment as the Ubuntu 20.04 LTS 64-bit (CoT) with ARM gcc compiler image we're using in this experiment is quite large so it'll take some time to load it onto the nodes.

Getting started with the EFM32GG+RFM95W (LoRa) module

To help you get started with the "EFM32GG+RFM95W" module, we've ported the LoraWAN network stack to the "EFM32GG+RFM95W". This port can be found in the following Github repository:

In this guide, we'll use that repository to set up a basic broadcast tx/rx between two nodes but the stack has many other capabilities as well.

Preparing the receiver node

1) SSH into the nodeRX and clone the LoRaMac-node repository 

git clone https://github.com/imec-idlab/LoRaMac-node

2) Change to the root dir of the repository 

cd LoraMac-node

3) Edit the file Makefile.local and make sure it has the following contents: 

TARGET = beacon_rx
CFLAGS += -DUSE_BAND_868=1
CFLAGS += -DUSE_MODEM_LORA=1

The TARGET line tells the compiler which application to build. The other lines tell the application to use the LoRa radio in the 868MHz band 4) Compile the binary using the make command: 

make -j4

If all went well you should now have a file named beacon_rx.bin in the local directory. If you get a complaint that no compiler could be found then, most likely you are not using the correct disk image. 5) Flash the binary onto the EFM32GG device using the flash_lora script: 

flash_lora ./beacon_rx.bin

6) Use picocom to listen to the serial port of the 'Lora' device 

sudo picocom -b 115200 /dev/ttyLORA

In the above command:

  • 115200 is the baud rate to use
  • /dev/ttyLORA is the path to the serial port of the Lora device. (This is a symlink to the actual 'ttyUSB' device that auto-generated via udev-rules present in all 'CoT' disk images)

At this point you won't see anything yet, but once the transmitter node has also been prepared you'll see text appearing here

Preparing the transmitter node

The steps needed to prepare the transmitter node are almost identical to the steps needed to prepare the receiver node.

1) Open a new terminal, SSH into the nodeTX and clone the LoRaMac-node repository

2) Change to the root dir of the repository

3) Edit the file Makefile.local and make sure it has the following contents: 

TARGET = beacon_tx
CFLAGS += -DUSE_BAND_868=1
CFLAGS += -DUSE_MODEM_LORA=1

The only difference between the Makefile.local used here and the one used for the receiver is that we are now building the beacon_tx rather than the beacon_rx app. The TARGET line tells the compiler which application to build. The other lines tell the application to use the LoRa radio in the 868MHz band

4) Compile the binary using the make command.

5) Flash the binary onto the EFM32GG device using the flash_lora script: 

flash_lora ./beacon_tx.bin

6) Use picocom to listen to the serial port of the 'Lora' device 

sudo picocom -b 115200 /dev/ttyLORA

You should now see lines similar to the ones below appearing: 

Sent Packet using LORA. size=16, counter=3 TimeOnAir(us)=52
Sent Packet using LORA. size=16, counter=4 TimeOnAir(us)=52
Sent Packet using LORA. size=16, counter=5 TimeOnAir(us)=52

7) Switch back to the terminal of the nodeRX testbed node. You should see lines similar to the ones below appearing 

0x520B4614248AB601,10,-33,25
0x520B4614248AB601,11,-35,25
0x520B4614248AB601,12,-34,26
0x520B4614248AB601,13,-33,24

In the reported lines, the first field is the UUID of the node sending the beacons, the second field is the sequence number of the packet and the 3rd & 4th fields are the RSSI & LQI of the received beacon packet.

Experiment Cleanup

In both the nodeTX and nodeTX terminals, perform the following actions to clean up the experiment:

1) Press the 'Control' key and then press the 'A' and 'X' one after the other while holding the 'Control' key pressed down. This control-sequence stops the running picocom program

2) Run the erase_lora program to wipe the LoRa devices. 

erase_lora

It is important you do this since otherwise the transmitter node will keep sending beacons.

Running Contiki-NG on the OpenUSB Radios

For this guide we re-use the same JFed experiment setup as for the 'LoRa device' (discussed above). In this section we'll flash two OpenUSB devices and ping from one to the other. The guide in this section is based on the Hello World, Shell and IPv6 Ping tutorials on the Contiki-NG documentation website, but focusses specifically on the OpenMote platform.

For more information on how to use Contiki-NG consult the Contiki-NG documentation at:

Cloning, Compiling & Flashing the nodes

1) SSH into both the nodeTX and nodeRX experiment nodes in two separate terminals. Then perform the steps below on both experiment nodes

2) Clone the contiki-ng git repository 

git clone https://github.com/contiki-ng/contiki-ng/

3) Change to the root of the source tree 

cd contiki-ng

4) Pull in all submodules (please note: this will take a while) 

git submodule update --init --recursive

4) move to the 'app' directory of the hello-world example application 

cd examples/hello-world

5) Edit the file hello-world.c and change the following line: 

  etimer_set(&timer, CLOCK_SECOND * 10);

Into the following one: 

  etimer_set(&timer, CLOCK_SECOND * 120);

The reason we do this is because we'll be opening a 'shell' to the device later on and having the "Hello World" prompt interrupting the shell session every 10 seconds is annoying.

6) Edit the Makefile and add the line MODULES += os/services/shell just below the all: $(CONTIKI_PROJECT) line. The end result should look like this: 

CONTIKI_PROJECT = hello-world
all: $(CONTIKI_PROJECT)

MODULES += os/services/shell

CONTIKI = ../..
include $(CONTIKI)/Makefile.include

7) Run make distclean to ensure the build environment is clean

8) Compile the hello-world application for the Openmote platform using the following command 

make TARGET=openmote BOARD=openmote-cc2538

9) Flash the hello-world application on the device using the following command: 

sudo make TARGET=openmote BOARD=openmote-cc2538 PORT=/dev/ttyOPENUSB hello-world.upload

10) Connect with picocom to the serial port of the openmote: 

sudo picocom -c -b 115200 --imap lfcrlf /dev/ttyOPENUSB

In the above command:

  • 115200 is the baudrate
  • -c turns on local echo (so you can see what you type)
  • --imap lfcrlf automaticall converts the "\n" printed by the Openmote into "\r\n" so the terminal behaves as you expect it to

11) Type help and press enter to see a list of all commands available

Pinging from one node to another

If you've followed the steps above you should now have two 'terminal' windows open. One where you are logged in to the serial console of the OpenUSB devices of nodeTX and one where you are logged in to the console of the OpenUSB device connected to nodeRX.


12) In the nodeRX terminal, enter ip-addr and press enter to retrieve the link-local address of the Openmote. The result should be similar to this: 

#0012.4b00.0YYY.XXXX> ip-addr
Node IPv6 addresses:
-- fe80::212:4b00:YYY:XXXX
#0012.4b00.0YYY.XXXX>

13) In the nodeTX terminal, enter the following command: 

ping <ip>

Where <ip> is the ip-address of the nodeRX. The result should be similar to this: 

#0012.4b00.0YYY.ZZZZ> ping fe80::212:4b00:YYY:XXXX
Pinging fe80::212:4b00:613:1506
Received ping reply from fe80::212:4b00:YYY:XXXX, len 4, ttl 64, delay 78 ms

Experiment Cleanup

In both the nodeTX and nodeTX terminals, perform the following actions to clean up the experiment:

1) Press the 'Control' key and then press the 'A' and 'X' one after the other while holding the 'Control' key pressed down. This control-sequence stops the running picocom program

2) From the examples/hello-world directory in the contiki-ng source tree, run the following command to wipe the flash on the OpenUSB device: 

../../tools/cc2538-bsl/cc2538-bsl.py -e -p /dev/ttyOPENUSB --bootloader-invert-lines

It is important you do this since otherwise the OpenUSB devices will remain accessible over the wireless interface.

Retrieved from "https://doc.lab.cityofthings.eu/w/index.php?title=Embedded_Radios_Quick_Start_Guide&oldid=380"