localhorst/ttn-esp32
1
0
Fork 0
mirror of https://github.com/manuelbl/ttn-esp32.git synced 2025-07-13 22:42:52 +02:00
Code Issues Packages Projects Releases Wiki Activity

Improve documentation

Browse Source
This commit is contained in:
Manuel Bl
2020-08-02 19:53:02 +02:00
parent bb41c4960f
commit fffe7bd8b3
5 changed files with 2931 additions and 51 deletions
Download Patch File Download Diff File Expand all files Collapse all files

93
include/TheThingsNetwork.h
View File

@ -156,67 +156,65 @@ typedef void (*TTNMessageCallback)(const uint8_t* payload, size_t length, port_t
/**
* @brief TTN device
*
* The 'TheThingsNetwork' class enables ESP32 devices with SX1272/73/76/77/78/79 LoRaWAN chips
* This class enables ESP32 devices with SX1272/73/76/77/78/79 LoRaWAN chips
* to communicate via The Things Network.
*
* Only one instance of this class must be created.
* Only one instance of this class may be created.
*/
class TheThingsNetwork
{
public:
/**
* @brief Construct a new The Things Network device instance.
* @brief Constructs a new The Things Network device instance.
*/
TheThingsNetwork();
/**
* @brief Destroy the The Things Network device instance.
* @brief Destroys the The Things Network device instance.
*/
~TheThingsNetwork();
/**
* @brief Reset the LoRaWAN radio.
* @brief Resets the LoRaWAN radio.
*
* To restart communication, `join()` must be called.
* Neither clears the provisioned keys nor the configured pins.
* To restart communication, join() must be called.
* It neither clears the provisioned keys nor the configured pins.
*/
void reset();
/**
* @brief Configures the pins used to communicate with the LoRaWAN radio chip.
*
*
* Before calling this member function, the SPI bus needs to be configured using `spi_bus_initialize()`.
* Additionally, `gpio_install_isr_service()` must have been called to initialize the GPIO ISR handler service.
*
* @param spi_host The SPI bus/peripherial to use (SPI_HOST, HSPI_HOST or VSPI_HOST).
* @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 (`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 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
*/
void configurePins(spi_host_device_t spi_host, uint8_t nss, uint8_t rxtx, uint8_t rst, uint8_t dio0, uint8_t dio1);
/**
* @brief Sets the information needed to activate the device via OTAA, without actually activating.
* @brief Sets the credentials needed to activate the device via OTAA, without activating it.
*
* The provided device EUI, app EUI and app key 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.
*
* Call join() without arguments to activate.
* Call join() to activate the device.
*
* @param devEui Device EUI (16 character string with hexadecimal data)
* @param appEui Application EUI of the device (16 character string with hexadecimal data)
* @param appKey App Key of the device (32 character string with hexadecimal data)
* @return true if the provisioning was successful
* @return false if the provisioning failed
* @return `true` if the provisioning was successful, `false` if the provisioning failed
*/
bool provision(const char *devEui, const char *appEui, const char *appKey);
/**
* @brief Sets the information needed to activate the device via OTAA, using the MAC to generate the device EUI
* and without actually activating.
* and without activating it.
*
* The generated device EUI and the provided app EUI and app key are saved in non-volatile memory. Before
* this function is called, 'nvs_flash_init' must have been called once.
@ -230,47 +228,45 @@ 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() without arguments to activate.
* Call join() to activate.
*
* @param appEui Application EUI of the device (16 character string with hexadecimal data)
* @param appKey App Key of the device (32 character string with hexadecimal data)
* @return true if the provisioning was successful
* @return false if the provisioning failed
* @return `true` if the provisioning was successful, `false` if the provisioning failed
*/
bool provisionWithMAC(const char *appEui, const char *appKey);
/**
* @brief Start task that listens on configured UART for AT commands.
* @brief Starts task listening on configured UART for AT commands.
*
* Run 'make menuconfig' to configure it.
* Run `make menuconfig` to configure it.
*/
void startProvisioningTask();
/**
* @brief Wait until the device EUI, app EUI and app key have been provisioned
* via the provisioning task.
* @brief Waits until the device EUI, app EUI and app key have been provisioned
* by the provisioning task.
*
* If device is already provisioned (stored data in NVS, call to 'provision()'
* or call to 'join(const char*, const char*, const char*)', this function
* 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.
*/
void waitForProvisioning();
/**
* @brief Activate the device via OTAA.
* @brief Activates the device via OTAA.
*
* The app EUI, app key and dev EUI must already have been provisioned by a call to 'provision()'.
* Before this function is called, 'nvs_flash_init' must have been called once.
* The app EUI, app key and dev EUI must have already been provisioned by a call to provision().
* Before this function is called, `nvs_flash_init()` must have been called once.
*
* The function blocks until the activation has completed or failed.
*
* @return true if the activation was succeful
* @return false if the activation failed
* @return `true` if the activation was succesful, `false` if the activation failed
*/
bool join();
/**
* @brief Set the device EUI, app EUI and app key and activate the device via OTAA.
* @brief Sets the device EUI, app EUI and app key and activate the device via OTAA.
*
* The device EUI, app EUI and app key are NOT saved in non-volatile memory.
*
@ -279,13 +275,12 @@ public:
* @param devEui Device EUI (16 character string with hexadecimal data)
* @param appEui Application EUI of the device (16 character string with hexadecimal data)
* @param appKey App Key of the device (32 character string with hexadecimal data)
* @return true if the activation was succeful
* @return false if the activation failed
* @return `true` if the activation was succesful, `false` if the activation failed
*/
bool join(const char *devEui, const char *appEui, const char *appKey);
/**
* @brief Transmit a message
* @brief Transmits a message
*
* The function blocks until the message could be transmitted and a message has been received
* in the subsequent receive window (or the window expires). Additionally, the function will
@ -293,23 +288,21 @@ public:
*
* @param payload bytes to be transmitted
* @param length number of bytes to be transmitted
* @param port port (default to 1)
* @param confirm flag indicating if a confirmation should be requested. Default to 'false'
* @return TkTTNSuccessfulTransmission Successful transmission
* @return kTTNErrorTransmissionFailed Transmission failed
* @return TkTTNErrorUnexpected Unexpected error
* @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
*/
TTNResponseCode transmitMessage(const uint8_t *payload, size_t length, port_t port = 1, bool confirm = false);
/**
* @brief Set the function to be called when a message is received
* @brief Sets the function to be called when a message is received
*
* When a message is received, the specified function is called. The
* message, its length and the port number are provided as
* 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
* 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.
*
@ -319,10 +312,9 @@ public:
/**
* @brief Checks if device EUI, app EUI and app key 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 join(const char*, const char*, const char*).
*
* @return true if they are stored, complete and of the correct size
* @return false otherwise
* @return `true` if they are stored, complete and of the correct size, `false` otherwise
*/
bool isProvisioned();
@ -340,8 +332,7 @@ public:
/**
* Returns whether Adaptive Data Rate (ADR) is enabled.
*
* @return true if enabled
* @return false if disabled
* @return `true` if enabled, `false` if disabled
*/
bool adrEnabled();
@ -358,20 +349,20 @@ public:
/**
* @brief Stops all activies and shuts down the RF module and the background tasks.
*
* To restart communication, `startup()` and `join()` must be called.
* Neither clears the provisioned keys nor the configured pins.
* To restart communication, startup() and join() must be called.
* it neither clears the provisioned keys nor the configured pins.
*/
void shutdown();
/**
* @brief Restarts the background tasks and RF module.
*
* This member function must only be called after a call to `shutdowna()`.
* This member function must only be called after a call to shutdowna().
*/
void startup();
/**
* @brief Gets currentRX/TX window
* @brief Gets current RX/TX window
* @return window
*/
TTNRxTxWindow rxTxWindow();