1 /*! 2 * \file RegionUS915.h 3 * 4 * \brief Region definition for US915 5 * 6 * \copyright Revised BSD License, see section \ref LICENSE. 7 * 8 * \code 9 * ______ _ 10 * / _____) _ | | 11 * ( (____ _____ ____ _| |_ _____ ____| |__ 12 * \____ \| ___ | (_ _) ___ |/ ___) _ \ 13 * _____) ) ____| | | || |_| ____( (___| | | | 14 * (______/|_____)_|_|_| \__)_____)\____)_| |_| 15 * (C)2013-2017 Semtech 16 * 17 * ___ _____ _ ___ _ _____ ___ ___ ___ ___ 18 * / __|_ _/_\ / __| |/ / __/ _ \| _ \/ __| __| 19 * \__ \ | |/ _ \ (__| ' <| _| (_) | / (__| _| 20 * |___/ |_/_/ \_\___|_|\_\_| \___/|_|_\\___|___| 21 * embedded.connectivity.solutions=============== 22 * 23 * \endcode 24 * 25 * \author Miguel Luis ( Semtech ) 26 * 27 * \author Gregory Cristian ( Semtech ) 28 * 29 * \author Daniel Jaeckle ( STACKFORCE ) 30 * 31 * \author Johannes Bruder ( STACKFORCE ) 32 * 33 * \defgroup REGIONUS915 Region US915 34 * Implementation according to LoRaWAN Specification v1.0.2. 35 * \{ 36 */ 37 #ifndef __REGION_US915_H__ 38 #define __REGION_US915_H__ 39 40 #ifdef __cplusplus 41 extern "C" 42 { 43 #endif 44 45 #include "region/Region.h" 46 47 /*! 48 * LoRaMac maximum number of channels 49 */ 50 #define US915_MAX_NB_CHANNELS 72 51 52 /*! 53 * Minimal datarate that can be used by the node 54 */ 55 #define US915_TX_MIN_DATARATE DR_0 56 57 /*! 58 * Maximal datarate that can be used by the node 59 */ 60 #define US915_TX_MAX_DATARATE DR_4 61 62 /*! 63 * Minimal datarate that can be used by the node 64 */ 65 #define US915_RX_MIN_DATARATE DR_8 66 67 /*! 68 * Maximal datarate that can be used by the node 69 */ 70 #define US915_RX_MAX_DATARATE DR_13 71 72 /*! 73 * Default datarate used by the node 74 */ 75 #define US915_DEFAULT_DATARATE DR_0 76 77 /*! 78 * Minimal Rx1 receive datarate offset 79 */ 80 #define US915_MIN_RX1_DR_OFFSET 0 81 82 /*! 83 * Maximal Rx1 receive datarate offset 84 */ 85 #define US915_MAX_RX1_DR_OFFSET 3 86 87 /*! 88 * Minimal Tx output power that can be used by the node 89 */ 90 #define US915_MIN_TX_POWER TX_POWER_14 91 92 /*! 93 * Maximal Tx output power that can be used by the node 94 */ 95 #define US915_MAX_TX_POWER TX_POWER_0 96 97 /*! 98 * Default Tx output power used by the node 99 */ 100 #define US915_DEFAULT_TX_POWER TX_POWER_0 101 102 /*! 103 * Default Max ERP 104 */ 105 #define US915_DEFAULT_MAX_ERP 30.0f 106 107 /*! 108 * Enabled or disabled the duty cycle 109 */ 110 #define US915_DUTY_CYCLE_ENABLED 0 111 112 /*! 113 * Maximum RX window duration 114 */ 115 #define US915_MAX_RX_WINDOW 3000 116 117 /*! 118 * Second reception window channel frequency definition. 119 */ 120 #define US915_RX_WND_2_FREQ 923300000 121 122 /*! 123 * Second reception window channel datarate definition. 124 */ 125 #define US915_RX_WND_2_DR DR_8 126 127 /*! 128 * Default uplink dwell time configuration 129 */ 130 #define US915_DEFAULT_UPLINK_DWELL_TIME 0 131 132 /* 133 * CLASS B 134 */ 135 /*! 136 * Beacon frequency 137 */ 138 #define US915_BEACON_CHANNEL_FREQ 923300000 139 140 /*! 141 * Beacon frequency channel stepwidth 142 */ 143 #define US915_BEACON_CHANNEL_STEPWIDTH 600000 144 145 /*! 146 * Ping slot channel frequency 147 */ 148 #define US915_PING_SLOT_CHANNEL_FREQ 923300000 149 150 /*! 151 * Number of possible beacon channels 152 */ 153 #define US915_BEACON_NB_CHANNELS 8 154 155 /*! 156 * Payload size of a beacon frame 157 */ 158 #define US915_BEACON_SIZE 23 159 160 /*! 161 * Size of RFU 1 field 162 */ 163 #define US915_RFU1_SIZE 4 164 165 /*! 166 * Size of RFU 2 field 167 */ 168 #define US915_RFU2_SIZE 3 169 170 /*! 171 * Datarate of the beacon channel 172 */ 173 #define US915_BEACON_CHANNEL_DR DR_8 174 175 /*! 176 * Bandwith of the beacon channel 177 */ 178 #define US915_BEACON_CHANNEL_BW 2 179 180 /*! 181 * Ping slot channel datarate 182 */ 183 #define US915_PING_SLOT_CHANNEL_DR DR_8 184 185 /*! 186 * LoRaMac maximum number of bands 187 */ 188 #define US915_MAX_NB_BANDS 1 189 190 /*! 191 * Band 0 definition 192 * Band = { DutyCycle, TxMaxPower, LastBandUpdateTime, LastMaxCreditAssignTime, TimeCredits, MaxTimeCredits, ReadyForTransmission } 193 */ 194 #define US915_BAND0 { 1, US915_MAX_TX_POWER, 0, 0, 0, 0, 0 } // 100.0 % 195 196 /*! 197 * Defines the first channel for RX window 1 for US band 198 */ 199 #define US915_FIRST_RX1_CHANNEL ( (uint32_t) 923300000 ) 200 201 /*! 202 * Defines the last channel for RX window 1 for US band 203 */ 204 #define US915_LAST_RX1_CHANNEL ( (uint32_t) 927500000 ) 205 206 /*! 207 * Defines the step width of the channels for RX window 1 208 */ 209 #define US915_STEPWIDTH_RX1_CHANNEL ( (uint32_t) 600000 ) 210 211 /*! 212 * Data rates table definition 213 */ 214 static const uint8_t DataratesUS915[] = { 10, 9, 8, 7, 8, 0, 0, 0, 12, 11, 10, 9, 8, 7, 0, 0 }; 215 216 /*! 217 * Bandwidths table definition in Hz 218 */ 219 static const uint32_t BandwidthsUS915[] = { 125000, 125000, 125000, 125000, 500000, 0, 0, 0, 500000, 500000, 500000, 500000, 500000, 500000, 0, 0 }; 220 221 /*! 222 * Up/Down link data rates offset definition 223 */ 224 static const int8_t DatarateOffsetsUS915[5][4] = 225 { 226 { DR_10, DR_9 , DR_8 , DR_8 }, // DR_0 227 { DR_11, DR_10, DR_9 , DR_8 }, // DR_1 228 { DR_12, DR_11, DR_10, DR_9 }, // DR_2 229 { DR_13, DR_12, DR_11, DR_10 }, // DR_3 230 { DR_13, DR_13, DR_12, DR_11 }, // DR_4 231 }; 232 233 /*! 234 * Maximum payload with respect to the datarate index. 235 */ 236 static const uint8_t MaxPayloadOfDatarateUS915[] = { 11, 53, 125, 242, 242, 0, 0, 0, 53, 129, 242, 242, 242, 242, 0, 0 }; 237 238 /*! 239 * \brief The function gets a value of a specific phy attribute. 240 * 241 * \param [IN] getPhy Pointer to the function parameters. 242 * 243 * \retval Returns a structure containing the PHY parameter. 244 */ 245 PhyParam_t RegionUS915GetPhyParam( GetPhyParams_t* getPhy ); 246 247 /*! 248 * \brief Updates the last TX done parameters of the current channel. 249 * 250 * \param [IN] txDone Pointer to the function parameters. 251 */ 252 void RegionUS915SetBandTxDone( SetBandTxDoneParams_t* txDone ); 253 254 /*! 255 * \brief Initializes the channels masks and the channels. 256 * 257 * \param [IN] type Sets the initialization type. 258 */ 259 void RegionUS915InitDefaults( InitDefaultsParams_t* params ); 260 261 /*! 262 * \brief Verifies a parameter. 263 * 264 * \param [IN] verify Pointer to the function parameters. 265 * 266 * \param [IN] type Sets the initialization type. 267 * 268 * \retval Returns true, if the parameter is valid. 269 */ 270 bool RegionUS915Verify( VerifyParams_t* verify, PhyAttribute_t phyAttribute ); 271 272 /*! 273 * \brief The function parses the input buffer and sets up the channels of the 274 * CF list. 275 * 276 * \param [IN] applyCFList Pointer to the function parameters. 277 */ 278 void RegionUS915ApplyCFList( ApplyCFListParams_t* applyCFList ); 279 280 /*! 281 * \brief Sets a channels mask. 282 * 283 * \param [IN] chanMaskSet Pointer to the function parameters. 284 * 285 * \retval Returns true, if the channels mask could be set. 286 */ 287 bool RegionUS915ChanMaskSet( ChanMaskSetParams_t* chanMaskSet ); 288 289 /*! 290 * Computes the Rx window timeout and offset. 291 * 292 * \param [IN] datarate Rx window datarate index to be used 293 * 294 * \param [IN] minRxSymbols Minimum required number of symbols to detect an Rx frame. 295 * 296 * \param [IN] rxError System maximum timing error of the receiver. In milliseconds 297 * The receiver will turn on in a [-rxError : +rxError] ms 298 * interval around RxOffset 299 * 300 * \param [OUT]rxConfigParams Returns updated WindowTimeout and WindowOffset fields. 301 */ 302 void RegionUS915ComputeRxWindowParameters( int8_t datarate, uint8_t minRxSymbols, uint32_t rxError, RxConfigParams_t *rxConfigParams ); 303 304 /*! 305 * \brief Configuration of the RX windows. 306 * 307 * \param [IN] rxConfig Pointer to the function parameters. 308 * 309 * \param [OUT] datarate The datarate index which was set. 310 * 311 * \retval Returns true, if the configuration was applied successfully. 312 */ 313 bool RegionUS915RxConfig( RxConfigParams_t* rxConfig, int8_t* datarate ); 314 315 /*! 316 * \brief TX configuration. 317 * 318 * \param [IN] txConfig Pointer to the function parameters. 319 * 320 * \param [OUT] txPower The tx power index which was set. 321 * 322 * \param [OUT] txTimeOnAir The time-on-air of the frame. 323 * 324 * \retval Returns true, if the configuration was applied successfully. 325 */ 326 bool RegionUS915TxConfig( TxConfigParams_t* txConfig, int8_t* txPower, TimerTime_t* txTimeOnAir ); 327 328 /*! 329 * \brief The function processes a Link ADR Request. 330 * 331 * \param [IN] linkAdrReq Pointer to the function parameters. 332 * 333 * \retval Returns the status of the operation, according to the LoRaMAC specification. 334 */ 335 uint8_t RegionUS915LinkAdrReq( LinkAdrReqParams_t* linkAdrReq, int8_t* drOut, int8_t* txPowOut, uint8_t* nbRepOut, uint8_t* nbBytesParsed ); 336 337 /*! 338 * \brief The function processes a RX Parameter Setup Request. 339 * 340 * \param [IN] rxParamSetupReq Pointer to the function parameters. 341 * 342 * \retval Returns the status of the operation, according to the LoRaMAC specification. 343 */ 344 uint8_t RegionUS915RxParamSetupReq( RxParamSetupReqParams_t* rxParamSetupReq ); 345 346 /*! 347 * \brief The function processes a Channel Request. 348 * 349 * \param [IN] newChannelReq Pointer to the function parameters. 350 * 351 * \retval Returns the status of the operation, according to the LoRaMAC specification. 352 */ 353 int8_t RegionUS915NewChannelReq( NewChannelReqParams_t* newChannelReq ); 354 355 /*! 356 * \brief The function processes a TX ParamSetup Request. 357 * 358 * \param [IN] txParamSetupReq Pointer to the function parameters. 359 * 360 * \retval Returns the status of the operation, according to the LoRaMAC specification. 361 * Returns -1, if the functionality is not implemented. In this case, the end node 362 * shall not process the command. 363 */ 364 int8_t RegionUS915TxParamSetupReq( TxParamSetupReqParams_t* txParamSetupReq ); 365 366 /*! 367 * \brief The function processes a DlChannel Request. 368 * 369 * \param [IN] dlChannelReq Pointer to the function parameters. 370 * 371 * \retval Returns the status of the operation, according to the LoRaMAC specification. 372 */ 373 int8_t RegionUS915DlChannelReq( DlChannelReqParams_t* dlChannelReq ); 374 375 /*! 376 * \brief Alternates the datarate of the channel for the join request. 377 * 378 * \param [IN] currentDr Current datarate. 379 * 380 * \param [IN] type Alternation type. 381 * 382 * \retval Datarate to apply. 383 */ 384 int8_t RegionUS915AlternateDr( int8_t currentDr, AlternateDrType_t type ); 385 386 /*! 387 * \brief Searches and set the next random available channel 388 * 389 * \param [OUT] channel Next channel to use for TX. 390 * 391 * \param [OUT] time Time to wait for the next transmission according to the duty 392 * cycle. 393 * 394 * \param [OUT] aggregatedTimeOff Updates the aggregated time off. 395 * 396 * \retval Function status [1: OK, 0: Unable to find a channel on the current datarate] 397 */ 398 LoRaMacStatus_t RegionUS915NextChannel( NextChanParams_t* nextChanParams, uint8_t* channel, TimerTime_t* time, TimerTime_t* aggregatedTimeOff ); 399 400 /*! 401 * \brief Adds a channel. 402 * 403 * \param [IN] channelAdd Pointer to the function parameters. 404 * 405 * \retval Status of the operation. 406 */ 407 LoRaMacStatus_t RegionUS915ChannelAdd( ChannelAddParams_t* channelAdd ); 408 409 /*! 410 * \brief Removes a channel. 411 * 412 * \param [IN] channelRemove Pointer to the function parameters. 413 * 414 * \retval Returns true, if the channel was removed successfully. 415 */ 416 bool RegionUS915ChannelsRemove( ChannelRemoveParams_t* channelRemove ); 417 418 /*! 419 * \brief Computes new datarate according to the given offset 420 * 421 * \param [IN] downlinkDwellTime Downlink dwell time configuration. 0: No limit, 1: 400ms 422 * 423 * \param [IN] dr Current datarate 424 * 425 * \param [IN] drOffset Offset to be applied 426 * 427 * \retval newDr Computed datarate. 428 */ 429 uint8_t RegionUS915ApplyDrOffset( uint8_t downlinkDwellTime, int8_t dr, int8_t drOffset ); 430 431 /*! 432 * \brief Sets the radio into beacon reception mode 433 * 434 * \param [IN] rxBeaconSetup Pointer to the function parameters 435 */ 436 void RegionUS915RxBeaconSetup( RxBeaconSetup_t* rxBeaconSetup, uint8_t* outDr ); 437 438 /*! \} defgroup REGIONUS915 */ 439 440 #ifdef __cplusplus 441 } 442 #endif 443 444 #endif // __REGION_US915_H__ 445
