mirror of
https://github.com/manuelbl/ttn-esp32.git
synced 2024-09-28 04:13:59 +02:00
Improved API documentation
This commit is contained in:
Manuel Bleichenbacher
parent
5c1db030f2
commit
17e432d714
@ -633,7 +633,7 @@ FORCE_LOCAL_INCLUDES = NO
|
||||
# documentation for inline members.
|
||||
# The default value is: YES.
|
||||
|
||||
INLINE_INFO = YES
|
||||
INLINE_INFO = NO
|
||||
|
||||
# If the SORT_MEMBER_DOCS tag is set to YES then doxygen will sort the
|
||||
# (detailed) documentation of file and class members alphabetically by member
|
||||
@ -865,7 +865,7 @@ WARN_LOGFILE =
|
||||
# Note: If this tag is empty the current directory is searched.
|
||||
|
||||
INPUT = ../include \
|
||||
mainpage.h
|
||||
doc.dox
|
||||
|
||||
# This tag can be used to specify the character encoding of the source files
|
||||
# that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
|
||||
|
||||
21
doc/doc.dox
Normal file
21
doc/doc.dox
Normal file
@ -0,0 +1,21 @@
|
||||
/*!
|
||||
\mainpage ttn-esp32 API Documentation
|
||||
|
||||
ttn-esp32 is a C and C++ library for the ESP-IDF (ESP32) framework
|
||||
for The Things Network library end devices using Semtech SX127x chips.
|
||||
|
||||
|
||||
\section cplusplus C++ API
|
||||
|
||||
\ref TheThingsNetwork class
|
||||
|
||||
\ref TTNRFSettings struct
|
||||
|
||||
|
||||
\section c C API
|
||||
|
||||
\ref c_api
|
||||
|
||||
\ref ttn_rf_settings_t struct
|
||||
|
||||
*/
|
||||
@ -1,2 +1,3 @@
|
||||
#!/bin/sh
|
||||
rm -rf html
|
||||
doxygen Doxyfile
|
||||
|
||||
@ -1,8 +0,0 @@
|
||||
/*! \mainpage ttn-esp32 – The Things Network library for ESP32
|
||||
*
|
||||
* This library for ESP-IDF (ESP32) supports devices with Semtech SX127x chips.
|
||||
*
|
||||
* \ref TheThingsNetwork class
|
||||
*
|
||||
* \ref ttn.h C functions
|
||||
*/
|
||||
@ -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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user