Merge pull request #198 from TheThingsNetwork/feature/sendbytes-sf

Pass SF to sendBytes()

Author: johanstokking

docs/TheThingsNetwork.md

@@ -15,8 +15,8 @@ TheThingsNetwork ttn(Stream& modemStream, Stream& debugStream, fp_ttn_t fp, uint
 - `Stream& modemStream`: Stream for the LoRa modem (for The Things Node/Uno use `Serial1` and data rate `57600`).
 - `Stream& debugStream`: Stream to write debug logs to (for The Things Node/Uno use `Serial` and data rate `9600`).
 - `fp_ttn_fp fp`: The frequency plan: `TTN_FP_EU868` or `TTN_FP_US915` depending on the region you deploy in.
-- `uint8_t sf = 7`: Optional custom spreading factor. Can be `7` to `12` for `TTN_FP_EU868` and `7` to `12` for `TTN_FP_US915`. Defaults to `7`.
-- `uint8_t fsb = 2`: Optional custom front-side bus. Can be `1` to `8`. Defaults to `2`.
+- `uint8_t sf = 7`: Optional custom spreading factor. Can be `7` to `12` for `TTN_FP_EU868` and `7` to `10` for `TTN_FP_US915`. Defaults to `7`.
+- `uint8_t fsb = 2`: Optional custom frequency subband. Can be `1` to `8`. Defaults to `2` (for US915).
 
 ## Method: `reset`
 
@@ -122,13 +122,14 @@ See the [ABP](https://github.com/TheThingsNetwork/arduino-device-lib/blob/master
 Send a message to the application using raw bytes.
 
 ```c
-ttn_response_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, uint8_t sf = 0);
 ```
 
 - `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 `TTN_ERROR_UNEXPECTED_RESPONSE`.
+- `uint8_t sf = 0`: Override the spreading factor (SF). If the default value `0` is passed, the SF is not changed from the constructor or previous value.
 
 Returns a success or error code and logs the related error message:
 

src/TheThingsNetwork.cpp

@@ -457,7 +457,8 @@ bool TheThingsNetwork::personalize(const char *devAddr, const char *nwkSKey, con
 
 bool TheThingsNetwork::personalize()
 {
-  configureChannels(sf, fsb);
+  configureChannels(fsb);
+  setSF(sf);
   sendJoinSet(MAC_JOIN_MODE_ABP);
   readLine(buffer, sizeof(buffer));
   if (pgmstrcmp(buffer, CMP_ACCEPTED) != 0)
@@ -498,7 +499,8 @@ bool TheThingsNetwork::provision(const char *appEui, const char *appKey)
 
 bool TheThingsNetwork::join(int8_t retries, uint32_t retryDelay)
 {
-  configureChannels(sf, fsb);
+  configureChannels(fsb);
+  setSF(sf);
   while (retries == -1 || retries-- >= 0)
   {
     if (!sendJoinSet(MAC_JOIN_MODE_OTAA))
@@ -529,8 +531,13 @@ bool TheThingsNetwork::join(const char *appEui, const char *appKey, int8_t retri
   return provision(appEui, appKey) && join(retries, retryDelay);
 }
 
-ttn_response_t TheThingsNetwork::sendBytes(const uint8_t *payload, size_t length, port_t port, bool confirm)
+ttn_response_t TheThingsNetwork::sendBytes(const uint8_t *payload, size_t length, port_t port, bool confirm, uint8_t sf)
 {
+  if (sf != 0)
+  {
+    setSF(sf);
+  }
+
   uint8_t mode = confirm ? MAC_TX_TYPE_CNF : MAC_TX_TYPE_UCNF;
   if (!sendPayload(mode, port, (uint8_t *)payload, length))
   {
@@ -599,7 +606,7 @@ void TheThingsNetwork::showStatus()
   debugPrintIndex(SHOW_RX_DELAY_2, buffer);
 }
 
-void TheThingsNetwork::configureEU868(uint8_t sf)
+void TheThingsNetwork::configureEU868()
 {
   sendMacSet(MAC_RX2, "3 869525000");
   sendChSet(MAC_CHANNEL_DRRANGE, 1, "0 6");
@@ -620,16 +627,9 @@ void TheThingsNetwork::configureEU868(uint8_t sf)
     }
   }
   sendMacSet(MAC_PWRIDX, TTN_PWRIDX_EU868);
-  if (sf >= 7 && sf <= 12)
-  {
-    char dr[2];
-    dr[0] = '0' + (12 - sf);
-    dr[1] = '\0';
-    sendMacSet(MAC_DR, dr);
-  }
 }
 
-void TheThingsNetwork::configureUS915(uint8_t sf, uint8_t fsb)
+void TheThingsNetwork::configureUS915(uint8_t fsb)
 {
   uint8_t ch;
   uint8_t chLow = fsb > 0 ? (fsb - 1) * 8 : 0;
@@ -651,16 +651,9 @@ void TheThingsNetwork::configureUS915(uint8_t sf, uint8_t fsb)
     }
   }
   sendMacSet(MAC_PWRIDX, TTN_PWRIDX_US915);
-  if (sf >= 7 && sf <= 10)
-  {
-    char dr[2];
-    dr[0] = '0' + (10 - sf);
-    dr[1] = '\0';
-    sendMacSet(MAC_DR, dr);
-  }
 }
 
-void TheThingsNetwork::configureAS920_923(uint8_t sf)
+void TheThingsNetwork::configureAS920_923()
 {
   sendMacSet(MAC_ADR, "off"); // TODO: remove when ADR is implemented for this plan
   sendMacSet(MAC_RX2, "2 923200000");
@@ -687,27 +680,20 @@ void TheThingsNetwork::configureAS920_923(uint8_t sf)
   //sendChSet(MAC_CHANNEL_STATUS, 8, "on");
   // TODO: Add FSK channel
   sendMacSet(MAC_PWRIDX, TTN_PWRIDX_AS920_923);
-  if (sf >= 7 && sf <= 12)
-  {
-    char dr[2];
-    dr[0] = '0' + (12 - sf);
-    dr[1] = '\0';
-    sendMacSet(MAC_DR, dr);
-  }
 }
 
-void TheThingsNetwork::configureChannels(uint8_t sf, uint8_t fsb)
+void TheThingsNetwork::configureChannels(uint8_t fsb)
 {
   switch (fp)
   {
   case TTN_FP_EU868:
-    configureEU868(sf);
+    configureEU868();
     break;
   case TTN_FP_US915:
-    configureUS915(sf, fsb);
+    configureUS915(fsb);
     break;
   case TTN_FP_AS920_923:
-    configureAS920_923(sf);
+    configureAS920_923();
     break;
   default:
     debugPrintMessage(ERR_MESSAGE, ERR_INVALID_FP);
@@ -716,6 +702,25 @@ void TheThingsNetwork::configureChannels(uint8_t sf, uint8_t fsb)
   sendMacSet(MAC_RETX, TTN_RETX);
 }
 
+bool TheThingsNetwork::setSF(uint8_t sf)
+{
+  uint8_t dr;
+  switch (fp)
+  {
+  case TTN_FP_EU868:
+  case TTN_FP_AS920_923:
+    dr = 12 - sf;
+    break;
+  case TTN_FP_US915:
+    dr = 10 - sf;
+    break;
+  }
+  char s[2];
+  s[0] = '0' + dr;
+  s[1] = '\0';
+  return sendMacSet(MAC_DR, s);
+}
+
 void TheThingsNetwork::sendCommand(uint8_t table, uint8_t index, bool appendSpace, bool print)
 {
   char command[100];

src/TheThingsNetwork.h

@@ -57,10 +57,11 @@ class TheThingsNetwork
   void debugPrintMessage(uint8_t type, uint8_t index, const char *value = NULL);
 
   void autoBaud();
-  void configureEU868(uint8_t sf);
-  void configureUS915(uint8_t sf, uint8_t fsb);
-  void configureAS920_923(uint8_t sf);
-  void configureChannels(uint8_t sf, uint8_t fsb);
+  void configureEU868();
+  void configureUS915(uint8_t fsb);
+  void configureAS920_923();
+  void configureChannels(uint8_t fsb);
+  bool setSF(uint8_t sf);
   bool waitForOk();
 
   void sendCommand(uint8_t table, uint8_t index, bool appendSpace, bool print = true);
@@ -82,7 +83,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();
-  ttn_response_t sendBytes(const uint8_t *payload, size_t length, port_t port = 1, bool confirm = false);
+  ttn_response_t sendBytes(const uint8_t *payload, size_t length, port_t port = 1, bool confirm = false, uint8_t sf = 0);
   ttn_response_t poll(port_t port = 1, bool confirm = false);
   void sleep(uint32_t mseconds);
   void saveState();