Added defines for the return values of sendBytes,removed defines, rep…

…laced by enum, fix name, fixed docs (#141) Closes #133
TheThingsNetwork · Dec 14, 2016 · 73e6aa0 · 73e6aa0
1 parent 36d1e6a
commit 73e6aa0
Show file tree

Hide file tree

Showing 4 changed files with 45 additions and 34 deletions.
diff --git a/docs/TheThingsNetwork.md b/docs/TheThingsNetwork.md
@@ -91,21 +91,20 @@ See the [ABP](https://github.com/TheThingsNetwork/arduino-device-lib/blob/master
 Send a message to the application using raw bytes.
 
 ```c
-int8_t sendBytes(const byte* payload, size_t length, port_t port = 1, bool confirm = false);
+ttn_response_t sendBytes(const byte* payload, size_t length, port_t port = 1, bool confirm = false);
 ```
 
 - `const byte* payload `: Bytes to send.
 - `size_t length`: The number of bytes. Use `sizeof(payload)` to get it.
 - `port_t port = 1`: The port to address. Defaults to `1`.
-- `bool confirm = false`: Whether to ask for confirmation. Defaults to `false`. If confirmation fails, the method will return error code `-10`.
+- `bool confirm = false`: Whether to ask for confirmation. Defaults to `false`. If confirmation fails, the method will return error code `TTN_ERROR_UNEXPECTED_RESPONSE`.
 
 Returns a success or error code and logs the related error message:
 
-* `-1`: Send command failed.
-* `-2`: Time-out.
-* `1`: Successful transmission.
-* `2`: Successful transmission. Received \<N> bytes
-* `-10`: Unexpected response: \<Response>
+* `TTN_ERROR_SEND_COMMAND_FAILED`: Send command failed.
+* `TTN_SUCCESSFUL_TRANSMISSION`: Successful transmission.
+* `TTN_SUCCESSFUL_RECEIVE`: Successful transmission. Received \<N> bytes
+* `TTN_ERROR_UNEXPECTED_RESPONSE`: Unexpected response: \<Response>
 
 See the [Send](https://github.com/TheThingsNetwork/arduino-device-lib/blob/master/examples/Send/Send.ino) example.
 

diff --git a/keywords.txt b/keywords.txt
@@ -13,31 +13,36 @@ TheThingsMessage        KEYWORD1
 # Methods and Functions (KEYWORD2)
 #######################################
 
-showStatus              KEYWORD2
-onMessage               KEYWORD2
-provision               KEYWORD2
-join                    KEYWORD2
-personalize             KEYWORD2
-sendBytes               KEYWORD2
-poll                    KEYWORD2
-calculateAirtime        KEYWORD2
-airtime                 KEYWORD2
+showStatus                      KEYWORD2
+onMessage                       KEYWORD2
+provision                       KEYWORD2
+join                            KEYWORD2
+personalize                     KEYWORD2
+sendBytes                       KEYWORD2
+poll                            KEYWORD2
+calculateAirtime                KEYWORD2
+airtime                         KEYWORD2
 
-encodeDeviceData        KEYWORD2
-decodeAppData           KEYWORD2
+encodeDeviceData                KEYWORD2
+decodeAppData                   KEYWORD2
 
 #######################################
 # Constants (LITERAL1)
 #######################################
 
-TTN_BUFFER_SIZE         LITERAL1
-TTN_DEFAULT_WAIT_TIME   LITERAL1
-TTN_DEFAULT_SF          LITERAL1
-TTN_DEFAULT_FSB         LITERAL1
-TTN_ADR_SUPPORTED       LITERAL1
-TTN_PWRIDX_868          LITERAL1
-TTN_PWRIDX_915          LITERAL1
-TTN_FP_EU868            LITERAL1
-TTN_FP_EU915            LITERAL1
+TTN_BUFFER_SIZE                 LITERAL1
+TTN_DEFAULT_WAIT_TIME           LITERAL1
+TTN_DEFAULT_SF                  LITERAL1
+TTN_DEFAULT_FSB                 LITERAL1
+TTN_ADR_SUPPORTED               LITERAL1
+TTN_PWRIDX_868                  LITERAL1
+TTN_PWRIDX_915                  LITERAL1
+TTN_FP_EU868                    LITERAL1
+TTN_FP_EU915                    LITERAL1
 
-TTN_PIN_LED             LITERAL1
+TTN_PIN_LED                     LITERAL1
+
+TTN_ERROR_SEND_COMMAND_FAILED   LITERAL1
+TTN_ERROR_UNEXPECTED_RESPONSE   LITERAL1
+TTN_SUCCESSFUL_TRANSMISSION     LITERAL1
+TTN_SUCCESSFUL_RECEIVE          LITERAL1
diff --git a/src/TheThingsNetwork.cpp b/src/TheThingsNetwork.cpp
@@ -403,7 +403,7 @@ bool TheThingsNetwork::join(const char *appEui, const char *appKey, int8_t retri
   return join(retries, retryDelay);
 }
 
-int8_t TheThingsNetwork::sendBytes(const byte* payload, size_t length, port_t port, bool confirm) {
+ttn_response_t TheThingsNetwork::sendBytes(const byte* payload, size_t length, port_t port, bool confirm) {
   bool send;
   if (confirm) {
     send = sendPayload(MAC_TX_TYPE_CNF, port, (uint8_t *)payload, length);
@@ -412,7 +412,7 @@ int8_t TheThingsNetwork::sendBytes(const byte* payload, size_t length, port_t po
   }
   if (!send) {
     stateMessage(ERR_MESSAGE, ERR_SEND_COMMAND_FAILED);
-    return -1;
+    return TTN_ERROR_SEND_COMMAND_FAILED;
   }
 
   const char *response = readLine();
@@ -426,7 +426,7 @@ int8_t TheThingsNetwork::sendBytes(const byte* payload, size_t length, port_t po
   }
   if (compareStrings(response, CMP_MAC_TX_OK)) {
     stateMessage(SUCCESS_MESSAGE, SCS_SUCCESSFUL_TRANSMISSION);
-    return 1;
+    return TTN_SUCCESSFUL_TRANSMISSION;
   }
   if (compareStrings(response, CMP_MAC_RX, 5)) {
     port_t downlinkPort = receivedPort(response, 7);
@@ -439,11 +439,11 @@ int8_t TheThingsNetwork::sendBytes(const byte* payload, size_t length, port_t po
     stateMessage(SUCCESS_MESSAGE, SCS_SUCCESSFUL_TRANSMISSION_RECEIVED, (const char *)itoa(downlinkLength, set_buffer, 10));
     if (this->messageCallback)
       this->messageCallback(downlink, downlinkLength, downlinkPort);
-    return 2;
+    return TTN_SUCCESSFUL_RECEIVE;
   }
 
   stateMessage(ERR_MESSAGE, ERR_UNEXPECTED_RESPONSE, response);
-  return -10;
+  return TTN_ERROR_UNEXPECTED_RESPONSE;
 }
 
 size_t TheThingsNetwork::bufLength(const char *data) {

diff --git a/src/TheThingsNetwork.h b/src/TheThingsNetwork.h
@@ -19,6 +19,13 @@
 
 typedef uint8_t port_t;
 
+enum ttn_response_t {
+  TTN_ERROR_SEND_COMMAND_FAILED = (-1),
+  TTN_ERROR_UNEXPECTED_RESPONSE = (-10),
+  TTN_SUCCESSFUL_TRANSMISSION = 1,
+  TTN_SUCCESSFUL_RECEIVE = 2
+};
+
 enum ttn_fp_t {
   TTN_FP_EU868,
   TTN_FP_US915
@@ -82,7 +89,7 @@ class TheThingsNetwork
     bool join(int8_t retries = -1, uint32_t retryDelay = 10000);
     bool personalize(const char *devAddr, const char *nwkSKey, const char *appSKey);
     bool personalize();
-    int8_t sendBytes(const byte* payload, size_t length, port_t port = 1, bool confirm = false);
+    ttn_response_t sendBytes(const byte* payload, size_t length, port_t port = 1, bool confirm = false);
     int8_t poll(port_t port = 1, bool confirm = false);
 };