LoRaPHY Class Parent class for LoRa regional PHY implementations. More...
#include <LoRaPHY.h>
Public Member Functions | |
void | initialize (LoRaWANTimeHandler *lora_time) |
Initialize LoRaPHY. More... | |
void | set_radio_instance (LoRaRadio &radio) |
Stores a reference to Radio object. More... | |
void | put_radio_to_sleep (void) |
Puts radio in sleep mode. More... | |
void | put_radio_to_standby (void) |
Puts radio in standby mode. More... | |
void | handle_receive (void) |
Puts radio in receive mode. More... | |
void | handle_send (uint8_t *buf, uint8_t size) |
Delegates MAC layer request to transmit packet. More... | |
void | setup_public_network_mode (bool set) |
Enables/Disables public network mode. More... | |
uint32_t | get_radio_rng () |
Provides a random number from radio. More... | |
void | calculate_backoff (bool joined, bool last_tx_was_join_req, bool dc_enabled, uint8_t channel, lorawan_time_t elapsed_time, lorawan_time_t tx_toa) |
calculate_backoff Calculates and applies duty cycle back-off time. More... | |
bool | mask_bit_test (const uint16_t *mask, unsigned bit) |
Tests if a channel is on or off in the channel mask. More... | |
void | mask_bit_set (uint16_t *mask, unsigned bit) |
Tests if a channel is on or off in the channel mask. More... | |
void | mask_bit_clear (uint16_t *mask, unsigned bit) |
Tests if a channel is on or off in the channel mask. More... | |
virtual uint8_t | request_new_channel (int8_t channel_id, channel_params_t *new_channel) |
Entertain a new channel request MAC command. More... | |
virtual void | set_last_tx_done (uint8_t channel, bool joined, lorawan_time_t last_tx_done_time) |
Process PHY layer state after a successful transmission. More... | |
virtual void | restore_default_channels () |
Enables default channels only. More... | |
virtual void | apply_cf_list (const uint8_t *payload, uint8_t size) |
Processes the incoming CF-list. More... | |
bool | get_next_ADR (bool restore_channel_mask, int8_t &dr_out, int8_t &tx_power_out, uint32_t &adr_ack_counter) |
Calculates the next datarate to set, when ADR is on or off. More... | |
virtual bool | rx_config (rx_config_params_t *config) |
Configure radio reception. More... | |
virtual void | compute_rx_win_params (int8_t datarate, uint8_t min_rx_symbols, uint32_t rx_error, rx_config_params_t *rx_conf_params) |
Computing Receive Windows. More... | |
virtual bool | tx_config (tx_config_params_t *tx_config, int8_t *tx_power, lorawan_time_t *tx_toa) |
Configure radio transmission. More... | |
virtual uint8_t | link_ADR_request (adr_req_params_t *params, int8_t *dr_out, int8_t *tx_power_out, uint8_t *nb_rep_out, uint8_t *nb_bytes_parsed) |
Processes a Link ADR Request. More... | |
virtual uint8_t | accept_rx_param_setup_req (rx_param_setup_req_t *params) |
Accept or rejects RxParamSetupReq MAC command. More... | |
virtual bool | accept_tx_param_setup_req (uint8_t ul_dwell_time, uint8_t dl_dwell_time) |
accept_tx_param_setup_req Makes decision whether to accept or reject TxParamSetupReq MAC command. More... | |
virtual uint8_t | dl_channel_request (uint8_t channel_id, uint32_t rx1_frequency) |
Processes a DlChannelReq MAC command. More... | |
virtual int8_t | get_alternate_DR (uint8_t nb_trials) |
Alternates the datarate of the channel for the join request. More... | |
virtual lorawan_status_t | set_next_channel (channel_selection_params_t *nextChanParams, uint8_t *channel, lorawan_time_t *time, lorawan_time_t *aggregatedTimeOff) |
Searches and sets the next available channel. More... | |
virtual lorawan_status_t | add_channel (const channel_params_t *new_channel, uint8_t id) |
Adds a channel to the channel list. More... | |
virtual bool | remove_channel (uint8_t channel_id) |
Removes a channel from the channel list. More... | |
virtual void | set_tx_cont_mode (cw_mode_params_t *continuous_wave, uint32_t frequency=0) |
Puts the radio into continuous wave mode. More... | |
virtual uint8_t | apply_DR_offset (int8_t dr, int8_t dr_offset) |
Computes new data rate according to the given offset. More... | |
void | reset_to_default_values (loramac_protocol_params *params, bool init=false) |
reset_to_default_values resets some parameters to default values More... | |
int8_t | get_next_lower_tx_datarate (int8_t datarate) |
get_next_lower_tx_datarate Gets the next lower datarate More... | |
uint8_t | get_minimum_rx_datarate () |
get_minimum_rx_datarate Gets the minimum RX datarate supported by a device More... | |
uint8_t | get_minimum_tx_datarate () |
get_minimum_tx_datarate Gets the minimum TX datarate supported by a device More... | |
uint8_t | get_default_tx_datarate () |
get_default_tx_datarate Gets the default TX datarate More... | |
uint8_t | get_default_max_tx_datarate () |
get_default_max_tx_datarate Gets the maximum achievable data rate for LoRa modulation. More... | |
uint8_t | get_default_tx_power () |
get_default_tx_power Gets the default TX power More... | |
uint8_t | get_max_payload (uint8_t datarate, bool use_repeater=false) |
get_max_payload Gets maximum amount in bytes which device can send More... | |
uint16_t | get_maximum_frame_counter_gap () |
get_maximum_frame_counter_gap Gets maximum frame counter gap More... | |
uint32_t | get_ack_timeout () |
get_ack_timeout Gets timeout value for ACK to be received More... | |
uint32_t | get_default_rx2_frequency () |
get_default_rx2_frequency Gets default RX2 frequency More... | |
uint8_t | get_default_rx2_datarate () |
get_default_rx2_datarate Gets default RX2 datarate More... | |
uint16_t * | get_channel_mask (bool get_default=false) |
get_channel_mask Gets the channel mask More... | |
uint8_t | get_max_nb_channels () |
get_max_nb_channels Gets maximum number of channels supported More... | |
channel_params_t * | get_phy_channels () |
get_phy_channels Gets PHY channels More... | |
bool | is_custom_channel_plan_supported () |
is_custom_channel_plan_supported Checks if custom channel plan is supported More... | |
uint32_t | get_rx_time_on_air (uint8_t modem, uint16_t pkt_len) |
get_rx_time_on_air(...) calculates the time the received spent on air More... | |
bool | verify_rx_datarate (uint8_t datarate) |
verify_rx_datarate Verifies that given RX datarate is valid More... | |
bool | verify_tx_datarate (uint8_t datarate, bool use_default=false) |
verify_tx_datarate Verifies that given TX datarate is valid More... | |
bool | verify_tx_power (uint8_t tx_power) |
verify_tx_power Verifies that given TX power is valid More... | |
bool | verify_duty_cycle (bool cycle) |
verify_duty_cycle Verifies that given cycle is valid More... | |
bool | verify_nb_join_trials (uint8_t nb_join_trials) |
verify_nb_join_trials Verifies that given number of trials is valid More... | |
Protected Member Functions | |
int | lookup_band_for_frequency (uint32_t freq) const |
Looks up corresponding band for a frequency. More... | |
virtual bool | verify_frequency_for_band (uint32_t freq, uint8_t band) const |
Verifies, if a frequency is within a given band. More... | |
bool | val_in_range (int8_t value, int8_t min, int8_t max) |
Verifies, if a value is in a given range. More... | |
bool | verify_channel_DR (uint16_t *channelsMask, int8_t dr) |
Verifies, if a datarate is available on an active channel. More... | |
bool | disable_channel (uint16_t *channel_mask, uint8_t id, uint8_t max_channels) |
Disables a channel in a given channels mask. More... | |
uint8_t | count_bits (uint16_t mask, uint8_t nb_bits) |
Counts number of bits on in a given mask. More... | |
uint8_t | num_active_channels (uint16_t *channel_mask, uint8_t start_idx, uint8_t stop_idx) |
Counts the number of active channels in a given channels mask. More... | |
void | copy_channel_mask (uint16_t *dest_mask, uint16_t *src_mask, uint8_t len) |
Copy channel masks. More... | |
lorawan_time_t | update_band_timeoff (bool joined, bool dutyCycle, band_t *bands, uint8_t nb_bands) |
Updates the time-offs of the bands. More... | |
uint8_t | parse_link_ADR_req (const uint8_t *payload, uint8_t payload_size, link_adr_params_t *adr_params) |
Parses the parameter of an LinkAdrRequest. More... | |
uint8_t | verify_link_ADR_req (verify_adr_params_t *verify_params, int8_t *dr, int8_t *tx_pow, uint8_t *nb_rep) |
Verifies and updates the datarate, the TX power and the number of repetitions of a LinkAdrRequest. More... | |
void | get_rx_window_params (float t_symbol, uint8_t min_rx_symbols, float rx_error, float wakeup_time, uint32_t *window_length, uint32_t *window_length_ms, int32_t *window_offset, uint8_t phy_dr) |
Computes the RX window timeout and the RX window offset. More... | |
int8_t | compute_tx_power (int8_t txPowerIndex, float maxEirp, float antennaGain) |
Computes the txPower, based on the max EIRP and the antenna gain. More... | |
int32_t | get_random (int32_t min, int32_t max) |
Provides a random number in the range provided. More... | |
int8_t | get_next_lower_dr (int8_t dr, int8_t min_dr) |
Get next lower data rate. More... | |
uint8_t | get_bandwidth (uint8_t dr_index) |
Get channel bandwidth depending upon data rate table index. More... | |
LoRaPHY Class Parent class for LoRa regional PHY implementations.
|
virtual |
Accept or rejects RxParamSetupReq MAC command.
The function processes a RX parameter setup request in response to server MAC command for RX setup.
[in] | params | A pointer to rx parameter setup request. |
|
virtual |
accept_tx_param_setup_req Makes decision whether to accept or reject TxParamSetupReq MAC command.
ul_dwell_time | The uplink dwell time. |
dl_dwell_time | The downlink dwell time. |
|
virtual |
Adds a channel to the channel list.
Verifies the channel parameters and if everything is found legitimate, adds that particular channel to the channel list and updates the channel mask.
[in] | new_channel | A pointer to the parameters for the new channel. |
[in] | id | Channel ID |
|
virtual |
Processes the incoming CF-list.
Handles the payload containing CF-list and enables channels defined therein.
payload | Payload to process. |
size | Size of the payload. |
|
virtual |
Computes new data rate according to the given offset.
[in] | dr | The current datarate. |
[in] | dr_offset | The offset to be applied. |
void calculate_backoff | ( | bool | joined, |
bool | last_tx_was_join_req, | ||
bool | dc_enabled, | ||
uint8_t | channel, | ||
lorawan_time_t | elapsed_time, | ||
lorawan_time_t | tx_toa | ||
) |
calculate_backoff Calculates and applies duty cycle back-off time.
Explicitly updates the band time-off.
joined | Set to true, if the node has already joined a network, otherwise false. |
last_tx_was_join_req | Set to true, if the last uplink was a join request. |
dc_enabled | Set to true, if the duty cycle is enabled, otherwise false. |
channel | The current channel index. |
elapsed_time | Elapsed time since the start of the node. |
tx_toa | Time-on-air of the last transmission. |
|
virtual |
Computing Receive Windows.
The algorithm tries to calculate the length of receive windows (i.e., the minimum time it should remain to acquire a lock on the Preamble for synchronization) and the error offset which compensates for the system timing errors. Basic idea behind the algorithm is to optimize for the reception of last 'min_rx_symbols' symbols out of transmitted Premable symbols. The algorithm compensates for the clock drifts, tick granularity and system wake up time (from sleep state) by opening the window early for the lower SFs. For higher SFs, the symbol time is large enough that we can afford to open late (hence the positive offset). The table below shows the calculated values for SF7 to SF12 with 125 kHz bandwidth.
+-—+–—+----——+---——+-------------------——+----------------——+-------------------——+ | SF | BW (kHz) | rx_error (ms) | wake_up (ms) | min_rx_symbols | window_timeout(symb) | window_offset(ms) | +-—+–—+----——+---——+-------------------——+----------------——+-------------------——+ | 7 | 125 | 5 | 5 | 5 | 18 | -7 | | 8 | 125 | 5 | 5 | 5 | 10 | -4 | | 9 | 125 | 5 | 5 | 5 | 6 | 2 | | 10 | 125 | 5 | 5 | 5 | 6 | 14 | | 11 | 125 | 5 | 5 | 5 | 6 | 39 | | 12 | 125 | 5 | 5 | 5 | 6 | 88 | +-—+–—+----——+---——+-------------------——+----------------——+-------------------——+
For example for SF7, the receive window will open at downlink start time plus the offset calculated and will remain open for the length window_timeout.
Symbol time = 1.024 ms Downlink start: T = Tx + 1s (+/- 20 us) | | | | | +---+---+---+---+---+---+---+---+ | 8 Preamble Symbols | +---+---+---+---+---+---+---+---+
| RX Window start time = T +/- Offset +—+—+—+—+—+—+—+—+—+—+—+—+—+—+—+—+—+—+ | | | | | | | | | | | | | | | | | | | +—+—+—+—+—+—+—+—+—+—+—+—+—+—+—+—+—+—+
Similarly for SF12:
Symbol time = 32.768 ms Downlink start: T = Tx + 1s (+/- 20 us) | | | | | +---+---+---+---+---+---+---+---+ | 8 Preamble Symbols | +---+---+---+---+---+---+---+---+ | RX Window start time = T +/- Offset +---+---+---+---+---+---+ | | | | | | | +---+---+---+---+---+---+
Computes the RX window timeout and offset.
[in] | datarate | The RX window datarate index to be used. |
[in] | min_rx_symbols | The minimum number of symbols required to detect an RX frame. |
[in] | rx_error | The maximum timing error of the receiver in milliseconds. The receiver will turn on in a [-rxError : +rxError] ms interval around RxOffset. |
[out] | rx_conf_params | Pointer to the structure that needs to be filled with receive window parameters. |
|
protected |
Computes the txPower, based on the max EIRP and the antenna gain.
|
protected |
Copy channel masks.
|
protected |
Counts number of bits on in a given mask.
|
protected |
Disables a channel in a given channels mask.
|
virtual |
Processes a DlChannelReq MAC command.
channel_id | The channel ID to add the frequency. |
rx1_frequency | The alternative frequency for the Rx1 window. |
uint32_t get_ack_timeout | ( | ) |
get_ack_timeout Gets timeout value for ACK to be received
|
virtual |
Alternates the datarate of the channel for the join request.
nb_trials | Number of trials to be made on one given data rate. |
|
protected |
Get channel bandwidth depending upon data rate table index.
uint16_t* get_channel_mask | ( | bool | get_default = false | ) |
get_channel_mask Gets the channel mask
get_default | If true the default mask is returned, otherwise the current mask is returned |
uint8_t get_default_max_tx_datarate | ( | ) |
get_default_max_tx_datarate Gets the maximum achievable data rate for LoRa modulation.
This will always be the highest data rate achievable with LoRa as defined in the regional specifications.
uint8_t get_default_rx2_datarate | ( | ) |
get_default_rx2_datarate Gets default RX2 datarate
uint32_t get_default_rx2_frequency | ( | ) |
get_default_rx2_frequency Gets default RX2 frequency
uint8_t get_default_tx_datarate | ( | ) |
get_default_tx_datarate Gets the default TX datarate
uint8_t get_default_tx_power | ( | ) |
get_default_tx_power Gets the default TX power
uint8_t get_max_nb_channels | ( | ) |
get_max_nb_channels Gets maximum number of channels supported
uint8_t get_max_payload | ( | uint8_t | datarate, |
bool | use_repeater = false |
||
) |
get_max_payload Gets maximum amount in bytes which device can send
datarate | A datarate to use |
use_repeater | If true repeater table is used, otherwise payloads table is used |
uint16_t get_maximum_frame_counter_gap | ( | ) |
get_maximum_frame_counter_gap Gets maximum frame counter gap
uint8_t get_minimum_rx_datarate | ( | ) |
get_minimum_rx_datarate Gets the minimum RX datarate supported by a device
uint8_t get_minimum_tx_datarate | ( | ) |
get_minimum_tx_datarate Gets the minimum TX datarate supported by a device
bool get_next_ADR | ( | bool | restore_channel_mask, |
int8_t & | dr_out, | ||
int8_t & | tx_power_out, | ||
uint32_t & | adr_ack_counter | ||
) |
Calculates the next datarate to set, when ADR is on or off.
restore_channel_mask | A boolean set restore channel mask in case of failure. |
dr_out | The calculated datarate for the next TX. |
tx_power_out | The TX power for the next TX. |
adr_ack_counter | The calculated ADR acknowledgement counter. |
|
protected |
Get next lower data rate.
int8_t get_next_lower_tx_datarate | ( | int8_t | datarate | ) |
get_next_lower_tx_datarate Gets the next lower datarate
datarate | Current TX datarate |
channel_params_t* get_phy_channels | ( | ) |
get_phy_channels Gets PHY channels
uint32_t get_radio_rng | ( | ) |
Provides a random number from radio.
Returns a 32-bit random unsigned integer value based upon RSSI measurements.
|
protected |
Provides a random number in the range provided.
uint32_t get_rx_time_on_air | ( | uint8_t | modem, |
uint16_t | pkt_len | ||
) |
get_rx_time_on_air(...) calculates the time the received spent on air
|
protected |
Computes the RX window timeout and the RX window offset.
void handle_receive | ( | void | ) |
Puts radio in receive mode.
Requests the radio driver to enter receive mode.
void handle_send | ( | uint8_t * | buf, |
uint8_t | size | ||
) |
Delegates MAC layer request to transmit packet.
buf | a pointer to the data which needs to be transmitted |
size | size of the data in bytes |
void initialize | ( | LoRaWANTimeHandler * | lora_time | ) |
Initialize LoRaPHY.
LoRaMac calls this to initialize LoRaPHY.
lora_time | a pointer to LoRaWANTimeHandler object |
bool is_custom_channel_plan_supported | ( | ) |
is_custom_channel_plan_supported Checks if custom channel plan is supported
|
virtual |
Processes a Link ADR Request.
[in] | params | A pointer ADR request parameters. |
[out] | dr_out | The datarate applied. |
[out] | tx_power_out | The TX power applied. |
[out] | nb_rep_out | The number of repetitions to apply. |
[out] | nb_bytes_parsed | The number of bytes parsed. |
|
protected |
Looks up corresponding band for a frequency.
Returns -1 if not in any band.
void mask_bit_clear | ( | uint16_t * | mask, |
unsigned | bit | ||
) |
Tests if a channel is on or off in the channel mask.
void mask_bit_set | ( | uint16_t * | mask, |
unsigned | bit | ||
) |
Tests if a channel is on or off in the channel mask.
bool mask_bit_test | ( | const uint16_t * | mask, |
unsigned | bit | ||
) |
Tests if a channel is on or off in the channel mask.
|
protected |
Counts the number of active channels in a given channels mask.
|
protected |
Parses the parameter of an LinkAdrRequest.
void put_radio_to_sleep | ( | void | ) |
Puts radio in sleep mode.
Requests the radio driver to enter sleep mode.
void put_radio_to_standby | ( | void | ) |
Puts radio in standby mode.
Requests the radio driver to enter standby mode.
|
virtual |
Removes a channel from the channel list.
[in] | channel_id | Index of the channel to be removed |
|
virtual |
Entertain a new channel request MAC command.
MAC command subsystem processes the new channel request coming form the network server and then MAC layer asks the PHY layer to entertain the request.
channel_id | The channel ID. |
new_channel | A pointer to the new channel's parameters. |
void reset_to_default_values | ( | loramac_protocol_params * | params, |
bool | init = false |
||
) |
reset_to_default_values resets some parameters to default values
params | Pointer to MAC protocol parameters which will be reset |
init | If true, most of the values will be modified |
|
virtual |
Enables default channels only.
Falls back to a channel mask where only default channels are enabled, all other channels are disabled.
|
virtual |
Configure radio reception.
[in] | config | A pointer to the RX configuration. |
|
virtual |
Process PHY layer state after a successful transmission.
set_last_tx_done Updates times of the last transmission for the particular channel and band upon which last transmission took place.
channel | The channel in use. |
joined | Boolean telling if node has joined the network. |
last_tx_done_time | The last TX done time. |
|
virtual |
Searches and sets the next available channel.
If there are multiple channels found available, one of them is selected randomly.
[in] | nextChanParams | Parameters for the next channel. |
[out] | channel | The next channel to use for TX. |
[out] | time | The time to wait for the next transmission according to the duty cycle. |
[out] | aggregatedTimeOff | Updates the aggregated time off. |
void set_radio_instance | ( | LoRaRadio & | radio | ) |
Stores a reference to Radio object.
Application is responsible for constructing a 'LoRaRadio' object which is passed down to the PHY layer.
radio | a reference to radio driver object |
|
virtual |
Puts the radio into continuous wave mode.
[in] | continuous_wave | A pointer to the function parameters. |
[in] | frequency | Frequency to transmit at |
void setup_public_network_mode | ( | bool | set | ) |
Enables/Disables public network mode.
Public and private LoRaWAN network constitute different preambles and Net IDs. This API isused to tell the radio which network mode is in use.
set | true or false |
|
virtual |
Configure radio transmission.
[in] | tx_config | Structure containing tx parameters. |
[out] | tx_power | The TX power which will be set. |
[out] | tx_toa | The time-on-air of the frame. |
|
protected |
Updates the time-offs of the bands.
|
protected |
Verifies, if a value is in a given range.
|
protected |
Verifies, if a datarate is available on an active channel.
bool verify_duty_cycle | ( | bool | cycle | ) |
verify_duty_cycle Verifies that given cycle is valid
cycle | Cycle to check |
|
protectedvirtual |
Verifies, if a frequency is within a given band.
|
protected |
Verifies and updates the datarate, the TX power and the number of repetitions of a LinkAdrRequest.
bool verify_nb_join_trials | ( | uint8_t | nb_join_trials | ) |
verify_nb_join_trials Verifies that given number of trials is valid
nb_join_trials | Number to check |
bool verify_rx_datarate | ( | uint8_t | datarate | ) |
verify_rx_datarate Verifies that given RX datarate is valid
datarate | Datarate to check |
bool verify_tx_datarate | ( | uint8_t | datarate, |
bool | use_default = false |
||
) |
verify_tx_datarate Verifies that given TX datarate is valid
datarate | Datarate to check |
use_default | If true validation is done against default value |
bool verify_tx_power | ( | uint8_t | tx_power | ) |
verify_tx_power Verifies that given TX power is valid
tx_power | Power to check |