Jose Rios / Mbed OS xdot-test

Basic xdot code to check how many memory is available for user APP after initializing libxdot lorawan stack

README.md@42:20f6b29a9903, 2021-05-25 (annotated)

Committer:
Taylor Heck
Date:
Tue May 25 09:54:33 2021 -0500
Revision:
42:20f6b29a9903
Target mbed-os 6 and Dot Library version 4.

Who changed what in which revision?

UserRevisionLine numberNew contents of line
Taylor Heck 42:20f6b29a9903 1 # dot-examples
Taylor Heck 42:20f6b29a9903 2 Example programs for MultiTech Dot devices demonstrating how to use the Dot devices and the Dot libraries for LoRa communication.
Taylor Heck 42:20f6b29a9903 3
Taylor Heck 42:20f6b29a9903 4 ## Instructions for building Dot-Examples
Taylor Heck 42:20f6b29a9903 5
Taylor Heck 42:20f6b29a9903 6 1. Import dot-examples
Taylor Heck 42:20f6b29a9903 7 $ mbed import http://os.mbed.com/teams/MultiTech/code/Dot-Examples/
Taylor Heck 42:20f6b29a9903 8
Taylor Heck 42:20f6b29a9903 9 2. Change directory to the Dot-Examples/examples and import the dot library stack
Taylor Heck 42:20f6b29a9903 10 Choose either the stable or dev library for your dot device
Taylor Heck 42:20f6b29a9903 11 e.g. to get the latest development library for the xDot
Taylor Heck 42:20f6b29a9903 12 $ mbed add http://os.mbed.com/teams/MultiTech/code/libxDot-dev/
Taylor Heck 42:20f6b29a9903 13
Taylor Heck 42:20f6b29a9903 14 3. Update mbed-os revision to match that of the dot library you just imported.
Taylor Heck 42:20f6b29a9903 15 This information can be found in the library's commit history.
Taylor Heck 42:20f6b29a9903 16 e.g.
Taylor Heck 42:20f6b29a9903 17 $ cd Dot-Examples/mbed-os
Taylor Heck 42:20f6b29a9903 18 $ mbed update mbed-os-6.1.0
Taylor Heck 42:20f6b29a9903 19
Taylor Heck 42:20f6b29a9903 20 4. Modify the Dot-Examples/examples/example_config.h to select the channel plan and which example to build
Taylor Heck 42:20f6b29a9903 21 By default, the OTA example is selected to build with the US channel plan
Taylor Heck 42:20f6b29a9903 22
Taylor Heck 42:20f6b29a9903 23 5. Once the example is selected, modify the example source file to match the configuration of your gateway.
Taylor Heck 42:20f6b29a9903 24 Make sure the network_name, network_passphrase, frequency_sub_band (US), public_network, and join_delay settings match that of your gateway
Taylor Heck 42:20f6b29a9903 25
Taylor Heck 42:20f6b29a9903 26 ### Compiler Versions
Taylor Heck 42:20f6b29a9903 27
Taylor Heck 42:20f6b29a9903 28 * [Arm Compiler](https://developer.arm.com/tools-and-software/embedded/arm-compiler/downloads/version-6) version 6.11 or newer
Taylor Heck 42:20f6b29a9903 29 * [GNU Arm Embedded Toolchain](https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm/downloads) version 9 2019-q4-major or newer
Taylor Heck 42:20f6b29a9903 30
Taylor Heck 42:20f6b29a9903 31 _When compiling for XDot GCC can cause out-of-memory errors._
Taylor Heck 42:20f6b29a9903 32
Taylor Heck 42:20f6b29a9903 33 ### Programming Over Serial
Taylor Heck 42:20f6b29a9903 34
Taylor Heck 42:20f6b29a9903 35 The lastest bootloader requires firmware images to be application only and have a CRC appended. [Multitool](https://pypi.org/project/mtsmultitool) can be used to transfer firmware files over serial.
Taylor Heck 42:20f6b29a9903 36
Taylor Heck 42:20f6b29a9903 37 Example multitool commands for stripping the bootloader, appending a CRC, and sending a file to an mDot or xDot over serial.
Taylor Heck 42:20f6b29a9903 38 ```
Taylor Heck 42:20f6b29a9903 39 multitool device upgrade -b COM3 MTDOT mbed_output.bin
Taylor Heck 42:20f6b29a9903 40 multitool device upgrade -b COM3 XDOT mbed_output.bin
Taylor Heck 42:20f6b29a9903 41 ```
Taylor Heck 42:20f6b29a9903 42
Taylor Heck 42:20f6b29a9903 43 ## Example Programs Description
Taylor Heck 42:20f6b29a9903 44 This application contains multiple example programs. Each example demonstrates a different way to configure and use a Dot. A short summary of each example is provided below. Common code used by multiple examples is in the dot_utils.cpp file.
Taylor Heck 42:20f6b29a9903 45
Taylor Heck 42:20f6b29a9903 46 All examples print logging, including RX data, on the USB debug port at 115200 baud. Each example defaults the Dot's configuration and saves the new configuration to NVM.
Taylor Heck 42:20f6b29a9903 47
Taylor Heck 42:20f6b29a9903 48 ### OTA Example
Taylor Heck 42:20f6b29a9903 49 This example demonstrates configuring the Dot for OTA join mode and entering sleep or deepsleep mode between transactions with the gateway. If deepsleep mode is used, the session is saved and restored so that a rejoin is not necessary after waking up even though RAM contents have been lost. ACKs are disabled, but network link checks are configured - if enough link checks are missed, the Dot will no longer be considered joined to the network and will attempt to rejoin before transmitting more data.
Taylor Heck 42:20f6b29a9903 50
Taylor Heck 42:20f6b29a9903 51 ### AUTO_OTA Example
Taylor Heck 42:20f6b29a9903 52 This example demonstrates configuring the Dot for AUTO_OTA join mode and entering sleep or deepsleep mode between transactions with the gateway. AUTO_OTA join mode automatically saves and restores the session when deepsleep mode is used, so the manual saving and restoring of the session is not necessary. ACKs are disabled, but network link checks are configured - if enough link checks are missed, the Dot will no longer be considered joined to the network and will attempt to rejoin before transmitting more data.
Taylor Heck 42:20f6b29a9903 53
Taylor Heck 42:20f6b29a9903 54 ### Manual Example
Taylor Heck 42:20f6b29a9903 55 This example demonstrates configuring the Dot for MANUAL join mode and entering sleep or deepsleep mode between transactions with the gateway. The Dot must be provisioned on the gateway before its packets will be accepted! Follow these steps to provision the Dot on a Conduit gateway:
Taylor Heck 42:20f6b29a9903 56
Taylor Heck 42:20f6b29a9903 57 * ssh into the conduit
Taylor Heck 42:20f6b29a9903 58 * use the lora-query application to provision the Dot on the gateway
Taylor Heck 42:20f6b29a9903 59 lora-query -a 01020304 A 0102030401020304 <your Dot's device ID> 01020304010203040102030401020304 01020304010203040102030401020304
Taylor Heck 42:20f6b29a9903 60 * if any of the credentials change on the Dot side, they must be updated on the gateway side as well
Taylor Heck 42:20f6b29a9903 61 To provision a Dot on a third-party gateway, see the gateway or network provider documentation.
Taylor Heck 42:20f6b29a9903 62
Taylor Heck 42:20f6b29a9903 63 ### Class C Example
Taylor Heck 42:20f6b29a9903 64 This example demonstrates configuring the Dot for OTA join mode and communicating with the gateway using class C mode. In class C mode the gateway can send a packet to the Dot at any time, so it must be listening whenever it is not transmitting. This means that the Dot cannot enter sleep or deepsleep mode. The gateway will not immediately send packets to the Dot (outside the receive windows following a transmission from the Dot) until it is informed that the Dot is operating in class C mode. The lora-query application can be used to configure a Conduit gateway to communicate with a Dot in class C mode. For information on how to inform a third-party gateway that a Dot is operating in class C mode, see the gateway or network provider documentation.
Taylor Heck 42:20f6b29a9903 65
Taylor Heck 42:20f6b29a9903 66 ### Class B Example
Taylor Heck 42:20f6b29a9903 67 This example demonstrates how to configure the dot for an OTA join, how to acquire a lock on a GPS synchronized beacon, and then to subsequently enter class B mode of operation. After a successful join, the device will request to the dot-library to switch to class B. When this happens, the library will send an uplink to the network server (hence we must be joined first before entering this mode) requesting the GPS time to calculate when the next beacon is expected. Once this time elapses, the dot will open an rx window to demodulate the broadcasted beacon and fire an mDotEvent::BeaconRx event upon successful reception. After the beacon is received, the example sends an uplink which will have the class B bit in the packet's frame control set to indicate to the network server that downlinks may now be scheduled on ping slots. The lora-query application can be used to configure a Conduit gateway to communicate with a Dot in class B mode. For information on how to inform a third-party gateway that a Dot is operating in class B mode, see the gateway or network provider documentation.
Taylor Heck 42:20f6b29a9903 68
Taylor Heck 42:20f6b29a9903 69 ### FOTA Example
Taylor Heck 42:20f6b29a9903 70 Full FOTA support is available on mDot and on xDot with external flash. See [this article](https://multitechsystems.github.io/dot-development-xdot) for details on adding external flash for xDot FOTA.
Taylor Heck 42:20f6b29a9903 71
Taylor Heck 42:20f6b29a9903 72 Without external flash xDot can use the FOTA example to dynamically join a multicast session only. After joining the multicast session the received Fragmentation packets could be handed to a host MCU for processing and at completion the firmware can be loaded into the xDot using the bootloader and y-modem. See [xDot Developer Guide](https://www.multitech.com/brands/multiconnect-xdot).
Taylor Heck 42:20f6b29a9903 73
Taylor Heck 42:20f6b29a9903 74 This example demonstrates how to incorporate over-the-air updates to an application. The example uses a Class C application. Class A or B functionality could also be used. The device will automatically enter into Class C operation for the FOTA operation, Class B would be disabled during the FOTA transfer.
Taylor Heck 42:20f6b29a9903 75
Taylor Heck 42:20f6b29a9903 76 Add the following code to allow Fota to use the Dot instance
Taylor Heck 42:20f6b29a9903 77 >examples/src/fota_example.cpp
Taylor Heck 42:20f6b29a9903 78 ```c
Taylor Heck 42:20f6b29a9903 79 // Initialize FOTA singleton
Taylor Heck 42:20f6b29a9903 80 Fota::getInstance(dot);
Taylor Heck 42:20f6b29a9903 81 ```
Taylor Heck 42:20f6b29a9903 82
Taylor Heck 42:20f6b29a9903 83 Add fragmentation handling the the PacketRx event
Taylor Heck 42:20f6b29a9903 84
Taylor Heck 42:20f6b29a9903 85 Note: The type for snr changed from int8_t in 3.2.x to int16_t in 3.3.x library
Taylor Heck 42:20f6b29a9903 86
Taylor Heck 42:20f6b29a9903 87 >examples/inc/RadioEvent.h
Taylor Heck 42:20f6b29a9903 88 ```c
Taylor Heck 42:20f6b29a9903 89 virtual void PacketRx(uint8_t port, uint8_t *payload, uint16_t size, int16_t rssi, int16_t snr, lora::DownlinkControl ctrl, uint8_t slot, uint8_t retries, uint32_t address, uint32_t fcnt, bool dupRx) {
Taylor Heck 42:20f6b29a9903 90 mDotEvent::PacketRx(port, payload, size, rssi, snr, ctrl, slot, retries, address, fcnt, dupRx);
Taylor Heck 42:20f6b29a9903 91
Taylor Heck 42:20f6b29a9903 92 #if ACTIVE_EXAMPLE == FOTA_EXAMPLE
Taylor Heck 42:20f6b29a9903 93 if(port == 200 || port == 201 || port == 202) {
Taylor Heck 42:20f6b29a9903 94 Fota::getInstance()->processCmd(payload, port, size);
Taylor Heck 42:20f6b29a9903 95 }
Taylor Heck 42:20f6b29a9903 96 #endif
Taylor Heck 42:20f6b29a9903 97 }
Taylor Heck 42:20f6b29a9903 98 ```
Taylor Heck 42:20f6b29a9903 99
Taylor Heck 42:20f6b29a9903 100 The FOTA implementation has a few differences from the [LoRaWAN FOTA Protocol](https://lora-alliance.org/resource-hub/lorawan-fragmented-data-block-transport-specification-v100)
Taylor Heck 42:20f6b29a9903 101 * Fragmentation Indexing starts at 0
Taylor Heck 42:20f6b29a9903 102 * McKEKey is 00-00-00-00-00-00-00-00-00-00-00-00-00-00-00-00
Taylor Heck 42:20f6b29a9903 103 * Start Time is a count-down in seconds to start of session
Taylor Heck 42:20f6b29a9903 104
Taylor Heck 42:20f6b29a9903 105
Taylor Heck 42:20f6b29a9903 106 ### Peer to Peer Example
Taylor Heck 42:20f6b29a9903 107 This example demonstrates configuring Dots for peer to peer communication without a gateway. It should be compiled and run on two Dots. Peer to peer communication uses LoRa modulation but uses a single higher throughput (usually 500kHz or 250kHz) datarate. It is similar to class C operation - when a Dot isn't transmitting, it's listening for packets from the other Dot. Both Dots must be configured exactly the same for peer to peer communication to be successful.
Taylor Heck 42:20f6b29a9903 108
Taylor Heck 42:20f6b29a9903 109
Taylor Heck 42:20f6b29a9903 110 ## Choosing An Example Program and Channel Plan
Taylor Heck 42:20f6b29a9903 111 Only the active example is compiled. The active example can be updated by changing the **ACTIVE_EXAMPLE** definition in the examples/example_config.h file.
Taylor Heck 42:20f6b29a9903 112
Taylor Heck 42:20f6b29a9903 113 By default the OTA_EXAMPLE will be compiled and the US915 channel plan will be used.
Taylor Heck 42:20f6b29a9903 114 >example_config.h
Taylor Heck 42:20f6b29a9903 115
Taylor Heck 42:20f6b29a9903 116 ```c
Taylor Heck 42:20f6b29a9903 117 #ifndef __EXAMPLE__CONFIG_H__
Taylor Heck 42:20f6b29a9903 118 #define __EXAMPLE__CONFIG_H__
Taylor Heck 42:20f6b29a9903 119
Taylor Heck 42:20f6b29a9903 120 #define OTA_EXAMPLE 1 // see ota_example.cpp
Taylor Heck 42:20f6b29a9903 121 #define AUTO_OTA_EXAMPLE 2 // see auto_ota_example.cpp
Taylor Heck 42:20f6b29a9903 122 #define MANUAL_EXAMPLE 3 // see manual_example.cpp
Taylor Heck 42:20f6b29a9903 123 #define PEER_TO_PEER_EXAMPLE 4 // see peer_to_peer_example.cpp
Taylor Heck 42:20f6b29a9903 124 #define CLASS_C_EXAMPLE 5 // see class_c_example.cpp
Taylor Heck 42:20f6b29a9903 125 #define CLASS_B_EXAMPLE 6 // see class_b_example.cpp
Taylor Heck 42:20f6b29a9903 126 #define FOTA_EXAMPLE 7 // see fota_example.cpp
Taylor Heck 42:20f6b29a9903 127
Taylor Heck 42:20f6b29a9903 128 // the active example is the one that will be compiled
Taylor Heck 42:20f6b29a9903 129 #if !defined(ACTIVE_EXAMPLE)
Taylor Heck 42:20f6b29a9903 130 #define ACTIVE_EXAMPLE OTA_EXAMPLE
Taylor Heck 42:20f6b29a9903 131 #endif
Taylor Heck 42:20f6b29a9903 132
Taylor Heck 42:20f6b29a9903 133 // the active channel plan is the one that will be compiled
Taylor Heck 42:20f6b29a9903 134 // options are :
Taylor Heck 42:20f6b29a9903 135 // CP_US915
Taylor Heck 42:20f6b29a9903 136 // CP_AU915
Taylor Heck 42:20f6b29a9903 137 // CP_EU868
Taylor Heck 42:20f6b29a9903 138 // CP_KR920
Taylor Heck 42:20f6b29a9903 139 // CP_AS923
Taylor Heck 42:20f6b29a9903 140 // CP_AS923_JAPAN
Taylor Heck 42:20f6b29a9903 141 #if !defined(CHANNEL_PLAN)
Taylor Heck 42:20f6b29a9903 142 #define CHANNEL_PLAN CP_US915
Taylor Heck 42:20f6b29a9903 143 #endif
Taylor Heck 42:20f6b29a9903 144
Taylor Heck 42:20f6b29a9903 145 #endif
Taylor Heck 42:20f6b29a9903 146 ```
Taylor Heck 42:20f6b29a9903 147
Taylor Heck 42:20f6b29a9903 148 Compile the AUTO_OTA_EXAMPLE and use the EU868 channel plan instead.
Taylor Heck 42:20f6b29a9903 149 ```c
Taylor Heck 42:20f6b29a9903 150 #ifndef __EXAMPLE__CONFIG_H__
Taylor Heck 42:20f6b29a9903 151 #define __EXAMPLE__CONFIG_H__
Taylor Heck 42:20f6b29a9903 152
Taylor Heck 42:20f6b29a9903 153 #define OTA_EXAMPLE 1 // see ota_example.cpp
Taylor Heck 42:20f6b29a9903 154 #define AUTO_OTA_EXAMPLE 2 // see auto_ota_example.cpp
Taylor Heck 42:20f6b29a9903 155 #define MANUAL_EXAMPLE 3 // see manual_example.cpp
Taylor Heck 42:20f6b29a9903 156 #define PEER_TO_PEER_EXAMPLE 4 // see peer_to_peer_example.cpp
Taylor Heck 42:20f6b29a9903 157 #define CLASS_C_EXAMPLE 5 // see class_c_example.cpp
Taylor Heck 42:20f6b29a9903 158
Taylor Heck 42:20f6b29a9903 159 // the active example is the one that will be compiled
Taylor Heck 42:20f6b29a9903 160 #if !defined(ACTIVE_EXAMPLE)
Taylor Heck 42:20f6b29a9903 161 #define ACTIVE_EXAMPLE AUTO_OTA_EXAMPLE
Taylor Heck 42:20f6b29a9903 162 #endif
Taylor Heck 42:20f6b29a9903 163
Taylor Heck 42:20f6b29a9903 164 // the active channel plan is the one that will be compiled
Taylor Heck 42:20f6b29a9903 165 // options are :
Taylor Heck 42:20f6b29a9903 166 // CP_US915
Taylor Heck 42:20f6b29a9903 167 // CP_AU915
Taylor Heck 42:20f6b29a9903 168 // CP_EU868
Taylor Heck 42:20f6b29a9903 169 // CP_KR920
Taylor Heck 42:20f6b29a9903 170 // CP_AS923
Taylor Heck 42:20f6b29a9903 171 // CP_AS923_JAPAN
Taylor Heck 42:20f6b29a9903 172 #if !defined(CHANNEL_PLAN)
Taylor Heck 42:20f6b29a9903 173 #define CHANNEL_PLAN CP_EU868
Taylor Heck 42:20f6b29a9903 174 #endif
Taylor Heck 42:20f6b29a9903 175
Taylor Heck 42:20f6b29a9903 176 #endif
Taylor Heck 42:20f6b29a9903 177 ```
Taylor Heck 42:20f6b29a9903 178
Taylor Heck 42:20f6b29a9903 179 ## Dot Libraries
Taylor Heck 42:20f6b29a9903 180 Stable and development libraries are available for both mDot and xDot platforms. The library chosen must match the target platform. Compiling for the mDot platform with the xDot library or vice versa will not succeed.
Taylor Heck 42:20f6b29a9903 181
Taylor Heck 42:20f6b29a9903 182 ### mDot Library
Taylor Heck 42:20f6b29a9903 183 #### Development library for mDot
Taylor Heck 42:20f6b29a9903 184
Taylor Heck 42:20f6b29a9903 185 Bleeding edge development version of the mDot library for mbed 6. This version of the library is not guaranteed to be stable or well tested and should not be used in production or deployment scenarios.
Taylor Heck 42:20f6b29a9903 186
Taylor Heck 42:20f6b29a9903 187 mbed add [https://github.com/MultiTechSystems/libmDot-dev](https://github.com/MultiTechSystems/libmDot-dev)
Taylor Heck 42:20f6b29a9903 188
Taylor Heck 42:20f6b29a9903 189 #### Stable library for mDot
Taylor Heck 42:20f6b29a9903 190
Taylor Heck 42:20f6b29a9903 191 Stable version of the mDot library for mbed 6. This version of the library is suitable for deployment scenarios. See lastest commit message for version of mbed-os library that has been tested against.
Taylor Heck 42:20f6b29a9903 192
Taylor Heck 42:20f6b29a9903 193 mbed add [https://github.com/MultiTechSystems/libmDot](https://github.com/MultiTechSystems/libmDot)
Taylor Heck 42:20f6b29a9903 194
Taylor Heck 42:20f6b29a9903 195 ### xDot Library
Taylor Heck 42:20f6b29a9903 196 #### Development library for xDot
Taylor Heck 42:20f6b29a9903 197 Bleeding edge development version of the xDot library for mbed 6. This version of the library is not guaranteed to be stable or well tested and should not be used in production or deployment scenarios.
Taylor Heck 42:20f6b29a9903 198
Taylor Heck 42:20f6b29a9903 199 mbed add [https://github.com/MultiTechSystems/libxDot-dev](https://github.com/MultiTechSystems/libxDot-dev)
Taylor Heck 42:20f6b29a9903 200
Taylor Heck 42:20f6b29a9903 201 #### Stable library for xDot
Taylor Heck 42:20f6b29a9903 202
Taylor Heck 42:20f6b29a9903 203 Stable version of the xDot library for mbed 6. This version of the library is suitable for deployment scenarios.
Taylor Heck 42:20f6b29a9903 204
Taylor Heck 42:20f6b29a9903 205 mbed add [https://github.com/MultiTechSystems/libxDot](https://github.com/MultiTechSystems/libxDot)