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@9:ec2fffe31793, 2015-11-10 (annotated)

Committer:: jreiss
Date:: Tue Nov 10 14:44:36 2015 -0600
Revision:: 9:ec2fffe31793
Parent:: 7:683dba5d576f
Child:: 10:27dafba9fe19

Update libmDot with RTC clock changes to preserve over sleep

Who changed what in which revision?

User	Revision	Line number	New contents of line
jreiss	9:ec2fffe31793	1	// TODO: add license header
mfiore	0:c62615f15125	2
mfiore	0:c62615f15125	3	#ifndef MDOT_H
mfiore	0:c62615f15125	4	#define MDOT_H
mfiore	0:c62615f15125	5
mfiore	0:c62615f15125	6	#include "mbed.h"
mfiore	0:c62615f15125	7	#include "rtos.h"
mfiore	0:c62615f15125	8	#include <vector>
mfiore	0:c62615f15125	9	#include <map>
mfiore	0:c62615f15125	10	#include <string>
mfiore	0:c62615f15125	11
mfiore	0:c62615f15125	12	class LoRaMacEvent;
mfiore	0:c62615f15125	13	class LoRaConfig;
mfiore	0:c62615f15125	14	class LoRaMac;
mfiore	0:c62615f15125	15	class MdotRadio;
mfiore	0:c62615f15125	16
mfiore	0:c62615f15125	17	class mDot {
mfiore	0:c62615f15125	18
mfiore	0:c62615f15125	19	private:
mfiore	0:c62615f15125	20
mfiore	0:c62615f15125	21	mDot();
mfiore	0:c62615f15125	22	~mDot();
mfiore	0:c62615f15125	23
mfiore	0:c62615f15125	24	static void idle(void const* args) {
mfiore	0:c62615f15125	25	while (1)
mfiore	0:c62615f15125	26	__WFI();
mfiore	0:c62615f15125	27	}
mfiore	0:c62615f15125	28
mfiore	0:c62615f15125	29	void setLastError(const std::string& str);
mfiore	0:c62615f15125	30
mfiore	0:c62615f15125	31	static bool validateBaudRate(const uint32_t& baud);
mfiore	0:c62615f15125	32	static bool validateFrequencySubBand(const uint8_t& band);
mfiore	0:c62615f15125	33	bool validateDataRate(const uint8_t& dr);
mfiore	0:c62615f15125	34
mfiore	0:c62615f15125	35	int32_t joinBase(const uint32_t& retries);
mfiore	0:c62615f15125	36	int32_t sendBase(const std::vector<uint8_t>& data, const bool& confirmed = false, const bool& blocking = true, const bool& highBw = false);
mfiore	0:c62615f15125	37	void waitForPacket();
mfiore	0:c62615f15125	38	void waitForLinkCheck();
mfiore	0:c62615f15125	39
mfiore	0:c62615f15125	40	void setActivityLedState(const uint8_t& state);
mfiore	0:c62615f15125	41	uint8_t getActivityLedState();
mfiore	0:c62615f15125	42
mfiore	0:c62615f15125	43	void blinkActivityLed(void) {
Mike Fiore	6:390fc83d588d	44	if (_activity_led) {
Mike Fiore	6:390fc83d588d	45	int val = _activity_led->read();
Mike Fiore	6:390fc83d588d	46	_activity_led->write(!val);
Mike Fiore	6:390fc83d588d	47	}
mfiore	0:c62615f15125	48	}
mfiore	0:c62615f15125	49
mfiore	0:c62615f15125	50	mDot(const mDot&);
mfiore	0:c62615f15125	51	mDot& operator=(const mDot&);
mfiore	0:c62615f15125	52
Mike Fiore	7:683dba5d576f	53	uint32_t RTC_ReadBackupRegister(uint32_t RTC_BKP_DR);
Mike Fiore	7:683dba5d576f	54	void RTC_WriteBackupRegister(uint32_t RTC_BKP_DR, uint32_t Data);
Mike Fiore	7:683dba5d576f	55
Mike Fiore	7:683dba5d576f	56	void wakeup();
Mike Fiore	7:683dba5d576f	57
mfiore	0:c62615f15125	58	static mDot* _instance;
mfiore	0:c62615f15125	59
mfiore	0:c62615f15125	60	LoRaMac* _mac;
mfiore	0:c62615f15125	61	MdotRadio* _radio;
mfiore	0:c62615f15125	62	LoRaMacEvent* _events;
mfiore	0:c62615f15125	63	LoRaConfig* _config;
mfiore	0:c62615f15125	64	Thread _idle_thread;
mfiore	0:c62615f15125	65	std::string _last_error;
mfiore	0:c62615f15125	66	static const uint32_t _baud_rates[];
mfiore	0:c62615f15125	67	uint8_t _activity_led_state;
mfiore	0:c62615f15125	68	Ticker _tick;
Mike Fiore	6:390fc83d588d	69	DigitalOut* _activity_led;
Mike Fiore	6:390fc83d588d	70	bool _activity_led_enable;
Mike Fiore	6:390fc83d588d	71	PinName _activity_led_pin;
Mike Fiore	5:0bfe6a650513	72	bool _activity_led_external;
jreiss	9:ec2fffe31793	73	uint8_t _linkFailCount;
Mike Fiore	7:683dba5d576f	74	uint8_t _class;
Mike Fiore	7:683dba5d576f	75	InterruptIn* _wakeup;
Mike Fiore	7:683dba5d576f	76	PinName _wakeup_pin;
mfiore	0:c62615f15125	77
mfiore	0:c62615f15125	78	typedef enum {
mfiore	0:c62615f15125	79	OFF, ON, BLINK,
mfiore	0:c62615f15125	80	} state;
mfiore	0:c62615f15125	81
mfiore	0:c62615f15125	82	public:
mfiore	0:c62615f15125	83
mfiore	0:c62615f15125	84	typedef enum {
Mike Fiore	7:683dba5d576f	85	FM_APPEND = (1 << 0),
Mike Fiore	7:683dba5d576f	86	FM_TRUNC = (1 << 1),
Mike Fiore	7:683dba5d576f	87	FM_CREAT = (1 << 2),
Mike Fiore	7:683dba5d576f	88	FM_RDONLY = (1 << 3),
Mike Fiore	7:683dba5d576f	89	FM_WRONLY = (1 << 4),
Mike Fiore	7:683dba5d576f	90	FM_RDWR = (FM_RDONLY \| FM_WRONLY),
Mike Fiore	7:683dba5d576f	91	FM_DIRECT = (1 << 5)
Mike Fiore	7:683dba5d576f	92	} FileMode;
Mike Fiore	7:683dba5d576f	93
Mike Fiore	7:683dba5d576f	94	typedef enum {
mfiore	0:c62615f15125	95	MDOT_OK = 0,
mfiore	0:c62615f15125	96	MDOT_INVALID_PARAM = -1,
mfiore	0:c62615f15125	97	MDOT_TX_ERROR = -2,
mfiore	0:c62615f15125	98	MDOT_RX_ERROR = -3,
mfiore	0:c62615f15125	99	MDOT_JOIN_ERROR = -4,
mfiore	0:c62615f15125	100	MDOT_TIMEOUT = -5,
mfiore	0:c62615f15125	101	MDOT_NOT_JOINED = -6,
mfiore	0:c62615f15125	102	MDOT_ENCRYPTION_DISABLED = -7,
mfiore	0:c62615f15125	103	MDOT_NO_FREE_CHAN = -8,
mfiore	0:c62615f15125	104	MDOT_ERROR = -1024,
mfiore	0:c62615f15125	105	} mdot_ret_code;
mfiore	0:c62615f15125	106
mfiore	0:c62615f15125	107	enum JoinMode {
mfiore	0:c62615f15125	108	MANUAL, OTA, AUTO_OTA
mfiore	0:c62615f15125	109	};
mfiore	0:c62615f15125	110
mfiore	0:c62615f15125	111	enum Mode {
mfiore	0:c62615f15125	112	COMMAND_MODE, SERIAL_MODE
mfiore	0:c62615f15125	113	};
mfiore	0:c62615f15125	114
mfiore	0:c62615f15125	115	enum RX_Output {
mfiore	0:c62615f15125	116	HEXADECIMAL, BINARY
mfiore	0:c62615f15125	117	};
mfiore	0:c62615f15125	118
mfiore	0:c62615f15125	119	enum DataRates {
mfiore	0:c62615f15125	120	SF_12, SF_11, SF_10, SF_9, SF_8, SF_7, SF_7H, SF_50
mfiore	0:c62615f15125	121	};
mfiore	0:c62615f15125	122
mfiore	0:c62615f15125	123	enum FrequencyBands {
mfiore	0:c62615f15125	124	FB_868, FB_915
mfiore	0:c62615f15125	125	};
mfiore	0:c62615f15125	126
mfiore	0:c62615f15125	127	enum FrequencySubBands {
mfiore	0:c62615f15125	128	FSB_ALL, FSB_1, FSB_2, FSB_3, FSB_4, FSB_5, FSB_6, FSB_7, FSB_8
mfiore	0:c62615f15125	129	};
mfiore	0:c62615f15125	130
Mike Fiore	6:390fc83d588d	131	enum JoinByteOrder {
Mike Fiore	6:390fc83d588d	132	LSB, MSB
Mike Fiore	6:390fc83d588d	133	};
Mike Fiore	6:390fc83d588d	134
Mike Fiore	7:683dba5d576f	135	enum wakeup_mode {
Mike Fiore	7:683dba5d576f	136	RTC_ALARM, INTERRUPT
Mike Fiore	7:683dba5d576f	137	};
Mike Fiore	7:683dba5d576f	138
jreiss	9:ec2fffe31793	139	enum UserBackupRegs {
jreiss	9:ec2fffe31793	140	UBR0, UBR1, UBR2, UBR3, UBR4, UBR5, UBR6, UBR7, UBR8, UBR9
jreiss	9:ec2fffe31793	141	};
jreiss	9:ec2fffe31793	142
Mike Fiore	7:683dba5d576f	143	typedef struct {
Mike Fiore	7:683dba5d576f	144	int16_t fd;
Mike Fiore	7:683dba5d576f	145	char name[30];
Mike Fiore	7:683dba5d576f	146	uint32_t size;
Mike Fiore	7:683dba5d576f	147	} mdot_file;
Mike Fiore	7:683dba5d576f	148
mfiore	0:c62615f15125	149	typedef struct {
mfiore	0:c62615f15125	150	uint32_t Up;
mfiore	0:c62615f15125	151	uint32_t Down;
mfiore	0:c62615f15125	152	uint32_t Joins;
mfiore	0:c62615f15125	153	uint32_t JoinFails;
mfiore	0:c62615f15125	154	uint32_t MissedAcks;
mfiore	0:c62615f15125	155	} mdot_stats;
mfiore	0:c62615f15125	156
mfiore	0:c62615f15125	157	typedef struct {
mfiore	0:c62615f15125	158	int16_t last;
mfiore	0:c62615f15125	159	int16_t min;
mfiore	0:c62615f15125	160	int16_t max;
mfiore	0:c62615f15125	161	int16_t avg;
mfiore	0:c62615f15125	162	} rssi_stats;
mfiore	0:c62615f15125	163
mfiore	0:c62615f15125	164	typedef struct {
mfiore	0:c62615f15125	165	int8_t last;
mfiore	0:c62615f15125	166	int8_t min;
mfiore	0:c62615f15125	167	int8_t max;
mfiore	0:c62615f15125	168	int8_t avg;
mfiore	0:c62615f15125	169	} snr_stats;
mfiore	0:c62615f15125	170
mfiore	0:c62615f15125	171	typedef struct {
mfiore	0:c62615f15125	172	bool status;
mfiore	0:c62615f15125	173	int32_t dBm;
mfiore	0:c62615f15125	174	uint32_t gateways;
mfiore	0:c62615f15125	175	std::vector<uint8_t> payload;
mfiore	0:c62615f15125	176	} link_check;
mfiore	0:c62615f15125	177
mfiore	0:c62615f15125	178	typedef struct {
mfiore	0:c62615f15125	179	int32_t status;
mfiore	0:c62615f15125	180	int16_t rssi;
mfiore	0:c62615f15125	181	int16_t snr;
mfiore	0:c62615f15125	182	} ping_response;
mfiore	0:c62615f15125	183
mfiore	0:c62615f15125	184	static const uint8_t MaxLengths_915[];
mfiore	0:c62615f15125	185	static const uint8_t MaxLengths_868[];
mfiore	0:c62615f15125	186
mfiore	0:c62615f15125	187	static std::string JoinModeStr(uint8_t mode);
mfiore	0:c62615f15125	188	static std::string ModeStr(uint8_t mode);
mfiore	0:c62615f15125	189	static std::string RxOutputStr(uint8_t format);
mfiore	0:c62615f15125	190	static std::string DataRateStr(uint8_t rate);
mfiore	0:c62615f15125	191	static std::string FrequencyBandStr(uint8_t band);
mfiore	0:c62615f15125	192	static std::string FrequencySubBandStr(uint8_t band);
mfiore	0:c62615f15125	193
jreiss	9:ec2fffe31793	194	uint32_t UserRegisters[10];
jreiss	9:ec2fffe31793	195
mfiore	0:c62615f15125	196	/** Get a handle to the singleton object
mfiore	0:c62615f15125	197	* @returns pointer to mDot object
mfiore	0:c62615f15125	198	*/
mfiore	0:c62615f15125	199	static mDot* getInstance();
mfiore	0:c62615f15125	200
mfiore	0:c62615f15125	201	/** Get library version information
mfiore	0:c62615f15125	202	* @returns string containing library version information
mfiore	0:c62615f15125	203	*/
mfiore	0:c62615f15125	204	std::string getId();
mfiore	0:c62615f15125	205
mfiore	0:c62615f15125	206	/** Perform a soft reset of the system
mfiore	0:c62615f15125	207	*/
mfiore	0:c62615f15125	208	void resetCpu();
mfiore	0:c62615f15125	209
mfiore	0:c62615f15125	210	/** Reset config to factory default
mfiore	0:c62615f15125	211	*/
mfiore	0:c62615f15125	212	void resetConfig();
mfiore	0:c62615f15125	213
mfiore	0:c62615f15125	214	/** Save config data to non volatile memory
mfiore	0:c62615f15125	215	* @returns true if success, false if failure
mfiore	0:c62615f15125	216	*/
mfiore	0:c62615f15125	217	bool saveConfig();
mfiore	0:c62615f15125	218
mfiore	0:c62615f15125	219	/** Set the log level for the library
mfiore	0:c62615f15125	220	* options are:
mfiore	0:c62615f15125	221	* NONE_LEVEL - logging is off at this level
mfiore	0:c62615f15125	222	* FATAL_LEVEL - only critical errors will be reported
mfiore	0:c62615f15125	223	* ERROR_LEVEL
mfiore	0:c62615f15125	224	* WARNING_LEVEL
mfiore	0:c62615f15125	225	* INFO_LEVEL
mfiore	0:c62615f15125	226	* DEBUG_LEVEL
mfiore	0:c62615f15125	227	* TRACE_LEVEL - every detail will be reported
mfiore	0:c62615f15125	228	* @param level the level to log at
mfiore	0:c62615f15125	229	* @returns MDOT_OK if success
mfiore	0:c62615f15125	230	*/
mfiore	0:c62615f15125	231	int32_t setLogLevel(const uint8_t& level);
mfiore	0:c62615f15125	232
mfiore	0:c62615f15125	233	/** Get the current log level for the library
mfiore	0:c62615f15125	234	* @returns current log level
mfiore	0:c62615f15125	235	*/
Mike Fiore	6:390fc83d588d	236	uint8_t getLogLevel();
Mike Fiore	6:390fc83d588d	237
Mike Fiore	6:390fc83d588d	238	/** Enable or disable the activity LED.
Mike Fiore	6:390fc83d588d	239	* @param enable true to enable the LED, false to disable
Mike Fiore	6:390fc83d588d	240	*/
Mike Fiore	6:390fc83d588d	241	void setActivityLedEnable(const bool& enable);
Mike Fiore	4:94969e981dcc	242
Mike Fiore	6:390fc83d588d	243	/** Find out if the activity LED is enabled
Mike Fiore	6:390fc83d588d	244	* @returns true if activity LED is enabled, false if disabled
Mike Fiore	6:390fc83d588d	245	*/
Mike Fiore	6:390fc83d588d	246	bool getActivityLedEnable();
Mike Fiore	6:390fc83d588d	247
Mike Fiore	6:390fc83d588d	248	/** Use a different pin for the activity LED.
Mike Fiore	6:390fc83d588d	249	* The default is XBEE_RSSI.
Mike Fiore	6:390fc83d588d	250	* @param pin the new pin to use
Mike Fiore	6:390fc83d588d	251	*/
Mike Fiore	6:390fc83d588d	252	void setActivityLedPin(const PinName& pin);
Mike Fiore	6:390fc83d588d	253
Mike Fiore	5:0bfe6a650513	254	/** Use an external DigitalOut object for the activity LED.
Mike Fiore	5:0bfe6a650513	255	* The pointer must stay valid!
Mike Fiore	5:0bfe6a650513	256	* @param pin the DigitalOut object to use
Mike Fiore	5:0bfe6a650513	257	*/
Mike Fiore	5:0bfe6a650513	258	void setActivityLedPin(DigitalOut* pin);
Mike Fiore	6:390fc83d588d	259
Mike Fiore	6:390fc83d588d	260	/** Find out what pin the activity LED is on
Mike Fiore	6:390fc83d588d	261	* @returns the pin the activity LED is using
Mike Fiore	6:390fc83d588d	262	*/
Mike Fiore	6:390fc83d588d	263	PinName getActivityLedPin();
mfiore	0:c62615f15125	264
mfiore	0:c62615f15125	265	/** Get list of channel frequencies currently in use
mfiore	0:c62615f15125	266	* @returns vector of channels currently in use
mfiore	0:c62615f15125	267	*/
mfiore	0:c62615f15125	268	std::vector<uint32_t> getChannels();
mfiore	0:c62615f15125	269
mfiore	0:c62615f15125	270	/** Get frequency band
mfiore	0:c62615f15125	271	* @returns FB_915 if configured for United States, FB_868 if configured for Europe
mfiore	0:c62615f15125	272	*/
mfiore	0:c62615f15125	273	uint8_t getFrequencyBand();
mfiore	0:c62615f15125	274
mfiore	0:c62615f15125	275	/** Set frequency sub band
mfiore	0:c62615f15125	276	* only applicable if frequency band is set for United States (FB_915)
mfiore	0:c62615f15125	277	* sub band 0 will allow the radio to use all 64 channels
mfiore	0:c62615f15125	278	* sub band 1 - 8 will allow the radio to use the 8 channels in that sub band
mfiore	0:c62615f15125	279	* for use with Conduit gateway and MTAC_LORA, use sub bands 1 - 8, not sub band 0
mfiore	0:c62615f15125	280	* @param band the sub band to use (0 - 8)
mfiore	0:c62615f15125	281	* @returns MDOT_OK if success
mfiore	0:c62615f15125	282	*/
mfiore	0:c62615f15125	283	int32_t setFrequencySubBand(const uint8_t& band);
mfiore	0:c62615f15125	284
mfiore	0:c62615f15125	285	/** Get frequency sub band
mfiore	0:c62615f15125	286	* @returns frequency sub band currently in use
mfiore	0:c62615f15125	287	*/
mfiore	0:c62615f15125	288	uint8_t getFrequencySubBand();
mfiore	0:c62615f15125	289
mfiore	0:c62615f15125	290	/** Enable/disable public network mode
mfiore	0:c62615f15125	291	* @param on should be true to enable public network mode
mfiore	0:c62615f15125	292	* @returns MDOT_OK if success
mfiore	0:c62615f15125	293	*/
mfiore	0:c62615f15125	294	int32_t setPublicNetwork(const bool& on);
mfiore	0:c62615f15125	295
mfiore	0:c62615f15125	296	/** Get public network mode
mfiore	0:c62615f15125	297	* @returns true if public network mode is enabled
mfiore	0:c62615f15125	298	*/
mfiore	0:c62615f15125	299	bool getPublicNetwork();
mfiore	0:c62615f15125	300
mfiore	0:c62615f15125	301	/** Get the device ID
mfiore	0:c62615f15125	302	* @returns vector containing the device ID (size 8)
mfiore	0:c62615f15125	303	*/
mfiore	0:c62615f15125	304	std::vector<uint8_t> getDeviceId();
mfiore	0:c62615f15125	305
mfiore	0:c62615f15125	306	/** Set network address
mfiore	0:c62615f15125	307	* for use with MANUAL network join mode, will be assigned in OTA & AUTO_OTA modes
mfiore	0:c62615f15125	308	* @param addr a vector of 4 bytes
mfiore	0:c62615f15125	309	* @returns MDOT_OK if success
mfiore	0:c62615f15125	310	*/
mfiore	0:c62615f15125	311	int32_t setNetworkAddress(const std::vector<uint8_t>& addr);
mfiore	0:c62615f15125	312
mfiore	0:c62615f15125	313	/** Get network address
mfiore	0:c62615f15125	314	* @returns vector containing network address (size 4)
mfiore	0:c62615f15125	315	*/
mfiore	0:c62615f15125	316	std::vector<uint8_t> getNetworkAddress();
mfiore	0:c62615f15125	317
mfiore	0:c62615f15125	318	/** Set network session key
mfiore	0:c62615f15125	319	* for use with MANUAL network join mode, will be assigned in OTA & AUTO_OTA modes
mfiore	0:c62615f15125	320	* @param key a vector of 16 bytes
mfiore	0:c62615f15125	321	* @returns MDOT_OK if success
mfiore	0:c62615f15125	322	*/
mfiore	0:c62615f15125	323	int32_t setNetworkSessionKey(const std::vector<uint8_t>& key);
mfiore	0:c62615f15125	324
mfiore	0:c62615f15125	325	/** Get network session key
mfiore	0:c62615f15125	326	* @returns vector containing network session key (size 16)
mfiore	0:c62615f15125	327	*/
mfiore	0:c62615f15125	328	std::vector<uint8_t> getNetworkSessionKey();
mfiore	0:c62615f15125	329
mfiore	0:c62615f15125	330	/** Set data session key
mfiore	0:c62615f15125	331	* for use with MANUAL network join mode, will be assigned in OTA & AUTO_OTA modes
mfiore	0:c62615f15125	332	* @param key a vector of 16 bytes
mfiore	0:c62615f15125	333	* @returns MDOT_OK if success
mfiore	0:c62615f15125	334	*/
mfiore	0:c62615f15125	335	int32_t setDataSessionKey(const std::vector<uint8_t>& key);
mfiore	0:c62615f15125	336
mfiore	0:c62615f15125	337	/** Get data session key
mfiore	0:c62615f15125	338	* @returns vector containing data session key (size 16)
mfiore	0:c62615f15125	339	*/
mfiore	0:c62615f15125	340	std::vector<uint8_t> getDataSessionKey();
mfiore	0:c62615f15125	341
mfiore	0:c62615f15125	342	/** Set network name
mfiore	0:c62615f15125	343	* for use with OTA & AUTO_OTA network join modes
mfiore	0:c62615f15125	344	* generates network ID (crc64 of name) automatically
mfiore	0:c62615f15125	345	* @param name a string of of at least 8 bytes and no more than 128 bytes
mfiore	0:c62615f15125	346	* @return MDOT_OK if success
mfiore	0:c62615f15125	347	*/
mfiore	0:c62615f15125	348	int32_t setNetworkName(const std::string& name);
mfiore	0:c62615f15125	349
mfiore	0:c62615f15125	350	/** Get network name
mfiore	0:c62615f15125	351	* @return string containing network name (size 8 to 128)
mfiore	0:c62615f15125	352	*/
mfiore	0:c62615f15125	353	std::string getNetworkName();
mfiore	0:c62615f15125	354
mfiore	0:c62615f15125	355	/** Set network ID
mfiore	0:c62615f15125	356	* for use with OTA & AUTO_OTA network join modes
mfiore	0:c62615f15125	357	* setting network ID via this function sets network name to empty
mfiore	0:c62615f15125	358	* @param id a vector of 8 bytes
mfiore	0:c62615f15125	359	* @returns MDOT_OK if success
mfiore	0:c62615f15125	360	*/
mfiore	0:c62615f15125	361	int32_t setNetworkId(const std::vector<uint8_t>& id);
mfiore	0:c62615f15125	362
mfiore	0:c62615f15125	363	/** Get network ID
mfiore	0:c62615f15125	364	* @returns vector containing network ID (size 8)
mfiore	0:c62615f15125	365	*/
mfiore	0:c62615f15125	366	std::vector<uint8_t> getNetworkId();
mfiore	0:c62615f15125	367
mfiore	0:c62615f15125	368	/** Set network passphrase
mfiore	0:c62615f15125	369	* for use with OTA & AUTO_OTA network join modes
mfiore	0:c62615f15125	370	* generates network key (cmac of passphrase) automatically
mfiore	0:c62615f15125	371	* @param name a string of of at least 8 bytes and no more than 128 bytes
mfiore	0:c62615f15125	372	* @return MDOT_OK if success
mfiore	0:c62615f15125	373	*/
mfiore	0:c62615f15125	374	int32_t setNetworkPassphrase(const std::string& passphrase);
mfiore	0:c62615f15125	375
mfiore	0:c62615f15125	376	/** Get network passphrase
mfiore	0:c62615f15125	377	* @return string containing network passphrase (size 8 to 128)
mfiore	0:c62615f15125	378	*/
mfiore	0:c62615f15125	379	std::string getNetworkPassphrase();
mfiore	0:c62615f15125	380
mfiore	0:c62615f15125	381	/** Set network key
mfiore	0:c62615f15125	382	* for use with OTA & AUTO_OTA network join modes
mfiore	0:c62615f15125	383	* setting network key via this function sets network passphrase to empty
mfiore	0:c62615f15125	384	* @param id a vector of 16 bytes
mfiore	0:c62615f15125	385	* @returns MDOT_OK if success
mfiore	0:c62615f15125	386	*/
mfiore	0:c62615f15125	387	int32_t setNetworkKey(const std::vector<uint8_t>& id);
mfiore	0:c62615f15125	388
mfiore	0:c62615f15125	389	/** Get network key
mfiore	0:c62615f15125	390	* @returns a vector containing network key (size 16)
mfiore	0:c62615f15125	391	*/
mfiore	0:c62615f15125	392	std::vector<uint8_t> getNetworkKey();
mfiore	0:c62615f15125	393
Mike Fiore	6:390fc83d588d	394	/** Set join byte order
Mike Fiore	6:390fc83d588d	395	* @param order 0:LSB 1:MSB
Mike Fiore	6:390fc83d588d	396	*/
Mike Fiore	6:390fc83d588d	397	uint32_t setJoinByteOrder(uint8_t order);
Mike Fiore	6:390fc83d588d	398
Mike Fiore	6:390fc83d588d	399	/** Get join byte order
Mike Fiore	6:390fc83d588d	400	* @returns byte order to use in joins 0:LSB 1:MSB
Mike Fiore	6:390fc83d588d	401	*/
Mike Fiore	6:390fc83d588d	402	uint8_t getJoinByteOrder();
Mike Fiore	6:390fc83d588d	403
mfiore	0:c62615f15125	404	/** Attempt to join network
mfiore	0:c62615f15125	405	* retries according to configuration set by setJoinRetries()
mfiore	0:c62615f15125	406	* @returns MDOT_OK if success
mfiore	0:c62615f15125	407	*/
mfiore	0:c62615f15125	408	int32_t joinNetwork();
mfiore	0:c62615f15125	409
mfiore	0:c62615f15125	410	/** Attempts to join network once
mfiore	0:c62615f15125	411	* @returns MDOT_OK if success
mfiore	0:c62615f15125	412	*/
mfiore	0:c62615f15125	413	int32_t joinNetworkOnce();
mfiore	0:c62615f15125	414
mfiore	0:c62615f15125	415	/** Resets current network session, essentially disconnecting from the network
mfiore	0:c62615f15125	416	* has no effect for MANUAL network join mode
mfiore	0:c62615f15125	417	*/
mfiore	0:c62615f15125	418	void resetNetworkSession();
mfiore	0:c62615f15125	419
mfiore	0:c62615f15125	420	/** Set number of times joining will retry before giving up
mfiore	0:c62615f15125	421	* @param retries must be between 0 - 255
mfiore	0:c62615f15125	422	* @returns MDOT_OK if success
mfiore	0:c62615f15125	423	*/
mfiore	0:c62615f15125	424	int32_t setJoinRetries(const uint8_t& retries);
mfiore	0:c62615f15125	425
mfiore	0:c62615f15125	426	/** Set number of times joining will retry before giving up
mfiore	0:c62615f15125	427	* @returns join retries (0 - 255)
mfiore	0:c62615f15125	428	*/
mfiore	0:c62615f15125	429	uint8_t getJoinRetries();
mfiore	0:c62615f15125	430
mfiore	0:c62615f15125	431	/** Set network join mode
mfiore	0:c62615f15125	432	* MANUAL: set network address and session keys manually
mfiore	0:c62615f15125	433	* OTA: User sets network name and passphrase, then attempts to join
mfiore	0:c62615f15125	434	* AUTO_OTA: same as OTA, but network sessions can be saved and restored
mfiore	0:c62615f15125	435	* @param mode MANUAL, OTA, or AUTO_OTA
mfiore	0:c62615f15125	436	* @returns MDOT_OK if success
mfiore	0:c62615f15125	437	*/
mfiore	0:c62615f15125	438	int32_t setJoinMode(const uint8_t& mode);
mfiore	0:c62615f15125	439
mfiore	0:c62615f15125	440	/** Get network join mode
mfiore	0:c62615f15125	441	* @returns MANUAL, OTA, or AUTO_OTA
mfiore	0:c62615f15125	442	*/
mfiore	0:c62615f15125	443	uint8_t getJoinMode();
mfiore	0:c62615f15125	444
mfiore	0:c62615f15125	445	/** Get network join status
mfiore	0:c62615f15125	446	* @returns true if currently joined to network
mfiore	0:c62615f15125	447	*/
mfiore	0:c62615f15125	448	bool getNetworkJoinStatus();
mfiore	0:c62615f15125	449
mfiore	0:c62615f15125	450	/** Do a network link check
mfiore	0:c62615f15125	451	* application data may be returned in response to a network link check command
mfiore	0:c62615f15125	452	* @returns link_check structure containing success, dBm above noise floor, gateways in range, and packet payload
mfiore	0:c62615f15125	453	*/
mfiore	0:c62615f15125	454	link_check networkLinkCheck();
mfiore	0:c62615f15125	455
mfiore	0:c62615f15125	456	/** Set network link check count to perform automatic link checks every count packets
mfiore	0:c62615f15125	457	* only applicable if ACKs are disabled
mfiore	0:c62615f15125	458	* @param count must be between 0 - 255
mfiore	0:c62615f15125	459	* @returns MDOT_OK if success
mfiore	0:c62615f15125	460	*/
mfiore	0:c62615f15125	461	int32_t setLinkCheckCount(const uint8_t& count);
mfiore	0:c62615f15125	462
mfiore	0:c62615f15125	463	/** Get network link check count
mfiore	0:c62615f15125	464	* @returns count (0 - 255)
mfiore	0:c62615f15125	465	*/
mfiore	0:c62615f15125	466	uint8_t getLinkCheckCount();
mfiore	0:c62615f15125	467
mfiore	0:c62615f15125	468	/** Set network link check threshold, number of link check failures or missed acks to tolerate
mfiore	0:c62615f15125	469	* before considering network connection lost
mfiore	0:c62615f15125	470	* @pararm count must be between 0 - 255
mfiore	0:c62615f15125	471	* @returns MDOT_OK if success
mfiore	0:c62615f15125	472	*/
mfiore	0:c62615f15125	473	int32_t setLinkCheckThreshold(const uint8_t& count);
mfiore	0:c62615f15125	474
mfiore	0:c62615f15125	475	/** Get network link check threshold
mfiore	0:c62615f15125	476	* @returns threshold (0 - 255)
mfiore	0:c62615f15125	477	*/
mfiore	0:c62615f15125	478	uint8_t getLinkCheckThreshold();
mfiore	0:c62615f15125	479
mfiore	0:c62615f15125	480	/** Get UpLinkCounter
mfiore	0:c62615f15125	481	* @returns number of packets sent to the gateway during this network session (sequence number)
mfiore	0:c62615f15125	482	*/
mfiore	0:c62615f15125	483	uint32_t getUpLinkCounter();
mfiore	0:c62615f15125	484
mfiore	0:c62615f15125	485	/** Enable/disable AES encryption
mfiore	0:c62615f15125	486	* AES encryption must be enabled for use with Conduit gateway and MTAC_LORA card
mfiore	0:c62615f15125	487	* @param on true for AES encryption to be enabled
mfiore	0:c62615f15125	488	* @returns MDOT_OK if success
mfiore	0:c62615f15125	489	*/
mfiore	0:c62615f15125	490	int32_t setAesEncryption(const bool& on);
mfiore	0:c62615f15125	491
mfiore	0:c62615f15125	492	/** Get AES encryption
mfiore	0:c62615f15125	493	* @returns true if AES encryption is enabled
mfiore	0:c62615f15125	494	*/
mfiore	0:c62615f15125	495	bool getAesEncryption();
mfiore	0:c62615f15125	496
mfiore	0:c62615f15125	497	/** Get RSSI stats
mfiore	0:c62615f15125	498	* @returns rssi_stats struct containing last, min, max, and avg RSSI
mfiore	0:c62615f15125	499	*/
mfiore	0:c62615f15125	500	rssi_stats getRssiStats();
mfiore	0:c62615f15125	501
mfiore	0:c62615f15125	502	/** Get SNR stats
mfiore	0:c62615f15125	503	* @returns snr_stats struct containing last, min, max, and avg SNR
mfiore	0:c62615f15125	504	*/
mfiore	0:c62615f15125	505	snr_stats getSnrStats();
mfiore	0:c62615f15125	506
mfiore	0:c62615f15125	507	/** Get ms until next free channel
mfiore	0:c62615f15125	508	* only applicable for European models, US models return 0
mfiore	0:c62615f15125	509	* @returns time (ms) until a channel is free to use for transmitting
mfiore	0:c62615f15125	510	*/
mfiore	0:c62615f15125	511	uint32_t getNextTxMs();
mfiore	0:c62615f15125	512
mfiore	0:c62615f15125	513	/** Get data pending
mfiore	0:c62615f15125	514	* only valid after sending data to the gateway
mfiore	0:c62615f15125	515	* @returns true if server has available packet(s)
mfiore	0:c62615f15125	516	*/
mfiore	0:c62615f15125	517	bool getDataPending();
mfiore	0:c62615f15125	518
mfiore	0:c62615f15125	519	/** Get transmitting
mfiore	0:c62615f15125	520	* @returns true if currently transmitting
mfiore	0:c62615f15125	521	*/
mfiore	0:c62615f15125	522	bool getIsTransmitting();
mfiore	0:c62615f15125	523
mfiore	0:c62615f15125	524	/** Set TX data rate
mfiore	0:c62615f15125	525	* data rates affect maximum payload size
mfiore	0:c62615f15125	526	* @param dr SF_7 - SF_12 for Europe, SF_7 - SF_10 for United States
mfiore	0:c62615f15125	527	* @returns MDOT_OK if success
mfiore	0:c62615f15125	528	*/
mfiore	0:c62615f15125	529	int32_t setTxDataRate(const uint8_t& dr);
mfiore	0:c62615f15125	530
mfiore	0:c62615f15125	531	/** Get TX data rate
mfiore	0:c62615f15125	532	* @returns current TX data rate (SF_7 - SF_12)
mfiore	0:c62615f15125	533	*/
mfiore	0:c62615f15125	534	uint8_t getTxDataRate();
mfiore	0:c62615f15125	535
mfiore	0:c62615f15125	536	/** Set TX power
mfiore	0:c62615f15125	537	* power affects maximum range
mfiore	0:c62615f15125	538	* @param power 2 dBm - 20 dBm
mfiore	0:c62615f15125	539	* @returns MDOT_OK if success
mfiore	0:c62615f15125	540	*/
mfiore	0:c62615f15125	541	int32_t setTxPower(const uint32_t& power);
mfiore	0:c62615f15125	542
mfiore	0:c62615f15125	543	/** Get TX power
mfiore	0:c62615f15125	544	* @returns TX power (2 dBm - 20 dBm)
mfiore	0:c62615f15125	545	*/
mfiore	0:c62615f15125	546	uint32_t getTxPower();
mfiore	0:c62615f15125	547
mfiore	0:c62615f15125	548	/** Enable/disable TX waiting for rx windows
mfiore	0:c62615f15125	549	* when enabled, send calls will block until a packet is received or RX timeout
mfiore	0:c62615f15125	550	* @param enable set to true if expecting responses to transmitted packets
mfiore	0:c62615f15125	551	* @returns MDOT_OK if success
mfiore	0:c62615f15125	552	*/
mfiore	0:c62615f15125	553	int32_t setTxWait(const bool& enable);
mfiore	0:c62615f15125	554
mfiore	0:c62615f15125	555	/** Get TX wait
mfiore	0:c62615f15125	556	* @returns true if TX wait is enabled
mfiore	0:c62615f15125	557	*/
mfiore	0:c62615f15125	558	bool getTxWait();
mfiore	0:c62615f15125	559
mfiore	0:c62615f15125	560	/** Get time on air
mfiore	0:c62615f15125	561	* @returns the amount of time (in ms) it would take to send bytes bytes based on current configuration
mfiore	0:c62615f15125	562	*/
mfiore	0:c62615f15125	563	uint32_t getTimeOnAir(uint8_t bytes);
mfiore	0:c62615f15125	564
mfiore	0:c62615f15125	565	/** Get min frequency
mfiore	0:c62615f15125	566	* @returns minimum frequency based on current configuration
mfiore	0:c62615f15125	567	*/
mfiore	0:c62615f15125	568	uint32_t getMinFrequency();
mfiore	0:c62615f15125	569
mfiore	0:c62615f15125	570	/** Get max frequency
mfiore	0:c62615f15125	571	* @returns maximum frequency based on current configuration
mfiore	0:c62615f15125	572	*/
mfiore	0:c62615f15125	573	uint32_t getMaxFrequency();
mfiore	0:c62615f15125	574
mfiore	0:c62615f15125	575	/** Set forward error correction bytes
mfiore	0:c62615f15125	576	* @param bytes 1 - 4 bytes
mfiore	0:c62615f15125	577	* @returns MDOT_OK if success
mfiore	0:c62615f15125	578	*/
mfiore	0:c62615f15125	579	int32_t setFec(const uint8_t& bytes);
mfiore	0:c62615f15125	580
mfiore	0:c62615f15125	581	/** Get forward error correction bytes
mfiore	0:c62615f15125	582	* @returns bytes (1 - 4)
mfiore	0:c62615f15125	583	*/
mfiore	0:c62615f15125	584	uint8_t getFec();
mfiore	0:c62615f15125	585
mfiore	0:c62615f15125	586	/** Enable/disable CRC checking of packets
mfiore	0:c62615f15125	587	* CRC checking must be enabled for use with Conduit gateway and MTAC_LORA card
mfiore	0:c62615f15125	588	* @param on set to true to enable CRC checking
mfiore	0:c62615f15125	589	* @returns MDOT_OK if success
mfiore	0:c62615f15125	590	*/
mfiore	0:c62615f15125	591	int32_t setCrc(const bool& on);
mfiore	0:c62615f15125	592
mfiore	0:c62615f15125	593	/** Get CRC checking
mfiore	0:c62615f15125	594	* @returns true if CRC checking is enabled
mfiore	0:c62615f15125	595	*/
mfiore	0:c62615f15125	596	bool getCrc();
mfiore	0:c62615f15125	597
mfiore	0:c62615f15125	598	/** Set ack
mfiore	0:c62615f15125	599	* @param retries 0 to disable acks, otherwise 1 - 8
mfiore	0:c62615f15125	600	* @returns MDOT_OK if success
mfiore	0:c62615f15125	601	*/
mfiore	0:c62615f15125	602	int32_t setAck(const uint8_t& retries);
mfiore	0:c62615f15125	603
mfiore	0:c62615f15125	604	/** Get ack
mfiore	0:c62615f15125	605	* @returns 0 if acks are disabled, otherwise retries (1 - 8)
mfiore	0:c62615f15125	606	*/
mfiore	0:c62615f15125	607	uint8_t getAck();
mfiore	0:c62615f15125	608
mfiore	0:c62615f15125	609	/** Send data to the gateway
mfiore	0:c62615f15125	610	* validates data size (based on spreading factor)
mfiore	0:c62615f15125	611	* @param data a vector of up to 242 bytes (may be less based on spreading factor)
mfiore	0:c62615f15125	612	* @returns MDOT_OK if packet was sent successfully (ACKs disabled), or if an ACK was received (ACKs enabled)
mfiore	0:c62615f15125	613	*/
mfiore	0:c62615f15125	614	int32_t send(const std::vector<uint8_t>& data, const bool& blocking = true, const bool& highBw = false);
mfiore	0:c62615f15125	615
mfiore	0:c62615f15125	616	/** Fetch data received from the gateway
mfiore	0:c62615f15125	617	* this function only checks to see if a packet has been received - it does not open a receive window
mfiore	0:c62615f15125	618	* send() must be called before recv()
mfiore	0:c62615f15125	619	* @param data a vector to put the received data into
mfiore	0:c62615f15125	620	* @returns MDOT_OK if packet was successfully received
mfiore	0:c62615f15125	621	*/
mfiore	0:c62615f15125	622	int32_t recv(std::vector<uint8_t>& data);
mfiore	0:c62615f15125	623
Mike Fiore	6:390fc83d588d	624
mfiore	0:c62615f15125	625	/** Ping
mfiore	0:c62615f15125	626	* status will be MDOT_OK if ping succeeded
mfiore	0:c62615f15125	627	* @returns ping_response struct containing status, RSSI, and SNR
mfiore	0:c62615f15125	628	*/
mfiore	0:c62615f15125	629	ping_response ping();
mfiore	0:c62615f15125	630
mfiore	0:c62615f15125	631	/** Get return code string
mfiore	0:c62615f15125	632	* @returns string containing a description of the given error code
mfiore	0:c62615f15125	633	*/
mfiore	0:c62615f15125	634	static std::string getReturnCodeString(const int32_t& code);
mfiore	0:c62615f15125	635
mfiore	0:c62615f15125	636	/** Get last error
mfiore	0:c62615f15125	637	* @returns string explaining the last error that occured
mfiore	0:c62615f15125	638	*/
mfiore	0:c62615f15125	639	std::string getLastError();
mfiore	0:c62615f15125	640
Mike Fiore	7:683dba5d576f	641	/** Go to sleep
Mike Fiore	7:683dba5d576f	642	* @param interval the number of seconds to sleep before waking up if wakeup_mode == RTC_ALARM, else ignored
Mike Fiore	7:683dba5d576f	643	* @param wakeup_mode RTC_ALARM, INTERRUPT
Mike Fiore	7:683dba5d576f	644	* if RTC_ALARM the real time clock is configured to wake the device up after the specified interval
Mike Fiore	7:683dba5d576f	645	* if INTERRUPT the device will wake up on the rising edge of the interrupt pin
Mike Fiore	7:683dba5d576f	646	* @param deepsleep if true go into deep sleep mode (lowest power, all memory and registers are lost, peripherals turned off)
Mike Fiore	7:683dba5d576f	647	* else go into sleep mode (low power, memory and registers are maintained, peripherals stay on)
Mike Fiore	7:683dba5d576f	648	*
Mike Fiore	7:683dba5d576f	649	* CURRENTLY ONLY DEEPSLEEP MODE IS AVAILABLE
Mike Fiore	7:683dba5d576f	650	*
Mike Fiore	7:683dba5d576f	651	* in sleep mode, the device can be woken up on any of the XBEE pins or by the RTC alarm
Mike Fiore	7:683dba5d576f	652	* in deepsleep mode, the device can only be woken up using the WKUP pin (PA0, XBEE_DIO7) or by the RTC alarm
Mike Fiore	7:683dba5d576f	653	*/
Mike Fiore	7:683dba5d576f	654	void sleep(const uint32_t& interval, const uint8_t& wakeup_mode = RTC_ALARM, const bool& deepsleep = true);
Mike Fiore	7:683dba5d576f	655
Mike Fiore	7:683dba5d576f	656	/** Set wake pin
Mike Fiore	7:683dba5d576f	657	* @param pin the pin to use to wake the device from sleep mode
Mike Fiore	7:683dba5d576f	658	*/
Mike Fiore	7:683dba5d576f	659	void setWakePin(const PinName& pin);
Mike Fiore	7:683dba5d576f	660
Mike Fiore	7:683dba5d576f	661	/** Get wake pin
Mike Fiore	7:683dba5d576f	662	* @returns the pin to use to wake the device from sleep mode
Mike Fiore	7:683dba5d576f	663	*/
Mike Fiore	7:683dba5d576f	664	PinName getWakePin();
Mike Fiore	7:683dba5d576f	665
jreiss	9:ec2fffe31793	666	/** Write data in a user backup register
jreiss	9:ec2fffe31793	667	* @param register one of UBR0 through UBR9
jreiss	9:ec2fffe31793	668	* @param data user data to back up
jreiss	9:ec2fffe31793	669	* @returns true if success
jreiss	9:ec2fffe31793	670	*/
jreiss	9:ec2fffe31793	671	bool writeUserBackupRegister(uint32_t reg, uint32_t data);
jreiss	9:ec2fffe31793	672
jreiss	9:ec2fffe31793	673	/** Read data in a user backup register
jreiss	9:ec2fffe31793	674	* @param register one of UBR0 through UBR9
jreiss	9:ec2fffe31793	675	* @param data gets set to content of register
jreiss	9:ec2fffe31793	676	* @returns true if success
jreiss	9:ec2fffe31793	677	*/
jreiss	9:ec2fffe31793	678	bool readUserBackupRegister(uint32_t reg, uint32_t& data);
jreiss	9:ec2fffe31793	679
mfiore	0:c62615f15125	680	/******************************************
mfiore	0:c62615f15125	681	* THESE FEATURES ARE NOT FULLY IMPLEMENTED
mfiore	0:c62615f15125	682	*****************************************/
mfiore	0:c62615f15125	683	// get/set adaptive data rate
mfiore	0:c62615f15125	684	// configure data rates and power levels based on signal to noise information from gateway
mfiore	0:c62615f15125	685	// true == adaptive data rate is on
mfiore	0:c62615f15125	686	// set function returns MDOT_OK if success
mfiore	0:c62615f15125	687	int32_t setAdr(const bool& on);
mfiore	0:c62615f15125	688	bool getAdr();
mfiore	0:c62615f15125	689
mfiore	0:c62615f15125	690	/*************************************************************************
mfiore	0:c62615f15125	691	* The following functions are only used by the AT command application and
mfiore	0:c62615f15125	692	* should not be used by standard applications consuming the mDot library
mfiore	0:c62615f15125	693	************************************************************************/
Mike Fiore	7:683dba5d576f	694
mfiore	0:c62615f15125	695	// set/get configured baud rate for command port
mfiore	0:c62615f15125	696	// only for use in conjunction with AT interface
mfiore	0:c62615f15125	697	// set function returns MDOT_OK if success
mfiore	0:c62615f15125	698	int32_t setBaud(const uint32_t& baud);
mfiore	0:c62615f15125	699	uint32_t getBaud();
mfiore	0:c62615f15125	700
mfiore	0:c62615f15125	701	// set/get baud rate for debug port
mfiore	0:c62615f15125	702	// set function returns MDOT_OK if success
mfiore	0:c62615f15125	703	int32_t setDebugBaud(const uint32_t& baud);
mfiore	0:c62615f15125	704	uint32_t getDebugBaud();
mfiore	0:c62615f15125	705
mfiore	0:c62615f15125	706	// set/get command terminal echo
mfiore	0:c62615f15125	707	// set function returns MDOT_OK if success
mfiore	0:c62615f15125	708	int32_t setEcho(const bool& on);
mfiore	0:c62615f15125	709	bool getEcho();
mfiore	0:c62615f15125	710
mfiore	0:c62615f15125	711	// set/get command terminal verbose mode
mfiore	0:c62615f15125	712	// set function returns MDOT_OK if success
mfiore	0:c62615f15125	713	int32_t setVerbose(const bool& on);
mfiore	0:c62615f15125	714	bool getVerbose();
mfiore	0:c62615f15125	715
mfiore	0:c62615f15125	716	// set/get startup mode
mfiore	0:c62615f15125	717	// COMMAND_MODE (default), starts up ready to accept AT commands
mfiore	0:c62615f15125	718	// SERIAL_MODE, read serial data and send it as LoRa packets
mfiore	0:c62615f15125	719	// set function returns MDOT_OK if success
mfiore	0:c62615f15125	720	int32_t setStartUpMode(const uint8_t& mode);
mfiore	0:c62615f15125	721	uint8_t getStartUpMode();
mfiore	0:c62615f15125	722
mfiore	0:c62615f15125	723	int32_t setRxDataRate(const uint8_t& dr);
mfiore	0:c62615f15125	724	uint8_t getRxDataRate();
mfiore	0:c62615f15125	725
mfiore	0:c62615f15125	726	// get/set TX/RX frequency
mfiore	0:c62615f15125	727	// if frequency band == FB_868 (Europe), must be between 863000000 - 870000000
mfiore	0:c62615f15125	728	// if frequency band == FB_915 (United States), must be between 902000000-928000000
mfiore	0:c62615f15125	729	// if set to 0, device will hop frequencies
mfiore	0:c62615f15125	730	// set function returns MDOT_OK if success
mfiore	0:c62615f15125	731	int32_t setTxFrequency(const uint32_t& freq);
mfiore	0:c62615f15125	732	uint32_t getTxFrequency();
mfiore	0:c62615f15125	733	int32_t setRxFrequency(const uint32_t& freq);
mfiore	0:c62615f15125	734	uint32_t getRxFrequency();
mfiore	0:c62615f15125	735
mfiore	0:c62615f15125	736	// get/set TX/RX inverted
mfiore	0:c62615f15125	737	// true == signal is inverted
mfiore	0:c62615f15125	738	// set function returns MDOT_OK if success
mfiore	0:c62615f15125	739	int32_t setTxInverted(const bool& on);
mfiore	0:c62615f15125	740	bool getTxInverted();
mfiore	0:c62615f15125	741	int32_t setRxInverted(const bool& on);
mfiore	0:c62615f15125	742	bool getRxInverted();
mfiore	0:c62615f15125	743
mfiore	0:c62615f15125	744	// get/set RX output mode
mfiore	0:c62615f15125	745	// valid options are HEXADECIMAL and BINARY
mfiore	0:c62615f15125	746	// set function returns MDOT_OK if success
mfiore	0:c62615f15125	747	int32_t setRxOutput(const uint8_t& mode);
mfiore	0:c62615f15125	748	uint8_t getRxOutput();
mfiore	0:c62615f15125	749
mfiore	0:c62615f15125	750	// get/set serial wake interval
mfiore	0:c62615f15125	751	// valid values are 2 s - INT_MAX (2147483647) s
mfiore	0:c62615f15125	752	// set function returns MDOT_OK if success
Mike Fiore	7:683dba5d576f	753	int32_t setWakeInterval(const uint32_t& interval);
Mike Fiore	7:683dba5d576f	754	uint32_t getWakeInterval();
mfiore	0:c62615f15125	755
mfiore	0:c62615f15125	756	// get/set serial wake delay
mfiore	0:c62615f15125	757	// valid values are 2 ms - INT_MAX (2147483647) ms
mfiore	0:c62615f15125	758	// set function returns MDOT_OK if success
Mike Fiore	7:683dba5d576f	759	int32_t setWakeDelay(const uint32_t& delay);
Mike Fiore	7:683dba5d576f	760	uint32_t getWakeDelay();
mfiore	0:c62615f15125	761
mfiore	0:c62615f15125	762	// get/set serial receive timeout
mfiore	0:c62615f15125	763	// valid values are 0 ms - 65000 ms
mfiore	0:c62615f15125	764	// set function returns MDOT_OK if success
Mike Fiore	7:683dba5d576f	765	int32_t setWakeTimeout(const uint16_t& timeout);
Mike Fiore	7:683dba5d576f	766	uint16_t getWakeTimeout();
Mike Fiore	7:683dba5d576f	767
Mike Fiore	7:683dba5d576f	768	// get/set serial wake mode
Mike Fiore	7:683dba5d576f	769	// valid values are INTERRUPT or RTC_ALARM
Mike Fiore	7:683dba5d576f	770	// set function returns MDOT_OK if success
Mike Fiore	7:683dba5d576f	771	int32_t setWakeMode(const uint8_t& delay);
Mike Fiore	7:683dba5d576f	772	uint8_t getWakeMode();
Mike Fiore	7:683dba5d576f	773
Mike Fiore	7:683dba5d576f	774	// Save user file data to flash
Mike Fiore	7:683dba5d576f	775	// file - name of file max 30 chars
Mike Fiore	7:683dba5d576f	776	// data - data of file
Mike Fiore	7:683dba5d576f	777	// size - size of file
Mike Fiore	7:683dba5d576f	778	bool saveUserFile(const char* file, void* data, uint32_t size);
Mike Fiore	7:683dba5d576f	779
Mike Fiore	7:683dba5d576f	780	// Append user file data to flash
Mike Fiore	7:683dba5d576f	781	// file - name of file max 30 chars
Mike Fiore	7:683dba5d576f	782	// data - data of file
Mike Fiore	7:683dba5d576f	783	// size - size of file
Mike Fiore	7:683dba5d576f	784	bool appendUserFile(const char* file, void* data, uint32_t size);
Mike Fiore	7:683dba5d576f	785
Mike Fiore	7:683dba5d576f	786	// Read user file data from flash
Mike Fiore	7:683dba5d576f	787	// file - name of file max 30 chars
Mike Fiore	7:683dba5d576f	788	// data - data of file
Mike Fiore	7:683dba5d576f	789	// size - size of file
Mike Fiore	7:683dba5d576f	790	bool readUserFile(const char* file, void* data, uint32_t size);
Mike Fiore	7:683dba5d576f	791
Mike Fiore	7:683dba5d576f	792	// Move a user file in flash
Mike Fiore	7:683dba5d576f	793	// file - name of file
Mike Fiore	7:683dba5d576f	794	// new_name - new name of file
Mike Fiore	7:683dba5d576f	795	bool moveUserFile(const char* file, const char* new_name);
Mike Fiore	7:683dba5d576f	796
Mike Fiore	7:683dba5d576f	797	// Delete user file data from flash
Mike Fiore	7:683dba5d576f	798	// file - name of file max 30 chars
Mike Fiore	7:683dba5d576f	799	bool deleteUserFile(const char* file);
Mike Fiore	7:683dba5d576f	800
Mike Fiore	7:683dba5d576f	801	// Open user file in flash, max of 4 files open concurrently
Mike Fiore	7:683dba5d576f	802	// file - name of file max 30 chars
Mike Fiore	7:683dba5d576f	803	// mode - combination of FM_APPEND \| FM_TRUNC \| FM_CREAT \|
Mike Fiore	7:683dba5d576f	804	// FM_RDONLY \| FM_WRONLY \| FM_RDWR \| FM_DIRECT
Mike Fiore	7:683dba5d576f	805	// returns - mdot_file struct, fd field will be a negative value if file could not be opened
Mike Fiore	7:683dba5d576f	806	mDot::mdot_file openUserFile(const char* file, int mode);
Mike Fiore	7:683dba5d576f	807
Mike Fiore	7:683dba5d576f	808	// Seek an open file
Mike Fiore	7:683dba5d576f	809	// file - mdot file struct
Mike Fiore	7:683dba5d576f	810	// offset - offset in bytes
Mike Fiore	7:683dba5d576f	811	// whence - where offset is based SEEK_SET, SEEK_CUR, SEEK_END
Mike Fiore	7:683dba5d576f	812	bool seekUserFile(mDot::mdot_file& file, size_t offset, int whence);
Mike Fiore	7:683dba5d576f	813
Mike Fiore	7:683dba5d576f	814	// Read bytes from open file
Mike Fiore	7:683dba5d576f	815	// file - mdot file struct
Mike Fiore	7:683dba5d576f	816	// data - mem location to store data
Mike Fiore	7:683dba5d576f	817	// length - number of bytes to read
Mike Fiore	7:683dba5d576f	818	// returns - number of bytes written
Mike Fiore	7:683dba5d576f	819	int readUserFile(mDot::mdot_file& file, void* data, size_t length);
Mike Fiore	7:683dba5d576f	820
Mike Fiore	7:683dba5d576f	821	// Write bytes to open file
Mike Fiore	7:683dba5d576f	822	// file - mdot file struct
Mike Fiore	7:683dba5d576f	823	// data - data to write
Mike Fiore	7:683dba5d576f	824	// length - number of bytes to write
Mike Fiore	7:683dba5d576f	825	// returns - number of bytes written
Mike Fiore	7:683dba5d576f	826	int writeUserFile(mDot::mdot_file& file, void* data, size_t length);
Mike Fiore	7:683dba5d576f	827
Mike Fiore	7:683dba5d576f	828	// Close open file
Mike Fiore	7:683dba5d576f	829	// file - mdot file struct
Mike Fiore	7:683dba5d576f	830	bool closeUserFile(mDot::mdot_file& file);
Mike Fiore	7:683dba5d576f	831
Mike Fiore	7:683dba5d576f	832	// List user files stored in flash
Mike Fiore	7:683dba5d576f	833	std::vector<mDot::mdot_file> listUserFiles();
Mike Fiore	7:683dba5d576f	834
Mike Fiore	7:683dba5d576f	835	// Move file into the firmware upgrade path to be flashed on next boot
Mike Fiore	7:683dba5d576f	836	// file - name of file
Mike Fiore	7:683dba5d576f	837	bool moveUserFileToFirmwareUpgrade(const char* file);
Mike Fiore	7:683dba5d576f	838
Mike Fiore	7:683dba5d576f	839	// get current statistics
Mike Fiore	7:683dba5d576f	840	// Join Attempts, Join Fails, Up Packets, Down Packets, Missed Acks
Mike Fiore	7:683dba5d576f	841	mdot_stats getStats();
Mike Fiore	7:683dba5d576f	842
Mike Fiore	7:683dba5d576f	843	// reset statistics
Mike Fiore	7:683dba5d576f	844	// Join Attempts, Join Fails, Up Packets, Down Packets, Missed Acks
Mike Fiore	7:683dba5d576f	845	void resetStats();
Mike Fiore	7:683dba5d576f	846
Mike Fiore	7:683dba5d576f	847	// Convert pin number 2-8 to pin name DIO2-DI8
Mike Fiore	7:683dba5d576f	848	static PinName pinNum2Name(uint8_t num);
Mike Fiore	7:683dba5d576f	849
Mike Fiore	7:683dba5d576f	850	// Convert pin name DIO2-DI8 to pin number 2-8
Mike Fiore	7:683dba5d576f	851	static uint8_t pinName2Num(PinName name);
Mike Fiore	7:683dba5d576f	852
Mike Fiore	7:683dba5d576f	853	// Convert pin name DIO2-DI8 to string
Mike Fiore	7:683dba5d576f	854	static std::string pinName2Str(PinName name);
Mike Fiore	7:683dba5d576f	855
mfiore	0:c62615f15125	856
mfiore	0:c62615f15125	857	uint64_t crc64(uint64_t crc, const unsigned char *s, uint64_t l);
mfiore	0:c62615f15125	858
mfiore	0:c62615f15125	859	// MTS_RADIO_DEBUG_COMMANDS
Mike Fiore	7:683dba5d576f	860
Mike Fiore	7:683dba5d576f	861	void openRxWindow(uint32_t timeout, uint8_t bandwidth = 0);
Mike Fiore	6:390fc83d588d	862	void sendContinuous();
mfiore	0:c62615f15125	863	int32_t setDeviceId(const std::vector<uint8_t>& id);
mfiore	0:c62615f15125	864	int32_t setFrequencyBand(const uint8_t& band);
mfiore	0:c62615f15125	865	bool saveProtectedConfig();
mfiore	0:c62615f15125	866	void resetRadio();
mfiore	0:c62615f15125	867	int32_t setRadioMode(const uint8_t& mode);
mfiore	0:c62615f15125	868	std::map<uint8_t, uint8_t> dumpRegisters();
mfiore	0:c62615f15125	869	void eraseFlash();
mfiore	0:c62615f15125	870
Mike Fiore	7:683dba5d576f	871
Mike Fiore	7:683dba5d576f	872	// deprecated - use setWakeInterval
Mike Fiore	7:683dba5d576f	873	int32_t setSerialWakeInterval(const uint32_t& interval);
Mike Fiore	7:683dba5d576f	874	// deprecated - use getWakeInterval
Mike Fiore	7:683dba5d576f	875	uint32_t getSerialWakeInterval();
Mike Fiore	6:390fc83d588d	876
Mike Fiore	7:683dba5d576f	877	// deprecated - use setWakeDelay
Mike Fiore	7:683dba5d576f	878	int32_t setSerialWakeDelay(const uint32_t& delay);
Mike Fiore	7:683dba5d576f	879	// deprecated - use setWakeDelay
Mike Fiore	7:683dba5d576f	880	uint32_t getSerialWakeDelay();
Mike Fiore	7:683dba5d576f	881
Mike Fiore	7:683dba5d576f	882	// deprecated - use setWakeTimeout
Mike Fiore	7:683dba5d576f	883	int32_t setSerialReceiveTimeout(const uint16_t& timeout);
Mike Fiore	7:683dba5d576f	884	// deprecated - use getWakeTimeout
Mike Fiore	7:683dba5d576f	885	uint16_t getSerialReceiveTimeout();
mfiore	0:c62615f15125	886
mfiore	0:c62615f15125	887	private:
mfiore	0:c62615f15125	888	mdot_stats _stats;
mfiore	0:c62615f15125	889
mfiore	0:c62615f15125	890	};
mfiore	0:c62615f15125	891
mfiore	0:c62615f15125	892	#endif