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
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:
- libmDot-mbed5 -> production-ready build for mDot
- libmDot-dev-mbed5 -> development build for mDot
- libxDot-mbed5 -> production-ready build for xDot
- libxDot-dev-mbed5 -> development build for xDot
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
Diff: mDot.h
- Revision:
- 65:acc0468b9aec
- Parent:
- 64:64982192a2af
- Child:
- 68:5f787643e7d7
diff -r 64982192a2af -r acc0468b9aec mDot.h --- a/mDot.h Thu Aug 23 14:18:55 2018 -0500 +++ b/mDot.h Thu Apr 18 14:55:19 2019 -0500 @@ -1,4 +1,30 @@ -// TODO: add license header +/********************************************************************** +* COPYRIGHT 2015 MULTI-TECH SYSTEMS, INC. +* +* Redistribution and use in source and binary forms, with or without modification, +* are permitted provided that the following conditions are met: +* 1. Redistributions of source code must retain the above copyright notice, +* this list of conditions and the following disclaimer. +* 2. Redistributions in binary form must reproduce the above copyright notice, +* this list of conditions and the following disclaimer in the documentation +* and/or other materials provided with the distribution. +* 3. Neither the name of MULTI-TECH SYSTEMS, INC. nor the names of its contributors +* may be used to endorse or promote products derived from this software +* without specific prior written permission. +* +* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +* AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE +* DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE +* FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +* DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR +* SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER +* CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +* OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +* OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +* +****************************************************************************** +*/ #ifndef MDOT_H #define MDOT_H @@ -35,9 +61,14 @@ void waitForPacket(); void waitForLinkCheck(); + + MBED_DEPRECATED("Will be removed in dotlib 3.3.0") void setActivityLedState(const uint8_t& state); + + MBED_DEPRECATED("Will be removed in dotlib 3.3.0") uint8_t getActivityLedState(); + MBED_DEPRECATED("Will be removed in dotlib 3.3.0") void blinkActivityLed(void) { if (_activity_led) { int val = _activity_led->read(); @@ -51,6 +82,9 @@ uint32_t RTC_ReadBackupRegister(uint32_t RTC_BKP_DR); void RTC_WriteBackupRegister(uint32_t RTC_BKP_DR, uint32_t Data); + void RTC_DisableWakeupTimer(); + void RTC_EnableWakeupTimer(); + void enterStopMode(const uint32_t& interval, const uint8_t& wakeup_mode = RTC_ALARM); void enterStandbyMode(const uint32_t& interval, const uint8_t& wakeup_mode = RTC_ALARM); @@ -63,12 +97,12 @@ std::string _last_error; static const uint32_t _baud_rates[]; - uint8_t _activity_led_state; + uint8_t _activity_led_state; //deprecated will be removed Ticker _tick; - DigitalOut* _activity_led; - bool _activity_led_enable; - PinName _activity_led_pin; - bool _activity_led_external; + DigitalOut* _activity_led; //deprecated will be removed + bool _activity_led_enable; //deprecated will be removed + PinName _activity_led_pin; //deprecated will be removed + bool _activity_led_external; //deprecated will be removed uint8_t _linkFailCount; uint8_t _class; InterruptIn* _wakeup; @@ -127,7 +161,8 @@ enum RX_Output { HEXADECIMAL, - BINARY + BINARY, + EXTENDED }; enum DataRates { @@ -161,11 +196,6 @@ FSB_8 }; - enum JoinByteOrder { - LSB, - MSB - }; - enum wakeup_mode { RTC_ALARM, INTERRUPT, @@ -264,7 +294,7 @@ static mDot* getInstance(lora::ChannelPlan* plan); /** - * Can only be used after a dot has + * Can only be used after a dot has * configured with a plan * @returns pointer to mDot object */ @@ -328,41 +358,29 @@ */ void seedRandom(uint32_t seed); + /** + * @returns true if MAC command answers are ready to be sent + */ + bool hasMacCommands(); + uint8_t setChannelPlan(lora::ChannelPlan* plan); lora::Settings* getSettings(); - /** - * Enable or disable the activity LED. - * @param enable true to enable the LED, false to disable - */ + MBED_DEPRECATED("Will be removed in dotlib 3.3.0") void setActivityLedEnable(const bool& enable); - /** - * Find out if the activity LED is enabled - * @returns true if activity LED is enabled, false if disabled - */ + MBED_DEPRECATED("Will be removed in dotlib 3.3.0") bool getActivityLedEnable(); - /** - * Use a different pin for the activity LED. - * The default is XBEE_RSSI. - * @param pin the new pin to use - */ + MBED_DEPRECATED("Will be removed in dotlib 3.3.0") void setActivityLedPin(const PinName& pin); - /** - * Use an external DigitalOut object for the activity LED. - * The pointer must stay valid! - * @param pin the DigitalOut object to use - */ + MBED_DEPRECATED("Will be removed in dotlib 3.3.0") void setActivityLedPin(DigitalOut* pin); - /** - * Find out what pin the activity LED is on - * @returns the pin the activity LED is using - */ + MBED_DEPRECATED("Will be removed in dotlib 3.3.0") PinName getActivityLedPin(); /** @@ -723,18 +741,6 @@ int32_t setMulticastDownlinkCounter(uint8_t index, uint32_t count); /** - * Set join byte order - * @param order 0:LSB 1:MSB - */ - uint32_t setJoinByteOrder(uint8_t order); - - /** - * Get join byte order - * @returns byte order to use in joins 0:LSB 1:MSB - */ - uint8_t getJoinByteOrder(); - - /** * Attempt to join network * each attempt will be made with a random datarate up to the configured datarate * JoinRequest backoff between tries is enforced to 1% for 1st hour, 0.1% for 1-10 hours and 0.01% after 10 hours @@ -903,6 +909,12 @@ uint32_t getNextTxMs(); /** + * Get available bytes for payload + * @returns bytes + */ + uint8_t getNextTxMaxSize(); + + /** * Get join delay in seconds * Defaults to 5 seconds * Must match join delay setting of the network server @@ -1077,6 +1089,7 @@ * @returns spreading factor and bandwidth */ std::string getDataRateDetails(uint8_t rate); + MBED_DEPRECATED("Will be removed in 3.3.0") std::string getDateRateDetails(uint8_t rate); @@ -1194,6 +1207,21 @@ uint8_t getMinTxPower(); /** + * Set ping slot periodicity + * Specify the the number of ping slots in a given beacon interval + * Note: Must switch back to class A for the change to take effect + * @param exp - number_of_pings = 2^(7 - exp) where 0 <= exp <= 7 + * @returns MDOT_OK if success + */ + uint32_t setPingPeriodicity(uint8_t exp); + + /** + * Get ping slot periodicity + * @returns exp = 7 - log2(number_of_pings) + */ + uint8_t getPingPeriodicity(); + + /** * * get/set adaptive data rate * configure data rates and power levels based on signal to noise of packets received at gateway @@ -1204,17 +1232,28 @@ bool getAdr(); /** - * Set forward error correction bytes - * @param bytes 1 - 4 bytes - * @returns MDOT_OK if success + * Set the ADR ACK Limit + * @param limit - ADR ACK limit */ - int32_t setFec(const uint8_t& bytes); + void setAdrAckLimit(uint16_t limit); /** - * Get forward error correction bytes - * @returns bytes (1 - 4) + * Get the ADR ACK Limit + * @returns ADR ACK limit */ - uint8_t getFec(); + uint16_t getAdrAckLimit(); + + /** + * Set the ADR ACK Delay + * @param delay - ADR ACK delay + */ + void setAdrAckDelay(uint16_t delay); + + /** + * Get the ADR ACK Delay + * @returns ADR ACK delay + */ + uint16_t getAdrAckDelay(); /** * Enable/disable CRC checking of packets @@ -1404,6 +1443,26 @@ */ int8_t getLbtThreshold(); + /** + * Get Radio Frequency Offset + * Used for fine calibration of radio frequencies + * @returns frequency offset in MHz + */ + int32_t getFrequencyOffset(); + /** + * Get Radio Frequency Offset + * Used for fine calibration of radio frequencies + * @param offset frequency offset in MHz + */ + void setFrequencyOffset(int32_t offset); + + /** + * Get GPS time from network server + * Sends a DeviceTimeReq command to the network server + * @returns time since GPS epoch, 0 on failure + */ + uint64_t getGPSTime(); + #if defined(TARGET_MTS_MDOT_F411RE) /////////////////////////////////////////////////////////////////// // Filesystem (Non Volatile Memory) Operation Functions for mDot // @@ -1481,11 +1540,15 @@ // file - name of file // returns true if successful bool moveUserFileToFirmwareUpgrade(const char* file); + + // Return total size of all files saved in FLASH + // Does not include SPIFFS overhead + uint32_t getUsedSpace(); #else /////////////////////////////////////////////////////////////// // EEPROM (Non Volatile Memory) Operation Functions for xDot // /////////////////////////////////////////////////////////////// - + // Write to EEPROM // addr - address to write to (0 - 0x17FF) // data - data to write @@ -1557,8 +1620,6 @@ uint8_t getRxDataRate(); // get/set TX/RX frequency - // if frequency band == FB_868 (Europe), must be between 863000000 - 870000000 - // if frequency band == FB_915 (United States), must be between 902000000-928000000 // if set to 0, device will hop frequencies // set function returns MDOT_OK if success int32_t setTxFrequency(const uint32_t& freq); @@ -1566,16 +1627,8 @@ int32_t setRxFrequency(const uint32_t& freq); uint32_t getRxFrequency(); - // get/set TX/RX inverted - // true == signal is inverted - // set function returns MDOT_OK if success - int32_t setTxInverted(const bool& on); - bool getTxInverted(); - int32_t setRxInverted(const bool& on); - bool getRxInverted(); - // get/set RX output mode - // valid options are HEXADECIMAL and BINARY + // valid options are HEXADECIMAL, BINARY, and EXTENDED // set function returns MDOT_OK if success int32_t setRxOutput(const uint8_t& mode); uint8_t getRxOutput(); @@ -1644,67 +1697,39 @@ void openRxWindow(uint32_t timeout, uint8_t bandwidth = 0); void closeRxWindow(); - void sendContinuous(bool enable=true); + void sendContinuous(bool enable=true, uint32_t timeout=0, uint32_t frequency=0, int8_t txpower=-1); int32_t setDeviceId(const std::vector<uint8_t>& id); int32_t setProtectedAppEUI(const std::vector<uint8_t>& appEUI); int32_t setProtectedAppKey(const std::vector<uint8_t>& appKey); int32_t setDefaultFrequencyBand(const uint8_t& band); bool saveProtectedConfig(); - // resets the radio/mac/link + // resets the radio/mac/link void resetRadio(); int32_t setRadioMode(const uint8_t& mode); std::map<uint8_t, uint8_t> dumpRegisters(); void eraseFlash(); - // deprecated - use setWakeInterval - int32_t setSerialWakeInterval(const uint32_t& interval); - // deprecated - use getWakeInterval - uint32_t getSerialWakeInterval(); - - // deprecated - use setWakeDelay - int32_t setSerialWakeDelay(const uint32_t& delay); - // deprecated - use setWakeDelay - uint32_t getSerialWakeDelay(); - - // deprecated - use setWakeTimeout - int32_t setSerialReceiveTimeout(const uint16_t& timeout); - // deprecated - use getWakeTimeout - uint16_t getSerialReceiveTimeout(); - void setWakeupCallback(void (*function)(void)); template<typename T> void setWakeupCallback(T *object, void (T::*member)(void)) { _wakeup_callback.attach(object, member); } - - lora::ChannelPlan* getChannelPlan(void); + + lora::ChannelPlan* getChannelPlan(void); uint32_t setRx2DataRate(uint8_t dr); uint8_t getRx2DataRate(); - void mcGroupKeys(uint8_t *mcKeyEncrypt, uint32_t addr, uint8_t groupId, uint32_t frame_count); + void mcGroupKeys(uint8_t *mcKeyEncrypt, uint32_t addr, uint8_t groupId, uint32_t frame_count); private: - typedef enum { - AUTO_SLEEP_EVT_CFG, - AUTO_SLEEP_EVT_TXDONE, - AUTO_SLEEP_EVT_RX1_TIMEOUT, - AUTO_SLEEP_EVT_CLEANUP - } AutoSleepEvent_t; - - typedef enum { - USER_SLEEP, - AUTO_SLEEP - } SleepClient_t; void sleep_ms(uint32_t interval, uint8_t wakeup_mode = RTC_ALARM, - bool deepsleep = true, - SleepClient_t sleep_client = USER_SLEEP); + bool deepsleep = true); - void auto_sleep(AutoSleepEvent_t evt); - void wakeup(SleepClient_t sleep_client); + void wakeup(); mdot_stats _stats;