lora_phy_ds.h

00001 /**
00002  *  @file lora_phy_ds.h
00003  *
00004  *  @brief Data structures relating to PHY layer
00005  *
00006  *  \code
00007  *   ______                              _
00008  *  / _____)             _              | |
00009  * ( (____  _____ ____ _| |_ _____  ____| |__
00010  *  \____ \| ___ |    (_   _) ___ |/ ___)  _ \
00011  *  _____) ) ____| | | || |_| ____( (___| | | |
00012  * (______/|_____)_|_|_| \__)_____)\____)_| |_|
00013  *   (C)2013 Semtech
00014  *  ___ _____ _   ___ _  _____ ___  ___  ___ ___
00015  * / __|_   _/_\ / __| |/ / __/ _ \| _ \/ __| __|
00016  * \__ \ | |/ _ \ (__| ' <| _| (_) |   / (__| _|
00017  * |___/ |_/_/ \_\___|_|\_\_| \___/|_|_\\___|___|
00018  * embedded.connectivity.solutions===============
00019  *
00020  * \endcode
00021  *
00022  * License: Revised BSD License, see LICENSE.TXT file include in the project
00023  *
00024  * Maintainer: Miguel Luis ( Semtech ), Gregory Cristian ( Semtech ) and Daniel Jaeckle ( STACKFORCE )
00025  *
00026  * Copyright (c) 2017, Arm Limited and affiliates.
00027  * SPDX-License-Identifier: BSD-3-Clause
00028  *
00029  */
00030 
00031 #ifndef MBED_OS_LORA_PHY_DATASTRUCTURES_
00032 #define MBED_OS_LORA_PHY_DATASTRUCTURES_
00033 
00034 #include "system/lorawan_data_structures.h"
00035 
00036 /*!
00037  * \brief Returns the minimum value between a and b.
00038  *
00039  * \param [in] a The first value.
00040  * \param [in] b The second value.
00041  * \retval minValue The minimum value.
00042  */
00043 #ifndef MIN
00044 #define MIN( a, b ) ( ( ( a ) < ( b ) ) ? ( a ) : ( b ) )
00045 #endif
00046 
00047 /*!
00048  * \brief Returns the maximum value between a and b
00049  *
00050  * \param [in] a The first value.
00051  * \param [in] b The second value.
00052  * \retval maxValue The maximum value.
00053  */
00054 #ifndef MAX
00055 #define MAX( a, b ) ( ( ( a ) > ( b ) ) ? ( a ) : ( b ) )
00056 #endif
00057 
00058 /**
00059  * LoRaMac maximum number of channels.
00060  */
00061 #define LORA_MAX_NB_CHANNELS                        16
00062 
00063 /*!
00064  * Macro to compute bit of a channel index.
00065  */
00066 #define LC( channelIndex )                          ( uint16_t )( 1 << ( channelIndex - 1 ) )
00067 
00068 
00069 
00070 
00071 /*!
00072  * Region       | dBM
00073  * ------------ | :-----:
00074  * AS923        | Max EIRP
00075  * AU915        | Max EIRP
00076  * CN470        | Max EIRP
00077  * CN779        | Max EIRP
00078  * EU433        | Max EIRP
00079  * EU868        | Max EIRP
00080  * IN865        | Max EIRP
00081  * KR920        | Max EIRP
00082  * US915        | Max ERP
00083  * US915_HYBRID | Max ERP
00084  */
00085 #define TX_POWER_0                                  0
00086 
00087 /*!
00088  * Region       | dBM
00089  * ------------ | :-----:
00090  * AS923        | Max EIRP - 2
00091  * AU915        | Max EIRP - 2
00092  * CN470        | Max EIRP - 2
00093  * CN779        | Max EIRP - 2
00094  * EU433        | Max EIRP - 2
00095  * EU868        | Max EIRP - 2
00096  * IN865        | Max EIRP - 2
00097  * KR920        | Max EIRP - 2
00098  * US915        | Max ERP - 2
00099  * US915_HYBRID | Max ERP - 2
00100  */
00101 #define TX_POWER_1                                  1
00102 
00103 /*!
00104  * Region       | dBM
00105  * ------------ | :-----:
00106  * AS923        | Max EIRP - 4
00107  * AU915        | Max EIRP - 4
00108  * CN470        | Max EIRP - 4
00109  * CN779        | Max EIRP - 4
00110  * EU433        | Max EIRP - 4
00111  * EU868        | Max EIRP - 4
00112  * IN865        | Max EIRP - 4
00113  * KR920        | Max EIRP - 4
00114  * US915        | Max ERP - 4
00115  * US915_HYBRID | Max ERP - 4
00116  */
00117 #define TX_POWER_2                                  2
00118 
00119 /*!
00120  * Region       | dBM
00121  * ------------ | :-----:
00122  * AS923        | Max EIRP - 6
00123  * AU915        | Max EIRP - 6
00124  * CN470        | Max EIRP - 6
00125  * CN779        | Max EIRP - 6
00126  * EU433        | Max EIRP - 6
00127  * EU868        | Max EIRP - 6
00128  * IN865        | Max EIRP - 6
00129  * KR920        | Max EIRP - 6
00130  * US915        | Max ERP - 6
00131  * US915_HYBRID | Max ERP - 6
00132  */
00133 #define TX_POWER_3                                  3
00134 
00135 /*!
00136  * Region       | dBM
00137  * ------------ | :-----:
00138  * AS923        | Max EIRP - 8
00139  * AU915        | Max EIRP - 8
00140  * CN470        | Max EIRP - 8
00141  * CN779        | Max EIRP - 8
00142  * EU433        | Max EIRP - 8
00143  * EU868        | Max EIRP - 8
00144  * IN865        | Max EIRP - 8
00145  * KR920        | Max EIRP - 8
00146  * US915        | Max ERP - 8
00147  * US915_HYBRID | Max ERP - 8
00148  */
00149 #define TX_POWER_4                                  4
00150 
00151 /*!
00152  * Region       | dBM
00153  * ------------ | :-----:
00154  * AS923        | Max EIRP - 10
00155  * AU915        | Max EIRP - 10
00156  * CN470        | Max EIRP - 10
00157  * CN779        | Max EIRP - 10
00158  * EU433        | Max EIRP - 10
00159  * EU868        | Max EIRP - 10
00160  * IN865        | Max EIRP - 10
00161  * KR920        | Max EIRP - 10
00162  * US915        | Max ERP - 10
00163  * US915_HYBRID | Max ERP - 10
00164  */
00165 #define TX_POWER_5                                  5
00166 
00167 /*!
00168  * Region       | dBM
00169  * ------------ | :-----:
00170  * AS923        | Max EIRP - 12
00171  * AU915        | Max EIRP - 12
00172  * CN470        | Max EIRP - 12
00173  * CN779        | -
00174  * EU433        | -
00175  * EU868        | Max EIRP - 12
00176  * IN865        | Max EIRP - 12
00177  * KR920        | Max EIRP - 12
00178  * US915        | Max ERP - 12
00179  * US915_HYBRID | Max ERP - 12
00180  */
00181 #define TX_POWER_6                                  6
00182 
00183 /*!
00184  * Region       | dBM
00185  * ------------ | :-----:
00186  * AS923        | Max EIRP - 14
00187  * AU915        | Max EIRP - 14
00188  * CN470        | Max EIRP - 14
00189  * CN779        | -
00190  * EU433        | -
00191  * EU868        | Max EIRP - 14
00192  * IN865        | Max EIRP - 14
00193  * KR920        | Max EIRP - 14
00194  * US915        | Max ERP - 14
00195  * US915_HYBRID | Max ERP - 14
00196  */
00197 #define TX_POWER_7                                  7
00198 
00199 /*!
00200  * Region       | dBM
00201  * ------------ | :-----:
00202  * AS923        | -
00203  * AU915        | Max EIRP - 16
00204  * CN470        | -
00205  * CN779        | -
00206  * EU433        | -
00207  * EU868        | -
00208  * IN865        | Max EIRP - 16
00209  * KR920        | -
00210  * US915        | Max ERP - 16
00211  * US915_HYBRID | Max ERP -16
00212  */
00213 #define TX_POWER_8                                  8
00214 
00215 /*!
00216  * Region       | dBM
00217  * ------------ | :-----:
00218  * AS923        | -
00219  * AU915        | Max EIRP - 18
00220  * CN470        | -
00221  * CN779        | -
00222  * EU433        | -
00223  * EU868        | -
00224  * IN865        | Max EIRP - 18
00225  * KR920        | -
00226  * US915        | Max ERP - 16
00227  * US915_HYBRID | Max ERP - 16
00228  */
00229 #define TX_POWER_9                                  9
00230 
00231 /*!
00232  * Region       | dBM
00233  * ------------ | :-----:
00234  * AS923        | -
00235  * AU915        | Max EIRP - 20
00236  * CN470        | -
00237  * CN779        | -
00238  * EU433        | -
00239  * EU868        | -
00240  * IN865        | Max EIRP - 20
00241  * KR920        | -
00242  * US915        | Max ERP - 10
00243  * US915_HYBRID | Max ERP - 10
00244  */
00245 #define TX_POWER_10                                 10
00246 
00247 /*!
00248  * RFU
00249  */
00250 #define TX_POWER_11                                 11
00251 
00252 /*!
00253  * RFU
00254  */
00255 #define TX_POWER_12                                 12
00256 
00257 /*!
00258  * RFU
00259  */
00260 #define TX_POWER_13                                 13
00261 
00262 /*!
00263  * RFU
00264  */
00265 #define TX_POWER_14                                 14
00266 
00267 /*!
00268  * RFU
00269  */
00270 #define TX_POWER_15                                 15
00271 
00272 /**
00273  * TX configuration parameters.
00274  */
00275 typedef struct {
00276     /**
00277      * The TX channel.
00278      */
00279     uint8_t channel;
00280     /**
00281      * The TX datarate.
00282      */
00283     int8_t datarate;
00284     /**
00285      * The TX power.
00286      */
00287     int8_t tx_power;
00288     /**
00289      * The Max EIRP, if applicable.
00290      */
00291     float max_eirp;
00292     /**
00293      * The antenna gain, if applicable.
00294      */
00295     float antenna_gain;
00296     /**
00297      * The frame length to set up.
00298      */
00299     uint16_t pkt_len;
00300 } tx_config_params_t;
00301 
00302 /**
00303  * This structure contains parameters for ADR request coming from
00304  * network server.
00305  */
00306 typedef struct {
00307     /*!
00308      * A pointer to the payload containing the MAC commands.
00309      */
00310     const uint8_t* payload ;
00311     /*!
00312      * The size of the payload.
00313      */
00314     uint8_t payload_size ;
00315     /*!
00316      * The uplink dwell time.
00317      */
00318     uint8_t ul_dwell_time ;
00319     /*!
00320      * Set to true, if ADR is enabled.
00321      */
00322     bool adr_enabled ;
00323     /*!
00324      * The current datarate.
00325      */
00326     int8_t current_datarate ;
00327     /*!
00328      * The current TX power.
00329      */
00330     int8_t current_tx_power ;
00331     /*!
00332      * The current number of repetitions.
00333      */
00334     uint8_t current_nb_rep ;
00335 } adr_req_params_t;
00336 
00337 /**
00338  * Structure containing data for local ADR settings
00339  */
00340 typedef struct link_adr_params_s {
00341     /**
00342      * The number of repetitions.
00343      */
00344     uint8_t nb_rep;
00345     /**
00346      * Datarate.
00347      */
00348     int8_t datarate;
00349     /**
00350      * TX power.
00351      */
00352     int8_t tx_power;
00353     /**
00354      * Channels mask control field.
00355      */
00356     uint8_t ch_mask_ctrl;
00357     /**
00358      * Channels mask field.
00359      */
00360     uint16_t channel_mask;
00361 } link_adr_params_t;
00362 
00363 /**
00364  * Structure used to store ADR values received from network
00365  * for verification (legality) purposes.
00366  */
00367 typedef struct verify_adr_params_s {
00368     /*!
00369      * The current status of the AdrLinkRequest.
00370      */
00371     uint8_t status ;
00372     /*!
00373      * Set to true, if ADR is enabled.
00374      */
00375     bool adr_enabled ;
00376     /*!
00377      * The datarate the AdrLinkRequest wants to set.
00378      */
00379     int8_t datarate ;
00380     /*!
00381      * The TX power the AdrLinkRequest wants to set.
00382      */
00383     int8_t tx_power ;
00384     /*!
00385      * The number of repetitions the AdrLinkRequest wants to set.
00386      */
00387     uint8_t nb_rep ;
00388     /*!
00389      * The current datarate the node is using.
00390      */
00391     int8_t current_datarate ;
00392     /*!
00393      * The current TX power the node is using.
00394      */
00395     int8_t current_tx_power ;
00396     /*!
00397      * The current number of repetitions the node is using.
00398      */
00399     int8_t current_nb_rep ;
00400 
00401     /*!
00402      * A pointer to the first element of the channels mask.
00403      */
00404     uint16_t* channel_mask ;
00405 } verify_adr_params_t;
00406 
00407 /**
00408  * Contains rx parameter setup request coming from
00409  * network server.
00410  */
00411 typedef struct rx_param_setup_req_s {
00412     /**
00413      * The datarate to set up.
00414      */
00415     int8_t datarate;
00416     /**
00417      * The datarate offset.
00418      */
00419     int8_t dr_offset;
00420     /**
00421      * The frequency to set up.
00422      */
00423     uint32_t frequency;
00424 } rx_param_setup_req_t;
00425 
00426 /**
00427  * The parameter structure for the function RegionNextChannel.
00428  */
00429 typedef struct channel_selection_params_s {
00430     /**
00431      * The aggregated time-off time.
00432      */
00433     lorawan_time_t aggregate_timeoff;
00434     /**
00435      * The time of the last aggregated TX.
00436      */
00437     lorawan_time_t last_aggregate_tx_time;
00438     /**
00439      * The current datarate.
00440      */
00441     int8_t current_datarate;
00442     /**
00443      * Set to true, if the node has already joined a network, otherwise false.
00444      */
00445     bool joined;
00446     /**
00447      * Set to true, if the duty cycle is enabled, otherwise false.
00448      */
00449     bool dc_enabled;
00450 } channel_selection_params_t;
00451 
00452 /*!
00453  * The parameter structure for the function RegionContinuousWave.
00454  */
00455 typedef struct continuous_wave_mode_params_s  {
00456     /*!
00457      * The current channel index.
00458      */
00459     uint8_t channel ;
00460     /*!
00461      * The datarate. Used to limit the TX power.
00462      */
00463     int8_t datarate ;
00464     /*!
00465      * The TX power to set up.
00466      */
00467     int8_t tx_power ;
00468     /*!
00469      * The max EIRP, if applicable.
00470      */
00471     float max_eirp ;
00472     /*!
00473      * The antenna gain, if applicable.
00474      */
00475     float antenna_gain ;
00476     /*!
00477      * Specifies the time the radio will stay in CW mode.
00478      */
00479     uint16_t timeout ;
00480 } cw_mode_params_t ;
00481 
00482 typedef struct {
00483     void *table;
00484     uint8_t size;
00485 } loraphy_table_t;
00486 
00487 typedef struct {
00488 
00489     uint8_t channel_list_size;
00490     uint8_t  mask_size;
00491 
00492     uint16_t *mask;
00493     uint16_t *default_mask;
00494     channel_params_t *channel_list;
00495 } loraphy_channels_t;
00496 
00497 typedef struct {
00498     bool duty_cycle_enabled;
00499     bool accept_tx_param_setup_req;
00500     bool fsk_supported;
00501     bool cflist_supported;
00502     bool custom_channelplans_supported;
00503     bool dl_channel_req_supported;
00504 
00505     uint8_t default_channel_cnt;
00506     uint8_t cflist_channel_cnt;
00507     uint8_t max_channel_cnt;
00508     uint8_t min_tx_power;
00509     uint8_t max_tx_power;
00510     uint8_t default_tx_power;
00511     uint8_t adr_ack_limit;
00512     uint8_t adr_ack_delay;
00513 
00514     uint8_t min_tx_datarate;
00515     uint8_t max_tx_datarate;
00516     uint8_t min_rx_datarate;
00517     uint8_t max_rx_datarate;
00518     uint8_t default_datarate;
00519     uint8_t default_max_datarate;
00520     uint8_t min_rx1_dr_offset;
00521     uint8_t max_rx1_dr_offset;
00522     uint8_t default_rx1_dr_offset;
00523     uint8_t dwell_limit_datarate;
00524 
00525     uint16_t max_rx_window;
00526     uint16_t recv_delay1;
00527     uint16_t recv_delay2;
00528     uint16_t join_accept_delay1;
00529     uint16_t join_accept_delay2;
00530     uint16_t join_channel_mask;
00531     uint16_t max_fcnt_gap;
00532     uint16_t ack_timeout;
00533     uint16_t ack_timeout_rnd;
00534 
00535     float default_max_eirp;
00536     float default_antenna_gain;
00537 
00538     uint8_t rx_window2_datarate;
00539     uint32_t rx_window2_frequency;
00540 
00541     loraphy_table_t bands;
00542     loraphy_table_t bandwidths;
00543     loraphy_table_t datarates;
00544     loraphy_table_t payloads;
00545     loraphy_table_t payloads_with_repeater;
00546 
00547     loraphy_channels_t channels;
00548 
00549 
00550     unsigned ul_dwell_time_setting : 1;
00551     unsigned dl_dwell_time_setting : 1;
00552 
00553 } loraphy_params_t;
00554 
00555 
00556 #endif /* MBED_OS_LORA_PHY_DATASTRUCTURES_ */