ARMmbed
/
mbed-os
mirror of https://github.com/ARMmbed/mbed-os.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Merge pull request #9330 from hasnainvirk/doxy_loraradio 

Doxygen update for LoRaRadio class
pull/9369/head
Martin Kojtal 2019-01-14 08:44:37 +00:00 committed by GitHub
parent 58a6c24f6b fd04d25e52
commit 7a5192f969
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 327 additions and 73 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

400
features/lorawan/LoRaRadio.h
View File

@ -18,129 +18,382 @@
#ifndef LORARADIO_H_
#define LORARADIO_H_
/** @addtogroup LoRaWAN
* Parent class for a LoRa radio driver
* @{
*/
#include "platform/Callback.h"
#include "PinNames.h"
/**
* Structure to hold RF controls for LoRa Radio.
* SX1276 have an extra control for the crystal (used in DOSCO-L072CZ)
* SX1276 have an extra control for the crystal (used in DISCO-L072CZ).
* A subset of these pins may be used by the driver in accordance with the physical
* implementation.
*/
typedef struct {
/** TX latch switch pin.
* Exact operation is implementation specific.
*/
PinName rf_switch_ctl1;
/** RX latch switch pin.
* Exact operation is implementation specific.
*/
PinName rf_switch_ctl2;
/** TX control pin for transceiver packaged as a module.
* Exact operation is implementation specific.
*/
PinName txctl;
/** RX control pin for transceiver packaged as a module.
* Exact operation is implementation specific.
*/
PinName rxctl;
/** Transceiver switch pin.
* Exact operation is implementation specific. One of the polarities of the
* pin may drive the transceiver in either TX or RX mode.
*/
PinName ant_switch;
/** Power amplifier control pin.
* Exact operation is implementation specific. If defined,
* controls the operation of an external power amplifier.
*/
PinName pwr_amp_ctl;
/** TCXO crystal control pin.
* Exact operation is implementation specific.
*/
PinName tcxo;
} rf_ctrls;
/** Radio driver internal state.
* State machine states definition.
* Helps identify current state of the transceiver.
*/
typedef enum radio_state {
/** IDLE state.
* Radio is in idle state.
*/
RF_IDLE = 0,
/** RX state.
* Radio is receiving.
*/
RF_RX_RUNNING,
/** TX state.
* Radio is transmitting.
*/
RF_TX_RUNNING,
/** CAD state.
* Radio is detecting channel activity.
*/
RF_CAD,
} radio_state_t;
/** Type of the modem.
/** Type of modem.
* [LORA/FSK]
*/
typedef enum modem_type {
/** FSK operation mode.
* Radio is using FSK modulation.
*/
MODEM_FSK = 0,
/** LoRa operation mode.
* Radio is using LoRa modulation.
*/
MODEM_LORA
} radio_modems_t;
/** Radio FSK modem parameters.
*
/** FSK modem parameters.
* Parameters encompassing FSK modulation.
*/
typedef struct radio_fsk_settings {
/**
* Transmit power.
*/
int8_t power;
/**
* Frequency deviation.
*/
uint32_t f_dev;
/**
* Modulation bandwidth.
*/
uint32_t bandwidth;
/**
* Automated frequency correction bandwidth.
*/
uint32_t bandwidth_afc;
/**
* Data rate (SF).
*/
uint32_t datarate;
/**
* Expected preamble length.
*/
uint16_t preamble_len;
bool fix_len;
/**
* This flag turns on if the TX data size is fixed.
*/
bool fix_len;
/**
* Size of outgoing data.
*/
uint8_t payload_len;
bool crc_on;
bool iq_inverted;
bool rx_continuous;
/**
* Turn CRC on/off.
*/
bool crc_on;
/** @deprecated
* Does not apply to FSK. Will be removed.
*/
bool iq_inverted;
/**
* Turn continuous reception mode (such as Class C mode) on/off.
*/
bool rx_continuous;
/**
* Timeout value in milliseconds (ms) after which the radio driver reports
* a timeout if the radio was unable to transmit.
*/
uint32_t tx_timeout;
/**
* Timeout value in symbols (symb) after which the radio driver reports a timeout
* if the radio did not receive a Preamble.
*/
uint32_t rx_single_timeout;
} radio_fsk_settings_t;
/** Radio FSK packet handler state.
*
/** FSK packet handle.
* Contains information about an FSK packet and various metadata.
*/
typedef struct radio_fsk_packet_handler {
uint8_t preamble_detected;
uint8_t sync_word_detected;
int8_t rssi_value;
int32_t afc_value;
uint8_t rx_gain;
/**
* Set to true (1) when a Preamble is detected, otherwise false (0).
*/
uint8_t preamble_detected;
/**
* Set to true (1) when a SyncWord is detected, otherwise false (0).
*/
uint8_t sync_word_detected;
/**
* Storage for RSSI value of the received signal.
*/
int8_t rssi_value;
/**
* Automated frequency correction value.
*/
int32_t afc_value;
/**
* LNA gain value (dbm).
*/
uint8_t rx_gain;
/**
* Size of the received data in bytes.
*/
uint16_t size;
/**
* Keeps track of number of bytes already read from the RX FIFO.
*/
uint16_t nb_bytes;
uint8_t fifo_thresh;
uint8_t chunk_size;
/**
* Stores the FIFO threshold value.
*/
uint8_t fifo_thresh;
/**
* Defines the size of a chunk of outgoing buffer written to
* the FIFO at a unit time. For example, if the size of the data exceeds the FIFO
* limit, a certain sized chunk is written to the FIFO. Later, a FIFO-level
* interrupt enables writing of the remaining data to the FIFO chunk by chunk until
* transmission is complete.
*/
uint8_t chunk_size;
} radio_fsk_packet_handler_t;
/** Radio LoRa modem parameters.
*
/** LoRa modem parameters.
* Parameters encompassing LoRa modulation.
*/
typedef struct radio_lora_settings {
int8_t power;
/**
* Transmit power.
*/
int8_t power;
/**
* Modulation bandwidth.
*/
uint32_t bandwidth;
/**
* Data rate (SF).
*/
uint32_t datarate;
bool low_datarate_optimize;
uint8_t coderate;
/**
* Turn low data rate optimization on/off.
*/
bool low_datarate_optimize;
/**
* Error correction code rate.
*/
uint8_t coderate;
/**
* Preamble length in symbols.
*/
uint16_t preamble_len;
bool fix_len;
uint8_t payload_len;
bool crc_on;
bool freq_hop_on;
uint8_t hop_period;
bool iq_inverted;
bool rx_continuous;
/**
* Set to true if the outgoing payload length is fixed.
*/
bool fix_len;
/**
* Size of outgoing payload.
*/
uint8_t payload_len;
/**
* Turn CRC on/off.
*/
bool crc_on;
/**
* Turn frequency hopping on/off.
*/
bool freq_hop_on;
/**
* Number of symbols between two frequency hops.
*/
uint8_t hop_period;
/**
* Turn IQ inversion on/off. Usually, the end device sends an IQ inverted
* signal, and the base stations do not invert. We recommended sending an
* IQ inverted signal from the device side, so any transmissions from the
* base stations do not interfere with end device transmission.
*/
bool iq_inverted;
/**
* Turn continuous reception mode (such as in Class C) on/off.
*/
bool rx_continuous;
/**
* Timeout in milliseconds (ms) after which the radio driver reports an error
* if the radio was unable to transmit.
*/
uint32_t tx_timeout;
bool public_network;
/**
* Change the network mode to Public or Private.
*/
bool public_network;
} radio_lora_settings_t;
/** Radio LoRa packet handler state.
*
/** LoRa packet
* Contains information about a LoRa packet.
*/
typedef struct radio_lora_packet_handler {
int8_t snr_value;
int8_t rssi_value;
/**
* Signal-to-noise ratio of a received packet.
*/
int8_t snr_value;
/**
* RSSI value in dBm for the received packet.
*/
int8_t rssi_value;
/**
* Size of the transmitted or received packet.
*/
uint8_t size;
} radio_lora_packet_handler_t;
/** Radio settings.
*
/** Global radio settings.
* Contains settings for the overall transceiver operation.
*/
typedef struct radio_settings {
/**
* Current state of the radio, such as RF_IDLE.
*/
uint8_t state;
/**
* Current modem operation, such as MODEM_LORA.
*/
uint8_t modem;
/**
* Current channel of operation.
*/
uint32_t channel;
/**
* Settings for FSK modem part.
*/
radio_fsk_settings_t fsk;
/**
* FSK packet and meta data.
*/
radio_fsk_packet_handler_t fsk_packet_handler;
/**
* Settings for LoRa modem part.
*/
radio_lora_settings_t lora;
/**
* LoRa packet and metadata.
*/
radio_lora_packet_handler_t lora_packet_handler;
} radio_settings_t;
/** Radio driver callback functions.
*
/** Reporting functions for upper layers.
* The radio driver reports various vital events to the upper controlling layers
* using callback functions provided by the upper layers at the initialization
* phase.
*/
typedef struct radio_events {
/**
* Callback when Transmission is done
* Callback when Transmission is done.
*/
mbed::Callback<void()> tx_done;
/**
* Callback when Transmission is timed out
* Callback when Transmission is timed out.
*/
mbed::Callback<void()> tx_timeout;
@ -157,12 +410,12 @@ typedef struct radio_events {
mbed::Callback<void(const uint8_t *payload, uint16_t size, int16_t rssi, int8_t snr)> rx_done;
/**
* Callback when Reception is timed out
* Callback when Reception is timed out.
*/
mbed::Callback<void()> rx_timeout;
/**
* Callback when Reception ends up in error
* Callback when Reception ends up in error.
*/
mbed::Callback<void()> rx_error;
@ -182,16 +435,16 @@ typedef struct radio_events {
} radio_events_t;
/**
* Interface for the radios, contains the main functions that a radio needs, and five callback functions.
* Interface for the radios, containing the main functions that a radio needs, and five callback functions.
*/
class LoRaRadio {
public:
/**
* Registers radio events with the Mbed LoRaWAN stack and undergoes the initialization steps if any.
* Registers radio events with the Mbed LoRaWAN stack and undergoes initialization steps, if any.
*
* @param events The structure containing the driver callback functions.
* @param events Contains driver callback functions.
*/
virtual void init_radio(radio_events_t *events) = 0;
@ -201,19 +454,19 @@ public:
virtual void radio_reset() = 0;
/**
* Put the RF module in the sleep mode.
* Put the RF module in sleep mode.
*/
virtual void sleep(void) = 0;
/**
* Sets the radio in the standby mode.
* Sets the radio to standby mode.
*/
virtual void standby(void) = 0;
/**
* Sets the reception parameters.
* Sets reception parameters.
*
* @param modem The radio modem to be used [0: FSK, 1: LoRa].
* @param modem The radio modem [0: FSK, 1: LoRa].
* @param bandwidth Sets the bandwidth.
* FSK : >= 2600 and <= 250000 Hz
* LoRa: [0: 125 kHz, 1: 250 kHz,
@ -236,13 +489,13 @@ public:
* LoRa: Timeout in symbols
* @param fix_len Fixed length packets [0: variable, 1: fixed].
* @param payload_len Sets the payload length when fixed length is used.
* @param crc_on Enables/disables the CRC [0: OFF, 1: ON].
* @param freq_hop_on Enables/disables the intra-packet frequency hopping [0: OFF, 1: ON] (LoRa only).
* @param crc_on Enables/disables CRC [0: OFF, 1: ON].
* @param freq_hop_on Enables/disables intra-packet frequency hopping [0: OFF, 1: ON] (LoRa only).
* @param hop_period The number of symbols bewteen each hop (LoRa only).
* @param iq_inverted Inverts the IQ signals (LoRa only).
* FSK : N/A (set to 0)
* LoRa: [0: not inverted, 1: inverted]
* @param rx_continuous Sets the reception in continuous mode.
* @param rx_continuous Sets the reception to continuous mode.
* [false: single mode, true: continuous mode]
*/
virtual void set_rx_config(radio_modems_t modem, uint32_t bandwidth,
@ -256,7 +509,7 @@ public:
/**
* Sets the transmission parameters.
*
* @param modem The radio modem to be used [0: FSK, 1: LoRa].
* @param modem The radio modem [0: FSK, 1: LoRa].
* @param power Sets the output power [dBm].
* @param fdev Sets the frequency deviation (FSK only).
* FSK : [Hz]
@ -274,8 +527,8 @@ public:
* LoRa: [1: 4/5, 2: 4/6, 3: 4/7, 4: 4/8]
* @param preamble_len Sets the preamble length.
* @param fix_len Fixed length packets [0: variable, 1: fixed].
* @param crc_on Enables/disables the CRC [0: OFF, 1: ON].
* @param freq_hop_on Enables/disables the intra-packet frequency hopping [0: OFF, 1: ON] (LoRa only).
* @param crc_on Enables/disables CRC [0: OFF, 1: ON].
* @param freq_hop_on Enables/disables intra-packet frequency hopping [0: OFF, 1: ON] (LoRa only).
* @param hop_period The number of symbols between each hop (LoRa only).
* @param iq_inverted Inverts IQ signals (LoRa only)
* FSK : N/A (set to 0).
@ -289,9 +542,9 @@ public:
uint8_t hop_period, bool iq_inverted, uint32_t timeout) = 0;
/**
* Sends the buffer of size
* Sends the packet.
*
* Prepares the packet to be sent and sets the radio in transmission.
* Prepares the packet to be sent and sets the radio to transmission mode.
*
* @param buffer A pointer to the buffer.
* @param size The buffer size.
@ -299,21 +552,21 @@ public:
virtual void send(uint8_t *buffer, uint8_t size) = 0;
/**
* Sets the radio in reception mode.
* Sets the radio to reception mode.
*
* For configuration of the receiver use the `set_rx_config()` API.
* To configure the receiver, use the `set_rx_config()` API.
*/
virtual void receive(void) = 0;
/**
* Sets the carrier frequency
* Sets the carrier frequency.
*
* @param freq Channel RF frequency.
*/
virtual void set_channel(uint32_t freq) = 0;
/**
* Generates a 32 bit random value based on the RSSI readings.
* Generates a 32 bit random value based on RSSI readings.
*
* \remark This function sets the radio in LoRa modem mode and disables all interrupts.
* After calling this function, either `Radio.SetRxConfig` or
@ -333,7 +586,7 @@ public:
/**
* Sets the maximum payload length.
*
* @param modem The radio modem to be used [0: FSK, 1: LoRa].
* @param modem The radio modem [0: FSK, 1: LoRa].
* @param max The maximum payload length in bytes.
*/
virtual void set_max_payload_length(radio_modems_t modem, uint8_t max) = 0;
@ -343,16 +596,16 @@ public:
*
* Updates the sync byte. Applies to LoRa modem only.
*
* @param enable If true, it enables a public network.
* @param enable If true, enables a public network.
*/
virtual void set_public_network(bool enable) = 0;
/**
* Computes the packet time on air for the given payload.
*
* \remark This can only be called once `SetRxConfig` or `SetTxConfig` have been called.
* \remark This can only be called after `SetRxConfig` or `SetTxConfig`.
*
* @param modem The radio modem to be used [0: FSK, 1: LoRa].
* @param modem The radio modem [0: FSK, 1: LoRa].
* @param pkt_len The packet payload length.
* @return The computed `airTime` for the given packet payload length.
*/
@ -362,10 +615,10 @@ public:
* Performs carrier sensing.
*
* Checks for a certain time if the RSSI is above a given threshold.
* This threshold determines whether or not there is a transmission going on
* in the channel already.
* This threshold determines whether or not there is a transmission on
* the channel already.
*
* @param modem The type of the radio modem.
* @param modem The type of radio modem.
* @param freq The carrier frequency.
* @param rssi_threshold The threshold value of RSSI.
* @param max_carrier_sense_time The time set for sensing the channel (ms).
@ -379,7 +632,7 @@ public:
uint32_t max_carrier_sense_time) = 0;
/**
* Sets the radio in CAD mode.
* Sets the radio to CAD mode.
*
*/
virtual void start_cad(void) = 0;
@ -387,11 +640,11 @@ public:
/**
* Checks whether the given RF is in range.
*
* @param frequency The frequency to be checked.
* @param frequency The frequency to check.
*/
virtual bool check_rf_frequency(uint32_t frequency) = 0;
/** Sets the radio in continuous wave transmission mode.
/** Sets the radio to continuous wave transmission mode.
*
* @param freq The RF frequency of the channel.
* @param power The output power [dBm].
@ -405,9 +658,10 @@ public:
virtual void lock(void) = 0;
/**
* Releases the exclusive access to this radio.
* Releases exclusive access to this radio.
*/
virtual void unlock(void) = 0;
};
#endif // LORARADIO_H_
/** @}*/