MultiTech / libxDot-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 libxDot-dev-mbed5-deprecated by MultiTech

The Connect example can be used as a starting point for an xDot application.

Import programmDot_LoRa_Connect_Example_CUSTOM_AS923

Example configuration of frequencies and datarates for AS923 channel plan.

Last commit 07 Mar 2017 by MultiTech

Change the libmDot-Custom library to libxDot-Custom after importing the above example.

Change the platform for the project to xDot in upper right corner of the compiler page.

Ensure the mbed-os version matches the with the library commit.

Currently the AT Firmware cannot be built online for the xDot.

Creating new channel plans

Copy EU868 or US915 custom channel plan as a starting point

Import librarymDot_Channel_Plans

Channel plans to enable libmDot-Custom

Last commit 07 Feb 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_KR920.h@23:17a25e16ccf1, 2016-10-31 (annotated)

Committer:
jreiss
Date:
Mon Oct 31 14:51:55 2016 +0000
Revision:
23:17a25e16ccf1
update to mbed-os 5.2.1

Who changed what in which revision?

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