MultiTech / libxDot-mbed5

Stable version of the xDot library for mbed 5. This version of the library is suitable for deployment scenarios.

Dependents:   Dot-Examples XDOT-Devicewise Dot-Examples-delujoc Dot-Examples_receive ... more

Fork of libxDot-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:

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

examples/src/fota_example.cpp

    // Initialize FOTA singleton
    Fota::getInstance(dot);
  • Add fragmentation handling the the PacketRx event

examples/inc/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
    }

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@29:fb5769f4a67c, 2020-04-02 (annotated)

Committer:
Jenkins@KEILDM1.dc.multitech.prv
Date:
Thu Apr 02 09:36:13 2020 -0500
Revision:
29:fb5769f4a67c
Parent:
19:aa5b1fcd05be 
xdot-library revision 3.3.5 and mbed-os revision mbed-os-5.15.1

Who changed what in which revision?

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