MultiTech / libmDot-mbed5

Stable version of the mDot library for mbed 5. 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.

Dependents:   mdot_two_way unh-hackathon-example unh-hackathon-example-raw TelitSensorToCloud ... more

Fork of libmDot-dev-mbed5-deprecated by MultiTech

The Dot library provides a LoRaWan certified stack for LoRa communication using MultiTech mDot and xDot devices. The stack is compatible with mbed 5.

The name of the repository can be used to determine which device the stack was compiled for and if it's a development or production-ready build:

A changelog for the Dot library can be found here.

The Dot library version and the version of mbed-os it was compiled against can both be found in the commit message for that revision of the Dot library. Building your application with the same version of mbed-os as what was used to build the Dot library is highly recommended!

The Dot-Examples repository demonstrates how to use the Dot library in a custom application.

The mDot and xDot platform pages have lots of platform specific information and document potential issues, gotchas, etc, and provide instructions for getting started with development. Please take a look at the platform page before starting development as they should answer many questions you will have.

FOTA

Full FOTA support is only available with mDot, xDot does not have the required 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.

  • Add the following code to allow Fota to use the Dot instance

main.cpp

    // Initialize FOTA singleton
    Fota::getInstance(dot);
  • Add fragmentation handling the the PacketRx event

RadioEvent.h

    virtual void PacketRx(uint8_t port, uint8_t *payload, uint16_t size, int16_t rssi, int8_t snr, lora::DownlinkControl ctrl, uint8_t slot, uint8_t retries, uint32_t address, bool dupRx) {
        mDotEvent::PacketRx(port, payload, size, rssi, snr, ctrl, slot, retries, address, dupRx);

#if ACTIVE_EXAMPLE == FOTA_EXAMPLE
        if(port == 200 || port == 201 || port == 202) {
            Fota::getInstance()->processCmd(payload, port, size);
        }
#endif
    }

A definition is needed to enable Fragmentation support on mDot and save fragments to flash. This should not be defined for xDot and will result in a compiler error.

mbed_app.json

{
    "macros": [
        "FOTA=1"
    ]
}

The FOTA implementation has a few differences from the LoRaWAN Protocol

  • Fragmentation Indexing starts at 0
  • McKEKey is 00-00-00-00-00-00-00-00-00-00-00-00-00-00-00-00
  • Start Time is a count-down in seconds to start of session

Mote.h@19:f3a46d2bb9b3, 2016-08-19 (annotated)

Committer:
Jenkins@KEILDM1.dc.multitech.prv
Date:
Fri Aug 19 16:23:07 2016 -0500
Revision:
19:f3a46d2bb9b3
Parent:
17:306ffaa5d79b
Child:
26:17479e0039f6
update from git revision 2.0.3-15-g0042cdf

Who changed what in which revision?

UserRevisionLine numberNew contents of line
Mike Fiore 16:b630e18103e5 1 /** __ ___ ____ _ ______ __ ____ __ ____
Mike Fiore 16:b630e18103e5 2 * / |/ /_ __/ / /_(_)__/_ __/__ ____/ / / __/_ _____ / /____ __ _ ___ / _/__ ____
Mike Fiore 16:b630e18103e5 3 * / /|_/ / // / / __/ /___// / / -_) __/ _ \ _\ \/ // (_-</ __/ -_) ' \(_-< _/ // _ \/ __/ __
Mike Fiore 16:b630e18103e5 4 * /_/ /_/\_,_/_/\__/_/ /_/ \__/\__/_//_/ /___/\_, /___/\__/\__/_/_/_/___/ /___/_//_/\__/ /_/
Mike Fiore 16:b630e18103e5 5 * Copyright (C) 2015 by Multi-Tech Systems /___/
Mike Fiore 16:b630e18103e5 6 *
Mike Fiore 16:b630e18103e5 7 *
Mike Fiore 16:b630e18103e5 8 * @author Jason Reiss
Mike Fiore 16:b630e18103e5 9 * @date 10-31-2015
Mike Fiore 16:b630e18103e5 10 * @brief lora::Mote provides a user level class that abstracts the complexity of the Mac layer
Mike Fiore 16:b630e18103e5 11 *
Mike Fiore 16:b630e18103e5 12 * @details
Mike Fiore 16:b630e18103e5 13 *
Mike Fiore 16:b630e18103e5 14 */
Mike Fiore 16:b630e18103e5 15
Mike Fiore 16:b630e18103e5 16 #ifndef __LORA_MOTE_H__
Mike Fiore 16:b630e18103e5 17 #define __LORA_MOTE_H__
Mike Fiore 16:b630e18103e5 18
Mike Fiore 16:b630e18103e5 19 #include "rtos.h"
Mike Fiore 16:b630e18103e5 20 #include "MacEvents.h"
Mike Fiore 16:b630e18103e5 21 #include <vector>
Mike Fiore 16:b630e18103e5 22
Mike Fiore 16:b630e18103e5 23 class SxRadio;
Mike Fiore 16:b630e18103e5 24 class SxRadio1272;
Mike Fiore 16:b630e18103e5 25
Mike Fiore 16:b630e18103e5 26 namespace lora {
Mike Fiore 16:b630e18103e5 27
Mike Fiore 16:b630e18103e5 28 class Mac;
Mike Fiore 16:b630e18103e5 29 class ChannelPlan;
Mike Fiore 16:b630e18103e5 30
Mike Fiore 16:b630e18103e5 31 class MoteEvents: public MacEvents {
Mike Fiore 16:b630e18103e5 32
Mike Fiore 16:b630e18103e5 33 /**
Mike Fiore 16:b630e18103e5 34 * Fired at end of TX
Mike Fiore 16:b630e18103e5 35 * @param dr datarate used for TX
Mike Fiore 16:b630e18103e5 36 */
Mike Fiore 16:b630e18103e5 37 virtual void TxDone(uint8_t dr);
Mike Fiore 16:b630e18103e5 38
Mike Fiore 16:b630e18103e5 39 /**
Mike Fiore 16:b630e18103e5 40 * Fired if TX timed out
Mike Fiore 16:b630e18103e5 41 */
Mike Fiore 16:b630e18103e5 42 virtual void TxTimeout(void);
Mike Fiore 16:b630e18103e5 43
Mike Fiore 16:b630e18103e5 44 /**
Mike Fiore 16:b630e18103e5 45 * Fired when JoinAccept message is received and MIC is validated
Mike Fiore 16:b630e18103e5 46 * @param payload received bytes
Mike Fiore 16:b630e18103e5 47 * @param size number of received bytes
Mike Fiore 16:b630e18103e5 48 * @param rssi of received packet
Mike Fiore 16:b630e18103e5 49 * @param snr of received packet
Mike Fiore 16:b630e18103e5 50 */
Mike Fiore 16:b630e18103e5 51 virtual void JoinAccept(uint8_t *payload, uint16_t size, int16_t rssi, int8_t snr);
Mike Fiore 16:b630e18103e5 52
Mike Fiore 16:b630e18103e5 53 /**
Mike Fiore 16:b630e18103e5 54 * Fired when JoinAccept message is received and MIC is not valid
Mike Fiore 16:b630e18103e5 55 * @param payload received bytes
Mike Fiore 16:b630e18103e5 56 * @param size number of received bytes
Mike Fiore 16:b630e18103e5 57 * @param rssi of received packet
Mike Fiore 16:b630e18103e5 58 * @param snr of received packet
Mike Fiore 16:b630e18103e5 59 */
Mike Fiore 16:b630e18103e5 60 virtual void JoinFailed(uint8_t *payload, uint16_t size, int16_t rssi, int8_t snr);
Mike Fiore 16:b630e18103e5 61
Mike Fiore 16:b630e18103e5 62 /**
Mike Fiore 16:b630e18103e5 63 * Fired when non duplicate packet is received and MIC is valid
Mike Fiore 16:b630e18103e5 64 * @param port of packet
Mike Fiore 16:b630e18103e5 65 * @param payload received bytes
Mike Fiore 16:b630e18103e5 66 * @param size number of received bytes
Mike Fiore 16:b630e18103e5 67 * @param rssi of received packet
Mike Fiore 16:b630e18103e5 68 * @param snr of received packet
Mike Fiore 16:b630e18103e5 69 * @param ctrl Downlink control field of packet
Mike Fiore 16:b630e18103e5 70 * @param slot rx window packet was received
Mike Fiore 16:b630e18103e5 71 * @param retries number of attempts before ack was received
Mike Fiore 16:b630e18103e5 72 */
Mike Fiore 16:b630e18103e5 73 virtual void PacketRx(uint8_t port, uint8_t *payload, uint16_t size, int16_t rssi, int8_t snr, lora::DownlinkControl ctrl, uint8_t slot, uint8_t retries = 0);
Mike Fiore 16:b630e18103e5 74
Mike Fiore 16:b630e18103e5 75 /**
Mike Fiore 16:b630e18103e5 76 * Fired when radio has received a packet, packet is not validated
Mike Fiore 16:b630e18103e5 77 * @param payload received bytes
Mike Fiore 16:b630e18103e5 78 * @param size number of received bytes
Mike Fiore 16:b630e18103e5 79 * @param rssi of received packet
Mike Fiore 16:b630e18103e5 80 * @param snr of received packet
Mike Fiore 16:b630e18103e5 81 * @param ctrl Downlink control field of packet
Mike Fiore 16:b630e18103e5 82 * @param slot rx window packet was received
Mike Fiore 16:b630e18103e5 83 */
Mike Fiore 16:b630e18103e5 84 virtual void RxDone(uint8_t *payload, uint16_t size, int16_t rssi, int8_t snr, lora::DownlinkControl ctrl, uint8_t slot);
Mike Fiore 16:b630e18103e5 85
Mike Fiore 16:b630e18103e5 86 /**
Mike Fiore 16:b630e18103e5 87 * Fired if rx window times out
Mike Fiore 16:b630e18103e5 88 * @param slot rx window that timed out
Mike Fiore 16:b630e18103e5 89 */
Mike Fiore 16:b630e18103e5 90 virtual void RxTimeout(uint8_t slot);
Mike Fiore 16:b630e18103e5 91
Mike Fiore 16:b630e18103e5 92 /**
Mike Fiore 16:b630e18103e5 93 * Fired if rx CRC error
Mike Fiore 16:b630e18103e5 94 * @param slot rx window that errored
Mike Fiore 16:b630e18103e5 95 */
Mike Fiore 16:b630e18103e5 96 virtual void RxError(uint8_t slot);
Mike Fiore 16:b630e18103e5 97
Mike Fiore 16:b630e18103e5 98 /**
Mike Fiore 16:b630e18103e5 99 * Fired if pong packet is received
Mike Fiore 16:b630e18103e5 100 * @param m_rssi of received packet at mote
Mike Fiore 16:b630e18103e5 101 * @param m_snr of received packet at mote
Mike Fiore 16:b630e18103e5 102 * @param s_rssi of received packet at server
Mike Fiore 16:b630e18103e5 103 * @param s_snr of received packet at server
Mike Fiore 16:b630e18103e5 104 */
Mike Fiore 16:b630e18103e5 105 virtual void Pong(int16_t m_rssi, int8_t m_snr, int16_t s_rssi, int8_t s_snr);
Mike Fiore 16:b630e18103e5 106
Mike Fiore 16:b630e18103e5 107 /**
Mike Fiore 16:b630e18103e5 108 * Fired if network link check answer is received
Mike Fiore 16:b630e18103e5 109 * @param m_rssi of received packet at mote
Mike Fiore 16:b630e18103e5 110 * @param m_snr of received packet at mote
Mike Fiore 16:b630e18103e5 111 * @param s_snr margin of received packet at server
Mike Fiore 16:b630e18103e5 112 * @param s_gateways number of gateways reporting the packet
Mike Fiore 16:b630e18103e5 113 */
Mike Fiore 16:b630e18103e5 114 virtual void NetworkLinkCheck(int16_t m_rssi, int8_t m_snr, int8_t s_snr, uint8_t s_gateways);
Mike Fiore 16:b630e18103e5 115
Mike Fiore 16:b630e18103e5 116 /**
Mike Fiore 16:b630e18103e5 117 * Callback to for device to measure the battery level and report to server
Mike Fiore 16:b630e18103e5 118 * @return battery level 0-255, 0 - external power, 1-254 level min-max, 255 device unable to measure battery
Mike Fiore 16:b630e18103e5 119 */
Mike Fiore 16:b630e18103e5 120 virtual uint8_t MeasureBattery();
Mike Fiore 16:b630e18103e5 121 };
Mike Fiore 16:b630e18103e5 122
Mike Fiore 16:b630e18103e5 123 class Mote {
Mike Fiore 16:b630e18103e5 124 public:
Mike Fiore 16:b630e18103e5 125 Mote(Settings* settings);
Mike Fiore 16:b630e18103e5 126 virtual ~Mote();
Mike Fiore 16:b630e18103e5 127
Mike Fiore 16:b630e18103e5 128 /**
Mike Fiore 16:b630e18103e5 129 * Indicator for network session join status
Mike Fiore 16:b630e18103e5 130 * @return true if joined to network
Mike Fiore 16:b630e18103e5 131 */
Mike Fiore 16:b630e18103e5 132 bool Joined();
Mike Fiore 16:b630e18103e5 133
Mike Fiore 16:b630e18103e5 134 /**
Mike Fiore 16:b630e18103e5 135 * Send join request
Mike Fiore 16:b630e18103e5 136 * @return LORA_OK if request was sent
Mike Fiore 16:b630e18103e5 137 */
Mike Fiore 16:b630e18103e5 138 uint8_t Join();
Mike Fiore 16:b630e18103e5 139
Mike Fiore 16:b630e18103e5 140 /**
Mike Fiore 16:b630e18103e5 141 * Send a packet
Mike Fiore 16:b630e18103e5 142 * @param port to send packet
Mike Fiore 16:b630e18103e5 143 * @param payload of packet
Mike Fiore 16:b630e18103e5 144 * @param size in bytes
Mike Fiore 16:b630e18103e5 145 * @return LORA_OK if successful
Mike Fiore 16:b630e18103e5 146 * @return LORA_MAX_PAYLOAD_EXCEEDED if payload size exceeds datarate maximum
Mike Fiore 16:b630e18103e5 147 * @return LORA_NO_CHANS_ENABLED if there is not an available channel that supports the current datarate
Mike Fiore 16:b630e18103e5 148 * @return LORA_LINK_BUSY if link was busy
Mike Fiore 16:b630e18103e5 149 * @return LORA_RADIO_BUSY if radio was busy
Mike Fiore 16:b630e18103e5 150 * @return LORA_BUFFER_FULL if mac commands filled the packet, client should resend the packet
Mike Fiore 16:b630e18103e5 151 */
Mike Fiore 16:b630e18103e5 152 uint8_t Send(uint8_t port, const uint8_t* payload, uint8_t size);
Mike Fiore 16:b630e18103e5 153
Mike Fiore 16:b630e18103e5 154 /**
Mike Fiore 16:b630e18103e5 155 * Configure the channel plan
Mike Fiore 16:b630e18103e5 156 * @param freqBand EU868, US915, AU915
Mike Fiore 16:b630e18103e5 157 * @return LORA_OK
Mike Fiore 16:b630e18103e5 158 */
Mike Fiore 16:b630e18103e5 159 uint8_t SetChannelPlan(uint8_t freqBand);
Mike Fiore 16:b630e18103e5 160
Mike Fiore 16:b630e18103e5 161 /**
Mike Fiore 16:b630e18103e5 162 * Get the channel mask of currently enabled channels
Mike Fiore 16:b630e18103e5 163 * @return vector containing channel bit masks
Mike Fiore 16:b630e18103e5 164 */
Mike Fiore 16:b630e18103e5 165 std::vector<uint16_t> GetChannelMask();
Mike Fiore 16:b630e18103e5 166
Mike Fiore 16:b630e18103e5 167 /**
Mike Fiore 16:b630e18103e5 168 * Set a 16 bit channel mask with index
Mike Fiore 16:b630e18103e5 169 * @param index of mask to set 0:0-15, 1:16-31 ...
Mike Fiore 16:b630e18103e5 170 * @param mask 16 bit mask of enabled channels
Mike Fiore 16:b630e18103e5 171 * @return true
Mike Fiore 16:b630e18103e5 172 */
Mike Fiore 16:b630e18103e5 173 virtual uint8_t SetChannelMask(uint8_t index, uint16_t mask);
Mike Fiore 16:b630e18103e5 174
Mike Fiore 16:b630e18103e5 175 /**
Mike Fiore 16:b630e18103e5 176 * Set the current channel group for hybrid operation 1-8 else 0 for 64 channel operation
Mike Fiore 16:b630e18103e5 177 * @param group 0-8
Mike Fiore 16:b630e18103e5 178 */
Mike Fiore 16:b630e18103e5 179 uint8_t SetChannelGroup(uint8_t group);
Mike Fiore 16:b630e18103e5 180
Mike Fiore 16:b630e18103e5 181 /**
Mike Fiore 16:b630e18103e5 182 * Get the current channel group
Mike Fiore 16:b630e18103e5 183 * @return group 0-8
Mike Fiore 16:b630e18103e5 184 */
Mike Fiore 16:b630e18103e5 185 uint8_t GetChannelGroup();
Mike Fiore 16:b630e18103e5 186
Mike Fiore 16:b630e18103e5 187 /**
Mike Fiore 16:b630e18103e5 188 * Add a channel to the channel plan
Mike Fiore 16:b630e18103e5 189 * EU868 allows additional channels to be added
Mike Fiore 16:b630e18103e5 190 * Channels 0-2 are fixed default channels
Mike Fiore 16:b630e18103e5 191 *
Mike Fiore 16:b630e18103e5 192 * @param index of the channel
Mike Fiore 16:b630e18103e5 193 * @param frequency of the channel or 0 to remove channel
Mike Fiore 16:b630e18103e5 194 * @param range of datarates allowed by the channel
Mike Fiore 16:b630e18103e5 195 * @return LORA_OK if channel was added
Mike Fiore 16:b630e18103e5 196 */
Mike Fiore 16:b630e18103e5 197 uint8_t AddChannel(uint8_t index, uint32_t frequency, lora::DatarateRange range);
Mike Fiore 16:b630e18103e5 198
Mike Fiore 16:b630e18103e5 199 /**
Mike Fiore 16:b630e18103e5 200 * Set network mode
Mike Fiore 16:b630e18103e5 201 * Choose Public LoRaWAN mode or Private Multitech mode
Mike Fiore 16:b630e18103e5 202 *
Mike Fiore 16:b630e18103e5 203 * Public mode uses 0x34 sync word with 5/6 second join windows
Mike Fiore 16:b630e18103e5 204 * Private mode uses 0x12 sync word with 1/2 second join windows
Mike Fiore 16:b630e18103e5 205 * US915/AU915 Rx1 and Rx2 are fixed per Channel Group setting
Mike Fiore 16:b630e18103e5 206 *
Mike Fiore 16:b630e18103e5 207 * @param mode public or private
Mike Fiore 16:b630e18103e5 208 * @return LORA_OK
Mike Fiore 16:b630e18103e5 209 */
Mike Fiore 16:b630e18103e5 210 uint8_t SetNetworkMode(uint8_t mode);
Mike Fiore 16:b630e18103e5 211
Mike Fiore 16:b630e18103e5 212 /**
Mike Fiore 16:b630e18103e5 213 * Get a pointer to the mac layer
Mike Fiore 16:b630e18103e5 214 * @return Mac mac
Mike Fiore 16:b630e18103e5 215 */
Mike Fiore 16:b630e18103e5 216 Mac* GetMac();
Mike Fiore 16:b630e18103e5 217
Mike Fiore 16:b630e18103e5 218 /**
Mike Fiore 16:b630e18103e5 219 * Get a pointer to the radio
Mike Fiore 16:b630e18103e5 220 * Can be used to read radio registers or get a random value based on RSSI
Mike Fiore 16:b630e18103e5 221 *
Mike Fiore 16:b630e18103e5 222 * @return SxRadio pointer
Mike Fiore 16:b630e18103e5 223 */
Mike Fiore 16:b630e18103e5 224 SxRadio* GetRadio();
Mike Fiore 16:b630e18103e5 225
Mike Fiore 16:b630e18103e5 226 /**
Mike Fiore 16:b630e18103e5 227 * Get the current statistics for the device
Mike Fiore 16:b630e18103e5 228 * @return Statistics
Mike Fiore 16:b630e18103e5 229 */
Mike Fiore 16:b630e18103e5 230 Statistics& GetStats();
Mike Fiore 16:b630e18103e5 231
Mike Fiore 16:b630e18103e5 232 /**
Mike Fiore 16:b630e18103e5 233 * Get time on air with current settings for provided payload bytes
Mike Fiore 16:b630e18103e5 234 * 13 overhead bytes will be added to payload
Mike Fiore 16:b630e18103e5 235 * @param bytes of payload data
Mike Fiore 16:b630e18103e5 236 * @return time-on-air in ms
Mike Fiore 16:b630e18103e5 237 */
Mike Fiore 16:b630e18103e5 238 uint32_t GetTimeOnAir(uint8_t bytes);
Mike Fiore 16:b630e18103e5 239
Mike Fiore 16:b630e18103e5 240 /**
Mike Fiore 16:b630e18103e5 241 * Call before setting device in sleep mode to place radio in sleep
Mike Fiore 16:b630e18103e5 242 */
Mike Fiore 16:b630e18103e5 243 void Sleep();
Mike Fiore 16:b630e18103e5 244
Mike Fiore 16:b630e18103e5 245 protected:
Mike Fiore 16:b630e18103e5 246 SxRadio1272* _radio;
Mike Fiore 16:b630e18103e5 247 Settings* _settings;
Mike Fiore 16:b630e18103e5 248 Mac* _mac;
Mike Fiore 16:b630e18103e5 249
Mike Fiore 16:b630e18103e5 250 private:
Mike Fiore 16:b630e18103e5 251 ChannelPlan* _plan;
Mike Fiore 16:b630e18103e5 252 MoteEvents _events;
Mike Fiore 16:b630e18103e5 253 };
Mike Fiore 16:b630e18103e5 254
Mike Fiore 16:b630e18103e5 255 }
Mike Fiore 16:b630e18103e5 256 #endif