libmDot-mbed5 - Stable version of the mDot library for mbed 5. Th…

MultiTech » Code » 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:

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

mDot.h@0:c62615f15125, 2015-06-24 (annotated)

Committer:: mfiore
Date:: Wed Jun 24 21:51:42 2015 +0000
Revision:: 0:c62615f15125
Child:: 4:94969e981dcc

initial commit, mDot header

Who changed what in which revision?

User	Revision	Line number	New contents of line
mfiore	0:c62615f15125	1	/************************************************
mfiore	0:c62615f15125	2	* MultiTech MTDOT Library
mfiore	0:c62615f15125	3	* Copyright (c) 2015 MultiTech Systems
mfiore	0:c62615f15125	4	*
mfiore	0:c62615f15125	5	* See LICENSE file for license information
mfiore	0:c62615f15125	6	***********************************************/
mfiore	0:c62615f15125	7
mfiore	0:c62615f15125	8	#ifndef MDOT_H
mfiore	0:c62615f15125	9	#define MDOT_H
mfiore	0:c62615f15125	10
mfiore	0:c62615f15125	11	#include "mbed.h"
mfiore	0:c62615f15125	12	#include "rtos.h"
mfiore	0:c62615f15125	13	#include <vector>
mfiore	0:c62615f15125	14	#include <map>
mfiore	0:c62615f15125	15	#include <string>
mfiore	0:c62615f15125	16
mfiore	0:c62615f15125	17	class LoRaMacEvent;
mfiore	0:c62615f15125	18	class LoRaConfig;
mfiore	0:c62615f15125	19	class LoRaMac;
mfiore	0:c62615f15125	20	class MdotRadio;
mfiore	0:c62615f15125	21
mfiore	0:c62615f15125	22
mfiore	0:c62615f15125	23	class mDot {
mfiore	0:c62615f15125	24
mfiore	0:c62615f15125	25	private:
mfiore	0:c62615f15125	26
mfiore	0:c62615f15125	27	mDot();
mfiore	0:c62615f15125	28	~mDot();
mfiore	0:c62615f15125	29
mfiore	0:c62615f15125	30	static void idle(void const* args) {
mfiore	0:c62615f15125	31	while (1)
mfiore	0:c62615f15125	32	__WFI();
mfiore	0:c62615f15125	33	}
mfiore	0:c62615f15125	34
mfiore	0:c62615f15125	35	void setLastError(const std::string& str);
mfiore	0:c62615f15125	36
mfiore	0:c62615f15125	37	static bool validateBaudRate(const uint32_t& baud);
mfiore	0:c62615f15125	38	static bool validateFrequencySubBand(const uint8_t& band);
mfiore	0:c62615f15125	39	bool validateDataRate(const uint8_t& dr);
mfiore	0:c62615f15125	40
mfiore	0:c62615f15125	41	int32_t joinBase(const uint32_t& retries);
mfiore	0:c62615f15125	42	int32_t sendBase(const std::vector<uint8_t>& data, const bool& confirmed = false, const bool& blocking = true, const bool& highBw = false);
mfiore	0:c62615f15125	43	void waitForPacket();
mfiore	0:c62615f15125	44	void waitForLinkCheck();
mfiore	0:c62615f15125	45
mfiore	0:c62615f15125	46	void setActivityLedState(const uint8_t& state);
mfiore	0:c62615f15125	47	uint8_t getActivityLedState();
mfiore	0:c62615f15125	48
mfiore	0:c62615f15125	49	void blinkActivityLed(void) {
mfiore	0:c62615f15125	50	_activity_led = !_activity_led;
mfiore	0:c62615f15125	51	}
mfiore	0:c62615f15125	52
mfiore	0:c62615f15125	53	mDot(const mDot&);
mfiore	0:c62615f15125	54	mDot& operator=(const mDot&);
mfiore	0:c62615f15125	55
mfiore	0:c62615f15125	56	static mDot* _instance;
mfiore	0:c62615f15125	57
mfiore	0:c62615f15125	58	LoRaMac* _mac;
mfiore	0:c62615f15125	59	MdotRadio* _radio;
mfiore	0:c62615f15125	60	LoRaMacEvent* _events;
mfiore	0:c62615f15125	61	LoRaConfig* _config;
mfiore	0:c62615f15125	62	Thread _idle_thread;
mfiore	0:c62615f15125	63	std::string _last_error;
mfiore	0:c62615f15125	64	static const uint32_t _baud_rates[];
mfiore	0:c62615f15125	65	uint8_t _activity_led_state;
mfiore	0:c62615f15125	66	Ticker _tick;
mfiore	0:c62615f15125	67	DigitalOut _activity_led;
mfiore	0:c62615f15125	68	uint16_t _linkFailCount;
mfiore	0:c62615f15125	69
mfiore	0:c62615f15125	70	typedef enum {
mfiore	0:c62615f15125	71	OFF, ON, BLINK,
mfiore	0:c62615f15125	72	} state;
mfiore	0:c62615f15125	73
mfiore	0:c62615f15125	74	public:
mfiore	0:c62615f15125	75
mfiore	0:c62615f15125	76	typedef enum {
mfiore	0:c62615f15125	77	MDOT_OK = 0,
mfiore	0:c62615f15125	78	MDOT_INVALID_PARAM = -1,
mfiore	0:c62615f15125	79	MDOT_TX_ERROR = -2,
mfiore	0:c62615f15125	80	MDOT_RX_ERROR = -3,
mfiore	0:c62615f15125	81	MDOT_JOIN_ERROR = -4,
mfiore	0:c62615f15125	82	MDOT_TIMEOUT = -5,
mfiore	0:c62615f15125	83	MDOT_NOT_JOINED = -6,
mfiore	0:c62615f15125	84	MDOT_ENCRYPTION_DISABLED = -7,
mfiore	0:c62615f15125	85	MDOT_NO_FREE_CHAN = -8,
mfiore	0:c62615f15125	86	MDOT_ERROR = -1024,
mfiore	0:c62615f15125	87	} mdot_ret_code;
mfiore	0:c62615f15125	88
mfiore	0:c62615f15125	89	enum JoinMode {
mfiore	0:c62615f15125	90	MANUAL, OTA, AUTO_OTA
mfiore	0:c62615f15125	91	};
mfiore	0:c62615f15125	92
mfiore	0:c62615f15125	93	enum Mode {
mfiore	0:c62615f15125	94	COMMAND_MODE, SERIAL_MODE
mfiore	0:c62615f15125	95	};
mfiore	0:c62615f15125	96
mfiore	0:c62615f15125	97	enum RX_Output {
mfiore	0:c62615f15125	98	HEXADECIMAL, BINARY
mfiore	0:c62615f15125	99	};
mfiore	0:c62615f15125	100
mfiore	0:c62615f15125	101	enum DataRates {
mfiore	0:c62615f15125	102	SF_12, SF_11, SF_10, SF_9, SF_8, SF_7, SF_7H, SF_50
mfiore	0:c62615f15125	103	};
mfiore	0:c62615f15125	104
mfiore	0:c62615f15125	105	enum FrequencyBands {
mfiore	0:c62615f15125	106	FB_868, FB_915
mfiore	0:c62615f15125	107	};
mfiore	0:c62615f15125	108
mfiore	0:c62615f15125	109	enum FrequencySubBands {
mfiore	0:c62615f15125	110	FSB_ALL, FSB_1, FSB_2, FSB_3, FSB_4, FSB_5, FSB_6, FSB_7, FSB_8
mfiore	0:c62615f15125	111	};
mfiore	0:c62615f15125	112
mfiore	0:c62615f15125	113	typedef struct {
mfiore	0:c62615f15125	114	uint32_t Up;
mfiore	0:c62615f15125	115	uint32_t Down;
mfiore	0:c62615f15125	116	uint32_t Joins;
mfiore	0:c62615f15125	117	uint32_t JoinFails;
mfiore	0:c62615f15125	118	uint32_t MissedAcks;
mfiore	0:c62615f15125	119	} mdot_stats;
mfiore	0:c62615f15125	120
mfiore	0:c62615f15125	121	typedef struct {
mfiore	0:c62615f15125	122	int16_t last;
mfiore	0:c62615f15125	123	int16_t min;
mfiore	0:c62615f15125	124	int16_t max;
mfiore	0:c62615f15125	125	int16_t avg;
mfiore	0:c62615f15125	126	} rssi_stats;
mfiore	0:c62615f15125	127
mfiore	0:c62615f15125	128	typedef struct {
mfiore	0:c62615f15125	129	int8_t last;
mfiore	0:c62615f15125	130	int8_t min;
mfiore	0:c62615f15125	131	int8_t max;
mfiore	0:c62615f15125	132	int8_t avg;
mfiore	0:c62615f15125	133	} snr_stats;
mfiore	0:c62615f15125	134
mfiore	0:c62615f15125	135	typedef struct {
mfiore	0:c62615f15125	136	bool status;
mfiore	0:c62615f15125	137	int32_t dBm;
mfiore	0:c62615f15125	138	uint32_t gateways;
mfiore	0:c62615f15125	139	std::vector<uint8_t> payload;
mfiore	0:c62615f15125	140	} link_check;
mfiore	0:c62615f15125	141
mfiore	0:c62615f15125	142	typedef struct {
mfiore	0:c62615f15125	143	int32_t status;
mfiore	0:c62615f15125	144	int16_t rssi;
mfiore	0:c62615f15125	145	int16_t snr;
mfiore	0:c62615f15125	146	} ping_response;
mfiore	0:c62615f15125	147
mfiore	0:c62615f15125	148	static const uint8_t MaxLengths_915[];
mfiore	0:c62615f15125	149	static const uint8_t MaxLengths_868[];
mfiore	0:c62615f15125	150
mfiore	0:c62615f15125	151	static std::string JoinModeStr(uint8_t mode);
mfiore	0:c62615f15125	152	static std::string ModeStr(uint8_t mode);
mfiore	0:c62615f15125	153	static std::string RxOutputStr(uint8_t format);
mfiore	0:c62615f15125	154	static std::string DataRateStr(uint8_t rate);
mfiore	0:c62615f15125	155	static std::string FrequencyBandStr(uint8_t band);
mfiore	0:c62615f15125	156	static std::string FrequencySubBandStr(uint8_t band);
mfiore	0:c62615f15125	157
mfiore	0:c62615f15125	158	/** Get a handle to the singleton object
mfiore	0:c62615f15125	159	* @returns pointer to mDot object
mfiore	0:c62615f15125	160	*/
mfiore	0:c62615f15125	161	static mDot* getInstance();
mfiore	0:c62615f15125	162
mfiore	0:c62615f15125	163	/** Get library version information
mfiore	0:c62615f15125	164	* @returns string containing library version information
mfiore	0:c62615f15125	165	*/
mfiore	0:c62615f15125	166	std::string getId();
mfiore	0:c62615f15125	167
mfiore	0:c62615f15125	168	/** Perform a soft reset of the system
mfiore	0:c62615f15125	169	*/
mfiore	0:c62615f15125	170	void resetCpu();
mfiore	0:c62615f15125	171
mfiore	0:c62615f15125	172	/** Reset config to factory default
mfiore	0:c62615f15125	173	*/
mfiore	0:c62615f15125	174	void resetConfig();
mfiore	0:c62615f15125	175
mfiore	0:c62615f15125	176	/** Save config data to non volatile memory
mfiore	0:c62615f15125	177	* @returns true if success, false if failure
mfiore	0:c62615f15125	178	*/
mfiore	0:c62615f15125	179	bool saveConfig();
mfiore	0:c62615f15125	180
mfiore	0:c62615f15125	181	/** Set the log level for the library
mfiore	0:c62615f15125	182	* options are:
mfiore	0:c62615f15125	183	* NONE_LEVEL - logging is off at this level
mfiore	0:c62615f15125	184	* FATAL_LEVEL - only critical errors will be reported
mfiore	0:c62615f15125	185	* ERROR_LEVEL
mfiore	0:c62615f15125	186	* WARNING_LEVEL
mfiore	0:c62615f15125	187	* INFO_LEVEL
mfiore	0:c62615f15125	188	* DEBUG_LEVEL
mfiore	0:c62615f15125	189	* TRACE_LEVEL - every detail will be reported
mfiore	0:c62615f15125	190	* @param level the level to log at
mfiore	0:c62615f15125	191	* @returns MDOT_OK if success
mfiore	0:c62615f15125	192	*/
mfiore	0:c62615f15125	193	int32_t setLogLevel(const uint8_t& level);
mfiore	0:c62615f15125	194
mfiore	0:c62615f15125	195	/** Get the current log level for the library
mfiore	0:c62615f15125	196	* @returns current log level
mfiore	0:c62615f15125	197	*/
mfiore	0:c62615f15125	198	uint8_t getLogLevel();
mfiore	0:c62615f15125	199
mfiore	0:c62615f15125	200	/** Get list of channel frequencies currently in use
mfiore	0:c62615f15125	201	* @returns vector of channels currently in use
mfiore	0:c62615f15125	202	*/
mfiore	0:c62615f15125	203	std::vector<uint32_t> getChannels();
mfiore	0:c62615f15125	204
mfiore	0:c62615f15125	205	/** Get frequency band
mfiore	0:c62615f15125	206	* @returns FB_915 if configured for United States, FB_868 if configured for Europe
mfiore	0:c62615f15125	207	*/
mfiore	0:c62615f15125	208	uint8_t getFrequencyBand();
mfiore	0:c62615f15125	209
mfiore	0:c62615f15125	210	/** Set frequency sub band
mfiore	0:c62615f15125	211	* only applicable if frequency band is set for United States (FB_915)
mfiore	0:c62615f15125	212	* sub band 0 will allow the radio to use all 64 channels
mfiore	0:c62615f15125	213	* sub band 1 - 8 will allow the radio to use the 8 channels in that sub band
mfiore	0:c62615f15125	214	* for use with Conduit gateway and MTAC_LORA, use sub bands 1 - 8, not sub band 0
mfiore	0:c62615f15125	215	* @param band the sub band to use (0 - 8)
mfiore	0:c62615f15125	216	* @returns MDOT_OK if success
mfiore	0:c62615f15125	217	*/
mfiore	0:c62615f15125	218	int32_t setFrequencySubBand(const uint8_t& band);
mfiore	0:c62615f15125	219
mfiore	0:c62615f15125	220	/** Get frequency sub band
mfiore	0:c62615f15125	221	* @returns frequency sub band currently in use
mfiore	0:c62615f15125	222	*/
mfiore	0:c62615f15125	223	uint8_t getFrequencySubBand();
mfiore	0:c62615f15125	224
mfiore	0:c62615f15125	225	/** Enable/disable public network mode
mfiore	0:c62615f15125	226	* for use with Conduit gateway and MTAC_LORA, disable public network mode
mfiore	0:c62615f15125	227	* @param on should be true to enable public network mode
mfiore	0:c62615f15125	228	* @returns MDOT_OK if success
mfiore	0:c62615f15125	229	*/
mfiore	0:c62615f15125	230	int32_t setPublicNetwork(const bool& on);
mfiore	0:c62615f15125	231
mfiore	0:c62615f15125	232	/** Get public network mode
mfiore	0:c62615f15125	233	* @returns true if public network mode is enabled
mfiore	0:c62615f15125	234	*/
mfiore	0:c62615f15125	235	bool getPublicNetwork();
mfiore	0:c62615f15125	236
mfiore	0:c62615f15125	237	/** Get the device ID
mfiore	0:c62615f15125	238	* @returns vector containing the device ID (size 8)
mfiore	0:c62615f15125	239	*/
mfiore	0:c62615f15125	240	std::vector<uint8_t> getDeviceId();
mfiore	0:c62615f15125	241
mfiore	0:c62615f15125	242	/** Set network address
mfiore	0:c62615f15125	243	* for use with MANUAL network join mode, will be assigned in OTA & AUTO_OTA modes
mfiore	0:c62615f15125	244	* @param addr a vector of 4 bytes
mfiore	0:c62615f15125	245	* @returns MDOT_OK if success
mfiore	0:c62615f15125	246	*/
mfiore	0:c62615f15125	247	int32_t setNetworkAddress(const std::vector<uint8_t>& addr);
mfiore	0:c62615f15125	248
mfiore	0:c62615f15125	249	/** Get network address
mfiore	0:c62615f15125	250	* @returns vector containing network address (size 4)
mfiore	0:c62615f15125	251	*/
mfiore	0:c62615f15125	252	std::vector<uint8_t> getNetworkAddress();
mfiore	0:c62615f15125	253
mfiore	0:c62615f15125	254	/** Set network session key
mfiore	0:c62615f15125	255	* for use with MANUAL network join mode, will be assigned in OTA & AUTO_OTA modes
mfiore	0:c62615f15125	256	* @param key a vector of 16 bytes
mfiore	0:c62615f15125	257	* @returns MDOT_OK if success
mfiore	0:c62615f15125	258	*/
mfiore	0:c62615f15125	259	int32_t setNetworkSessionKey(const std::vector<uint8_t>& key);
mfiore	0:c62615f15125	260
mfiore	0:c62615f15125	261	/** Get network session key
mfiore	0:c62615f15125	262	* @returns vector containing network session key (size 16)
mfiore	0:c62615f15125	263	*/
mfiore	0:c62615f15125	264	std::vector<uint8_t> getNetworkSessionKey();
mfiore	0:c62615f15125	265
mfiore	0:c62615f15125	266	/** Set data session key
mfiore	0:c62615f15125	267	* for use with MANUAL network join mode, will be assigned in OTA & AUTO_OTA modes
mfiore	0:c62615f15125	268	* @param key a vector of 16 bytes
mfiore	0:c62615f15125	269	* @returns MDOT_OK if success
mfiore	0:c62615f15125	270	*/
mfiore	0:c62615f15125	271	int32_t setDataSessionKey(const std::vector<uint8_t>& key);
mfiore	0:c62615f15125	272
mfiore	0:c62615f15125	273	/** Get data session key
mfiore	0:c62615f15125	274	* @returns vector containing data session key (size 16)
mfiore	0:c62615f15125	275	*/
mfiore	0:c62615f15125	276	std::vector<uint8_t> getDataSessionKey();
mfiore	0:c62615f15125	277
mfiore	0:c62615f15125	278	/** Set network name
mfiore	0:c62615f15125	279	* for use with OTA & AUTO_OTA network join modes
mfiore	0:c62615f15125	280	* generates network ID (crc64 of name) automatically
mfiore	0:c62615f15125	281	* @param name a string of of at least 8 bytes and no more than 128 bytes
mfiore	0:c62615f15125	282	* @return MDOT_OK if success
mfiore	0:c62615f15125	283	*/
mfiore	0:c62615f15125	284	int32_t setNetworkName(const std::string& name);
mfiore	0:c62615f15125	285
mfiore	0:c62615f15125	286	/** Get network name
mfiore	0:c62615f15125	287	* @return string containing network name (size 8 to 128)
mfiore	0:c62615f15125	288	*/
mfiore	0:c62615f15125	289	std::string getNetworkName();
mfiore	0:c62615f15125	290
mfiore	0:c62615f15125	291	/** Set network ID
mfiore	0:c62615f15125	292	* for use with OTA & AUTO_OTA network join modes
mfiore	0:c62615f15125	293	* setting network ID via this function sets network name to empty
mfiore	0:c62615f15125	294	* @param id a vector of 8 bytes
mfiore	0:c62615f15125	295	* @returns MDOT_OK if success
mfiore	0:c62615f15125	296	*/
mfiore	0:c62615f15125	297	int32_t setNetworkId(const std::vector<uint8_t>& id);
mfiore	0:c62615f15125	298
mfiore	0:c62615f15125	299	/** Get network ID
mfiore	0:c62615f15125	300	* @returns vector containing network ID (size 8)
mfiore	0:c62615f15125	301	*/
mfiore	0:c62615f15125	302	std::vector<uint8_t> getNetworkId();
mfiore	0:c62615f15125	303
mfiore	0:c62615f15125	304	/** Set network passphrase
mfiore	0:c62615f15125	305	* for use with OTA & AUTO_OTA network join modes
mfiore	0:c62615f15125	306	* generates network key (cmac of passphrase) automatically
mfiore	0:c62615f15125	307	* @param name a string of of at least 8 bytes and no more than 128 bytes
mfiore	0:c62615f15125	308	* @return MDOT_OK if success
mfiore	0:c62615f15125	309	*/
mfiore	0:c62615f15125	310	int32_t setNetworkPassphrase(const std::string& passphrase);
mfiore	0:c62615f15125	311
mfiore	0:c62615f15125	312	/** Get network passphrase
mfiore	0:c62615f15125	313	* @return string containing network passphrase (size 8 to 128)
mfiore	0:c62615f15125	314	*/
mfiore	0:c62615f15125	315	std::string getNetworkPassphrase();
mfiore	0:c62615f15125	316
mfiore	0:c62615f15125	317	/** Set network key
mfiore	0:c62615f15125	318	* for use with OTA & AUTO_OTA network join modes
mfiore	0:c62615f15125	319	* setting network key via this function sets network passphrase to empty
mfiore	0:c62615f15125	320	* @param id a vector of 16 bytes
mfiore	0:c62615f15125	321	* @returns MDOT_OK if success
mfiore	0:c62615f15125	322	*/
mfiore	0:c62615f15125	323	int32_t setNetworkKey(const std::vector<uint8_t>& id);
mfiore	0:c62615f15125	324
mfiore	0:c62615f15125	325	/** Get network key
mfiore	0:c62615f15125	326	* @returns a vector containing network key (size 16)
mfiore	0:c62615f15125	327	*/
mfiore	0:c62615f15125	328	std::vector<uint8_t> getNetworkKey();
mfiore	0:c62615f15125	329
mfiore	0:c62615f15125	330	/** Attempt to join network
mfiore	0:c62615f15125	331	* retries according to configuration set by setJoinRetries()
mfiore	0:c62615f15125	332	* @returns MDOT_OK if success
mfiore	0:c62615f15125	333	*/
mfiore	0:c62615f15125	334	int32_t joinNetwork();
mfiore	0:c62615f15125	335
mfiore	0:c62615f15125	336	/** Attempts to join network once
mfiore	0:c62615f15125	337	* @returns MDOT_OK if success
mfiore	0:c62615f15125	338	*/
mfiore	0:c62615f15125	339	int32_t joinNetworkOnce();
mfiore	0:c62615f15125	340
mfiore	0:c62615f15125	341	/** Resets current network session, essentially disconnecting from the network
mfiore	0:c62615f15125	342	* has no effect for MANUAL network join mode
mfiore	0:c62615f15125	343	*/
mfiore	0:c62615f15125	344	void resetNetworkSession();
mfiore	0:c62615f15125	345
mfiore	0:c62615f15125	346	/** Set number of times joining will retry before giving up
mfiore	0:c62615f15125	347	* @param retries must be between 0 - 255
mfiore	0:c62615f15125	348	* @returns MDOT_OK if success
mfiore	0:c62615f15125	349	*/
mfiore	0:c62615f15125	350	int32_t setJoinRetries(const uint8_t& retries);
mfiore	0:c62615f15125	351
mfiore	0:c62615f15125	352	/** Set number of times joining will retry before giving up
mfiore	0:c62615f15125	353	* @returns join retries (0 - 255)
mfiore	0:c62615f15125	354	*/
mfiore	0:c62615f15125	355	uint8_t getJoinRetries();
mfiore	0:c62615f15125	356
mfiore	0:c62615f15125	357	/** Set network join mode
mfiore	0:c62615f15125	358	* MANUAL: set network address and session keys manually
mfiore	0:c62615f15125	359	* OTA: User sets network name and passphrase, then attempts to join
mfiore	0:c62615f15125	360	* AUTO_OTA: same as OTA, but network sessions can be saved and restored
mfiore	0:c62615f15125	361	* @param mode MANUAL, OTA, or AUTO_OTA
mfiore	0:c62615f15125	362	* @returns MDOT_OK if success
mfiore	0:c62615f15125	363	*/
mfiore	0:c62615f15125	364	int32_t setJoinMode(const uint8_t& mode);
mfiore	0:c62615f15125	365
mfiore	0:c62615f15125	366	/** Get network join mode
mfiore	0:c62615f15125	367	* @returns MANUAL, OTA, or AUTO_OTA
mfiore	0:c62615f15125	368	*/
mfiore	0:c62615f15125	369	uint8_t getJoinMode();
mfiore	0:c62615f15125	370
mfiore	0:c62615f15125	371	/** Get network join status
mfiore	0:c62615f15125	372	* @returns true if currently joined to network
mfiore	0:c62615f15125	373	*/
mfiore	0:c62615f15125	374	bool getNetworkJoinStatus();
mfiore	0:c62615f15125	375
mfiore	0:c62615f15125	376	/** Do a network link check
mfiore	0:c62615f15125	377	* application data may be returned in response to a network link check command
mfiore	0:c62615f15125	378	* @returns link_check structure containing success, dBm above noise floor, gateways in range, and packet payload
mfiore	0:c62615f15125	379	*/
mfiore	0:c62615f15125	380	link_check networkLinkCheck();
mfiore	0:c62615f15125	381
mfiore	0:c62615f15125	382	/** Set network link check count to perform automatic link checks every count packets
mfiore	0:c62615f15125	383	* only applicable if ACKs are disabled
mfiore	0:c62615f15125	384	* @param count must be between 0 - 255
mfiore	0:c62615f15125	385	* @returns MDOT_OK if success
mfiore	0:c62615f15125	386	*/
mfiore	0:c62615f15125	387	int32_t setLinkCheckCount(const uint8_t& count);
mfiore	0:c62615f15125	388
mfiore	0:c62615f15125	389	/** Get network link check count
mfiore	0:c62615f15125	390	* @returns count (0 - 255)
mfiore	0:c62615f15125	391	*/
mfiore	0:c62615f15125	392	uint8_t getLinkCheckCount();
mfiore	0:c62615f15125	393
mfiore	0:c62615f15125	394	/** Set network link check threshold, number of link check failures or missed acks to tolerate
mfiore	0:c62615f15125	395	* before considering network connection lost
mfiore	0:c62615f15125	396	* @pararm count must be between 0 - 255
mfiore	0:c62615f15125	397	* @returns MDOT_OK if success
mfiore	0:c62615f15125	398	*/
mfiore	0:c62615f15125	399	int32_t setLinkCheckThreshold(const uint8_t& count);
mfiore	0:c62615f15125	400
mfiore	0:c62615f15125	401	/** Get network link check threshold
mfiore	0:c62615f15125	402	* @returns threshold (0 - 255)
mfiore	0:c62615f15125	403	*/
mfiore	0:c62615f15125	404	uint8_t getLinkCheckThreshold();
mfiore	0:c62615f15125	405
mfiore	0:c62615f15125	406	/** Get UpLinkCounter
mfiore	0:c62615f15125	407	* @returns number of packets sent to the gateway during this network session (sequence number)
mfiore	0:c62615f15125	408	*/
mfiore	0:c62615f15125	409	uint32_t getUpLinkCounter();
mfiore	0:c62615f15125	410
mfiore	0:c62615f15125	411	/** Enable/disable AES encryption
mfiore	0:c62615f15125	412	* AES encryption must be enabled for use with Conduit gateway and MTAC_LORA card
mfiore	0:c62615f15125	413	* @param on true for AES encryption to be enabled
mfiore	0:c62615f15125	414	* @returns MDOT_OK if success
mfiore	0:c62615f15125	415	*/
mfiore	0:c62615f15125	416	int32_t setAesEncryption(const bool& on);
mfiore	0:c62615f15125	417
mfiore	0:c62615f15125	418	/** Get AES encryption
mfiore	0:c62615f15125	419	* @returns true if AES encryption is enabled
mfiore	0:c62615f15125	420	*/
mfiore	0:c62615f15125	421	bool getAesEncryption();
mfiore	0:c62615f15125	422
mfiore	0:c62615f15125	423	/** Get RSSI stats
mfiore	0:c62615f15125	424	* @returns rssi_stats struct containing last, min, max, and avg RSSI
mfiore	0:c62615f15125	425	*/
mfiore	0:c62615f15125	426	rssi_stats getRssiStats();
mfiore	0:c62615f15125	427
mfiore	0:c62615f15125	428	/** Get SNR stats
mfiore	0:c62615f15125	429	* @returns snr_stats struct containing last, min, max, and avg SNR
mfiore	0:c62615f15125	430	*/
mfiore	0:c62615f15125	431	snr_stats getSnrStats();
mfiore	0:c62615f15125	432
mfiore	0:c62615f15125	433	/** Get ms until next free channel
mfiore	0:c62615f15125	434	* only applicable for European models, US models return 0
mfiore	0:c62615f15125	435	* @returns time (ms) until a channel is free to use for transmitting
mfiore	0:c62615f15125	436	*/
mfiore	0:c62615f15125	437	uint32_t getNextTxMs();
mfiore	0:c62615f15125	438
mfiore	0:c62615f15125	439	/** Get data pending
mfiore	0:c62615f15125	440	* only valid after sending data to the gateway
mfiore	0:c62615f15125	441	* @returns true if server has available packet(s)
mfiore	0:c62615f15125	442	*/
mfiore	0:c62615f15125	443	bool getDataPending();
mfiore	0:c62615f15125	444
mfiore	0:c62615f15125	445	/** Get transmitting
mfiore	0:c62615f15125	446	* @returns true if currently transmitting
mfiore	0:c62615f15125	447	*/
mfiore	0:c62615f15125	448	bool getIsTransmitting();
mfiore	0:c62615f15125	449
mfiore	0:c62615f15125	450	/** Set TX data rate
mfiore	0:c62615f15125	451	* data rates affect maximum payload size
mfiore	0:c62615f15125	452	* @param dr SF_7 - SF_12 for Europe, SF_7 - SF_10 for United States
mfiore	0:c62615f15125	453	* @returns MDOT_OK if success
mfiore	0:c62615f15125	454	*/
mfiore	0:c62615f15125	455	int32_t setTxDataRate(const uint8_t& dr);
mfiore	0:c62615f15125	456
mfiore	0:c62615f15125	457	/** Get TX data rate
mfiore	0:c62615f15125	458	* @returns current TX data rate (SF_7 - SF_12)
mfiore	0:c62615f15125	459	*/
mfiore	0:c62615f15125	460	uint8_t getTxDataRate();
mfiore	0:c62615f15125	461
mfiore	0:c62615f15125	462	/** Set TX power
mfiore	0:c62615f15125	463	* power affects maximum range
mfiore	0:c62615f15125	464	* @param power 2 dBm - 20 dBm
mfiore	0:c62615f15125	465	* @returns MDOT_OK if success
mfiore	0:c62615f15125	466	*/
mfiore	0:c62615f15125	467	int32_t setTxPower(const uint32_t& power);
mfiore	0:c62615f15125	468
mfiore	0:c62615f15125	469	/** Get TX power
mfiore	0:c62615f15125	470	* @returns TX power (2 dBm - 20 dBm)
mfiore	0:c62615f15125	471	*/
mfiore	0:c62615f15125	472	uint32_t getTxPower();
mfiore	0:c62615f15125	473
mfiore	0:c62615f15125	474	/** Enable/disable TX waiting for rx windows
mfiore	0:c62615f15125	475	* when enabled, send calls will block until a packet is received or RX timeout
mfiore	0:c62615f15125	476	* @param enable set to true if expecting responses to transmitted packets
mfiore	0:c62615f15125	477	* @returns MDOT_OK if success
mfiore	0:c62615f15125	478	*/
mfiore	0:c62615f15125	479	int32_t setTxWait(const bool& enable);
mfiore	0:c62615f15125	480
mfiore	0:c62615f15125	481	/** Get TX wait
mfiore	0:c62615f15125	482	* @returns true if TX wait is enabled
mfiore	0:c62615f15125	483	*/
mfiore	0:c62615f15125	484	bool getTxWait();
mfiore	0:c62615f15125	485
mfiore	0:c62615f15125	486	/** Get time on air
mfiore	0:c62615f15125	487	* @returns the amount of time (in ms) it would take to send bytes bytes based on current configuration
mfiore	0:c62615f15125	488	*/
mfiore	0:c62615f15125	489	uint32_t getTimeOnAir(uint8_t bytes);
mfiore	0:c62615f15125	490
mfiore	0:c62615f15125	491	/** Get min frequency
mfiore	0:c62615f15125	492	* @returns minimum frequency based on current configuration
mfiore	0:c62615f15125	493	*/
mfiore	0:c62615f15125	494	uint32_t getMinFrequency();
mfiore	0:c62615f15125	495
mfiore	0:c62615f15125	496	/** Get max frequency
mfiore	0:c62615f15125	497	* @returns maximum frequency based on current configuration
mfiore	0:c62615f15125	498	*/
mfiore	0:c62615f15125	499	uint32_t getMaxFrequency();
mfiore	0:c62615f15125	500
mfiore	0:c62615f15125	501	/** Set forward error correction bytes
mfiore	0:c62615f15125	502	* @param bytes 1 - 4 bytes
mfiore	0:c62615f15125	503	* @returns MDOT_OK if success
mfiore	0:c62615f15125	504	*/
mfiore	0:c62615f15125	505	int32_t setFec(const uint8_t& bytes);
mfiore	0:c62615f15125	506
mfiore	0:c62615f15125	507	/** Get forward error correction bytes
mfiore	0:c62615f15125	508	* @returns bytes (1 - 4)
mfiore	0:c62615f15125	509	*/
mfiore	0:c62615f15125	510	uint8_t getFec();
mfiore	0:c62615f15125	511
mfiore	0:c62615f15125	512	/** Enable/disable CRC checking of packets
mfiore	0:c62615f15125	513	* CRC checking must be enabled for use with Conduit gateway and MTAC_LORA card
mfiore	0:c62615f15125	514	* @param on set to true to enable CRC checking
mfiore	0:c62615f15125	515	* @returns MDOT_OK if success
mfiore	0:c62615f15125	516	*/
mfiore	0:c62615f15125	517	int32_t setCrc(const bool& on);
mfiore	0:c62615f15125	518
mfiore	0:c62615f15125	519	/** Get CRC checking
mfiore	0:c62615f15125	520	* @returns true if CRC checking is enabled
mfiore	0:c62615f15125	521	*/
mfiore	0:c62615f15125	522	bool getCrc();
mfiore	0:c62615f15125	523
mfiore	0:c62615f15125	524	/** Set ack
mfiore	0:c62615f15125	525	* @param retries 0 to disable acks, otherwise 1 - 8
mfiore	0:c62615f15125	526	* @returns MDOT_OK if success
mfiore	0:c62615f15125	527	*/
mfiore	0:c62615f15125	528	int32_t setAck(const uint8_t& retries);
mfiore	0:c62615f15125	529
mfiore	0:c62615f15125	530	/** Get ack
mfiore	0:c62615f15125	531	* @returns 0 if acks are disabled, otherwise retries (1 - 8)
mfiore	0:c62615f15125	532	*/
mfiore	0:c62615f15125	533	uint8_t getAck();
mfiore	0:c62615f15125	534
mfiore	0:c62615f15125	535	/** Send data to the gateway
mfiore	0:c62615f15125	536	* validates data size (based on spreading factor)
mfiore	0:c62615f15125	537	* @param data a vector of up to 242 bytes (may be less based on spreading factor)
mfiore	0:c62615f15125	538	* @returns MDOT_OK if packet was sent successfully (ACKs disabled), or if an ACK was received (ACKs enabled)
mfiore	0:c62615f15125	539	*/
mfiore	0:c62615f15125	540	int32_t send(const std::vector<uint8_t>& data, const bool& blocking = true, const bool& highBw = false);
mfiore	0:c62615f15125	541
mfiore	0:c62615f15125	542	/** Fetch data received from the gateway
mfiore	0:c62615f15125	543	* this function only checks to see if a packet has been received - it does not open a receive window
mfiore	0:c62615f15125	544	* send() must be called before recv()
mfiore	0:c62615f15125	545	* @param data a vector to put the received data into
mfiore	0:c62615f15125	546	* @returns MDOT_OK if packet was successfully received
mfiore	0:c62615f15125	547	*/
mfiore	0:c62615f15125	548	int32_t recv(std::vector<uint8_t>& data);
mfiore	0:c62615f15125	549
mfiore	0:c62615f15125	550	/** Ping
mfiore	0:c62615f15125	551	* status will be MDOT_OK if ping succeeded
mfiore	0:c62615f15125	552	* @returns ping_response struct containing status, RSSI, and SNR
mfiore	0:c62615f15125	553	*/
mfiore	0:c62615f15125	554	ping_response ping();
mfiore	0:c62615f15125	555
mfiore	0:c62615f15125	556	/** Get return code string
mfiore	0:c62615f15125	557	* @returns string containing a description of the given error code
mfiore	0:c62615f15125	558	*/
mfiore	0:c62615f15125	559	static std::string getReturnCodeString(const int32_t& code);
mfiore	0:c62615f15125	560
mfiore	0:c62615f15125	561	/** Get last error
mfiore	0:c62615f15125	562	* @returns string explaining the last error that occured
mfiore	0:c62615f15125	563	*/
mfiore	0:c62615f15125	564	std::string getLastError();
mfiore	0:c62615f15125	565
mfiore	0:c62615f15125	566	/******************************************
mfiore	0:c62615f15125	567	* THESE FEATURES ARE NOT FULLY IMPLEMENTED
mfiore	0:c62615f15125	568	*****************************************/
mfiore	0:c62615f15125	569	void sleep();
mfiore	0:c62615f15125	570	void wakeup();
mfiore	0:c62615f15125	571
mfiore	0:c62615f15125	572	// get/set adaptive data rate
mfiore	0:c62615f15125	573	// configure data rates and power levels based on signal to noise information from gateway
mfiore	0:c62615f15125	574	// true == adaptive data rate is on
mfiore	0:c62615f15125	575	// set function returns MDOT_OK if success
mfiore	0:c62615f15125	576	int32_t setAdr(const bool& on);
mfiore	0:c62615f15125	577	bool getAdr();
mfiore	0:c62615f15125	578
mfiore	0:c62615f15125	579	/*************************************************************************
mfiore	0:c62615f15125	580	* The following functions are only used by the AT command application and
mfiore	0:c62615f15125	581	* should not be used by standard applications consuming the mDot library
mfiore	0:c62615f15125	582	************************************************************************/
mfiore	0:c62615f15125	583
mfiore	0:c62615f15125	584	// set/get configured baud rate for command port
mfiore	0:c62615f15125	585	// only for use in conjunction with AT interface
mfiore	0:c62615f15125	586	// set function returns MDOT_OK if success
mfiore	0:c62615f15125	587	int32_t setBaud(const uint32_t& baud);
mfiore	0:c62615f15125	588	uint32_t getBaud();
mfiore	0:c62615f15125	589
mfiore	0:c62615f15125	590	// set/get baud rate for debug port
mfiore	0:c62615f15125	591	// set function returns MDOT_OK if success
mfiore	0:c62615f15125	592	int32_t setDebugBaud(const uint32_t& baud);
mfiore	0:c62615f15125	593	uint32_t getDebugBaud();
mfiore	0:c62615f15125	594
mfiore	0:c62615f15125	595	// set/get command terminal echo
mfiore	0:c62615f15125	596	// set function returns MDOT_OK if success
mfiore	0:c62615f15125	597	int32_t setEcho(const bool& on);
mfiore	0:c62615f15125	598	bool getEcho();
mfiore	0:c62615f15125	599
mfiore	0:c62615f15125	600	// set/get command terminal verbose mode
mfiore	0:c62615f15125	601	// set function returns MDOT_OK if success
mfiore	0:c62615f15125	602	int32_t setVerbose(const bool& on);
mfiore	0:c62615f15125	603	bool getVerbose();
mfiore	0:c62615f15125	604
mfiore	0:c62615f15125	605	// set/get startup mode
mfiore	0:c62615f15125	606	// COMMAND_MODE (default), starts up ready to accept AT commands
mfiore	0:c62615f15125	607	// SERIAL_MODE, read serial data and send it as LoRa packets
mfiore	0:c62615f15125	608	// set function returns MDOT_OK if success
mfiore	0:c62615f15125	609	int32_t setStartUpMode(const uint8_t& mode);
mfiore	0:c62615f15125	610	uint8_t getStartUpMode();
mfiore	0:c62615f15125	611
mfiore	0:c62615f15125	612	int32_t setRxDataRate(const uint8_t& dr);
mfiore	0:c62615f15125	613	uint8_t getRxDataRate();
mfiore	0:c62615f15125	614
mfiore	0:c62615f15125	615	// get/set TX/RX frequency
mfiore	0:c62615f15125	616	// if frequency band == FB_868 (Europe), must be between 863000000 - 870000000
mfiore	0:c62615f15125	617	// if frequency band == FB_915 (United States), must be between 902000000-928000000
mfiore	0:c62615f15125	618	// if set to 0, device will hop frequencies
mfiore	0:c62615f15125	619	// set function returns MDOT_OK if success
mfiore	0:c62615f15125	620	int32_t setTxFrequency(const uint32_t& freq);
mfiore	0:c62615f15125	621	uint32_t getTxFrequency();
mfiore	0:c62615f15125	622	int32_t setRxFrequency(const uint32_t& freq);
mfiore	0:c62615f15125	623	uint32_t getRxFrequency();
mfiore	0:c62615f15125	624
mfiore	0:c62615f15125	625	// get/set TX/RX inverted
mfiore	0:c62615f15125	626	// true == signal is inverted
mfiore	0:c62615f15125	627	// set function returns MDOT_OK if success
mfiore	0:c62615f15125	628	int32_t setTxInverted(const bool& on);
mfiore	0:c62615f15125	629	bool getTxInverted();
mfiore	0:c62615f15125	630	int32_t setRxInverted(const bool& on);
mfiore	0:c62615f15125	631	bool getRxInverted();
mfiore	0:c62615f15125	632
mfiore	0:c62615f15125	633	// get/set RX output mode
mfiore	0:c62615f15125	634	// valid options are HEXADECIMAL and BINARY
mfiore	0:c62615f15125	635	// set function returns MDOT_OK if success
mfiore	0:c62615f15125	636	int32_t setRxOutput(const uint8_t& mode);
mfiore	0:c62615f15125	637	uint8_t getRxOutput();
mfiore	0:c62615f15125	638
mfiore	0:c62615f15125	639	// get/set serial wake interval
mfiore	0:c62615f15125	640	// valid values are 2 s - INT_MAX (2147483647) s
mfiore	0:c62615f15125	641	// set function returns MDOT_OK if success
mfiore	0:c62615f15125	642	int32_t setSerialWakeInterval(const uint32_t& interval);
mfiore	0:c62615f15125	643	uint32_t getSerialWakeInterval();
mfiore	0:c62615f15125	644
mfiore	0:c62615f15125	645	// get/set serial wake delay
mfiore	0:c62615f15125	646	// valid values are 2 ms - INT_MAX (2147483647) ms
mfiore	0:c62615f15125	647	// set function returns MDOT_OK if success
mfiore	0:c62615f15125	648	int32_t setSerialWakeDelay(const uint32_t& delay);
mfiore	0:c62615f15125	649	uint32_t getSerialWakeDelay();
mfiore	0:c62615f15125	650
mfiore	0:c62615f15125	651	// get/set serial receive timeout
mfiore	0:c62615f15125	652	// valid values are 0 ms - 65000 ms
mfiore	0:c62615f15125	653	// set function returns MDOT_OK if success
mfiore	0:c62615f15125	654	int32_t setSerialReceiveTimeout(const uint16_t& timeout);
mfiore	0:c62615f15125	655	uint16_t getSerialReceiveTimeout();
mfiore	0:c62615f15125	656
mfiore	0:c62615f15125	657	uint64_t crc64(uint64_t crc, const unsigned char *s, uint64_t l);
mfiore	0:c62615f15125	658
mfiore	0:c62615f15125	659	// MTS_RADIO_DEBUG_COMMANDS
mfiore	0:c62615f15125	660	int32_t setDeviceId(const std::vector<uint8_t>& id);
mfiore	0:c62615f15125	661	int32_t setFrequencyBand(const uint8_t& band);
mfiore	0:c62615f15125	662	bool saveProtectedConfig();
mfiore	0:c62615f15125	663	void resetRadio();
mfiore	0:c62615f15125	664	int32_t setRadioMode(const uint8_t& mode);
mfiore	0:c62615f15125	665	std::map<uint8_t, uint8_t> dumpRegisters();
mfiore	0:c62615f15125	666	void eraseFlash();
mfiore	0:c62615f15125	667
mfiore	0:c62615f15125	668	mdot_stats getStats();
mfiore	0:c62615f15125	669
mfiore	0:c62615f15125	670	private:
mfiore	0:c62615f15125	671	mdot_stats _stats;
mfiore	0:c62615f15125	672
mfiore	0:c62615f15125	673	};
mfiore	0:c62615f15125	674
mfiore	0:c62615f15125	675	#endif