MultiTech / libxDot-dev-mbed5-deprecated

Bleeding edge development version of the xDot library for mbed 5. This version of the library is not guaranteed to be stable or well tested and should not be used in production or deployment scenarios.

Dependents:   Dot-Examples Dot-AT-Firmware Dot-Examples TEST_FF1705 ... more

The Dot library provides a LoRaWan certified stack for LoRa communication using MultiTech mDot and xDot devices. The stack is compatible with mbed 5.

Dot Library Version 3 Updates

Dot Library versions 3.x.x require a channel plan to be injected into the stack. Channel plans are included with the 3.x.x Dot Library releases. The following code snippet demonstrates how to create a channel plan and inject it into the stack.

#include "mDot.h"
#include "channel_plans.h"

int main() {
    ChannelPlan* plan = new lora::ChannelPlan_US915();
    assert(plan);
    mDot* dot = mDot::getInstance(plan);
    assert(dot);

    // ...
}

Dot devices must not be deployed with software using a different channel plan than the Dot's default plan! This functionality is for development and testing only!

Multicast Sessions

Multicast sessions and packet rx events in library. When in Class C mode Multicast downlinks can be received. Recieved packets should be filtered on address, counter value will be maintained in the session or can be set explicitly depending on Application support to share Multicast Address, Keys and Counters.

mDot.h

        /**
         * Add a multicast session address and keys
         * Downlink counter is set to 0
         * Up to 3 MULTICAST_SESSIONS can be set
         */
        int32_t setMulticastSession(uint8_t index, uint32_t addr, const uint8_t* nsk, const uint8_t* dsk);
 
        /**
         * Set a multicast session counter
         * Up to 3 MULTICAST_SESSIONS can be set
         */
        int32_t setMulticastDownlinkCounter(uint8_t index, uint32_t count);

mDotEvent.h

The address field was added to PacketRx event.

        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);

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.

Diff: plans/ChannelPlan_IN865.h

Revision:
36:bf7b1b13d7da
Child:
114:8c46cd200c40
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/plans/ChannelPlan_IN865.h	Mon Jun 19 16:03:56 2017 -0500
@@ -0,0 +1,231 @@
+/**   __  ___     ____  _    ______        __     ____         __                  ____
+ *   /  |/  /_ __/ / /_(_)__/_  __/__ ____/ /    / __/_ _____ / /____ __ _  ___   /  _/__  ____
+ *  / /|_/ / // / / __/ /___// / / -_) __/ _ \  _\ \/ // (_-</ __/ -_)  ' \(_-<  _/ // _ \/ __/ __
+ * /_/  /_/\_,_/_/\__/_/    /_/  \__/\__/_//_/ /___/\_, /___/\__/\__/_/_/_/___/ /___/_//_/\__/ /_/
+ * Copyright (C) 2015 by Multi-Tech Systems        /___/
+ *
+ *
+ * @author Jason Reiss
+ * @date   10-31-2015
+ * @brief  lora::ChannelPlan provides an interface for LoRaWAN channel schemes
+ *
+ * @details
+ *
+ */
+
+#ifndef __CHANNEL_PLAN_IN865_H__
+#define __CHANNEL_PLAN_IN865_H__
+
+#include "Lora.h"
+#include "SxRadio.h"
+#include <vector>
+#include "ChannelPlan.h"
+
+namespace lora {
+
+    class ChannelPlan_IN865 : public lora::ChannelPlan {
+        public:
+            /**
+             * ChannelPlan constructor
+             * @param radio SxRadio object used to set Tx/Rx config
+             * @param settings Settings object
+             */
+            ChannelPlan_IN865();
+            ChannelPlan_IN865(Settings* settings);
+            ChannelPlan_IN865(SxRadio* radio, Settings* settings);
+
+            /**
+             * ChannelPlan destructor
+             */
+            virtual ~ChannelPlan_IN865();
+
+            /**
+             * Initialize channels, datarates and duty cycle bands according to current channel plan in settings
+             */
+            virtual void Init();
+
+            /**
+             * Get the next channel to use to transmit
+             * @return LORA_OK if channel was found
+             * @return LORA_NO_CHANS_ENABLED
+             */
+            virtual uint8_t GetNextChannel();
+
+            /**
+             * Add a channel to the ChannelPlan
+             * @param index of channel, use -1 to add to end
+             * @param channel settings to add
+             */
+            virtual uint8_t AddChannel(int8_t index, Channel channel);
+
+            /**
+             * Get channel at index
+             * @return Channel
+             */
+            virtual Channel GetChannel(int8_t index);
+
+            /**
+             * Get rx window settings for requested window
+             * RX_1, RX_2, RX_BEACON, RX_SLOT
+             * @param window
+             * @return RxWindow
+             */
+            virtual RxWindow GetRxWindow(uint8_t window);
+
+            /**
+             * Get datarate to use on the join request
+             * @return datarate index
+             */
+            virtual uint8_t GetJoinDatarate();
+
+            /**
+             * Calculate the next time a join request is possible
+             * @param size of join frame
+             * @returns LORA_OK
+             */
+            virtual uint8_t CalculateJoinBackoff(uint8_t size);
+
+            /**
+             * Get next channel and set the SxRadio tx config with current settings
+             * @return LORA_OK
+             */
+            virtual uint8_t SetTxConfig();
+
+            /**
+             * Set the SxRadio rx config provided window
+             * @param window to be opened
+             * @param continuous keep window open
+             * @return LORA_OK
+             */
+            virtual uint8_t SetRxConfig(uint8_t window, bool continuous);
+
+            /**
+             * Set frequency sub band if supported by plan
+             * @param sub_band
+             * @return LORA_OK
+             */
+            virtual uint8_t SetFrequencySubBand(uint8_t sub_band);
+
+            /**
+             * Callback for ACK timeout event
+             * @return LORA_OK
+             */
+            virtual uint8_t HandleAckTimeout();
+
+            /**
+             * Callback for Join Accept packet to load optional channels
+             * @return LORA_OK
+             */
+            virtual uint8_t HandleJoinAccept(const uint8_t* buffer, uint8_t size);
+
+            /**
+             * Callback to for rx parameter setup ServerCommand
+             * @param payload packet data
+             * @param index of start of command buffer
+             * @param size number of bytes in command buffer
+             * @param[out] status to be returned in MoteCommand answer
+             * @return LORA_OK
+             */
+            virtual uint8_t HandleRxParamSetup(const uint8_t* payload, uint8_t index, uint8_t size, uint8_t& status);
+
+            /**
+             * Callback to for new channel ServerCommand
+             * @param payload packet data
+             * @param index of start of command buffer
+             * @param size number of bytes in command buffer
+             * @param[out] status to be returned in MoteCommand answer
+             * @return LORA_OK
+             */
+            virtual uint8_t HandleNewChannel(const uint8_t* payload, uint8_t index, uint8_t size, uint8_t& status);
+
+            /**
+             * Callback to for ping slot channel request ServerCommand
+             * @param payload packet data
+             * @param index of start of command buffer
+             * @param size number of bytes in command buffer
+             * @param[out] status to be returned in MoteCommand answer
+             * @return LORA_OK
+             */
+            virtual uint8_t HandlePingSlotChannelReq(const uint8_t* payload, uint8_t index, uint8_t size, uint8_t& status);
+
+            /**
+             * Callback to for beacon frequency request ServerCommand
+             * @param payload packet data
+             * @param index of start of command buffer
+             * @param size number of bytes in command buffer
+             * @param[out] status to be returned in MoteCommand answer
+             * @return LORA_OK
+             */
+            virtual uint8_t HandleBeaconFrequencyReq(const uint8_t* payload, uint8_t index, uint8_t size, uint8_t& status);
+
+            /**
+             * Callback to for adaptive datarate ServerCommand
+             * @param payload packet data
+             * @param index of start of command buffer
+             * @param size number of bytes in command buffer
+             * @param[out] status to be returned in MoteCommand answer
+             * @return LORA_OK
+             */
+            virtual uint8_t HandleAdrCommand(const uint8_t* payload, uint8_t index, uint8_t size, uint8_t& status);
+
+            /**
+             * Validate the configuration after multiple ADR commands have been applied
+             * @return status to be returned in MoteCommand answer
+             */
+            virtual uint8_t ValidateAdrConfiguration();
+
+            /**
+             * Update duty cycle with at given frequency and time on air
+             * @param freq frequency
+             * @param time_on_air_ms tx time on air
+             */
+            virtual void UpdateDutyCycle(uint32_t freq, uint32_t time_on_air_ms);
+
+            /**
+             * Get the time the radio must be off air to comply with regulations
+             * Time to wait may be dependent on duty-cycle restrictions per channel
+             * Or duty-cycle of join requests if OTAA is being attempted
+             * @return ms of time to wait for next tx opportunity
+             */
+            virtual uint32_t GetTimeOffAir();
+
+            /**
+             * Get the channels in use by current channel plan
+             * @return channel frequencies
+             */
+            virtual std::vector<uint32_t> GetChannels();
+
+            /**
+             * Get the channel datarate ranges in use by current channel plan
+             * @return channel datarate ranges
+             */
+            virtual std::vector<uint8_t> GetChannelRanges();
+
+            /**
+             * Print log message for given rx window
+             * @param wnd 1 or 2
+             */
+            virtual void LogRxWindow(uint8_t wnd);
+
+            /**
+             * Enable the default channels of the channel plan
+             */
+            virtual void EnableDefaultChannels();
+
+            /**
+             * Called when MAC layer doesn't know about a command.
+             * Use to add custom or new mac command handling
+             * @return LORA_OK
+             */
+            virtual uint8_t HandleMacCommand(uint8_t* payload, uint8_t& index);
+
+        protected:
+
+            static const uint8_t IN865_TX_POWERS[11];                    //!< List of available tx powers
+            static const uint8_t IN865_RADIO_POWERS[21];                 //!< List of calibrated tx powers
+            static const uint8_t IN865_MAX_PAYLOAD_SIZE[];              //!< List of max payload sizes for each datarate
+            static const uint8_t IN865_MAX_PAYLOAD_SIZE_REPEATER[];     //!< List of repeater compatible max payload sizes for each datarate
+    };
+}
+
+#endif //__CHANNEL_PLAN_IN865_H__