Eliott Fersko
libmDot0mbed5
Fork of
libmDot-mbed5
by 
MultiTech
Diff: mDot.h
- Revision:
- 0:c62615f15125
- Child:
- 4:94969e981dcc
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/mDot.h Wed Jun 24 21:51:42 2015 +0000
@@ -0,0 +1,675 @@
+/************************************************
+ * MultiTech MTDOT Library
+ * Copyright (c) 2015 MultiTech Systems
+ *
+ * See LICENSE file for license information
+ ***********************************************/
+
+#ifndef MDOT_H
+#define MDOT_H
+
+#include "mbed.h"
+#include "rtos.h"
+#include <vector>
+#include <map>
+#include <string>
+
+class LoRaMacEvent;
+class LoRaConfig;
+class LoRaMac;
+class MdotRadio;
+
+
+class mDot {
+
+ private:
+
+ mDot();
+ ~mDot();
+
+ static void idle(void const* args) {
+ while (1)
+ __WFI();
+ }
+
+ void setLastError(const std::string& str);
+
+ static bool validateBaudRate(const uint32_t& baud);
+ static bool validateFrequencySubBand(const uint8_t& band);
+ bool validateDataRate(const uint8_t& dr);
+
+ int32_t joinBase(const uint32_t& retries);
+ int32_t sendBase(const std::vector<uint8_t>& data, const bool& confirmed = false, const bool& blocking = true, const bool& highBw = false);
+ void waitForPacket();
+ void waitForLinkCheck();
+
+ void setActivityLedState(const uint8_t& state);
+ uint8_t getActivityLedState();
+
+ void blinkActivityLed(void) {
+ _activity_led = !_activity_led;
+ }
+
+ mDot(const mDot&);
+ mDot& operator=(const mDot&);
+
+ static mDot* _instance;
+
+ LoRaMac* _mac;
+ MdotRadio* _radio;
+ LoRaMacEvent* _events;
+ LoRaConfig* _config;
+ Thread _idle_thread;
+ std::string _last_error;
+ static const uint32_t _baud_rates[];
+ uint8_t _activity_led_state;
+ Ticker _tick;
+ DigitalOut _activity_led;
+ uint16_t _linkFailCount;
+
+ typedef enum {
+ OFF, ON, BLINK,
+ } state;
+
+ public:
+
+ typedef enum {
+ MDOT_OK = 0,
+ MDOT_INVALID_PARAM = -1,
+ MDOT_TX_ERROR = -2,
+ MDOT_RX_ERROR = -3,
+ MDOT_JOIN_ERROR = -4,
+ MDOT_TIMEOUT = -5,
+ MDOT_NOT_JOINED = -6,
+ MDOT_ENCRYPTION_DISABLED = -7,
+ MDOT_NO_FREE_CHAN = -8,
+ MDOT_ERROR = -1024,
+ } mdot_ret_code;
+
+ enum JoinMode {
+ MANUAL, OTA, AUTO_OTA
+ };
+
+ enum Mode {
+ COMMAND_MODE, SERIAL_MODE
+ };
+
+ enum RX_Output {
+ HEXADECIMAL, BINARY
+ };
+
+ enum DataRates {
+ SF_12, SF_11, SF_10, SF_9, SF_8, SF_7, SF_7H, SF_50
+ };
+
+ enum FrequencyBands {
+ FB_868, FB_915
+ };
+
+ enum FrequencySubBands {
+ FSB_ALL, FSB_1, FSB_2, FSB_3, FSB_4, FSB_5, FSB_6, FSB_7, FSB_8
+ };
+
+ typedef struct {
+ uint32_t Up;
+ uint32_t Down;
+ uint32_t Joins;
+ uint32_t JoinFails;
+ uint32_t MissedAcks;
+ } mdot_stats;
+
+ typedef struct {
+ int16_t last;
+ int16_t min;
+ int16_t max;
+ int16_t avg;
+ } rssi_stats;
+
+ typedef struct {
+ int8_t last;
+ int8_t min;
+ int8_t max;
+ int8_t avg;
+ } snr_stats;
+
+ typedef struct {
+ bool status;
+ int32_t dBm;
+ uint32_t gateways;
+ std::vector<uint8_t> payload;
+ } link_check;
+
+ typedef struct {
+ int32_t status;
+ int16_t rssi;
+ int16_t snr;
+ } ping_response;
+
+ static const uint8_t MaxLengths_915[];
+ static const uint8_t MaxLengths_868[];
+
+ static std::string JoinModeStr(uint8_t mode);
+ static std::string ModeStr(uint8_t mode);
+ static std::string RxOutputStr(uint8_t format);
+ static std::string DataRateStr(uint8_t rate);
+ static std::string FrequencyBandStr(uint8_t band);
+ static std::string FrequencySubBandStr(uint8_t band);
+
+ /** Get a handle to the singleton object
+ * @returns pointer to mDot object
+ */
+ static mDot* getInstance();
+
+ /** Get library version information
+ * @returns string containing library version information
+ */
+ std::string getId();
+
+ /** Perform a soft reset of the system
+ */
+ void resetCpu();
+
+ /** Reset config to factory default
+ */
+ void resetConfig();
+
+ /** Save config data to non volatile memory
+ * @returns true if success, false if failure
+ */
+ bool saveConfig();
+
+ /** Set the log level for the library
+ * options are:
+ * NONE_LEVEL - logging is off at this level
+ * FATAL_LEVEL - only critical errors will be reported
+ * ERROR_LEVEL
+ * WARNING_LEVEL
+ * INFO_LEVEL
+ * DEBUG_LEVEL
+ * TRACE_LEVEL - every detail will be reported
+ * @param level the level to log at
+ * @returns MDOT_OK if success
+ */
+ int32_t setLogLevel(const uint8_t& level);
+
+ /** Get the current log level for the library
+ * @returns current log level
+ */
+ uint8_t getLogLevel();
+
+ /** Get list of channel frequencies currently in use
+ * @returns vector of channels currently in use
+ */
+ std::vector<uint32_t> getChannels();
+
+ /** Get frequency band
+ * @returns FB_915 if configured for United States, FB_868 if configured for Europe
+ */
+ uint8_t getFrequencyBand();
+
+ /** 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 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)
+ * @returns MDOT_OK if success
+ */
+ int32_t setFrequencySubBand(const uint8_t& band);
+
+ /** Get frequency sub band
+ * @returns frequency sub band currently in use
+ */
+ uint8_t getFrequencySubBand();
+
+ /** Enable/disable public network mode
+ * for use with Conduit gateway and MTAC_LORA, disable public network mode
+ * @param on should be true to enable public network mode
+ * @returns MDOT_OK if success
+ */
+ int32_t setPublicNetwork(const bool& on);
+
+ /** Get public network mode
+ * @returns true if public network mode is enabled
+ */
+ bool getPublicNetwork();
+
+ /** Get the device ID
+ * @returns vector containing the device ID (size 8)
+ */
+ std::vector<uint8_t> getDeviceId();
+
+ /** 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
+ * @returns MDOT_OK if success
+ */
+ int32_t setNetworkAddress(const std::vector<uint8_t>& addr);
+
+ /** Get network address
+ * @returns vector containing network address (size 4)
+ */
+ std::vector<uint8_t> getNetworkAddress();
+
+ /** Set network session key
+ * for use with MANUAL network join mode, will be assigned in OTA & AUTO_OTA modes
+ * @param key a vector of 16 bytes
+ * @returns MDOT_OK if success
+ */
+ int32_t setNetworkSessionKey(const std::vector<uint8_t>& key);
+
+ /** Get network session key
+ * @returns vector containing network session key (size 16)
+ */
+ std::vector<uint8_t> getNetworkSessionKey();
+
+ /** Set data session key
+ * for use with MANUAL network join mode, will be assigned in OTA & AUTO_OTA modes
+ * @param key a vector of 16 bytes
+ * @returns MDOT_OK if success
+ */
+ int32_t setDataSessionKey(const std::vector<uint8_t>& key);
+
+ /** Get data session key
+ * @returns vector containing data session key (size 16)
+ */
+ std::vector<uint8_t> getDataSessionKey();
+
+ /** Set network name
+ * for use with OTA & AUTO_OTA network join modes
+ * generates network ID (crc64 of name) automatically
+ * @param name a string of of at least 8 bytes and no more than 128 bytes
+ * @return MDOT_OK if success
+ */
+ int32_t setNetworkName(const std::string& name);
+
+ /** Get network name
+ * @return string containing network name (size 8 to 128)
+ */
+ std::string getNetworkName();
+
+ /** Set network ID
+ * for use with OTA & AUTO_OTA network join modes
+ * setting network ID via this function sets network name to empty
+ * @param id a vector of 8 bytes
+ * @returns MDOT_OK if success
+ */
+ int32_t setNetworkId(const std::vector<uint8_t>& id);
+
+ /** Get network ID
+ * @returns vector containing network ID (size 8)
+ */
+ std::vector<uint8_t> getNetworkId();
+
+ /** Set network passphrase
+ * for use with OTA & AUTO_OTA network join modes
+ * generates network key (cmac of passphrase) automatically
+ * @param name a string of of at least 8 bytes and no more than 128 bytes
+ * @return MDOT_OK if success
+ */
+ int32_t setNetworkPassphrase(const std::string& passphrase);
+
+ /** Get network passphrase
+ * @return string containing network passphrase (size 8 to 128)
+ */
+ std::string getNetworkPassphrase();
+
+ /** Set network key
+ * for use with OTA & AUTO_OTA network join modes
+ * setting network key via this function sets network passphrase to empty
+ * @param id a vector of 16 bytes
+ * @returns MDOT_OK if success
+ */
+ int32_t setNetworkKey(const std::vector<uint8_t>& id);
+
+ /** Get network key
+ * @returns a vector containing network key (size 16)
+ */
+ std::vector<uint8_t> getNetworkKey();
+
+ /** Attempt to join network
+ * retries according to configuration set by setJoinRetries()
+ * @returns MDOT_OK if success
+ */
+ int32_t joinNetwork();
+
+ /** Attempts to join network once
+ * @returns MDOT_OK if success
+ */
+ int32_t joinNetworkOnce();
+
+ /** Resets current network session, essentially disconnecting from the network
+ * has no effect for MANUAL network join mode
+ */
+ void resetNetworkSession();
+
+ /** Set number of times joining will retry before giving up
+ * @param retries must be between 0 - 255
+ * @returns MDOT_OK if success
+ */
+ int32_t setJoinRetries(const uint8_t& retries);
+
+ /** Set number of times joining will retry before giving up
+ * @returns join retries (0 - 255)
+ */
+ uint8_t getJoinRetries();
+
+ /** Set network join mode
+ * MANUAL: set network address and session keys manually
+ * OTA: User sets network name and passphrase, then attempts to join
+ * AUTO_OTA: same as OTA, but network sessions can be saved and restored
+ * @param mode MANUAL, OTA, or AUTO_OTA
+ * @returns MDOT_OK if success
+ */
+ int32_t setJoinMode(const uint8_t& mode);
+
+ /** Get network join mode
+ * @returns MANUAL, OTA, or AUTO_OTA
+ */
+ uint8_t getJoinMode();
+
+ /** Get network join status
+ * @returns true if currently joined to network
+ */
+ bool getNetworkJoinStatus();
+
+ /** Do a network link check
+ * application data may be returned in response to a network link check command
+ * @returns link_check structure containing success, dBm above noise floor, gateways in range, and packet payload
+ */
+ link_check networkLinkCheck();
+
+ /** Set network link check count to perform automatic link checks every count packets
+ * only applicable if ACKs are disabled
+ * @param count must be between 0 - 255
+ * @returns MDOT_OK if success
+ */
+ int32_t setLinkCheckCount(const uint8_t& count);
+
+ /** Get network link check count
+ * @returns count (0 - 255)
+ */
+ uint8_t getLinkCheckCount();
+
+ /** Set network link check threshold, number of link check failures or missed acks to tolerate
+ * before considering network connection lost
+ * @pararm count must be between 0 - 255
+ * @returns MDOT_OK if success
+ */
+ int32_t setLinkCheckThreshold(const uint8_t& count);
+
+ /** Get network link check threshold
+ * @returns threshold (0 - 255)
+ */
+ uint8_t getLinkCheckThreshold();
+
+ /** Get UpLinkCounter
+ * @returns number of packets sent to the gateway during this network session (sequence number)
+ */
+ uint32_t getUpLinkCounter();
+
+ /** 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
+ * @returns MDOT_OK if success
+ */
+ int32_t setAesEncryption(const bool& on);
+
+ /** Get AES encryption
+ * @returns true if AES encryption is enabled
+ */
+ bool getAesEncryption();
+
+ /** Get RSSI stats
+ * @returns rssi_stats struct containing last, min, max, and avg RSSI
+ */
+ rssi_stats getRssiStats();
+
+ /** Get SNR stats
+ * @returns snr_stats struct containing last, min, max, and avg SNR
+ */
+ snr_stats getSnrStats();
+
+ /** Get ms until next free channel
+ * only applicable for European models, US models return 0
+ * @returns time (ms) until a channel is free to use for transmitting
+ */
+ uint32_t getNextTxMs();
+
+ /** Get data pending
+ * only valid after sending data to the gateway
+ * @returns true if server has available packet(s)
+ */
+ bool getDataPending();
+
+ /** 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
+ * @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)
+ */
+ uint8_t getTxDataRate();
+
+ /** Set TX power
+ * power affects maximum range
+ * @param power 2 dBm - 20 dBm
+ * @returns MDOT_OK if success
+ */
+ int32_t setTxPower(const uint32_t& power);
+
+ /** Get TX power
+ * @returns TX power (2 dBm - 20 dBm)
+ */
+ uint32_t getTxPower();
+
+ /** 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
+ * @returns MDOT_OK if success
+ */
+ int32_t setTxWait(const bool& enable);
+
+ /** Get TX wait
+ * @returns true if TX wait is enabled
+ */
+ bool getTxWait();
+
+ /** Get time on air
+ * @returns the amount of time (in ms) it would take to send bytes bytes based on current configuration
+ */
+ uint32_t getTimeOnAir(uint8_t bytes);
+
+ /** Get min frequency
+ * @returns minimum frequency based on current configuration
+ */
+ uint32_t getMinFrequency();
+
+ /** Get max frequency
+ * @returns maximum frequency based on current configuration
+ */
+ uint32_t getMaxFrequency();
+
+ /** Set forward error correction bytes
+ * @param bytes 1 - 4 bytes
+ * @returns MDOT_OK if success
+ */
+ int32_t setFec(const uint8_t& bytes);
+
+ /** Get forward error correction bytes
+ * @returns bytes (1 - 4)
+ */
+ uint8_t getFec();
+
+ /** Enable/disable CRC checking of packets
+ * CRC checking must be enabled for use with Conduit gateway and MTAC_LORA card
+ * @param on set to true to enable CRC checking
+ * @returns MDOT_OK if success
+ */
+ int32_t setCrc(const bool& on);
+
+ /** Get CRC checking
+ * @returns true if CRC checking is enabled
+ */
+ bool getCrc();
+
+ /** Set ack
+ * @param retries 0 to disable acks, otherwise 1 - 8
+ * @returns MDOT_OK if success
+ */
+ int32_t setAck(const uint8_t& retries);
+
+ /** Get ack
+ * @returns 0 if acks are disabled, otherwise retries (1 - 8)
+ */
+ uint8_t getAck();
+
+ /** 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)
+ * @returns MDOT_OK if packet was sent successfully (ACKs disabled), or if an ACK was received (ACKs enabled)
+ */
+ int32_t send(const std::vector<uint8_t>& data, const bool& blocking = true, const bool& highBw = false);
+
+ /** Fetch data received from the gateway
+ * this function only checks to see if a packet has been received - it does not open a receive window
+ * send() must be called before recv()
+ * @param data a vector to put the received data into
+ * @returns MDOT_OK if packet was successfully received
+ */
+ 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
+ */
+ ping_response ping();
+
+ /** Get return code string
+ * @returns string containing a description of the given error code
+ */
+ static std::string getReturnCodeString(const int32_t& code);
+
+ /** Get last error
+ * @returns string explaining the last error that occured
+ */
+ std::string getLastError();
+
+ /******************************************
+ * THESE FEATURES ARE NOT FULLY IMPLEMENTED
+ *****************************************/
+ void sleep();
+ void wakeup();
+
+ // 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();
+
+ /*************************************************************************
+ * The following functions are only used by the AT command application and
+ * should not be used by standard applications consuming the mDot library
+ ************************************************************************/
+
+ // set/get configured baud rate for command port
+ // only for use in conjunction with AT interface
+ // set function returns MDOT_OK if success
+ int32_t setBaud(const uint32_t& baud);
+ uint32_t getBaud();
+
+ // set/get baud rate for debug port
+ // set function returns MDOT_OK if success
+ int32_t setDebugBaud(const uint32_t& baud);
+ uint32_t getDebugBaud();
+
+ // set/get command terminal echo
+ // set function returns MDOT_OK if success
+ int32_t setEcho(const bool& on);
+ bool getEcho();
+
+ // set/get command terminal verbose mode
+ // set function returns MDOT_OK if success
+ int32_t setVerbose(const bool& on);
+ bool getVerbose();
+
+ // set/get startup mode
+ // COMMAND_MODE (default), starts up ready to accept AT commands
+ // SERIAL_MODE, read serial data and send it as LoRa packets
+ // set function returns MDOT_OK if success
+ int32_t setStartUpMode(const uint8_t& mode);
+ uint8_t getStartUpMode();
+
+ int32_t setRxDataRate(const uint8_t& dr);
+ 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);
+ uint32_t getTxFrequency();
+ 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
+ // set function returns MDOT_OK if success
+ int32_t setRxOutput(const uint8_t& mode);
+ uint8_t getRxOutput();
+
+ // get/set serial wake interval
+ // valid values are 2 s - INT_MAX (2147483647) s
+ // set function returns MDOT_OK if success
+ int32_t setSerialWakeInterval(const uint32_t& interval);
+ uint32_t getSerialWakeInterval();
+
+ // get/set serial wake delay
+ // valid values are 2 ms - INT_MAX (2147483647) ms
+ // set function returns MDOT_OK if success
+ int32_t setSerialWakeDelay(const uint32_t& delay);
+ uint32_t getSerialWakeDelay();
+
+ // get/set serial receive timeout
+ // valid values are 0 ms - 65000 ms
+ // set function returns MDOT_OK if success
+ int32_t setSerialReceiveTimeout(const uint16_t& timeout);
+ uint16_t getSerialReceiveTimeout();
+
+ uint64_t crc64(uint64_t crc, const unsigned char *s, uint64_t l);
+
+ // MTS_RADIO_DEBUG_COMMANDS
+ int32_t setDeviceId(const std::vector<uint8_t>& id);
+ int32_t setFrequencyBand(const uint8_t& band);
+ bool saveProtectedConfig();
+ void resetRadio();
+ int32_t setRadioMode(const uint8_t& mode);
+ std::map<uint8_t, uint8_t> dumpRegisters();
+ void eraseFlash();
+
+ mdot_stats getStats();
+
+ private:
+ mdot_stats _stats;
+
+};
+
+#endif