1 /*! 2 * \file RegionAS923.h 3 * 4 * \brief Region definition for AS923 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 REGIONAS923 Region AS923 34 * Implementation according to LoRaWAN Specification v1.0.2. 35 * \{ 36 */ 37 #ifndef __REGION_AS923_H__ 38 #define __REGION_AS923_H__ 39 40 #ifdef __cplusplus 41 extern "C" 42 { 43 #endif 44 45 #include "region/Region.h" 46 47 48 /*! 49 * Channel plan group AS923-1 50 * AS923_FREQ_OFFSET = 0 51 */ 52 #define CHANNEL_PLAN_GROUP_AS923_1 1 53 54 /*! 55 * Channel plan group AS923-2 56 * AS923_FREQ_OFFSET = -1.8MHz 57 */ 58 #define CHANNEL_PLAN_GROUP_AS923_2 2 59 60 /*! 61 * Channel plan group AS923-3 62 * AS923_FREQ_OFFSET = -6.6MHz 63 */ 64 #define CHANNEL_PLAN_GROUP_AS923_3 3 65 66 /*! 67 * Channel plan group AS923-1 68 * AS923_FREQ_OFFSET = 0 69 */ 70 #define CHANNEL_PLAN_GROUP_AS923_1 1 71 72 /*! 73 * Channel plan group AS923-2 74 * AS923_FREQ_OFFSET = -1.8MHz 75 */ 76 #define CHANNEL_PLAN_GROUP_AS923_2 2 77 78 /*! 79 * Channel plan group AS923-3 80 * AS923_FREQ_OFFSET = -6.6MHz 81 */ 82 #define CHANNEL_PLAN_GROUP_AS923_3 3 83 84 /*! 85 * Channel plan group AS923-1 for Japan 86 * AS923_FREQ_OFFSET = 0 87 */ 88 #define CHANNEL_PLAN_GROUP_AS923_1_JP 4 89 90 /*! 91 * LoRaMac maximum number of channels 92 */ 93 #define AS923_MAX_NB_CHANNELS 16 94 95 /*! 96 * Number of default channels 97 */ 98 #define AS923_NUMB_DEFAULT_CHANNELS 2 99 100 /*! 101 * Number of channels to apply for the CF list 102 */ 103 #define AS923_NUMB_CHANNELS_CF_LIST 5 104 105 /*! 106 * Minimal datarate that can be used by the node 107 */ 108 #define AS923_TX_MIN_DATARATE DR_0 109 110 /*! 111 * Maximal datarate that can be used by the node 112 */ 113 #define AS923_TX_MAX_DATARATE DR_7 114 115 /*! 116 * Minimal datarate that can be used by the node 117 */ 118 #define AS923_RX_MIN_DATARATE DR_0 119 120 /*! 121 * Maximal datarate that can be used by the node 122 */ 123 #define AS923_RX_MAX_DATARATE DR_7 124 125 /*! 126 * Default datarate used by the node 127 */ 128 #define AS923_DEFAULT_DATARATE DR_2 129 130 /*! 131 * The minimum datarate which is used when the 132 * dwell time is limited. 133 */ 134 #define AS923_DWELL_LIMIT_DATARATE DR_2 135 136 /*! 137 * Minimal Rx1 receive datarate offset 138 */ 139 #define AS923_MIN_RX1_DR_OFFSET 0 140 141 /*! 142 * Maximal Rx1 receive datarate offset 143 */ 144 #define AS923_MAX_RX1_DR_OFFSET 7 145 146 /*! 147 * Minimal Tx output power that can be used by the node 148 */ 149 #define AS923_MIN_TX_POWER TX_POWER_7 150 151 /*! 152 * Maximal Tx output power that can be used by the node 153 */ 154 #define AS923_MAX_TX_POWER TX_POWER_0 155 156 /*! 157 * Default Tx output power used by the node 158 */ 159 #define AS923_DEFAULT_TX_POWER TX_POWER_0 160 161 /*! 162 * Default uplink dwell time configuration 163 */ 164 #define AS923_DEFAULT_UPLINK_DWELL_TIME 1 165 166 /*! 167 * Default Max EIRP 168 */ 169 #define AS923_DEFAULT_MAX_EIRP 16.0f 170 171 /*! 172 * Default antenna gain 173 */ 174 #define AS923_DEFAULT_ANTENNA_GAIN 2.15f 175 176 /*! 177 * Enabled or disabled the duty cycle 178 */ 179 #define AS923_DUTY_CYCLE_ENABLED 0 180 181 /*! 182 * Maximum RX window duration 183 */ 184 #define AS923_MAX_RX_WINDOW 3000 185 186 #if ( AS923_DEFAULT_DATARATE > DR_5 ) 187 #error "A default DR higher than DR_5 may lead to connectivity loss." 188 #endif 189 190 /*! 191 * Second reception window channel frequency definition. 192 */ 193 #define AS923_RX_WND_2_FREQ 923200000 194 195 /*! 196 * Second reception window channel datarate definition. 197 */ 198 #define AS923_RX_WND_2_DR DR_2 199 200 /* 201 * CLASS B 202 */ 203 /*! 204 * Beacon frequency 205 */ 206 #define AS923_BEACON_CHANNEL_FREQ 923400000 207 208 /*! 209 * Ping slot channel frequency 210 */ 211 #define AS923_PING_SLOT_CHANNEL_FREQ 923400000 212 213 /*! 214 * Payload size of a beacon frame 215 */ 216 #define AS923_BEACON_SIZE 17 217 218 /*! 219 * Size of RFU 1 field 220 */ 221 #define AS923_RFU1_SIZE 1 222 223 /*! 224 * Size of RFU 2 field 225 */ 226 #define AS923_RFU2_SIZE 0 227 228 /*! 229 * Datarate of the beacon channel 230 */ 231 #define AS923_BEACON_CHANNEL_DR DR_3 232 233 /*! 234 * Bandwith of the beacon channel 235 */ 236 #define AS923_BEACON_CHANNEL_BW 0 237 238 /*! 239 * Ping slot channel datarate 240 */ 241 #define AS923_PING_SLOT_CHANNEL_DR DR_3 242 243 /*! 244 * Maximum number of bands 245 */ 246 #define AS923_MAX_NB_BANDS 1 247 248 /*! 249 * Band 0 definition 250 * Band = { DutyCycle, TxMaxPower, LastBandUpdateTime, LastMaxCreditAssignTime, TimeCredits, MaxTimeCredits, ReadyForTransmission } 251 */ 252 #define AS923_BAND0 { 100, AS923_MAX_TX_POWER, 0, 0, 0, 0, 0 } // 1.0 % 253 254 /*! 255 * LoRaMac default channel 1 256 * Channel = { Frequency [Hz], RX1 Frequency [Hz], { ( ( DrMax << 4 ) | DrMin ) }, Band } 257 */ 258 #define AS923_LC1 { 923200000, 0, { ( ( DR_5 << 4 ) | DR_0 ) }, 0 } 259 260 /*! 261 * LoRaMac default channel 2 262 * Channel = { Frequency [Hz], RX1 Frequency [Hz], { ( ( DrMax << 4 ) | DrMin ) }, Band } 263 */ 264 #define AS923_LC2 { 923400000, 0, { ( ( DR_5 << 4 ) | DR_0 ) }, 0 } 265 266 /*! 267 * LoRaMac channels which are allowed for the join procedure 268 */ 269 #define AS923_JOIN_CHANNELS ( uint16_t )( LC( 1 ) | LC( 2 ) ) 270 271 /*! 272 * RSSI threshold for a free channel [dBm] 273 */ 274 #define AS923_RSSI_FREE_TH -80 275 276 /*! 277 * Specifies the time the node performs a carrier sense 278 */ 279 #define AS923_CARRIER_SENSE_TIME 5 280 281 /*! 282 * Data rates table definition 283 */ 284 static const uint8_t DataratesAS923[] = { 12, 11, 10, 9, 8, 7, 7, 50 }; 285 286 /*! 287 * Bandwidths table definition in Hz 288 */ 289 static const uint32_t BandwidthsAS923[] = { 125000, 125000, 125000, 125000, 125000, 125000, 250000, 0 }; 290 291 /*! 292 * Maximum payload with respect to the datarate index. 293 * The table is valid for the dwell time configuration of 0 for uplinks and downlinks. 294 */ 295 static const uint8_t MaxPayloadOfDatarateDwell0AS923[] = { 51, 51, 115, 115, 242, 242, 242, 242 }; 296 297 /*! 298 * Maximum payload with respect to the datarate index. 299 * The table is only valid for uplinks. 300 */ 301 static const uint8_t MaxPayloadOfDatarateDwell1AS923[] = { 0, 0, 11, 53, 125, 242, 242, 242 }; 302 303 /*! 304 * Effective datarate offsets for receive window 1 when downlink dwell time is zero. 305 */ 306 static const int8_t EffectiveRx1DrOffsetDownlinkDwell0AS923[8][8] = 307 { 308 { DR_0 , DR_0 , DR_0 , DR_0 , DR_0 , DR_0 , DR_1 , DR_2 }, // DR_0 309 { DR_1 , DR_0 , DR_0 , DR_0 , DR_0 , DR_0 , DR_2 , DR_3 }, // DR_1 310 { DR_2 , DR_1 , DR_0 , DR_0 , DR_0 , DR_0 , DR_3 , DR_4 }, // DR_2 311 { DR_3 , DR_2 , DR_1 , DR_0 , DR_0 , DR_0 , DR_4 , DR_5 }, // DR_3 312 { DR_4 , DR_3 , DR_2 , DR_1 , DR_0 , DR_0 , DR_5 , DR_6 }, // DR_4 313 { DR_5 , DR_4 , DR_3 , DR_2 , DR_1 , DR_0 , DR_6 , DR_7 }, // DR_5 314 { DR_6 , DR_5 , DR_4 , DR_3 , DR_2 , DR_1 , DR_7 , DR_7 }, // DR_6 315 { DR_7 , DR_6 , DR_5 , DR_4 , DR_3 , DR_2 , DR_7 , DR_7 }, // DR_7 316 }; 317 318 /*! 319 * Effective datarate offsets for receive window 1 when downlink dwell time is one. 320 */ 321 static const int8_t EffectiveRx1DrOffsetDownlinkDwell1AS923[8][8] = 322 { 323 { DR_2 , DR_2 , DR_2 , DR_2 , DR_2 , DR_2 , DR_2 , DR_2 }, // DR_0 324 { DR_2 , DR_2 , DR_2 , DR_2 , DR_2 , DR_2 , DR_2 , DR_3 }, // DR_1 325 { DR_2 , DR_2 , DR_2 , DR_2 , DR_2 , DR_2 , DR_3 , DR_4 }, // DR_2 326 { DR_3 , DR_2 , DR_2 , DR_2 , DR_2 , DR_2 , DR_4 , DR_5 }, // DR_3 327 { DR_4 , DR_3 , DR_2 , DR_2 , DR_2 , DR_2 , DR_5 , DR_6 }, // DR_4 328 { DR_5 , DR_4 , DR_3 , DR_2 , DR_2 , DR_2 , DR_6 , DR_7 }, // DR_5 329 { DR_6 , DR_5 , DR_4 , DR_3 , DR_2 , DR_2 , DR_7 , DR_7 }, // DR_6 330 { DR_7 , DR_6 , DR_5 , DR_4 , DR_3 , DR_2 , DR_7 , DR_7 }, // DR_7 331 }; 332 333 /*! 334 * \brief The function gets a value of a specific phy attribute. 335 * 336 * \param [IN] getPhy Pointer to the function parameters. 337 * 338 * \retval Returns a structure containing the PHY parameter. 339 */ 340 PhyParam_t RegionAS923GetPhyParam( GetPhyParams_t* getPhy ); 341 342 /*! 343 * \brief Updates the last TX done parameters of the current channel. 344 * 345 * \param [IN] txDone Pointer to the function parameters. 346 */ 347 void RegionAS923SetBandTxDone( SetBandTxDoneParams_t* txDone ); 348 349 /*! 350 * \brief Initializes the channels masks and the channels. 351 * 352 * \param [IN] type Sets the initialization type. 353 */ 354 void RegionAS923InitDefaults( InitDefaultsParams_t* params ); 355 356 /*! 357 * \brief Verifies a parameter. 358 * 359 * \param [IN] verify Pointer to the function parameters. 360 * 361 * \param [IN] type Sets the initialization type. 362 * 363 * \retval Returns true, if the parameter is valid. 364 */ 365 bool RegionAS923Verify( VerifyParams_t* verify, PhyAttribute_t phyAttribute ); 366 367 /*! 368 * \brief The function parses the input buffer and sets up the channels of the 369 * CF list. 370 * 371 * \param [IN] applyCFList Pointer to the function parameters. 372 */ 373 void RegionAS923ApplyCFList( ApplyCFListParams_t* applyCFList ); 374 375 /*! 376 * \brief Sets a channels mask. 377 * 378 * \param [IN] chanMaskSet Pointer to the function parameters. 379 * 380 * \retval Returns true, if the channels mask could be set. 381 */ 382 bool RegionAS923ChanMaskSet( ChanMaskSetParams_t* chanMaskSet ); 383 384 /*! 385 * Computes the Rx window timeout and offset. 386 * 387 * \param [IN] datarate Rx window datarate index to be used 388 * 389 * \param [IN] minRxSymbols Minimum required number of symbols to detect an Rx frame. 390 * 391 * \param [IN] rxError System maximum timing error of the receiver. In milliseconds 392 * The receiver will turn on in a [-rxError : +rxError] ms 393 * interval around RxOffset 394 * 395 * \param [OUT]rxConfigParams Returns updated WindowTimeout and WindowOffset fields. 396 */ 397 void RegionAS923ComputeRxWindowParameters( int8_t datarate, uint8_t minRxSymbols, uint32_t rxError, RxConfigParams_t *rxConfigParams ); 398 399 /*! 400 * \brief Configuration of the RX windows. 401 * 402 * \param [IN] rxConfig Pointer to the function parameters. 403 * 404 * \param [OUT] datarate The datarate index which was set. 405 * 406 * \retval Returns true, if the configuration was applied successfully. 407 */ 408 bool RegionAS923RxConfig( RxConfigParams_t* rxConfig, int8_t* datarate ); 409 410 /*! 411 * \brief TX configuration. 412 * 413 * \param [IN] txConfig Pointer to the function parameters. 414 * 415 * \param [OUT] txPower The tx power index which was set. 416 * 417 * \param [OUT] txTimeOnAir The time-on-air of the frame. 418 * 419 * \retval Returns true, if the configuration was applied successfully. 420 */ 421 bool RegionAS923TxConfig( TxConfigParams_t* txConfig, int8_t* txPower, TimerTime_t* txTimeOnAir ); 422 423 /*! 424 * \brief The function processes a Link ADR Request. 425 * 426 * \param [IN] linkAdrReq Pointer to the function parameters. 427 * 428 * \retval Returns the status of the operation, according to the LoRaMAC specification. 429 */ 430 uint8_t RegionAS923LinkAdrReq( LinkAdrReqParams_t* linkAdrReq, int8_t* drOut, int8_t* txPowOut, uint8_t* nbRepOut, uint8_t* nbBytesParsed ); 431 432 /*! 433 * \brief The function processes a RX Parameter Setup Request. 434 * 435 * \param [IN] rxParamSetupReq Pointer to the function parameters. 436 * 437 * \retval Returns the status of the operation, according to the LoRaMAC specification. 438 */ 439 uint8_t RegionAS923RxParamSetupReq( RxParamSetupReqParams_t* rxParamSetupReq ); 440 441 /*! 442 * \brief The function processes a Channel Request. 443 * 444 * \param [IN] newChannelReq Pointer to the function parameters. 445 * 446 * \retval Returns the status of the operation, according to the LoRaMAC specification. 447 */ 448 int8_t RegionAS923NewChannelReq( NewChannelReqParams_t* newChannelReq ); 449 450 /*! 451 * \brief The function processes a TX ParamSetup Request. 452 * 453 * \param [IN] txParamSetupReq Pointer to the function parameters. 454 * 455 * \retval Returns the status of the operation, according to the LoRaMAC specification. 456 * Returns -1, if the functionality is not implemented. In this case, the end node 457 * shall not process the command. 458 */ 459 int8_t RegionAS923TxParamSetupReq( TxParamSetupReqParams_t* txParamSetupReq ); 460 461 /*! 462 * \brief The function processes a DlChannel Request. 463 * 464 * \param [IN] dlChannelReq Pointer to the function parameters. 465 * 466 * \retval Returns the status of the operation, according to the LoRaMAC specification. 467 */ 468 int8_t RegionAS923DlChannelReq( DlChannelReqParams_t* dlChannelReq ); 469 470 /*! 471 * \brief Alternates the datarate of the channel for the join request. 472 * 473 * \param [IN] currentDr Current datarate. 474 * 475 * \retval Datarate to apply. 476 */ 477 int8_t RegionAS923AlternateDr( int8_t currentDr, AlternateDrType_t type ); 478 479 /*! 480 * \brief Searches and set the next random available channel 481 * 482 * \param [OUT] channel Next channel to use for TX. 483 * 484 * \param [OUT] time Time to wait for the next transmission according to the duty 485 * cycle. 486 * 487 * \param [OUT] aggregatedTimeOff Updates the aggregated time off. 488 * 489 * \retval Function status [1: OK, 0: Unable to find a channel on the current datarate] 490 */ 491 LoRaMacStatus_t RegionAS923NextChannel( NextChanParams_t* nextChanParams, uint8_t* channel, TimerTime_t* time, TimerTime_t* aggregatedTimeOff ); 492 493 /*! 494 * \brief Adds a channel. 495 * 496 * \param [IN] channelAdd Pointer to the function parameters. 497 * 498 * \retval Status of the operation. 499 */ 500 LoRaMacStatus_t RegionAS923ChannelAdd( ChannelAddParams_t* channelAdd ); 501 502 /*! 503 * \brief Removes a channel. 504 * 505 * \param [IN] channelRemove Pointer to the function parameters. 506 * 507 * \retval Returns true, if the channel was removed successfully. 508 */ 509 bool RegionAS923ChannelsRemove( ChannelRemoveParams_t* channelRemove ); 510 511 /*! 512 * \brief Computes new datarate according to the given offset 513 * 514 * \param [IN] downlinkDwellTime Downlink dwell time configuration. 0: No limit, 1: 400ms 515 * 516 * \param [IN] dr Current datarate 517 * 518 * \param [IN] drOffset Offset to be applied 519 * 520 * \retval newDr Computed datarate. 521 */ 522 uint8_t RegionAS923ApplyDrOffset( uint8_t downlinkDwellTime, int8_t dr, int8_t drOffset ); 523 524 /*! 525 * \brief Sets the radio into beacon reception mode 526 * 527 * \param [IN] rxBeaconSetup Pointer to the function parameters 528 */ 529 void RegionAS923RxBeaconSetup( RxBeaconSetup_t* rxBeaconSetup, uint8_t* outDr ); 530 531 /*! \} defgroup REGIONAS923 */ 532 533 #ifdef __cplusplus 534 } 535 #endif 536 537 #endif // __REGION_AS923_H__ 538
