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 for obtaining a QOS level set by
00333      * NS (applicable only to unconfirmed messages).
00334      */
00335     uint8_t current_nb_trans ;
00336 } adr_req_params_t;
00337 
00338 /**
00339  * Structure containing data for local ADR settings
00340  */
00341 typedef struct link_adr_params_s {
00342     /**
00343      * The number of repetitions.
00344      */
00345     uint8_t nb_rep;
00346     /**
00347      * Datarate.
00348      */
00349     int8_t datarate;
00350     /**
00351      * TX power.
00352      */
00353     int8_t tx_power;
00354     /**
00355      * Channels mask control field.
00356      */
00357     uint8_t ch_mask_ctrl;
00358     /**
00359      * Channels mask field.
00360      */
00361     uint16_t channel_mask;
00362 } link_adr_params_t;
00363 
00364 /**
00365  * Structure used to store ADR values received from network
00366  * for verification (legality) purposes.
00367  */
00368 typedef struct verify_adr_params_s {
00369     /*!
00370      * The current status of the AdrLinkRequest.
00371      */
00372     uint8_t status ;
00373     /*!
00374      * Set to true, if ADR is enabled.
00375      */
00376     bool adr_enabled ;
00377     /*!
00378      * The datarate the AdrLinkRequest wants to set.
00379      */
00380     int8_t datarate ;
00381     /*!
00382      * The TX power the AdrLinkRequest wants to set.
00383      */
00384     int8_t tx_power ;
00385     /*!
00386      * The number of repetitions the AdrLinkRequest wants to set.
00387      */
00388     uint8_t nb_rep ;
00389     /*!
00390      * The current datarate the node is using.
00391      */
00392     int8_t current_datarate ;
00393     /*!
00394      * The current TX power the node is using.
00395      */
00396     int8_t current_tx_power ;
00397     /*!
00398      * The current number of repetitions the node is using.
00399      */
00400     int8_t current_nb_rep ;
00401 
00402     /*!
00403      * A pointer to the first element of the channels mask.
00404      */
00405     uint16_t *channel_mask ;
00406 } verify_adr_params_t;
00407 
00408 /**
00409  * Contains rx parameter setup request coming from
00410  * network server.
00411  */
00412 typedef struct rx_param_setup_req_s {
00413     /**
00414      * The datarate to set up.
00415      */
00416     int8_t datarate;
00417     /**
00418      * The datarate offset.
00419      */
00420     int8_t dr_offset;
00421     /**
00422      * The frequency to set up.
00423      */
00424     uint32_t frequency;
00425 } rx_param_setup_req_t;
00426 
00427 /**
00428  * The parameter structure for the function RegionNextChannel.
00429  */
00430 typedef struct channel_selection_params_s {
00431     /**
00432      * The aggregated time-off time.
00433      */
00434     lorawan_time_t aggregate_timeoff;
00435     /**
00436      * The time of the last aggregated TX.
00437      */
00438     lorawan_time_t last_aggregate_tx_time;
00439     /**
00440      * The current datarate.
00441      */
00442     int8_t current_datarate;
00443     /**
00444      * Set to true, if the node has already joined a network, otherwise false.
00445      */
00446     bool joined;
00447     /**
00448      * Set to true, if the duty cycle is enabled, otherwise false.
00449      */
00450     bool dc_enabled;
00451 } channel_selection_params_t;
00452 
00453 /*!
00454  * The parameter structure for the function RegionContinuousWave.
00455  */
00456 typedef struct continuous_wave_mode_params_s  {
00457     /*!
00458      * The current channel index.
00459      */
00460     uint8_t channel ;
00461     /*!
00462      * The datarate. Used to limit the TX power.
00463      */
00464     int8_t datarate ;
00465     /*!
00466      * The TX power to set up.
00467      */
00468     int8_t tx_power ;
00469     /*!
00470      * The max EIRP, if applicable.
00471      */
00472     float max_eirp ;
00473     /*!
00474      * The antenna gain, if applicable.
00475      */
00476     float antenna_gain ;
00477     /*!
00478      * Specifies the time the radio will stay in CW mode.
00479      */
00480     uint16_t timeout ;
00481 } cw_mode_params_t ;
00482 
00483 /*!
00484  * Template for a table
00485  */
00486 typedef struct {
00487     void *table;
00488     uint8_t size;
00489 } loraphy_table_t ;
00490 
00491 /*!
00492  * Contains information regarding channel configuration of
00493  * a given PHY
00494  */
00495 typedef struct {
00496     uint8_t channel_list_size;
00497     uint8_t  mask_size;
00498     uint16_t *mask;
00499     uint16_t *default_mask;
00500     channel_params_t *channel_list;
00501 } loraphy_channels_t ;
00502 
00503 /*!
00504  * Global configuration parameters of a given PHY
00505  */
00506 typedef struct {
00507     bool duty_cycle_enabled;
00508     bool accept_tx_param_setup_req;
00509     bool fsk_supported;
00510     bool cflist_supported;
00511     bool custom_channelplans_supported;
00512     bool dl_channel_req_supported;
00513 
00514     uint8_t default_channel_cnt;
00515     uint8_t cflist_channel_cnt;
00516     uint8_t max_channel_cnt;
00517     uint8_t min_tx_power;
00518     uint8_t max_tx_power;
00519     uint8_t default_tx_power;
00520     uint8_t adr_ack_limit;
00521     uint8_t adr_ack_delay;
00522 
00523     uint8_t min_tx_datarate;
00524     uint8_t max_tx_datarate;
00525     uint8_t min_rx_datarate;
00526     uint8_t max_rx_datarate;
00527     uint8_t default_datarate;
00528     uint8_t default_max_datarate;
00529     uint8_t min_rx1_dr_offset;
00530     uint8_t max_rx1_dr_offset;
00531     uint8_t default_rx1_dr_offset;
00532     uint8_t dwell_limit_datarate;
00533 
00534     uint16_t max_rx_window;
00535     uint16_t recv_delay1;
00536     uint16_t recv_delay2;
00537     uint16_t join_accept_delay1;
00538     uint16_t join_accept_delay2;
00539     uint16_t join_channel_mask;
00540     uint16_t max_fcnt_gap;
00541     uint16_t ack_timeout;
00542     uint16_t ack_timeout_rnd;
00543 
00544     float default_max_eirp;
00545     float default_antenna_gain;
00546 
00547     uint8_t rx_window2_datarate;
00548     uint32_t rx_window2_frequency;
00549 
00550     loraphy_table_t  bands;
00551     loraphy_table_t  bandwidths;
00552     loraphy_table_t  datarates;
00553     loraphy_table_t  payloads;
00554     loraphy_table_t  payloads_with_repeater;
00555 
00556     loraphy_channels_t  channels;
00557 
00558 
00559     unsigned ul_dwell_time_setting : 1;
00560     unsigned dl_dwell_time_setting : 1;
00561 
00562 } loraphy_params_t ;
00563 
00564 
00565 #endif /* MBED_OS_LORA_PHY_DATASTRUCTURES_ */