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

MTS-Lora/vendor/multitech/MTS-Utils/MTSCircularBuffer.h@74:8b02b1a9a1b6, 2020-03-25 (annotated)

Committer:: jreiss
Date:: Wed Mar 25 17:06:41 2020 +0000
Revision:: 74:8b02b1a9a1b6
Parent:: 72:b1e07ec1c30d

Remove old ARMCC archive, only ARMC6 is available.

Who changed what in which revision?

User	Revision	Line number	New contents of line
Mike Fiore	16:b630e18103e5	1	#ifndef MTSCIRCULARBUFFER_H
Mike Fiore	16:b630e18103e5	2	#define MTSCIRCULARBUFFER_H
Mike Fiore	16:b630e18103e5	3
Jenkins@KEILDM1.dc.multitech.prv	64:64982192a2af	4	#include <Callback.h>
Jenkins@KEILDM1.dc.multitech.prv	64:64982192a2af	5
Mike Fiore	16:b630e18103e5	6	#include "Utils.h"
Mike Fiore	16:b630e18103e5	7
Mike Fiore	16:b630e18103e5	8	namespace mts
Mike Fiore	16:b630e18103e5	9	{
Mike Fiore	16:b630e18103e5	10
Mike Fiore	16:b630e18103e5	11	/** This class provides a circular byte buffer meant for temporary storage
Mike Fiore	16:b630e18103e5	12	* during IO transactions. It contains many of the common methods you
Mike Fiore	16:b630e18103e5	13	* would expect from a circular buffer like read, write, and various
Mike Fiore	16:b630e18103e5	14	* methods for checking the size or status. It should be noted that
Mike Fiore	16:b630e18103e5	15	* this class does not include any special code for thread safety like
Mike Fiore	16:b630e18103e5	16	* a lock. In most cases this is not problematic, but is something
Mike Fiore	16:b630e18103e5	17	* to be aware of.
Mike Fiore	16:b630e18103e5	18	*/
Mike Fiore	16:b630e18103e5	19	class MTSCircularBuffer
Mike Fiore	16:b630e18103e5	20	{
Mike Fiore	16:b630e18103e5	21	public:
Mike Fiore	16:b630e18103e5	22	/** Creates an MTSCircularBuffer object with the specified static size.
Mike Fiore	16:b630e18103e5	23	*
Mike Fiore	16:b630e18103e5	24	* @prarm bufferSize size of the buffer in bytes.
Mike Fiore	16:b630e18103e5	25	*/
Mike Fiore	16:b630e18103e5	26	MTSCircularBuffer(int bufferSize);
Mike Fiore	16:b630e18103e5	27
Mike Fiore	16:b630e18103e5	28	/** Destructs an MTSCircularBuffer object and frees all related resources.
Mike Fiore	16:b630e18103e5	29	*/
Mike Fiore	16:b630e18103e5	30	~MTSCircularBuffer();
Mike Fiore	16:b630e18103e5	31
Mike Fiore	16:b630e18103e5	32	/** This method enables bulk reads from the buffer. If more data is
Mike Fiore	16:b630e18103e5	33	* requested then available it simply returns all remaining data within the
Mike Fiore	16:b630e18103e5	34	* buffer.
Mike Fiore	16:b630e18103e5	35	*
Mike Fiore	16:b630e18103e5	36	* @param data the buffer where data read will be added to.
Mike Fiore	16:b630e18103e5	37	* @param length the amount of data in bytes to be read into the buffer.
Mike Fiore	16:b630e18103e5	38	* @returns the total number of bytes that were read.
Mike Fiore	16:b630e18103e5	39	*/
Mike Fiore	16:b630e18103e5	40	int read(char* data, int length);
Mike Fiore	16:b630e18103e5	41
Mike Fiore	16:b630e18103e5	42	/** This method reads a single byte from the buffer.
Mike Fiore	16:b630e18103e5	43	*
Mike Fiore	16:b630e18103e5	44	* @param data char where the read byte will be stored.
Mike Fiore	16:b630e18103e5	45	* @returns 1 if byte is read or 0 if no bytes available.
Mike Fiore	16:b630e18103e5	46	*/
Mike Fiore	16:b630e18103e5	47	int read(char& data);
Mike Fiore	16:b630e18103e5	48
Mike Fiore	16:b630e18103e5	49	/** This method enables bulk writes to the buffer. If more data
Mike Fiore	16:b630e18103e5	50	* is requested to be written then space available the method writes
Mike Fiore	16:b630e18103e5	51	* as much data as possible and returns the actual amount written.
Mike Fiore	16:b630e18103e5	52	*
Mike Fiore	16:b630e18103e5	53	* @param data the byte array to be written.
Mike Fiore	16:b630e18103e5	54	* @param length the length of data to be written from the data paramter.
Mike Fiore	16:b630e18103e5	55	* @returns the number of bytes written to the buffer, which is 0 if
Mike Fiore	16:b630e18103e5	56	* the buffer is full.
Mike Fiore	16:b630e18103e5	57	*/
Mike Fiore	16:b630e18103e5	58	int write(const char* data, int length);
Mike Fiore	16:b630e18103e5	59
Mike Fiore	16:b630e18103e5	60	/** This method writes a signle byte as a char to the buffer.
Mike Fiore	16:b630e18103e5	61	*
Mike Fiore	16:b630e18103e5	62	* @param data the byte to be written as a char.
Mike Fiore	16:b630e18103e5	63	* @returns 1 if the byte was written or 0 if the buffer was full.
Mike Fiore	16:b630e18103e5	64	*/
Mike Fiore	16:b630e18103e5	65	int write(char data);
Mike Fiore	16:b630e18103e5	66
Mike Fiore	16:b630e18103e5	67	/** This method is used to setup a callback funtion when the buffer reaches
Mike Fiore	16:b630e18103e5	68	* a certain threshold. The threshold condition is checked after every read
Mike Fiore	16:b630e18103e5	69	* and write call is completed. The condition is made up of both a threshold
Mike Fiore	16:b630e18103e5	70	* value and operator. An example that would trigger a callback is if the
Mike Fiore	16:b630e18103e5	71	* threshold was 10, the operator GREATER, and there were 12 bytes added to an
Mike Fiore	16:b630e18103e5	72	* empty buffer.
Mike Fiore	16:b630e18103e5	73	*
Mike Fiore	16:b630e18103e5	74	* @param tptr a pointer to the object to be called when the condition is met.
Mike Fiore	16:b630e18103e5	75	* @param mptr a pointer to the function within the object to be called when
Mike Fiore	16:b630e18103e5	76	* the condition is met.
Mike Fiore	16:b630e18103e5	77	* @param threshold the value in bytes to be used as part of the condition.
Mike Fiore	16:b630e18103e5	78	* @param op the operator to be used in conjunction with the threshold
Mike Fiore	16:b630e18103e5	79	* as part of the condition.
Mike Fiore	16:b630e18103e5	80	*/
Mike Fiore	16:b630e18103e5	81	template<typename T>
Mike Fiore	16:b630e18103e5	82	void attach(T tptr, void( T::mptr)(void), int threshold, RelationalOperator op) {
Mike Fiore	16:b630e18103e5	83	_threshold = threshold;
Mike Fiore	16:b630e18103e5	84	_op = op;
Jenkins@KEILDM1.dc.multitech.prv	72:b1e07ec1c30d	85	notify = callback(tptr, mptr);
Mike Fiore	16:b630e18103e5	86	}
Mike Fiore	16:b630e18103e5	87
Mike Fiore	16:b630e18103e5	88	/** This method is used to setup a callback funtion when the buffer reaches
Mike Fiore	16:b630e18103e5	89	* a certain threshold. The threshold condition is checked after every read
Mike Fiore	16:b630e18103e5	90	* and write call is completed. The condition is made up of both a threshold
Mike Fiore	16:b630e18103e5	91	* value and operator. An example that would trigger a callback is if the
Mike Fiore	16:b630e18103e5	92	* threshold was 10, the operator GREATER, and there were 12 bytes added to an
Mike Fiore	16:b630e18103e5	93	* empty buffer.
Mike Fiore	16:b630e18103e5	94	*
Mike Fiore	16:b630e18103e5	95	* @param fptr a pointer to the static function to be called when the condition
Mike Fiore	16:b630e18103e5	96	* is met.
Mike Fiore	16:b630e18103e5	97	* @param threshold the value in bytes to be used as part of the condition.
Mike Fiore	16:b630e18103e5	98	* @param op the operator to be used in conjunction with the threshold
Mike Fiore	16:b630e18103e5	99	* as part of the condition.
Mike Fiore	16:b630e18103e5	100	*/
Mike Fiore	16:b630e18103e5	101	void attach(void(*fptr)(void), int threshold, RelationalOperator op) {
Mike Fiore	16:b630e18103e5	102	_threshold = threshold;
Mike Fiore	16:b630e18103e5	103	_op = op;
Jenkins@KEILDM1.dc.multitech.prv	64:64982192a2af	104	notify = fptr;
Mike Fiore	16:b630e18103e5	105	}
Mike Fiore	16:b630e18103e5	106
Mike Fiore	16:b630e18103e5	107	/** This method returns the size of the storage space currently allocated for
Mike Fiore	16:b630e18103e5	108	* the buffer. This value is equivalent to the one passed into the constructor.
Mike Fiore	16:b630e18103e5	109	* This value is equal or greater than the size() of the buffer.
Mike Fiore	16:b630e18103e5	110	*
Mike Fiore	16:b630e18103e5	111	* @returns the allocated size of the buffer in bytes.
Mike Fiore	16:b630e18103e5	112	*/
Mike Fiore	16:b630e18103e5	113	int capacity();
Mike Fiore	16:b630e18103e5	114
Mike Fiore	16:b630e18103e5	115	/** This method returns the amount of space left for writing.
Mike Fiore	16:b630e18103e5	116	*
Mike Fiore	16:b630e18103e5	117	* @returns numbers of unused bytes in buffer.
Mike Fiore	16:b630e18103e5	118	*/
Mike Fiore	16:b630e18103e5	119	int remaining();
Mike Fiore	16:b630e18103e5	120
Mike Fiore	16:b630e18103e5	121	/** This method returns the number of bytes available for reading.
Mike Fiore	16:b630e18103e5	122	*
Mike Fiore	16:b630e18103e5	123	* @returns number of bytes currently in buffer.
Mike Fiore	16:b630e18103e5	124	*/
Mike Fiore	16:b630e18103e5	125	int size();
Mike Fiore	16:b630e18103e5	126
Mike Fiore	16:b630e18103e5	127	/** This method returns whether the buffer is full.
Mike Fiore	16:b630e18103e5	128	*
Mike Fiore	16:b630e18103e5	129	* @returns true if full, otherwise false.
Mike Fiore	16:b630e18103e5	130	*/
Mike Fiore	16:b630e18103e5	131	bool isFull();
Mike Fiore	16:b630e18103e5	132
Mike Fiore	16:b630e18103e5	133	/** This method returns whether the buffer is empty.
Mike Fiore	16:b630e18103e5	134	*
Mike Fiore	16:b630e18103e5	135	* @returns true if empty, otherwise false.
Mike Fiore	16:b630e18103e5	136	*/
Mike Fiore	16:b630e18103e5	137	bool isEmpty();
Mike Fiore	16:b630e18103e5	138
Mike Fiore	16:b630e18103e5	139	/** This method clears the buffer. This is done through
Mike Fiore	16:b630e18103e5	140	* setting the internal read and write indexes to the same
Mike Fiore	16:b630e18103e5	141	* value and is therefore not an expensive operation.
Mike Fiore	16:b630e18103e5	142	*/
Mike Fiore	16:b630e18103e5	143	void clear();
Mike Fiore	16:b630e18103e5	144
Mike Fiore	16:b630e18103e5	145
Mike Fiore	16:b630e18103e5	146	private:
Mike Fiore	16:b630e18103e5	147	int bufferSize; // total size of the buffer
Mike Fiore	16:b630e18103e5	148	char* buffer; // internal byte buffer as a character buffer
Mike Fiore	16:b630e18103e5	149	int readIndex; // read index for circular buffer
Mike Fiore	16:b630e18103e5	150	int writeIndex; // write index for circular buffer
Mike Fiore	16:b630e18103e5	151	int bytes; // available data
Jenkins@KEILDM1.dc.multitech.prv	64:64982192a2af	152	Callback<void()> notify; // Internal callback notification
Mike Fiore	16:b630e18103e5	153	int _threshold; // threshold for the notification
Mike Fiore	16:b630e18103e5	154	RelationalOperator _op; // operator that determines the direction of the threshold
Mike Fiore	16:b630e18103e5	155	void checkThreshold(); // private function that checks thresholds and processes notifications
Mike Fiore	16:b630e18103e5	156	};
Mike Fiore	16:b630e18103e5	157
Mike Fiore	16:b630e18103e5	158	}
Mike Fiore	16:b630e18103e5	159
Mike Fiore	16:b630e18103e5	160	#endif /* MTSCIRCULARBUFFER_H */