From fc34fed6def4c7d27f6e7b4f0474e3fc66157211 Mon Sep 17 00:00:00 2001 From: Manuel Bleichenbacher Date: Thu, 19 Jul 2018 22:04:32 +0200 Subject: [PATCH] Improve consistency of naming --- examples/hello_world/main/main.cpp | 6 +-- examples/send_recv/main/main.cpp | 8 ++-- include/TheThingsNetwork.h | 65 ++++++++++++++++++------------ src/TheThingsNetwork.cpp | 15 ++++--- 4 files changed, 55 insertions(+), 39 deletions(-) diff --git a/examples/hello_world/main/main.cpp b/examples/hello_world/main/main.cpp index c83b3fa..0fe985d 100644 --- a/examples/hello_world/main/main.cpp +++ b/examples/hello_world/main/main.cpp @@ -37,11 +37,11 @@ void send_messages(void* pvParameter) { while (1) { printf("Sending message...\n"); - ttn_response_t res = ttn.sendBytes(msgData, sizeof(msgData) - 1); - if (res == TTN_SUCCESSFUL_TRANSMISSION) + TTNResponseCode res = ttn.transmitBytes(msgData, sizeof(msgData) - 1); + if (res == kTTNSuccessfulTransmission) printf("Message sent.\n"); else - printf("Message transmission failed.\n"); + printf("Transmission failed.\n"); vTaskDelay(TX_INTERVAL * 1000 / portTICK_PERIOD_MS); } diff --git a/examples/send_recv/main/main.cpp b/examples/send_recv/main/main.cpp index 846df2f..59d34b9 100644 --- a/examples/send_recv/main/main.cpp +++ b/examples/send_recv/main/main.cpp @@ -37,13 +37,11 @@ void sendMessages(void* pvParameter) { while (1) { printf("Sending message...\n"); - ttn_response_t res = ttn.sendBytes(msgData, sizeof(msgData) - 1); - if (res == TTN_SUCCESSFUL_TRANSMISSION) + TTNResponseCode res = ttn.transmitBytes(msgData, sizeof(msgData) - 1); + if (res == kTTNSuccessfulTransmission) printf("Message sent.\n"); - else if (res == TTN_SUCCESSFUL_RECEIVE) - printf("Message sent and message received\n"); else - printf("Message transmission failed.\n"); + printf("Transmission failed.\n"); vTaskDelay(TX_INTERVAL * 1000 / portTICK_PERIOD_MS); } diff --git a/include/TheThingsNetwork.h b/include/TheThingsNetwork.h index d5c112b..e31cc6e 100644 --- a/include/TheThingsNetwork.h +++ b/include/TheThingsNetwork.h @@ -26,12 +26,12 @@ typedef uint8_t port_t; /** * @brief Response codes */ -enum ttn_response_t +enum TTNResponseCode { - TTN_ERROR_SEND_COMMAND_FAILED = (-1), - TTN_ERROR_UNEXPECTED_RESPONSE = (-10), - TTN_SUCCESSFUL_TRANSMISSION = 1, - TTN_SUCCESSFUL_RECEIVE = 2 + kTTNErrorTransmissionFailed = -1, + kTTNErrorUnexpected = -10, + kTTNSuccessfulTransmission = 1, + kTTNSuccessfulReceive = 2 }; /** @@ -41,12 +41,12 @@ enum ttn_response_t * @param length number of received bytes * @param port port the message was received on */ -typedef void (*message_cb_t)(const uint8_t* payload, size_t length, port_t port); +typedef void (*TTNMessageCallback)(const uint8_t* payload, size_t length, port_t port); /** * @brief TTN device * - * The TheThingsNetwork class enables ESP32 devices with SX1272/73/76/77/78/79 LoRaWAN chips + * The 'TheThingsNetwork' 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. @@ -74,7 +74,9 @@ public: /** * @brief Configures the pins used to communicate with the LoRaWAN radio chip. * + * * The SPI bus must be first configured using spi_bus_initialize(). Then it is passed as the first parameter. + * Additionally, 'gpio_install_isr_service()' must be 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 nss The GPIO pin number connected to the radio chip's NSS pin (serving as the SPI chip select) @@ -88,7 +90,7 @@ public: /** * @brief Sets the information needed to activate the device via OTAA, without actually activating. * - * Call join() without the first 2 arguments to activate. + * The provided EUIs and key are saved in non-volatile memory. Call join() without arguments to activate. * * @param devEui Device EUI (16 character string with hexadecimal data) * @param appEui Application EUI of the device (16 character string with hexadecimal data) @@ -99,55 +101,68 @@ public: bool provision(const char *devEui, const char *appEui, const char *appKey); /** - * @brief Activate the device via OTAA. + * @brief Set the EUIs and keys and activate the device via OTAA. + * + * The EUIs and key are NOT saved in non-volatile memory. + * + * The function blocks until the activation has completed or failed. * * @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 - * @return false + * @return true if the activation was succeful + * @return false if the activation failed */ bool join(const char *devEui, const char *appEui, const char *appKey); /** * @brief Activate the device via OTAA. * - * The app EUI, app key and dev EUI must already have been provisioned. + * The app EUI, app key and dev EUI must already have been provisioned by a call to 'provision()'. * - * @return true - * @return false + * The function blocks until the activation has completed or failed. + * + * @return true if the activation was succeful + * @return false if the activation failed */ bool join(); /** - * @brief Send a message + * @brief Transmit a message * - * @param payload bytes to be sent - * @param length number of bytes to be sent + * 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 + * first wait until the duty cycle allows a transmission (enforcing the duty cycle limits). + * + * @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 TTTN_SUCCESSFUL_TRANSMISSION Successful transmission - * @return TTTN_SUCCESSFUL_RECEIVE Successful transmission and a message has been received - * @return TTN_ERROR_SEND_COMMAND_FAILED Transmission failed - * @return TTTN_ERROR_UNEXPECTED_RESPONSE Unexpected response + * @return TkTTNSuccessfulTransmission Successful transmission + * @return kTTNErrorTransmissionFailed Transmission failed + * @return TkTTNErrorUnexpected Unexpected error */ - ttn_response_t sendBytes(const uint8_t *payload, size_t length, port_t port = 1, bool confirm = false); + TTNResponseCode transmitBytes(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 * * When a message is received, the specified function is called. The - * message, its length and the port is was received on are provided as + * 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 'transmitBytes' or 'poll'. The callback is called + * in the task that called any of these functions and it occurs before these functions + * return control to the caller. + * * @param callback the callback function */ - void onMessage(message_cb_t callback); + void onMessage(TTNMessageCallback callback); private: - message_cb_t messageCallback; + TTNMessageCallback messageCallback; bool decodeKeys(const char *devEui, const char *appEui, const char *appKey); }; diff --git a/src/TheThingsNetwork.cpp b/src/TheThingsNetwork.cpp index aa6af8d..a205268 100644 --- a/src/TheThingsNetwork.cpp +++ b/src/TheThingsNetwork.cpp @@ -131,13 +131,13 @@ bool TheThingsNetwork::join() return result == EV_JOINED; } -ttn_response_t TheThingsNetwork::sendBytes(const uint8_t *payload, size_t length, port_t port, bool confirm) +TTNResponseCode TheThingsNetwork::transmitBytes(const uint8_t *payload, size_t length, port_t port, bool confirm) { hal_enterCriticalSection(); if (LMIC.opmode & OP_TXRXPEND) { hal_leaveCriticalSection(); - return TTN_ERROR_SEND_COMMAND_FAILED; + return kTTNErrorTransmissionFailed; } clientAction = eActionSending; @@ -156,16 +156,19 @@ ttn_response_t TheThingsNetwork::sendBytes(const uint8_t *payload, size_t length port_t port = 0; if ((LMIC.txrxFlags & TXRX_PORT)) port = LMIC.frame[LMIC.dataBeg - 1]; - messageCallback(LMIC.frame + LMIC.dataBeg, LMIC.dataLen, port); + const uint8_t* msg = NULL; + if (LMIC.dataLen > 0) + msg = LMIC.frame + LMIC.dataBeg; + messageCallback(msg, LMIC.dataLen, port); } - return hasRecevied ? TTN_SUCCESSFUL_RECEIVE : TTN_SUCCESSFUL_TRANSMISSION; + return kTTNSuccessfulTransmission; } - return TTN_ERROR_SEND_COMMAND_FAILED; + return kTTNErrorTransmissionFailed; } -void TheThingsNetwork::onMessage(message_cb_t callback) +void TheThingsNetwork::onMessage(TTNMessageCallback callback) { messageCallback = callback; }