Improve consistency of naming

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);
+        TTNResponseCode res = ttn.transmitBytes(msgData, sizeof(msgData) - 1);
-        if (res == TTN_SUCCESSFUL_TRANSMISSION)
+        if (res == kTTNSuccessfulTransmission)
             printf("Message sent.\n");
         else
-            printf("Message transmission failed.\n");
+            printf("Transmission failed.\n");
 
         vTaskDelay(TX_INTERVAL * 1000 / portTICK_PERIOD_MS);
     }

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);
+        TTNResponseCode res = ttn.transmitBytes(msgData, sizeof(msgData) - 1);
-        if (res == TTN_SUCCESSFUL_TRANSMISSION)
+        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);
     }

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),
+  kTTNErrorTransmissionFailed = -1,
-  TTN_ERROR_UNEXPECTED_RESPONSE = (-10),
+  kTTNErrorUnexpected = -10,
-  TTN_SUCCESSFUL_TRANSMISSION = 1,
+  kTTNSuccessfulTransmission = 1,
-  TTN_SUCCESSFUL_RECEIVE = 2
+  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 true   if the activation was succeful
-     * @return false 
+     * @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 
+     * The function blocks until the activation has completed or failed.
-     * @return false 
+     * 
+     * @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
+     * The function blocks until the message could be transmitted and a message has been received
-     * @param length   number of bytes to be sent
+     * 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 TkTTNSuccessfulTransmission   Successful transmission
-     * @return TTTN_SUCCESSFUL_RECEIVE         Successful transmission and a message has been received
+     * @return kTTNErrorTransmissionFailed   Transmission failed
-     * @return TTN_ERROR_SEND_COMMAND_FAILED   Transmission failed
+     * @return TkTTNErrorUnexpected          Unexpected error
-     * @return TTTN_ERROR_UNEXPECTED_RESPONSE  Unexpected response
      */
-    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);
 };

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;
 }