From 701bb055a2b266bda899f9293ac9bca6ab178743 Mon Sep 17 00:00:00 2001 From: Mel W Date: Thu, 10 Jan 2019 15:06:23 +0200 Subject: [PATCH] Writer review Grammatical changes, passive -> active in some places, and future -> present. --- features/lorawan/LoRaRadio.h | 240 +++++++++++++++++------------------ 1 file changed, 120 insertions(+), 120 deletions(-) diff --git a/features/lorawan/LoRaRadio.h b/features/lorawan/LoRaRadio.h index 0442f52c97..bab586182c 100644 --- a/features/lorawan/LoRaRadio.h +++ b/features/lorawan/LoRaRadio.h @@ -29,196 +29,196 @@ /** * Structure to hold RF controls for LoRa Radio. * SX1276 have an extra control for the crystal (used in DISCO-L072CZ). - * A subset of these pins may be used by driver in accordance with the physical + * A subset of these pins may be used by the driver in accordance with the physical * implementation. */ typedef struct { - /** TX latch switch pin + /** TX latch switch pin. * Exact operation is implementation specific. */ PinName rf_switch_ctl1; - /** RX latch switch pin + /** RX latch switch pin. * Exact operation is implementation specific. */ PinName rf_switch_ctl2; - /** TX control pin for transceiver packaged as a module + /** 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 + /** RX control pin for transceiver packaged as a module. * Exact operation is implementation specific. */ PinName rxctl; - /** Transceiver switch pin + /** 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, would be used to - * control the operation of an external power amplifier. + /** 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 + /** TCXO crystal control pin. * Exact operation is implementation specific. */ PinName tcxo; } rf_ctrls; /** Radio driver internal state. - * Help to identify current state of the transceiver. + * Helps identify current state of the transceiver. */ typedef enum radio_state { - /** IDLE state - * Rdio is in idle state. + /** IDLE state. + * Radio is in idle state. */ RF_IDLE = 0, - /** RX state + /** RX state. * Radio is receiving. */ RF_RX_RUNNING, - /** TX state - * Radio is in transmitting. + /** TX state. + * Radio is transmitting. */ RF_TX_RUNNING, - /** CAD state + /** 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 + /** FSK operation mode. * Radio is using FSK modulation. */ MODEM_FSK = 0, - /** LoRa operation mode + /** LoRa operation mode. * Radio is using LoRa modulation. */ MODEM_LORA } radio_modems_t; -/** FSK modem parameters +/** FSK modem parameters. * Parameters encompassing FSK modulation. */ typedef struct radio_fsk_settings { /** - * Transmit power + * Transmit power. */ int8_t power; /** - * Frequency deviation + * Frequency deviation. */ uint32_t f_dev; /** - * Modulation bandwidth + * Modulation bandwidth. */ uint32_t bandwidth; /** - * Automated frequency correction bandwidth + * Automated frequency correction bandwidth. */ uint32_t bandwidth_afc; /** - * Data rate (SF) to be used + * Data rate (SF). */ uint32_t datarate; /** - * Expected preamble length + * Expected preamble length. */ uint16_t preamble_len; /** - * If the TX data size is fixed, this flag is turned on + * This flag turns on if the TX data size is fixed. */ bool fix_len; /** - * Size of the outgoing data + * Size of outgoing data. */ uint8_t payload_len; /** - * Turn on/off CRC + * Turn CRC on/off. */ bool crc_on; /** @deprecated - * Does not apply to FSK, will be removed. + * Does not apply to FSK. Will be removed. */ bool iq_inverted; /** - * Turn on/off continuous reception mode (e.g., Class C mode) + * Turn continuous reception mode (such as Class C mode) on/off. */ bool rx_continuous; /** - * Timeout value in milliseconds (ms) after which radio driver reports - * a timeout if the radio was not able to transmit + * 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 radio driver reports a timeout - * if the radio did not receive a Preamble + * 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; /** FSK packet handle. - * Contains information about the an FSK packet and various meta data. + * Contains information about an FSK packet and various metadata. */ typedef struct radio_fsk_packet_handler { /** - * Set to true (1) when a Preamble is detected otherwise false (0) + * 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) + * 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 + * Storage for RSSI value of the received signal. */ int8_t rssi_value; /** - * Automated frequency correction value + * Automated frequency correction value. */ int32_t afc_value; /** - * LNA gain value (dbm) + * LNA gain value (dbm). */ uint8_t rx_gain; /** - * Size of the received data in bytes + * Size of the received data in bytes. */ uint16_t size; /** - * Keeps track of number of bytes already read from the RX FIFO + * Keeps track of number of bytes already read from the RX FIFO. */ uint16_t nb_bytes; @@ -228,172 +228,172 @@ typedef struct radio_fsk_packet_handler { uint8_t fifo_thresh; /** - * Defines the size of a chunk of outgoing buffer which will be written to - * the FIFO at a unit time. For example, if the size of the data exceeds FIFO - * limit, a certain sized chunk will be written to the FIFO and later a FIFO level - * interrupt will enable writing of the remaining data to the FIFO chunk by chunk until - * everything is transmitted. + * 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; -/** LoRa modem parameters - * Parameters encompassing LoRa modulation +/** LoRa modem parameters. + * Parameters encompassing LoRa modulation. */ typedef struct radio_lora_settings { /** - * Transmit power + * Transmit power. */ int8_t power; /** - * Modulation bandwidth + * Modulation bandwidth. */ uint32_t bandwidth; /** - * Data rate (SF) to be used + * Data rate (SF). */ uint32_t datarate; /** - * Turn on/off low data rate optimization + * Turn low data rate optimization on/off. */ bool low_datarate_optimize; /** - * Error correction code rate to be used + * Error correction code rate. */ uint8_t coderate; /** - * Preamble length in symbols + * Preamble length in symbols. */ uint16_t preamble_len; /** - * Set to true if the outgoing payload length is fixed + * Set to true if the outgoing payload length is fixed. */ bool fix_len; /** - * Size of outgoing payload + * Size of outgoing payload. */ uint8_t payload_len; /** - * Turn on/off CRC + * Turn CRC on/off. */ bool crc_on; /** - * Turn frequency hopping on/off + * Turn frequency hopping on/off. */ bool freq_hop_on; /** - * Number of symbols between two frequency hops + * Number of symbols between two frequency hops. */ uint8_t hop_period; /** - * Turn on/off IQ inversion. Usually the end-devices will send an IQ inverted - * signal and the base stations will not invert. It's recommended to send an - * IQ inverted signal from the device side so that any transmission from the - * base stations do not interfere with an end-device transmission. + * 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 on/off continuous reception mode (e.g., in Class C) + * Turn continuous reception mode (such as in Class C) on/off. */ bool rx_continuous; /** - * Timeout in milliseconds (ms) after which the radio driver will report an error - * if the radio was not able to transmit. + * Timeout in milliseconds (ms) after which the radio driver reports an error + * if the radio was unable to transmit. */ uint32_t tx_timeout; /** - * Change the network mode to Public or Private + * Change the network mode to Public or Private. */ bool public_network; } radio_lora_settings_t; /** LoRa packet - * Contains information about a LoRa packet + * Contains information about a LoRa packet. */ typedef struct radio_lora_packet_handler { /** - * Signal to noise ratio of a received packet + * Signal-to-noise ratio of a received packet. */ int8_t snr_value; /** - * RSSI value in dBm for the received packet + * RSSI value in dBm for the received packet. */ int8_t rssi_value; /** - * Size of the transmitted or received packet + * Size of the transmitted or received packet. */ uint8_t size; } radio_lora_packet_handler_t; -/** Global radio settings - * Contains settings for the overall transceiver operation +/** Global radio settings. + * Contains settings for the overall transceiver operation. */ typedef struct radio_settings { /** - * Current state of the radio, e.g., RF_IDLE + * Current state of the radio, such as RF_IDLE. */ uint8_t state; /** - * Current modem operation, e.g., MODEM_LORA + * Current modem operation, such as MODEM_LORA. */ uint8_t modem; /** - * Current channel of operation + * Current channel of operation. */ uint32_t channel; /** - * Settings for FSK modem part + * Settings for FSK modem part. */ radio_fsk_settings_t fsk; /** - * FSK packet and meta data + * FSK packet and meta data. */ radio_fsk_packet_handler_t fsk_packet_handler; /** - * Settings for LoRa modem part + * Settings for LoRa modem part. */ radio_lora_settings_t lora; /** - * LoRa packet and meta data + * LoRa packet and metadata. */ radio_lora_packet_handler_t lora_packet_handler; } radio_settings_t; -/** Reporting functions for upper layers - * Radio driver reports various vital events to the upper controlling layers - * using the callback functions provided by the upper layers at the initialization +/** 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 tx_done; /** - * Callback when Transmission is timed out + * Callback when Transmission is timed out. */ mbed::Callback tx_timeout; @@ -410,12 +410,12 @@ typedef struct radio_events { mbed::Callback rx_done; /** - * Callback when Reception is timed out + * Callback when Reception is timed out. */ mbed::Callback rx_timeout; /** - * Callback when Reception ends up in error + * Callback when Reception ends up in error. */ mbed::Callback rx_error; @@ -435,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; @@ -454,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, @@ -489,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, @@ -509,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] @@ -527,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). @@ -542,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. @@ -552,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 @@ -586,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; @@ -596,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. */ @@ -615,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). @@ -632,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; @@ -640,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]. @@ -658,7 +658,7 @@ public: virtual void lock(void) = 0; /** - * Releases the exclusive access to this radio. + * Releases exclusive access to this radio. */ virtual void unlock(void) = 0; };