LoRaWAN App¶
Objective¶
The purpose of this tutorial is to demonstrate how to build the lora app shell application for either a class A or class C lora device and to perform basic functions such as joining and sending data packets to a lora gateway/server.
NOTE: This tutorial presumes that you have a running lora gateway and lora network server. No description of the gateway/server is provided. It is expected that the user understands how to configure and operate the gateway/server so that it can communicate with a class A or class C device.
Hardware needed¶
Telenor EE02 module
Segger J-Link or similar debugger
LORA gateway
Laptop running Mac OS
It is assumed you have already installed newt tool.
It is assumed you understand the basics of the mynewt OS
3-wire serial cable to connect telenor module to your laptop
Some form of terminal emulation application running on your laptop.
Create a project.¶
Create a new project to hold your work. For a deeper understanding, you can read about project creation in Get Started – Creating Your First Project or just follow the commands below.
$ mkdir ~/dev
$ cd ~/dev
$ newt new mylora
Downloading project skeleton from apache/mynewt-blinky...
Installing skeleton in mylora...
Project mylora successfully created.
$ cd mylora
Install Everything¶
Now that you have defined the needed repositories, it’s time to install everything so that you can get started.
$ newt upgrade -v
Downloading repository mynewt-core (commit: master) ...
...
apache-mynewt-core successfully upgraded to version 1.7.0
...
Create the targets¶
Create two targets - one for the bootloader and one for the lora app shell application.
$ newt target create telee02_boot
$ newt target set telee02_boot bsp=@apache-mynewt-core/hw/bsp/telee02
$ newt target set telee02_boot app=@mcuboot/boot/mynewt
$ newt target set telee02_boot build_profile=optimized
$ newt target create lora_app_shell_telee02
$ newt target set lora_app_shell_telee02 bsp=@apache-mynewt-core/hw/bsp/telee02
$ newt target set lora_app_shell_telee02 app=@apache-mynewt-core/apps/lora_app_shell
$ newt target set lora_app_shell_telee02 build_profile=optimized
The lora app shell application requires a few additional system configuration variables. Create and edit a file called syscfg.yml in dev/mylora/targets/lora_app_shell. The file contents should be the following:
### Package: targets/lora_app_shell_telee02
syscfg.vals:
SHELL_CMD_ARGC_MAX: "20"
LORA_MAC_TIMER_NUM: "4"
TIMER_4: "1"
You can now “display” the targets you created to make sure they are correct:
$ newt target show telee02_boot
targets/telee02_boot
app=@mcuboot/boot/mynewt
bsp=@apache-mynewt-core/hw/bsp/telee02
build_profile=optimized
$ newt target show lora_app_shell_telee02
targets/lora_app_shell_telee02
app=@apache-mynewt-core/apps/lora_app_shell
bsp=@apache-mynewt-core/hw/bsp/telee02
build_profile=optimized
syscfg=LORA_MAC_TIMER_NUM=4:SHELL_CMD_ARGC_MAX=20:TIMER_4=1
Note: If you’ve already built and installed a bootloader for your ee02 module then you do not need to create a target for it here, or build and load it as below.
Build the target executables¶
$ newt clean telee02_boot
$ newt build telee02_boot
Building target targets/telee02_boot
Compiling repos/apache-mynewt-core/boot/bootutil/src/image_rsa.c
Compiling repos/apache-mynewt-core/boot/bootutil/src/image_ec.c
Compiling repos/apache-mynewt-core/boot/bootutil/src/image_ec256.c
. . .
Archiving telee02_boot-sysinit-app.a
Archiving util_mem.a
Linking /Users/wes/dev/wes/bin/targets/telee02_boot/app/boot/mynewt/mynewt.elf
Target successfully built: targets/telee02_boot
$ newt clean lora_app_shell_telee02
$ newt build lora_app_shell_telee02
Building target targets/lora_app_shell_telee02
Assembling repos/apache-mynewt-core/hw/bsp/telee02/src/arch/cortex_m4/gcc_startup_nrf52_split.s
Compiling repos/apache-mynewt-core/encoding/base64/src/hex.c
Compiling repos/apache-mynewt-core/encoding/base64/src/base64.c
. . .
Archiving util_mem.a
Archiving util_parse.a
Linking /Users/wes/dev/wes/bin/targets/lora_app_shell_telee02/app/apps/lora_app_shell/lora_app_shell.elf
Target successfully built: targets/lora_app_shell_telee0
Note: The newt clean step is not necessary but shown here for good measure.
Sign and create the application image¶
You must sign and version your application image to download it using newt to the board. Use the newt create-image command to perform this action. You may assign an arbitrary version (e.g. 1.0.0) to the image.
$ newt create-image lora_app_shell_telee02 0.0.0
App image succesfully generated: /Users/wes/dev/wes/bin/targets/lora_app_shell_telee02/app/apps/lora_app_shell/lora_app_shell.img
Note: Only the application image requires this step; the bootloader does not
Connect the board¶
Connect the evaluation board via micro-USB to your PC via USB cable. Connect the Segger J-link debugger to the 9-pin SWD connector. Connect the UART pins (RX, TX and GND) to the board. Terminal settings 115200, N, 8, 1.
Download bootloader and application¶
Note: If you want to erase the flash and load the image again, you can use JLinkExe to issue an erase command.
$ JLinkExe -device nRF52 -speed 4000 -if SWD
SEGGER J-Link Commander V5.12c (Compiled Apr 21 2016 16:05:51)
DLL version V5.12c, compiled Apr 21 2016 16:05:45
Connecting to J-Link via USB...O.K.
Firmware: J-Link OB-SAM3U128-V2-NordicSemi compiled Mar 15 2016 18:03:17
Hardware version: V1.00
S/N: 682863966
VTref = 3.300V
Type "connect" to establish a target connection, '?' for help
J-Link>erase
Cortex-M4 identified.
Erasing device (0;?i?)...
Comparing flash [100%] Done.
Erasing flash [100%] Done.
Verifying flash [100%] Done.
J-Link: Flash download: Total time needed: 0.363s (Prepare: 0.093s, Compare: 0.000s, Erase: 0.262s, Program: 0.000s, Verify: 0.000s, Restore: 0.008s)
Erasing done.
J-Link>exit
$
$ newt load telee02_boot
Loading bootloader
$ newt load lora_app_shell_telee02
Loading app image into slot 1
Assuming you attached the serial port and have a terminal up you should set the following output on the terminal:
000002 lora_app_shell
### Shell Commands
There are a number of shell commands that will allow you to join and send both unconfirmed and confirmed data. If you type ‘help’ in your terminal you will see the various commands displayed. Here is a screen shot of the output of help
000002 lora_app_shell
help
032766 help
032766 stat
032767 tasks
032768 mpool
032769 date
032770 las_wr_mib
032771 las_rd_mib
032772 las_rd_dev_eui
032773 las_wr_dev_eui
032774 las_rd_app_eui
032775 las_wr_app_eui
032776 las_rd_app_key
032777 las_wr_app_key
032778 las_app_port
032779 las_app_tx
032780 las_join
032781 las_link_chk
032782 compat>
The following table lists the commands and gives a brief description of the commands. The lora commands are described in more detail later in the tutorial as well as their syntax (syntax not shown in the table).
Command |
Description |
|---|---|
help |
Display list of available shell commands |
stat |
Display statistics. Syntax: stat <statistics group>. ‘stat’ with no group displays avaialable groups |
tasks |
Display OS tasks |
mpool |
Displays OS memory pools and memory pool statistics |
date |
Displays current date/time |
las_wr_mib |
Write lora MIB |
las_rd_mib |
Read lora MIB |
las_rd_dev_eui |
Read lora device EUI |
las_wr_dev_eui |
Write lora device EUI |
las_rd_app_eui |
Read lora application EUI |
las_wr_app_eui |
Write lora application EUI |
las_rd_app_key |
Read lora application key |
las_wr_app_key |
Write lora application key |
las_app_port |
Open/close lora application port |
las_app_tx |
Transmit on lora application port |
las_join |
Perform a lora OTA join |
las_link_chk |
Perform a lora link check |
OTA Join¶
Before sending any application data a lora end device must be joined to its lora network. To perform a lora OTA (over-the-air) join there are some commands that must be issued prior to attempting to join. The reason for these commands is that a lora end device must be configured with a device EUI, application EUI and application key prior to performing an OTA join.
598763 compat> las_wr_app_eui 0x00:0x11:0x22:0x01:0x01:0x00:0x10:10
623106 compat> las_wr_app_key 03:03:03:03:03:03:03:03:03:03:03:03:03:03:03:03
623758 compat> las_wr_dev_eui 0x00:0x11:0x22:0x02:0x02:0x00:0x00:0x00
630333 compat> las_join 1
630634 Attempting to join...
019802 compat> Join cb. status=0 attempts=1
If the join is successful the status returned should be 0. If it fails the status will be a non-zero lora status code (lora status error codes are described later in this tutorial).
A note about “endianness” in the device EUI commands. The first three bytes of the EUI are the OUI and the last 5 bytes are unique (for that OUI). The above example assumes an OUI of 001122. This is not the same order as the address over the air as device addresses are sent “least significant byte” first (little endian). The same convention also applies to keys: they are in big-endian order in the command but sent little endian over the air.
Opening/closing an application port¶
Another step that must be performed prior to sending application data is to open an application port. All data frames containing application data are sent to a specific port. Port numbers are in the range 1 - 223 as port 0 is reserved for MLME-related activities. Ports 224-255 are reserved for future standardized application extensions.
The lora app shell does not open any application ports by default.
To open and/or close an application port the following commands are used. Note that the application port which you are using to send data must be open if you want to send data (or receive it).
115647 compat> las_app_port open 1
150958 Opened app port 1
150958 compat> las_app_port close 1
151882 Closed app port 1
Sending data¶
The lora app shell allows the user to send both unconfirmed and confirmed data. The command to send data is las_app_tx <port> <len> <type>
NOTE: the current usage for this command shows an optional data rate and retries for this command. That feature has not been implemented and the command will not be accepted if they are separated.
Where: port = port number on which to send len = size n bytes of app data type = 0 for unconfirmed, 1 for confirmed
To send a confirmed data transmission of size 5 bytes on port 10 the command would be: las_app_tx 10 20 1
Once the end device has sent the frame requested there should be a message which contains some additional information. Here is a screen shot using the above example. Note that there will be some delay between seeing the “Packet sent on port 10” message and the additional information as the additional information is the “confirmation” that the lora stack provides and the confirmation will not be returned until the lora stack is finished transmitting the frame and has received an acknowledgement or has finished waiting for all the receive windows.
449751 compat> las_app_tx 10 5 1
452144 Packet sent on port 10
452144 compat> Txd on port 10 type=conf status=0 len=5
452325 dr:0
452325 txpower:5
452325 tries:1
452326 ack_rxd:1
452326 tx_time_on_air:330
452327 uplink_cntr:0
452327 uplink_freq:903500000
The information contained in the confirmation is the following: