MultiTech / libmDot-Custom

Important changes to repositories hosted on mbed.com

Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.

To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.

It is also possible to export all your personal repositories from the account settings page.

Fork of libmDot-custom by Jason Reiss

Information

Library has been updated to mbed 5.x

The LoRaWAN Certification test mode implementation is built-in to libmDot code. When a start test mode packet is received the library will not return until test mode has ended.

Warning

This library is currently in BETA release. Unresolved issues may be experienced. Software is provided as is with no expectation of support of bug fixes in the future. Please report issues found through the mbed website or directly to support.multitech.com.

Changing of channel plan parameters may cause the device to no longer respect local RF regulations. Please use caution and respect your local regulations.

In AT Command Firmware remove line 803.

CommandTerminal/CommandTerminal.cpp

        delete[] info->RxBuffer;

Likewise, if your application is handling events from the library asynchronously.

Creating new channel plans

Copy EU868 or US915 custom channel plan as a starting point

Import programmDot_AT_firmware_CUSTOM

AT Firmware with custom channel plan support

Last commit 23 Mar 2017 by MultiTech

EU868 provides a framework for a DYNAMIC channel plan with duty-cycle limitations

US915 provides a framework for a FIXED channel plan

RADIO_POWERS are measured output in dBm for each radio tx power setting.

Additional MAC Commands can be implemented by overriding the HandleMacCommand function.

Steps

  1. Setup datarates, duty-cycle bands and channels in ChannelPlan_* constructor
  2. Modify GetJoinDatarate and CalculateJoinBackoff to change join datarates and backoff
  3. Customize HandleJoinAccept datarates
  4. Use GetRxWindow(int) to define how the device open Rx window 1 and 2
  5. GetNextChannel will pick a channel from the enabled channel at the current datarate before each TX

ChannelPlans/CustomChannelPlan_US915.h@30:ea6818a83412, 2017-03-23 (annotated)

Committer:
jreiss
Date:
Thu Mar 23 20:40:04 2017 +0000
Revision:
30:ea6818a83412
Add US915 and KR920 headers

Who changed what in which revision?

UserRevisionLine numberNew contents of line
jreiss 30:ea6818a83412 1 /** __ ___ ____ _ ______ __ ____ __ ____
jreiss 30:ea6818a83412 2 * / |/ /_ __/ / /_(_)__/_ __/__ ____/ / / __/_ _____ / /____ __ _ ___ / _/__ ____
jreiss 30:ea6818a83412 3 * / /|_/ / // / / __/ /___// / / -_) __/ _ \ _\ \/ // (_-</ __/ -_) ' \(_-< _/ // _ \/ __/ __
jreiss 30:ea6818a83412 4 * /_/ /_/\_,_/_/\__/_/ /_/ \__/\__/_//_/ /___/\_, /___/\__/\__/_/_/_/___/ /___/_//_/\__/ /_/
jreiss 30:ea6818a83412 5 * Copyright (C) 2015 by Multi-Tech Systems /___/
jreiss 30:ea6818a83412 6 *
jreiss 30:ea6818a83412 7 *
jreiss 30:ea6818a83412 8 * @author Jason Reiss
jreiss 30:ea6818a83412 9 * @date 10-31-2015
jreiss 30:ea6818a83412 10 * @brief lora::ChannelPlan provides an interface for LoRaWAN channel schemes
jreiss 30:ea6818a83412 11 *
jreiss 30:ea6818a83412 12 * @details
jreiss 30:ea6818a83412 13 *
jreiss 30:ea6818a83412 14 */
jreiss 30:ea6818a83412 15
jreiss 30:ea6818a83412 16 #ifndef __CUSTOM_CHANNEL_PLAN_US915_H__
jreiss 30:ea6818a83412 17 #define __CUSTOM_CHANNEL_PLAN_US915_H__
jreiss 30:ea6818a83412 18
jreiss 30:ea6818a83412 19 #include "Lora.h"
jreiss 30:ea6818a83412 20 #include "SxRadio.h"
jreiss 30:ea6818a83412 21 #include "ChannelPlan.h"
jreiss 30:ea6818a83412 22 #include <vector>
jreiss 30:ea6818a83412 23
jreiss 30:ea6818a83412 24 namespace lora {
jreiss 30:ea6818a83412 25
jreiss 30:ea6818a83412 26 class CustomChannelPlan_US915 : public lora::ChannelPlan {
jreiss 30:ea6818a83412 27 public:
jreiss 30:ea6818a83412 28
jreiss 30:ea6818a83412 29 /**
jreiss 30:ea6818a83412 30 * ChannelPlan constructor
jreiss 30:ea6818a83412 31 * @param radio SxRadio object used to set Tx/Rx config
jreiss 30:ea6818a83412 32 * @param settings Settings object
jreiss 30:ea6818a83412 33 */
jreiss 30:ea6818a83412 34 CustomChannelPlan_US915(SxRadio& radio, Settings& settings);
jreiss 30:ea6818a83412 35
jreiss 30:ea6818a83412 36 /**
jreiss 30:ea6818a83412 37 * ChannelPlan destructor
jreiss 30:ea6818a83412 38 */
jreiss 30:ea6818a83412 39 virtual ~CustomChannelPlan_US915();
jreiss 30:ea6818a83412 40
jreiss 30:ea6818a83412 41 /**
jreiss 30:ea6818a83412 42 * Initialize channels, datarates and duty cycle bands according to current channel plan in settings
jreiss 30:ea6818a83412 43 */
jreiss 30:ea6818a83412 44 virtual void Init();
jreiss 30:ea6818a83412 45
jreiss 30:ea6818a83412 46 /**
jreiss 30:ea6818a83412 47 * Get the next channel to use to transmit
jreiss 30:ea6818a83412 48 * @return LORA_OK if channel was found
jreiss 30:ea6818a83412 49 * @return LORA_NO_CHANS_ENABLED
jreiss 30:ea6818a83412 50 */
jreiss 30:ea6818a83412 51 virtual uint8_t GetNextChannel();
jreiss 30:ea6818a83412 52
jreiss 30:ea6818a83412 53 /**
jreiss 30:ea6818a83412 54 * Set the number of channels in the plan
jreiss 30:ea6818a83412 55 */
jreiss 30:ea6818a83412 56 virtual void SetNumberOfChannels(uint8_t channels, bool resize = true);
jreiss 30:ea6818a83412 57
jreiss 30:ea6818a83412 58 /**
jreiss 30:ea6818a83412 59 * Check if channel is enabled
jreiss 30:ea6818a83412 60 * @return true if enabled
jreiss 30:ea6818a83412 61 */
jreiss 30:ea6818a83412 62 virtual bool IsChannelEnabled(uint8_t channel);
jreiss 30:ea6818a83412 63
jreiss 30:ea6818a83412 64
jreiss 30:ea6818a83412 65 /**
jreiss 30:ea6818a83412 66 * Add a channel to the ChannelPlan
jreiss 30:ea6818a83412 67 * @param index of channel, use -1 to add to end
jreiss 30:ea6818a83412 68 * @param channel settings to add
jreiss 30:ea6818a83412 69 */
jreiss 30:ea6818a83412 70 virtual uint8_t AddChannel(int8_t index, Channel channel);
jreiss 30:ea6818a83412 71
jreiss 30:ea6818a83412 72 /**
jreiss 30:ea6818a83412 73 * Get channel at index
jreiss 30:ea6818a83412 74 * @return Channel
jreiss 30:ea6818a83412 75 */
jreiss 30:ea6818a83412 76 virtual Channel GetChannel(int8_t index);
jreiss 30:ea6818a83412 77
jreiss 30:ea6818a83412 78 /**
jreiss 30:ea6818a83412 79 * Get rx window settings for requested window
jreiss 30:ea6818a83412 80 * RX_1, RX_2, RX_BEACON, RX_SLOT
jreiss 30:ea6818a83412 81 * @param window
jreiss 30:ea6818a83412 82 * @return RxWindow
jreiss 30:ea6818a83412 83 */
jreiss 30:ea6818a83412 84 virtual RxWindow GetRxWindow(uint8_t window);
jreiss 30:ea6818a83412 85
jreiss 30:ea6818a83412 86 /**
jreiss 30:ea6818a83412 87 * Get datarate to use on the join request
jreiss 30:ea6818a83412 88 * @return datarate index
jreiss 30:ea6818a83412 89 */
jreiss 30:ea6818a83412 90 virtual uint8_t GetJoinDatarate();
jreiss 30:ea6818a83412 91
jreiss 30:ea6818a83412 92 /**
jreiss 30:ea6818a83412 93 * Calculate the next time a join request is possible
jreiss 30:ea6818a83412 94 * @param size of join frame
jreiss 30:ea6818a83412 95 * @returns LORA_OK
jreiss 30:ea6818a83412 96 */
jreiss 30:ea6818a83412 97 virtual uint8_t CalculateJoinBackoff(uint8_t size);
jreiss 30:ea6818a83412 98
jreiss 30:ea6818a83412 99 /**
jreiss 30:ea6818a83412 100 * Set the datarate offset used for first receive window
jreiss 30:ea6818a83412 101 * @param offset
jreiss 30:ea6818a83412 102 * @return LORA_OK
jreiss 30:ea6818a83412 103 */
jreiss 30:ea6818a83412 104 virtual uint8_t SetRx1Offset(uint8_t offset);
jreiss 30:ea6818a83412 105
jreiss 30:ea6818a83412 106 /**
jreiss 30:ea6818a83412 107 * Set the frequency for second receive window
jreiss 30:ea6818a83412 108 * @param freq
jreiss 30:ea6818a83412 109 * @return LORA_OK
jreiss 30:ea6818a83412 110 */
jreiss 30:ea6818a83412 111 virtual uint8_t SetRx2Frequency(uint32_t freq);
jreiss 30:ea6818a83412 112
jreiss 30:ea6818a83412 113 /**
jreiss 30:ea6818a83412 114 * Set the datarate index used for second receive window
jreiss 30:ea6818a83412 115 * @param index
jreiss 30:ea6818a83412 116 * @return LORA_OK
jreiss 30:ea6818a83412 117 */
jreiss 30:ea6818a83412 118 virtual uint8_t SetRx2DatarateIndex(uint8_t index);
jreiss 30:ea6818a83412 119
jreiss 30:ea6818a83412 120 /**
jreiss 30:ea6818a83412 121 * Get next channel and set the SxRadio tx config with current settings
jreiss 30:ea6818a83412 122 * @return LORA_OK
jreiss 30:ea6818a83412 123 */
jreiss 30:ea6818a83412 124 virtual uint8_t SetTxConfig();
jreiss 30:ea6818a83412 125
jreiss 30:ea6818a83412 126 /**
jreiss 30:ea6818a83412 127 * Set the SxRadio rx config provided window
jreiss 30:ea6818a83412 128 * @param window to be opened
jreiss 30:ea6818a83412 129 * @param continuous keep window open
jreiss 30:ea6818a83412 130 * @return LORA_OK
jreiss 30:ea6818a83412 131 */
jreiss 30:ea6818a83412 132 virtual uint8_t SetRxConfig(uint8_t window, bool continuous);
jreiss 30:ea6818a83412 133
jreiss 30:ea6818a83412 134 /**
jreiss 30:ea6818a83412 135 * Set channel group if supported by plan
jreiss 30:ea6818a83412 136 * @param group
jreiss 30:ea6818a83412 137 * @return LORA_OK
jreiss 30:ea6818a83412 138 */
jreiss 30:ea6818a83412 139 virtual uint8_t SetChannelGroup(uint8_t group);
jreiss 30:ea6818a83412 140
jreiss 30:ea6818a83412 141 /**
jreiss 30:ea6818a83412 142 * Callback for Join Accept packet to load optional channels
jreiss 30:ea6818a83412 143 * @return LORA_OK
jreiss 30:ea6818a83412 144 */
jreiss 30:ea6818a83412 145 virtual uint8_t HandleJoinAccept(const uint8_t* buffer, uint8_t size);
jreiss 30:ea6818a83412 146
jreiss 30:ea6818a83412 147 /**
jreiss 30:ea6818a83412 148 * Callback to for rx parameter setup ServerCommand
jreiss 30:ea6818a83412 149 * @param payload packet data
jreiss 30:ea6818a83412 150 * @param index of start of command buffer
jreiss 30:ea6818a83412 151 * @param size number of bytes in command buffer
jreiss 30:ea6818a83412 152 * @param[out] status to be returned in MoteCommand answer
jreiss 30:ea6818a83412 153 * @return LORA_OK
jreiss 30:ea6818a83412 154 */
jreiss 30:ea6818a83412 155 virtual uint8_t HandleRxParamSetup(const uint8_t* payload, uint8_t index, uint8_t size, uint8_t& status);
jreiss 30:ea6818a83412 156
jreiss 30:ea6818a83412 157 /**
jreiss 30:ea6818a83412 158 * Callback to for new channel ServerCommand
jreiss 30:ea6818a83412 159 * @param payload packet data
jreiss 30:ea6818a83412 160 * @param index of start of command buffer
jreiss 30:ea6818a83412 161 * @param size number of bytes in command buffer
jreiss 30:ea6818a83412 162 * @param[out] status to be returned in MoteCommand answer
jreiss 30:ea6818a83412 163 * @return LORA_OK
jreiss 30:ea6818a83412 164 */
jreiss 30:ea6818a83412 165 virtual uint8_t HandleNewChannel(const uint8_t* payload, uint8_t index, uint8_t size, uint8_t& status);
jreiss 30:ea6818a83412 166
jreiss 30:ea6818a83412 167 /**
jreiss 30:ea6818a83412 168 * Callback to for ping slot channel request ServerCommand
jreiss 30:ea6818a83412 169 * @param payload packet data
jreiss 30:ea6818a83412 170 * @param index of start of command buffer
jreiss 30:ea6818a83412 171 * @param size number of bytes in command buffer
jreiss 30:ea6818a83412 172 * @param[out] status to be returned in MoteCommand answer
jreiss 30:ea6818a83412 173 * @return LORA_OK
jreiss 30:ea6818a83412 174 */
jreiss 30:ea6818a83412 175 virtual uint8_t HandlePingSlotChannelReq(const uint8_t* payload, uint8_t index, uint8_t size, uint8_t& status);
jreiss 30:ea6818a83412 176
jreiss 30:ea6818a83412 177 /**
jreiss 30:ea6818a83412 178 * Callback to for beacon frequency request ServerCommand
jreiss 30:ea6818a83412 179 * @param payload packet data
jreiss 30:ea6818a83412 180 * @param index of start of command buffer
jreiss 30:ea6818a83412 181 * @param size number of bytes in command buffer
jreiss 30:ea6818a83412 182 * @param[out] status to be returned in MoteCommand answer
jreiss 30:ea6818a83412 183 * @return LORA_OK
jreiss 30:ea6818a83412 184 */
jreiss 30:ea6818a83412 185 virtual uint8_t HandleBeaconFrequencyReq(const uint8_t* payload, uint8_t index, uint8_t size, uint8_t& status);
jreiss 30:ea6818a83412 186
jreiss 30:ea6818a83412 187 /**
jreiss 30:ea6818a83412 188 * Callback to for adaptive datarate ServerCommand
jreiss 30:ea6818a83412 189 * @param payload packet data
jreiss 30:ea6818a83412 190 * @param index of start of command buffer
jreiss 30:ea6818a83412 191 * @param size number of bytes in command buffer
jreiss 30:ea6818a83412 192 * @param[out] status to be returned in MoteCommand answer
jreiss 30:ea6818a83412 193 * @return LORA_OK
jreiss 30:ea6818a83412 194 */
jreiss 30:ea6818a83412 195 virtual uint8_t HandleAdrCommand(const uint8_t* payload, uint8_t index, uint8_t size, uint8_t& status);
jreiss 30:ea6818a83412 196
jreiss 30:ea6818a83412 197 /**
jreiss 30:ea6818a83412 198 * Get the time the radio must be off air to comply with regulations
jreiss 30:ea6818a83412 199 * Time to wait may be dependent on duty-cycle restrictions per channel
jreiss 30:ea6818a83412 200 * Or duty-cycle of join requests if OTAA is being attempted
jreiss 30:ea6818a83412 201 * @return ms of time to wait for next tx opportunity
jreiss 30:ea6818a83412 202 */
jreiss 30:ea6818a83412 203 virtual uint32_t GetTimeOffAir();
jreiss 30:ea6818a83412 204
jreiss 30:ea6818a83412 205 /**
jreiss 30:ea6818a83412 206 * Get the channels in use by current channel plan
jreiss 30:ea6818a83412 207 * @return channel frequencies
jreiss 30:ea6818a83412 208 */
jreiss 30:ea6818a83412 209 virtual std::vector<uint32_t> GetChannels();
jreiss 30:ea6818a83412 210
jreiss 30:ea6818a83412 211 /**
jreiss 30:ea6818a83412 212 * Get the channel datarate ranges in use by current channel plan
jreiss 30:ea6818a83412 213 * @return channel datarate ranges
jreiss 30:ea6818a83412 214 */
jreiss 30:ea6818a83412 215 virtual std::vector<uint8_t> GetChannelRanges();
jreiss 30:ea6818a83412 216
jreiss 30:ea6818a83412 217
jreiss 30:ea6818a83412 218 /**
jreiss 30:ea6818a83412 219 * Print log message for given rx window
jreiss 30:ea6818a83412 220 * @param wnd 1 or 2
jreiss 30:ea6818a83412 221 */
jreiss 30:ea6818a83412 222 virtual void LogRxWindow(uint8_t wnd);
jreiss 30:ea6818a83412 223
jreiss 30:ea6818a83412 224 /**
jreiss 30:ea6818a83412 225 * Enable the default channels of the channel plan
jreiss 30:ea6818a83412 226 */
jreiss 30:ea6818a83412 227 virtual void EnableDefaultChannels();
jreiss 30:ea6818a83412 228
jreiss 30:ea6818a83412 229 virtual uint8_t GetMinDatarate();
jreiss 30:ea6818a83412 230
jreiss 30:ea6818a83412 231 virtual uint8_t GetMaxDatarate();
jreiss 30:ea6818a83412 232
jreiss 30:ea6818a83412 233 protected:
jreiss 30:ea6818a83412 234
jreiss 30:ea6818a83412 235 static const uint8_t US915_TX_POWERS[11]; //!< List of available tx powers
jreiss 30:ea6818a83412 236 static const uint8_t US915_RADIO_POWERS[21]; //!< List of calibrated tx powers
jreiss 30:ea6818a83412 237 static const uint8_t US915_MAX_PAYLOAD_SIZE[]; //!< List of max payload sizes for each datarate
jreiss 30:ea6818a83412 238 static const uint8_t US915_MAX_PAYLOAD_SIZE_REPEATER[]; //!< List of repeater compatible max payload sizes for each datarate
jreiss 30:ea6818a83412 239
jreiss 30:ea6818a83412 240 };
jreiss 30:ea6818a83412 241 }
jreiss 30:ea6818a83412 242
jreiss 30:ea6818a83412 243 #endif // __CUSTOM_CHANNEL_PLAN_US915_H__
jreiss 30:ea6818a83412 244