Library for LoRa communication using MultiTech MDOT.
Dependents: mDot_LoRa_Connect_CSA_Light mDot_LoRa_Connect_CSA_RH_Temp
Fork of libmDot by
Diff: mDot.h
- Revision:
- 11:9938ba31d428
- Parent:
- 10:0b4eb17d07ae
diff -r 0b4eb17d07ae -r 9938ba31d428 mDot.h --- a/mDot.h Thu Sep 10 13:19:35 2015 -0500 +++ b/mDot.h Tue Mar 29 10:18:28 2016 -0500 @@ -9,6 +9,7 @@ #include <map> #include <string> +class mDotEvent; class LoRaMacEvent; class LoRaConfig; class LoRaMac; @@ -55,6 +56,9 @@ void wakeup(); + 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); + static mDot* _instance; LoRaMac* _mac; @@ -76,7 +80,9 @@ PinName _wakeup_pin; typedef enum { - OFF, ON, BLINK, + OFF, + ON, + BLINK, } state; public: @@ -101,39 +107,95 @@ MDOT_NOT_JOINED = -6, MDOT_ENCRYPTION_DISABLED = -7, MDOT_NO_FREE_CHAN = -8, + MDOT_TEST_MODE = -9, + MDOT_NO_ENABLED_CHAN = -10, + MDOT_AGGREGATED_DUTY_CYCLE = -11, MDOT_ERROR = -1024, } mdot_ret_code; enum JoinMode { - MANUAL, OTA, AUTO_OTA + MANUAL, + OTA, + AUTO_OTA, + PEER_TO_PEER }; enum Mode { - COMMAND_MODE, SERIAL_MODE + COMMAND_MODE, + SERIAL_MODE }; enum RX_Output { - HEXADECIMAL, BINARY + HEXADECIMAL, + BINARY }; enum DataRates { - SF_12, SF_11, SF_10, SF_9, SF_8, SF_7, SF_7H, SF_50 + DR0, + DR1, + DR2, + DR3, + DR4, + DR5, + DR6, + DR7, + DR8, + DR9, + DR10, + DR11, + DR12, + DR13, + DR14, + DR15, + SF_12 = 16, + SF_11, + SF_10, + SF_9, + SF_8, + SF_7, + SF_7H, + SF_FSK }; enum FrequencyBands { - FB_868, FB_915 + FB_868, // EU868 + FB_915 // US915 }; enum FrequencySubBands { - FSB_ALL, FSB_1, FSB_2, FSB_3, FSB_4, FSB_5, FSB_6, FSB_7, FSB_8 + FSB_ALL, + FSB_1, + FSB_2, + FSB_3, + FSB_4, + FSB_5, + FSB_6, + FSB_7, + FSB_8 }; enum JoinByteOrder { - LSB, MSB + LSB, + MSB }; enum wakeup_mode { - RTC_ALARM, INTERRUPT + RTC_ALARM, + INTERRUPT, + RTC_ALARM_OR_INTERRUPT + }; + + enum UserBackupRegs { + UBR0, + UBR1, + UBR2, + UBR3, + UBR4, + UBR5, + UBR6, + UBR7, + UBR8, + UBR9 }; typedef struct { @@ -158,10 +220,10 @@ } rssi_stats; typedef struct { - int8_t last; - int8_t min; - int8_t max; - int8_t avg; + int16_t last; + int16_t min; + int16_t max; + int16_t avg; } snr_stats; typedef struct { @@ -187,11 +249,15 @@ static std::string FrequencyBandStr(uint8_t band); static std::string FrequencySubBandStr(uint8_t band); + uint32_t UserRegisters[10]; + /** Get a handle to the singleton object * @returns pointer to mDot object */ static mDot* getInstance(); + void setEvents(mDotEvent* events); + /** Get library version information * @returns string containing library version information */ @@ -229,6 +295,11 @@ */ uint8_t getLogLevel(); + /** Seed pseudo RNG in LoRaMac layer, uses random value from radio RSSI reading by default + * @param seed for RNG + */ + void seedRandom(uint32_t seed); + /** Enable or disable the activity LED. * @param enable true to enable the LED, false to disable */ @@ -256,11 +327,36 @@ */ PinName getActivityLedPin(); + /** Returns boolean indicative of start-up from standby mode + * @returns true if dot woke from standby + */ + bool getStandbyFlag(); + + /** Add a channel frequencies currently in use + * @returns MDOT_OK + */ + int32_t addChannel(uint8_t index, uint32_t frequency, uint8_t datarateRange); + /** Get list of channel frequencies currently in use * @returns vector of channels currently in use */ std::vector<uint32_t> getChannels(); + /** Get list of channel datarate ranges currently in use + * @returns vector of datarate ranges currently in use + */ + std::vector<uint8_t> getChannelRanges(); + + /** Get list of channel frequencies in config file to be used as session defaults + * @returns vector of channels in config file + */ + std::vector<uint32_t> getConfigChannels(); + + /** Get list of channel datarate ranges in config file to be used as session defaults + * @returns vector of datarate ranges in config file + */ + std::vector<uint8_t> getConfigChannelRanges(); + /** Get frequency band * @returns FB_915 if configured for United States, FB_868 if configured for Europe */ @@ -268,7 +364,7 @@ /** Set frequency sub band * only applicable if frequency band is set for United States (FB_915) - * sub band 0 will allow the radio to use all 64 channels + * sub band 0 will allow the radio to use all 64 channels * sub band 1 - 8 will allow the radio to use the 8 channels in that sub band * for use with Conduit gateway and MTAC_LORA, use sub bands 1 - 8, not sub band 0 * @param band the sub band to use (0 - 8) @@ -281,7 +377,14 @@ */ uint8_t getFrequencySubBand(); + /** Get the datarate currently in use within the MAC layer + * returns 0-15 + */ + uint8_t getSessionDataRate(); + /** Enable/disable public network mode + * JoinDelay will be set to (public: 5s, private: 1s) and + * RxDelay will be set to 1s both can be adjusted afterwards * @param on should be true to enable public network mode * @returns MDOT_OK if success */ @@ -297,6 +400,31 @@ */ std::vector<uint8_t> getDeviceId(); + /** Get the device port to be used for lora application data (1-223) + * @returns port + */ + uint8_t getAppPort(); + + /** Set the device port to be used for lora application data (1-223) + * @returns MDOT_OK if success + */ + int32_t setAppPort(uint8_t port); + + /** Set the device class A, B or C + * @returns MDOT_OK if success + */ + int32_t setClass(std::string newClass); + + /** Get the device class A, B or C + * @returns MDOT_OK if success + */ + std::string getClass(); + + /** Get the max packet length with current settings + * @returns max packet length + */ + uint8_t getMaxPacketLength(); + /** Set network address * for use with MANUAL network join mode, will be assigned in OTA & AUTO_OTA modes * @param addr a vector of 4 bytes @@ -396,7 +524,9 @@ uint8_t getJoinByteOrder(); /** Attempt to join network - * retries according to configuration set by setJoinRetries() + * 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 + * Check getNextTxMs() for time until next join attempt can be made * @returns MDOT_OK if success */ int32_t joinNetwork(); @@ -411,6 +541,16 @@ */ void resetNetworkSession(); + /** Restore saved network session from flash + * has no effect for MANUAL network join mode + */ + void restoreNetworkSession(); + + /** Save current network session to flash + * has no effect for MANUAL network join mode + */ + void saveNetworkSession(); + /** Set number of times joining will retry before giving up * @param retries must be between 0 - 255 * @returns MDOT_OK if success @@ -471,11 +611,32 @@ */ uint8_t getLinkCheckThreshold(); + /** Get/set number of failed link checks in the current session + * @returns count (0 - 255) + */ + uint8_t getLinkFailCount(); + int32_t setLinkFailCount(uint8_t count); + + /** Set UpLinkCounter number of packets sent to the gateway during this network session (sequence number) + * @returns MDOT_OK + */ + int32_t setUpLinkCounter(uint32_t count); + /** Get UpLinkCounter * @returns number of packets sent to the gateway during this network session (sequence number) */ uint32_t getUpLinkCounter(); + /** Set UpLinkCounter number of packets sent by the gateway during this network session (sequence number) + * @returns MDOT_OK + */ + int32_t setDownLinkCounter(uint32_t count); + + /** Get DownLinkCounter + * @returns number of packets sent by the gateway during this network session (sequence number) + */ + uint32_t getDownLinkCounter(); + /** Enable/disable AES encryption * AES encryption must be enabled for use with Conduit gateway and MTAC_LORA card * @param on true for AES encryption to be enabled @@ -489,12 +650,12 @@ bool getAesEncryption(); /** Get RSSI stats - * @returns rssi_stats struct containing last, min, max, and avg RSSI + * @returns rssi_stats struct containing last, min, max, and avg RSSI in dB */ rssi_stats getRssiStats(); /** Get SNR stats - * @returns snr_stats struct containing last, min, max, and avg SNR + * @returns snr_stats struct containing last, min, max, and avg SNR in cB */ snr_stats getSnrStats(); @@ -504,30 +665,102 @@ */ uint32_t getNextTxMs(); + /** Get join delay in seconds + * Public network defaults to 5 seconds + * Private network defaults to 1 second + * @returns number of seconds before join accept message is expected + */ + uint8_t getJoinDelay(); + + /** Set join delay in seconds + * Public network defaults to 5 seconds + * Private network defaults to 1 second + * @param delay number of seconds before join accept message is expected + * @return MDOT_OK if success + */ + uint32_t setJoinDelay(uint8_t delay); + + /** Get rx delay in seconds + * Defaults to 1 second + * @returns number of seconds before response message is expected + */ + uint8_t getRxDelay(); + + /** Set rx delay in seconds + * Defaults to 1 second + * @param delay number of seconds before response message is expected + * @return MDOT_OK if success + */ + uint32_t setRxDelay(uint8_t delay); + + /** Get preserve session to save network session info through reset or power down in AUTO_OTA mode + * Defaults to off + * @returns true if enabled + */ + bool getPreserveSession(); + + /** Set preserve session to save network session info through reset or power down in AUTO_OTA mode + * Defaults to off + * @param enable + * @return MDOT_OK if success + */ + uint32_t setPreserveSession(bool enable); + /** Get data pending * only valid after sending data to the gateway * @returns true if server has available packet(s) */ bool getDataPending(); - /** Get transmitting + /** Get transmitting * @returns true if currently transmitting */ bool getIsTransmitting(); /** Set TX data rate * data rates affect maximum payload size - * @param dr SF_7 - SF_12 for Europe, SF_7 - SF_10 for United States + * @param dr SF_7 - SF_12|DR0-DR7 for Europe, SF_7 - SF_10 | DR0-DR4 for United States * @returns MDOT_OK if success */ int32_t setTxDataRate(const uint8_t& dr); /** Get TX data rate - * @returns current TX data rate (SF_7 - SF_12) + * @returns current TX data rate (DR0-DR15) */ uint8_t getTxDataRate(); - /** Set TX power + /** Get a random value from the radio based on RSSI + * @returns randome value + */ + uint32_t getRadioRandom(); + + + /** Get data rate spreading factor and bandwidth + * EU868 Datarates + * --------------- + * DR0 - SF12BW125 + * DR1 - SF11BW125 + * DR2 - SF10BW125 + * DR3 - SF9BW125 + * DR4 - SF8BW125 + * DR5 - SF7BW125 + * DR6 - SF7BW250 + * DR7 - FSK + * + * US915 Datarates + * --------------- + * DR0 - SF10BW125 + * DR1 - SF9BW125 + * DR2 - SF8BW125 + * DR3 - SF7BW125 + * DR4 - SF8BW500 + * + * @returns spreading factor and bandwidth + */ + std::string getDateRateDetails(uint8_t rate); + + /** Set TX power output of radio before antenna gain, default: 14 dBm + * actual output power may be limited by local regulations for the chosen frequency * power affects maximum range * @param power 2 dBm - 20 dBm * @returns MDOT_OK if success @@ -539,6 +772,17 @@ */ uint32_t getTxPower(); + /** Get configured gain of installed antenna, default: +3 dBi + * @returns gain of antenna in dBi + */ + int8_t getAntennaGain(); + + /** Set configured gain of installed antenna, default: +3 dBi + * @param gain -127 dBi - 128 dBi + * @returns MDOT_OK if success + */ + int32_t setAntennaGain(int8_t gain); + /** Enable/disable TX waiting for rx windows * when enabled, send calls will block until a packet is received or RX timeout * @param enable set to true if expecting responses to transmitted packets @@ -566,6 +810,13 @@ */ uint32_t getMaxFrequency(); + // get/set adaptive data rate + // configure data rates and power levels based on signal to noise of packets received at gateway + // true == adaptive data rate is on + // set function returns MDOT_OK if success + int32_t setAdr(const bool& on); + bool getAdr(); + /** Set forward error correction bytes * @param bytes 1 - 4 bytes * @returns MDOT_OK if success @@ -600,6 +851,17 @@ */ uint8_t getAck(); + /** Set number of packet repeats for unconfirmed frames + * @param repeat 0 or 1 for no repeats, otherwise 2-15 + * @returns MDOT_OK if success + */ + int32_t setRepeat(const uint8_t& repeat); + + /** Get number of packet repeats for unconfirmed frames + * @returns 0 or 1 if no repeats, otherwise 2-15 + */ + uint8_t getRepeat(); + /** Send data to the gateway * validates data size (based on spreading factor) * @param data a vector of up to 242 bytes (may be less based on spreading factor) @@ -615,7 +877,6 @@ */ int32_t recv(std::vector<uint8_t>& data); - /** Ping * status will be MDOT_OK if ping succeeded * @returns ping_response struct containing status, RSSI, and SNR @@ -633,39 +894,126 @@ std::string getLastError(); /** Go to sleep - * @param interval the number of seconds to sleep before waking up if wakeup_mode == RTC_ALARM, else ignored - * @param wakeup_mode RTC_ALARM, INTERRUPT + * @param interval the number of seconds to sleep before waking up if wakeup_mode == RTC_ALARM or RTC_ALARM_OR_INTERRUPT, else ignored + * @param wakeup_mode RTC_ALARM, INTERRUPT, RTC_ALARM_OR_INTERRUPT * if RTC_ALARM the real time clock is configured to wake the device up after the specified interval * if INTERRUPT the device will wake up on the rising edge of the interrupt pin + * if RTC_ALARM_OR_INTERRUPT the device will wake on the first event to occur * @param deepsleep if true go into deep sleep mode (lowest power, all memory and registers are lost, peripherals turned off) * else go into sleep mode (low power, memory and registers are maintained, peripherals stay on) * - * ** CURRENTLY ONLY DEEPSLEEP MODE IS AVAILABLE ** - * - * in sleep mode, the device can be woken up on any of the XBEE pins or by the RTC alarm + * in sleep mode, the device can be woken up on an XBEE_DI (2-8) pin or by the RTC alarm * in deepsleep mode, the device can only be woken up using the WKUP pin (PA0, XBEE_DIO7) or by the RTC alarm */ void sleep(const uint32_t& interval, const uint8_t& wakeup_mode = RTC_ALARM, const bool& deepsleep = true); /** Set wake pin - * @param pin the pin to use to wake the device from sleep mode + * @param pin the pin to use to wake the device from sleep mode XBEE_DI (2-8) */ void setWakePin(const PinName& pin); /** Get wake pin - * @returns the pin to use to wake the device from sleep mode + * @returns the pin to use to wake the device from sleep mode XBEE_DI (2-8) */ PinName getWakePin(); - /****************************************** - * THESE FEATURES ARE NOT FULLY IMPLEMENTED - *****************************************/ - // get/set adaptive data rate - // configure data rates and power levels based on signal to noise information from gateway - // true == adaptive data rate is on - // set function returns MDOT_OK if success - int32_t setAdr(const bool& on); - bool getAdr(); + /** Write data in a user backup register + * @param register one of UBR0 through UBR9 + * @param data user data to back up + * @returns true if success + */ + bool writeUserBackupRegister(uint32_t reg, uint32_t data); + + /** Read data in a user backup register + * @param register one of UBR0 through UBR9 + * @param data gets set to content of register + * @returns true if success + */ + bool readUserBackupRegister(uint32_t reg, uint32_t& data); + + // Save user file data to flash + // file - name of file max 30 chars + // data - data of file + // size - size of file + bool saveUserFile(const char* file, void* data, uint32_t size); + + // Append user file data to flash + // file - name of file max 30 chars + // data - data of file + // size - size of file + bool appendUserFile(const char* file, void* data, uint32_t size); + + // Read user file data from flash + // file - name of file max 30 chars + // data - data of file + // size - size of file + bool readUserFile(const char* file, void* data, uint32_t size); + + // Move a user file in flash + // file - name of file + // new_name - new name of file + bool moveUserFile(const char* file, const char* new_name); + + // Delete user file data from flash + // file - name of file max 30 chars + bool deleteUserFile(const char* file); + + // Open user file in flash, max of 4 files open concurrently + // file - name of file max 30 chars + // mode - combination of FM_APPEND | FM_TRUNC | FM_CREAT | + // FM_RDONLY | FM_WRONLY | FM_RDWR | FM_DIRECT + // returns - mdot_file struct, fd field will be a negative value if file could not be opened + mDot::mdot_file openUserFile(const char* file, int mode); + + // Seek an open file + // file - mdot file struct + // offset - offset in bytes + // whence - where offset is based SEEK_SET, SEEK_CUR, SEEK_END + bool seekUserFile(mDot::mdot_file& file, size_t offset, int whence); + + // Read bytes from open file + // file - mdot file struct + // data - mem location to store data + // length - number of bytes to read + // returns - number of bytes written + int readUserFile(mDot::mdot_file& file, void* data, size_t length); + + // Write bytes to open file + // file - mdot file struct + // data - data to write + // length - number of bytes to write + // returns - number of bytes written + int writeUserFile(mDot::mdot_file& file, void* data, size_t length); + + // Close open file + // file - mdot file struct + bool closeUserFile(mDot::mdot_file& file); + + // List user files stored in flash + std::vector<mDot::mdot_file> listUserFiles(); + + // Move file into the firmware upgrade path to be flashed on next boot + // file - name of file + bool moveUserFileToFirmwareUpgrade(const char* file); + + // get current statistics + // Join Attempts, Join Fails, Up Packets, Down Packets, Missed Acks + mdot_stats getStats(); + + // reset statistics + // Join Attempts, Join Fails, Up Packets, Down Packets, Missed Acks + void resetStats(); + + // Convert pin number 2-8 to pin name DIO2-DI8 + static PinName pinNum2Name(uint8_t num); + + // Convert pin name DIO2-DI8 to pin number 2-8 + static uint8_t pinName2Num(PinName name); + + // Convert pin name DIO2-DI8 to string + static std::string pinName2Str(PinName name); + + uint64_t crc64(uint64_t crc, const unsigned char *s, uint64_t l); /************************************************************************* * The following functions are only used by the AT command application and @@ -751,90 +1099,17 @@ int32_t setWakeMode(const uint8_t& delay); uint8_t getWakeMode(); - // Save user file data to flash - // file - name of file max 30 chars - // data - data of file - // size - size of file - bool saveUserFile(const char* file, void* data, uint32_t size); - - // Append user file data to flash - // file - name of file max 30 chars - // data - data of file - // size - size of file - bool appendUserFile(const char* file, void* data, uint32_t size); - - // Read user file data from flash - // file - name of file max 30 chars - // data - data of file - // size - size of file - bool readUserFile(const char* file, void* data, uint32_t size); - - // Move a user file in flash - // file - name of file - // new_name - new name of file - bool moveUserFile(const char* file, const char* new_name); - - // Delete user file data from flash - // file - name of file max 30 chars - bool deleteUserFile(const char* file); - - // Open user file in flash, max of 4 files open concurrently - // file - name of file max 30 chars - // mode - combination of FM_APPEND | FM_TRUNC | FM_CREAT | - // FM_RDONLY | FM_WRONLY | FM_RDWR | FM_DIRECT - // returns - mdot_file struct, fd field will be a negative value if file could not be opened - mDot::mdot_file openUserFile(const char* file, int mode); - - // Seek an open file - // file - mdot file struct - // offset - offset in bytes - // whence - where offset is based SEEK_SET, SEEK_CUR, SEEK_END - bool seekUserFile(mDot::mdot_file& file, size_t offset, int whence); - - // Read bytes from open file - // file - mdot file struct - // data - mem location to store data - // length - number of bytes to read - // returns - number of bytes written - int readUserFile(mDot::mdot_file& file, void* data, size_t length); - - // Write bytes to open file - // file - mdot file struct - // data - data to write - // length - number of bytes to write - // returns - number of bytes written - int writeUserFile(mDot::mdot_file& file, void* data, size_t length); - - // Close open file - // file - mdot file struct - bool closeUserFile(mDot::mdot_file& file); - - // List user files stored in flash - std::vector<mDot::mdot_file> listUserFiles(); - - // Move file into the firmware upgrade path to be flashed on next boot - // file - name of file - bool moveUserFileToFirmwareUpgrade(const char* file); - - // get current statistics - // Join Attempts, Join Fails, Up Packets, Down Packets, Missed Acks - mdot_stats getStats(); - - // reset statistics - // Join Attempts, Join Fails, Up Packets, Down Packets, Missed Acks - void resetStats(); - - // Convert pin number 2-8 to pin name DIO2-DI8 - static PinName pinNum2Name(uint8_t num); - - // Convert pin name DIO2-DI8 to pin number 2-8 - static uint8_t pinName2Num(PinName name); - - // Convert pin name DIO2-DI8 to string - static std::string pinName2Str(PinName name); + // get/set serial flow control enabled + // set function returns MDOT_OK if success + int32_t setFlowControl(const bool& on); + bool getFlowControl(); - uint64_t crc64(uint64_t crc, const unsigned char *s, uint64_t l); + // get/set serial clear on error + // if enabled the data read from the serial port will be discarded if it cannot be sent or if the send fails + // set function returns MDOT_OK if success + int32_t setSerialClearOnError(const bool& on); + bool getSerialClearOnError(); // MTS_RADIO_DEBUG_COMMANDS @@ -848,7 +1123,6 @@ std::map<uint8_t, uint8_t> dumpRegisters(); void eraseFlash(); - // deprecated - use setWakeInterval int32_t setSerialWakeInterval(const uint32_t& interval); // deprecated - use getWakeInterval @@ -864,9 +1138,23 @@ // 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); + } + private: mdot_stats _stats; + FunctionPointer _wakeup_callback; + + bool _standbyFlag; + bool _testMode; + uint8_t _savedPort; + void handleTestModePacket(); + }; #endif