mirror of
https://github.com/manuelbl/ttn-esp32.git
synced 2025-07-13 22:42:52 +02:00
Improved API documentation
This commit is contained in:
Manuel Bleichenbacher
@ -440,8 +440,8 @@ public:
|
||||
/**
|
||||
* @brief Resets the LoRaWAN radio.
|
||||
*
|
||||
* To restart communication, join() must be called.
|
||||
* It neither clears the provisioned keys nor the configured pins.
|
||||
* To restart communication, @ref join() must be called.
|
||||
* Clears neither the provisioned keys nor the configured pins.
|
||||
*/
|
||||
void reset() { ttn_reset(); }
|
||||
|
||||
@ -453,8 +453,8 @@ public:
|
||||
*
|
||||
* @param spi_host The SPI bus/peripherial to use (`SPI_HOST`, `HSPI_HOST` or `VSPI_HOST`).
|
||||
* @param nss The GPIO pin number connected to the radio chip's NSS pin (serving as the SPI chip select)
|
||||
* @param rxtx The GPIO pin number connected to the radio chip's RXTX pin (`TTN_NOT_CONNECTED` if not connected)
|
||||
* @param rst The GPIO pin number connected to the radio chip's RST pin (`TTN_NOT_CONNECTED` if not connected)
|
||||
* @param rxtx The GPIO pin number connected to the radio chip's RXTX pin (@ref TTN_NOT_CONNECTED if not connected)
|
||||
* @param rst The GPIO pin number connected to the radio chip's RST pin (@ref TTN_NOT_CONNECTED if not connected)
|
||||
* @param dio0 The GPIO pin number connected to the radio chip's DIO0 pin
|
||||
* @param dio1 The GPIO pin number connected to the radio chip's DIO1 pin
|
||||
*/
|
||||
@ -483,7 +483,7 @@ public:
|
||||
* The provided DevEUI, AppEUI/JoinEUI and AppKey are saved in non-volatile memory. Before
|
||||
* this function is called, `nvs_flash_init()` must have been called once.
|
||||
*
|
||||
* Call join() to activate the device.
|
||||
* Call @ref join() to activate the device.
|
||||
*
|
||||
* @param devEui DevEUI (16 character string with hexadecimal data)
|
||||
* @param appEui AppEUI/JoinEUI of the device (16 character string with hexadecimal data)
|
||||
@ -497,7 +497,7 @@ public:
|
||||
* and without activating it.
|
||||
*
|
||||
* The generated DevEUI and the provided AppEUI/JoinEUI and AppKey are saved in non-volatile memory. Before
|
||||
* this function is called, 'nvs_flash_init' must have been called once.
|
||||
* this function is called, `nvs_flash_init` must have been called once.
|
||||
*
|
||||
* The DevEUI is generated by retrieving the ESP32's WiFi MAC address and expanding it into a DevEUI
|
||||
* by adding FFFE in the middle. So the MAC address A0:B1:C2:01:02:03 becomes the EUI A0B1C2FFFE010203.
|
||||
@ -508,7 +508,7 @@ public:
|
||||
* it is okay for that the LoRa communication of your application can easily be intercepted and that
|
||||
* forged data can be injected.
|
||||
*
|
||||
* Call join() to activate.
|
||||
* Call @ref join() to activate.
|
||||
*
|
||||
* @param appEui AppEUI/JoinEUI of the device (16 character string with hexadecimal data)
|
||||
* @param appKey AppKey of the device (32 character string with hexadecimal data)
|
||||
@ -528,7 +528,7 @@ public:
|
||||
* by the provisioning task.
|
||||
*
|
||||
* If the device has already been provisioned (stored data in NVS, call of provision()
|
||||
* or call of join(const char*, const char*, const char*), this function
|
||||
* or call of @ref join(const char*, const char*, const char*), this function
|
||||
* immediately returns.
|
||||
*/
|
||||
void waitForProvisioning() { ttn_wait_for_provisioning(); }
|
||||
@ -570,7 +570,7 @@ public:
|
||||
* @param length number of bytes to be transmitted
|
||||
* @param port port (defaults to 1)
|
||||
* @param confirm flag indicating if a confirmation should be requested. Defaults to `false`
|
||||
* @return `kTTNSuccessfulTransmission` for successful transmission, `kTTNErrorTransmissionFailed` for failed transmission, `kTTNErrorUnexpected` for unexpected error
|
||||
* @return @ref kTTNSuccessfulTransmission for successful transmission, @ref kTTNErrorTransmissionFailed for failed transmission, @ref kTTNErrorUnexpected for unexpected error
|
||||
*/
|
||||
TTNResponseCode transmitMessage(const uint8_t *payload, size_t length, ttn_port_t port = 1, bool confirm = false)
|
||||
{
|
||||
@ -585,9 +585,9 @@ public:
|
||||
* parameters. The values are only valid during the duration of the
|
||||
* callback. So they must be immediately processed or copied.
|
||||
*
|
||||
* Messages are received as a result of transmitMessage(). The callback is called
|
||||
* in the task that called any of these functions and it occurs before these functions
|
||||
* return control to the caller.
|
||||
* Messages are received as a result of a call to @ref transmitMessage(). The callback is called
|
||||
* in the task that called this function and it occurs before this function
|
||||
* returns control to the caller.
|
||||
*
|
||||
* @param callback the callback function
|
||||
*/
|
||||
@ -595,7 +595,7 @@ public:
|
||||
|
||||
/**
|
||||
* @brief Checks if DevEUI, AppEUI/JoinEUI and AppKey have been stored in non-volatile storage
|
||||
* or have been provided as by a call to join(const char*, const char*, const char*).
|
||||
* or have been provided as by a call to @ref join(const char*, const char*, const char*).
|
||||
*
|
||||
* @return `true` if they are stored, complete and of the correct size, `false` otherwise
|
||||
*/
|
||||
@ -635,7 +635,7 @@ public:
|
||||
* If ADR is enabled, it's is used as the initial data rate and later adjusted depending
|
||||
* on the RF conditions. If ADR is disabled, it is used for all uplink messages.
|
||||
*
|
||||
* @param data_rate data rate (use constants kTTNDataRate_xx)
|
||||
* @param data_rate data rate (use constants of enum @ref TTNDataRate)
|
||||
*/
|
||||
void setDataRate(TTNDataRate data_rate) { ttn_set_data_rate(static_cast<ttn_data_rate_t>(data_rate)); }
|
||||
|
||||
@ -643,7 +643,7 @@ public:
|
||||
* @brief Sets the maximum power for transmission
|
||||
*
|
||||
* The power is specified in dBm and sets the power emitted by the radio.
|
||||
* If the antenna has a gain, it must be substracted fro the specified value to
|
||||
* If the antenna has a gain, it must be substracted from the specified value to
|
||||
* achieve the correct transmission power.
|
||||
*
|
||||
* @param tx_pow power, in dBm
|
||||
@ -653,7 +653,7 @@ public:
|
||||
/**
|
||||
* @brief Stops all activies and shuts down the RF module and the background tasks.
|
||||
*
|
||||
* To restart communication, startup() and join() must be called.
|
||||
* To restart communication, @ref startup() and @ref join() must be called.
|
||||
* it neither clears the provisioned keys nor the configured pins.
|
||||
*/
|
||||
void shutdown() { ttn_shutdown(); }
|
||||
@ -673,7 +673,7 @@ public:
|
||||
|
||||
/**
|
||||
* @brief Gets the RF settings for the specified window
|
||||
* @param window RX/TX windows (valid values are `kTTNTxWindow`, `kTTNRx1Window` and `kTTNRx2Window`)
|
||||
* @param window RX/TX window (valid values are @ref kTTNTxWindow, @ref kTTNRx1Window and @ref kTTNRx2Window)
|
||||
*/
|
||||
TTNRFSettings getRFSettings(TTNRxTxWindow window);
|
||||
|
||||
|
||||
@ -11,9 +11,7 @@
|
||||
*******************************************************************************/
|
||||
|
||||
/**
|
||||
* @file ttn.h
|
||||
*
|
||||
* C interface for ttn-esp32
|
||||
* @defgroup c_api C API
|
||||
*/
|
||||
|
||||
#ifndef TTN_C_H
|
||||
@ -27,6 +25,12 @@
|
||||
extern "C" {
|
||||
#endif
|
||||
|
||||
/**
|
||||
* @addtogroup c_api
|
||||
*
|
||||
* @{
|
||||
*/
|
||||
|
||||
|
||||
/**
|
||||
* @brief Constant for indicating that a pin is not connected
|
||||
@ -44,9 +48,13 @@ typedef uint8_t ttn_port_t;
|
||||
*/
|
||||
typedef enum
|
||||
{
|
||||
/** @brief Transmission failed error */
|
||||
TTN_ERROR_TRANSMISSION_FAILED = -1,
|
||||
/** @brief Unexpected or internal error */
|
||||
TTN_ERROR_UNEXPECTED = -10,
|
||||
/** @brief Successful transmission of an uplink message */
|
||||
TTN_SUCCESSFUL_TRANSMISSION = 1,
|
||||
/** @brief Successful receipt of a downlink message */
|
||||
TTN_SUCCESSFUL_RECEIVE = 2
|
||||
} ttn_response_code_t;
|
||||
|
||||
@ -427,14 +435,16 @@ typedef void (*ttn_message_cb)(const uint8_t* payload, size_t length, ttn_port_t
|
||||
|
||||
|
||||
/**
|
||||
* @brief Constructs a new The Things Network device instance.
|
||||
* @brief Initializes The Things Network device instance.
|
||||
*
|
||||
* Call this function once at the start of the program and before all other TTN functions.
|
||||
*/
|
||||
void ttn_init(void);
|
||||
|
||||
/**
|
||||
* @brief Resets the LoRaWAN radio.
|
||||
*
|
||||
* To restart communication, join() must be called.
|
||||
* To restart communication, @ref ttn_join() or @ref ttn_join_provisioned() must be called.
|
||||
* It neither clears the provisioned keys nor the configured pins.
|
||||
*/
|
||||
void ttn_reset(void);
|
||||
@ -447,8 +457,8 @@ void ttn_reset(void);
|
||||
*
|
||||
* @param spi_host The SPI bus/peripherial to use (`SPI_HOST`, `HSPI_HOST` or `VSPI_HOST`).
|
||||
* @param nss The GPIO pin number connected to the radio chip's NSS pin (serving as the SPI chip select)
|
||||
* @param rxtx The GPIO pin number connected to the radio chip's RXTX pin (`TTN_NOT_CONNECTED` if not connected)
|
||||
* @param rst The GPIO pin number connected to the radio chip's RST pin (`TTN_NOT_CONNECTED` if not connected)
|
||||
* @param rxtx The GPIO pin number connected to the radio chip's RXTX pin (@ref TTN_NOT_CONNECTED if not connected)
|
||||
* @param rst The GPIO pin number connected to the radio chip's RST pin (@ref TTN_NOT_CONNECTED if not connected)
|
||||
* @param dio0 The GPIO pin number connected to the radio chip's DIO0 pin
|
||||
* @param dio1 The GPIO pin number connected to the radio chip's DIO1 pin
|
||||
*/
|
||||
@ -474,7 +484,7 @@ void ttn_set_subband(int band);
|
||||
* The provided DevEUI, AppEUI/JoinEUI and AppKey are saved in non-volatile memory. Before
|
||||
* this function is called, `nvs_flash_init()` must have been called once.
|
||||
*
|
||||
* Call join() to activate the device.
|
||||
* Call @ref ttn_join_provisioned() to activate the device.
|
||||
*
|
||||
* @param dev_eui DevEUI (16 character string with hexadecimal data)
|
||||
* @param app_eui AppEUI/JoinEUI of the device (16 character string with hexadecimal data)
|
||||
@ -488,7 +498,7 @@ bool ttn_provision(const char *dev_eui, const char *app_eui, const char *app_key
|
||||
* and without activating it.
|
||||
*
|
||||
* The generated DevEUI and the provided AppEUI/JoinEUI and AppKey are saved in non-volatile memory. Before
|
||||
* this function is called, 'nvs_flash_init' must have been called once.
|
||||
* this function is called, `nvs_flash_init` must have been called once.
|
||||
*
|
||||
* The DevEUI is generated by retrieving the ESP32's WiFi MAC address and expanding it into a DevEUI
|
||||
* by adding FFFE in the middle. So the MAC address A0:B1:C2:01:02:03 becomes the EUI A0B1C2FFFE010203.
|
||||
@ -499,7 +509,7 @@ bool ttn_provision(const char *dev_eui, const char *app_eui, const char *app_key
|
||||
* it is okay for that the LoRa communication of your application can easily be intercepted and that
|
||||
* forged data can be injected.
|
||||
*
|
||||
* Call join() to activate.
|
||||
* Call @ref ttn_join_provisioned() to activate.
|
||||
*
|
||||
* @param app_eui AppEUI/JoinEUI of the device (16 character string with hexadecimal data)
|
||||
* @param app_key AppKey of the device (32 character string with hexadecimal data)
|
||||
@ -519,12 +529,11 @@ void ttn_start_provisioning_task(void);
|
||||
* by the provisioning task.
|
||||
*
|
||||
* If the device has already been provisioned (stored data in NVS, call of provision()
|
||||
* or call of join(const char*, const char*, const char*), this function
|
||||
* immediately returns.
|
||||
* or call of @ref ttn_join(), this function immediately returns.
|
||||
*/
|
||||
void ttn_wait_for_provisioning(void);
|
||||
|
||||
/**
|
||||
/**
|
||||
* @brief Activates the device via OTAA.
|
||||
*
|
||||
* The DevEUI, AppEUI/JoinEUI and AppKey must have already been provisioned by a call to provision().
|
||||
@ -561,7 +570,7 @@ bool ttn_join(const char *dev_eui, const char *app_eui, const char *app_key);
|
||||
* @param length number of bytes to be transmitted
|
||||
* @param port port (use 1 as default)
|
||||
* @param confirm flag indicating if a confirmation should be requested (use `false` as default)
|
||||
* @return `kTTNSuccessfulTransmission` for successful transmission, `kTTNErrorTransmissionFailed` for failed transmission, `kTTNErrorUnexpected` for unexpected error
|
||||
* @return @ref TTN_SUCCESSFUL_TRANSMISSION for successful transmission, @ref TTN_ERROR_TRANSMISSION_FAILED for failed transmission, @ref TTN_ERROR_UNEXPECTED for unexpected error
|
||||
*/
|
||||
ttn_response_code_t ttn_transmit_message(const uint8_t *payload, size_t length, ttn_port_t port, bool confirm);
|
||||
|
||||
@ -573,9 +582,9 @@ ttn_response_code_t ttn_transmit_message(const uint8_t *payload, size_t length,
|
||||
* parameters. The values are only valid during the duration of the
|
||||
* callback. So they must be immediately processed or copied.
|
||||
*
|
||||
* Messages are received as a result of transmitMessage(). The callback is called
|
||||
* in the task that called any of these functions and it occurs before these functions
|
||||
* return control to the caller.
|
||||
* Messages are received as a result of @ref ttn_transmit_message(). The callback is called
|
||||
* in the task that called this function and it occurs before this function
|
||||
* returns control to the caller.
|
||||
*
|
||||
* @param callback the callback function
|
||||
*/
|
||||
@ -583,7 +592,7 @@ void ttn_on_message(ttn_message_cb callback);
|
||||
|
||||
/**
|
||||
* @brief Checks if DevEUI, AppEUI/JoinEUI and AppKey have been stored in non-volatile storage
|
||||
* or have been provided as by a call to join(const char*, const char*, const char*).
|
||||
* or have been provided as by a call to @ref ttn_join().
|
||||
*
|
||||
* @return `true` if they are stored, complete and of the correct size, `false` otherwise
|
||||
*/
|
||||
@ -623,7 +632,7 @@ void ttn_set_adr_enabled(bool enabled);
|
||||
* If ADR is enabled, it's is used as the initial data rate and later adjusted depending
|
||||
* on the RF conditions. If ADR is disabled, it is used for all uplink messages.
|
||||
*
|
||||
* @param data_rate data rate (use constants TTN_DR_xx)
|
||||
* @param data_rate data rate (use constants of enum @ref ttn_data_rate_t)
|
||||
*/
|
||||
void ttn_set_data_rate(ttn_data_rate_t data_rate);
|
||||
|
||||
@ -631,7 +640,7 @@ void ttn_set_data_rate(ttn_data_rate_t data_rate);
|
||||
* @brief Sets the maximum power for transmission
|
||||
*
|
||||
* The power is specified in dBm and sets the power emitted by the radio.
|
||||
* If the antenna has a gain, it must be substracted fro the specified value to
|
||||
* If the antenna has a gain, it must be substracted from the specified value to
|
||||
* achieve the correct transmission power.
|
||||
*
|
||||
* @param tx_pow power, in dBm
|
||||
@ -641,7 +650,7 @@ void ttn_set_max_tx_pow(int tx_pow);
|
||||
/**
|
||||
* @brief Stops all activies and shuts down the RF module and the background tasks.
|
||||
*
|
||||
* To restart communication, startup() and join() must be called.
|
||||
* To restart communication, @ref ttn_startup() and @ref ttn_join() must be called.
|
||||
* it neither clears the provisioned keys nor the configured pins.
|
||||
*/
|
||||
void ttn_shutdown(void);
|
||||
@ -661,7 +670,7 @@ ttn_rx_tx_window_t ttn_rx_tx_window(void);
|
||||
|
||||
/**
|
||||
* @brief Gets the RF settings for the specified window
|
||||
* @param window RX/TX windows (valid values are `kTTNTxWindow`, `kTTNRx1Window` and `kTTNRx2Window`)
|
||||
* @param window RX/TX window (valid values are @ref TTN_WINDOW_TX, @ref TTN_WINDOW_RX1 and @ref TTN_WINDOW_RX2
|
||||
*/
|
||||
ttn_rf_settings_t ttn_get_rf_settings(ttn_rx_tx_window_t window);
|
||||
|
||||
@ -693,6 +702,11 @@ ttn_rf_settings_t ttn_rx2_settings(void);
|
||||
int ttn_rssi();
|
||||
|
||||
|
||||
/**
|
||||
* @}
|
||||
*/
|
||||
|
||||
|
||||
#ifdef __cplusplus
|
||||
}
|
||||
#endif
|
||||
|
||||
Reference in New Issue
Block a user