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@4:94969e981dcc, 2015-06-30 (annotated)

Committer:: Mike Fiore
Date:: Tue Jun 30 16:18:24 2015 -0500
Revision:: 4:94969e981dcc
Parent:: 0:c62615f15125
Child:: 5:0bfe6a650513

update mDot library and mDot.h from git revision c5af21e8ddc6d37b5cd2f375c4b3b50ab50af026

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