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.

.. contents::
  :local:
  :depth: 2

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 :doc:`Get Started -- Creating Your First Project <../../get_started/project_create>` 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 install -v 
        apache-mynewt-core
        Downloading repository description for apache-mynewt-core... success!
        ...
        apache-mynewt-core successfully installed version 1.2.0-none
        ...

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=@apache-mynewt-core/apps/boot
    $ 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=@apache-mynewt-core/apps/boot
        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/apps/boot/boot.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:

| dr: The data rate on which the frame was sent.
| txpower: Transmit power level of the device.
| tries: # of attempts made to transmit the frame successfully.
| ack\_rxd: Was an acknowledgement received (0 no 1 yes).
| tx\_time\_on\_air: The on-air length of the frame (in milliseconds).
| uplink\_cntr: The frame uplink counter that this frame used.
| uplink\_freq: The frequency (logical) on which the frame was sent (in Hz).