Update smooth-scroll, move Arduino v2 guide to current, update Uno current guide, Catch pull status errors, closes TheThingsNetwork#101

Author: FokkeZB

Gemfile.lock

@@ -11,35 +11,39 @@ GEM
     coffee-script (2.4.1)
       coffee-script-source
       execjs
-    coffee-script-source (1.10.0)
-    colorator (0.1)
+    coffee-script-source (1.11.1)
+    colorator (1.1.0)
     colored (1.2)
     ethon (0.9.0)
       ffi (>= 1.3.0)
     execjs (2.7.0)
-    faraday (0.9.2)
+    faraday (0.10.0)
       multipart-post (>= 1.2, < 3)
     ffi (1.9.14)
+    forwardable-extended (2.6.0)
     gemoji (2.1.0)
-    github-pages (91)
+    github-pages (104)
       activesupport (= 4.2.7)
       github-pages-health-check (= 1.2.0)
-      jekyll (= 3.1.6)
+      jekyll (= 3.3.0)
+      jekyll-avatar (= 0.4.2)
       jekyll-coffeescript (= 1.0.1)
-      jekyll-feed (= 0.5.1)
+      jekyll-feed (= 0.8.0)
       jekyll-gist (= 1.4.0)
-      jekyll-github-metadata (= 2.0.2)
-      jekyll-mentions (= 1.1.3)
+      jekyll-github-metadata (= 2.2.0)
+      jekyll-mentions (= 1.2.0)
       jekyll-paginate (= 1.1.0)
       jekyll-redirect-from (= 0.11.0)
       jekyll-sass-converter (= 1.3.0)
-      jekyll-seo-tag (= 2.0.0)
-      jekyll-sitemap (= 0.10.0)
+      jekyll-seo-tag (= 2.1.0)
+      jekyll-sitemap (= 0.12.0)
+      jekyll-swiss (= 0.4.0)
       jemoji (= 0.7.0)
       kramdown (= 1.11.1)
       liquid (= 3.0.6)
       listen (= 3.0.6)
       mercenary (~> 0.3)
+      minima (= 2.0.0)
       rouge (= 1.11.1)
       terminal-table (~> 1.4)
     github-pages-health-check (1.2.0)
@@ -61,34 +65,42 @@ GEM
       typhoeus (~> 0.7)
       yell (~> 2.0)
     i18n (0.7.0)
-    jekyll (3.1.6)
-      colorator (~> 0.1)
+    jekyll (3.3.0)
+      addressable (~> 2.4)
+      colorator (~> 1.0)
       jekyll-sass-converter (~> 1.0)
       jekyll-watch (~> 1.1)
       kramdown (~> 1.3)
       liquid (~> 3.0)
       mercenary (~> 0.3.3)
+      pathutil (~> 0.9)
       rouge (~> 1.7)
       safe_yaml (~> 1.0)
+    jekyll-avatar (0.4.2)
+      jekyll (~> 3.0)
     jekyll-coffeescript (1.0.1)
       coffee-script (~> 2.2)
-    jekyll-feed (0.5.1)
+    jekyll-feed (0.8.0)
+      jekyll (~> 3.3)
     jekyll-gist (1.4.0)
       octokit (~> 4.2)
-    jekyll-github-metadata (2.0.2)
+    jekyll-github-metadata (2.2.0)
       jekyll (~> 3.1)
-      octokit (~> 4.0)
-    jekyll-mentions (1.1.3)
+      octokit (~> 4.0, != 4.4.0)
+    jekyll-mentions (1.2.0)
+      activesupport (~> 4.0)
       html-pipeline (~> 2.3)
       jekyll (~> 3.0)
     jekyll-paginate (1.1.0)
     jekyll-redirect-from (0.11.0)
       jekyll (>= 2.0)
     jekyll-sass-converter (1.3.0)
       sass (~> 3.2)
-    jekyll-seo-tag (2.0.0)
-      jekyll (~> 3.1)
-    jekyll-sitemap (0.10.0)
+    jekyll-seo-tag (2.1.0)
+      jekyll (~> 3.3)
+    jekyll-sitemap (0.12.0)
+      jekyll (~> 3.3)
+    jekyll-swiss (0.4.0)
     jekyll-watch (1.5.0)
       listen (~> 3.0, < 3.1)
     jemoji (0.7.0)
@@ -104,40 +116,50 @@ GEM
       rb-inotify (>= 0.9.7)
     mercenary (0.3.6)
     mini_portile2 (2.1.0)
+    minima (2.0.0)
     minitest (5.9.0)
     multipart-post (2.0.0)
     net-dns (0.8.0)
     nokogiri (1.6.8)
       mini_portile2 (~> 2.1.0)
       pkg-config (~> 1.1.7)
-    octokit (4.3.0)
-      sawyer (~> 0.7.0, >= 0.5.3)
+    octokit (4.6.2)
+      sawyer (~> 0.8.0, >= 0.5.3)
     parallel (1.9.0)
+    pathutil (0.14.0)
+      forwardable-extended (~> 2.6)
     pkg-config (1.1.7)
     public_suffix (1.5.3)
-    rb-fsevent (0.9.7)
+    rake (10.5.0)
+    rake-jekyll (1.1.0)
+      rake (~> 10.0)
+    rb-fsevent (0.9.8)
     rb-inotify (0.9.7)
       ffi (>= 0.5.0)
     rouge (1.11.1)
     safe_yaml (1.0.4)
     sass (3.4.22)
-    sawyer (0.7.0)
-      addressable (>= 2.3.5, < 2.5)
-      faraday (~> 0.8, < 0.10)
-    terminal-table (1.6.0)
+    sawyer (0.8.1)
+      addressable (>= 2.3.5, < 2.6)
+      faraday (~> 0.8, < 1.0)
+    terminal-table (1.7.3)
+      unicode-display_width (~> 1.1.1)
     thread_safe (0.3.5)
     typhoeus (0.8.0)
       ethon (>= 0.8.0)
     tzinfo (1.2.2)
       thread_safe (~> 0.1)
+    unicode-display_width (1.1.1)
     yell (2.0.6)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
-  github-pages
+  github-pages (= 104)
   html-proofer
+  rake
+  rake-jekyll
 
 BUNDLED WITH
    1.12.5

_includes/current/arduino.md

@@ -5,10 +5,12 @@ sections:
  - arduino/_ide.md
  - arduino/_usage.md
  - arduino/_api.md
+ - arduino/_bytes.md
  - arduino/_examples.md
  - arduino/_resources.md
 redirect_from:
- - /arduino/
+ - /refactor/arduino/
+ - /v2-preview/arduino/
 ---
 
 [Arduino](https://www.arduino.cc/en/Guide/Introduction) is an open-source electronics platform based on easy-to-use hardware and software. It's intended for anyone making interactive projects.
@@ -17,8 +19,6 @@ With [The Things Network Library](https://github.com/thethingsnetwork/arduino-de
 
 ## Prerequisites
 
-* Access to [staging.thethingsnetwork.org](https://staging.thethingsnetwork.org/).
+* A staging or preview account.
 * Arduino board with [Microchip RN2xx3 module](http://www.microchip.com/design-centers/wireless-connectivity/embedded-wireless/lora-technology) for LoRaWAN.
-* Version 0.x of the [The Things Network Arduino Library](https://github.com/thethingsnetwork/arduino-device-lib).
-
-> Since version 0.17, the library now has its [own repository](https://github.com/thethingsnetwork/arduino-device-lib), can be installed via the [Library Manager](https://www.arduino.cc/en/Guide/Libraries#toc3) and has been renamed from `TheThingsUno` to `TheThingsNetwork`. I guess it should have been bumped to 1.x - oops! 😝
+* Version 1.x of the [The Things Network Arduino Library](https://github.com/thethingsnetwork/arduino-device-lib).

_includes/current/arduino/_api.md

@@ -1,36 +1,24 @@
+<!-- EDIT AT https://github.com/TheThingsNetwork/arduino-device-lib/blob/master/docs/TheThingsNetwork.md -->
+
 # API Reference
+Include and instantiate the TheThingsNetwork class. The constructor initialize the library with the Streams it should communicate with. It also sets the value of the spreading factor, the front-side Bus and the frequency plan.
 
-Include TheThingsNetwork library:
+## Class: TheThingsNetwork
 
 ```c
 #include <TheThingsNetwork.h>
-```
-
-## Method: reset
-Reset the LoRaWAN module. In most cases you'd call this with no arguments before calling `init()`.
-
-```c
-void reset(bool adr = true, int sf = DEFAULT_SF, int fsb = DEFAULT_FSB);
-```
 
-- `bool adr = true` **TODO**
-- `int sf = DEFAULT_SF` **TODO**
-- `int fsb = DEFAULT_FSB` **TODO**
-
-## Method: init
-Initialize the library with the streams it should communicate with.
-
-```c
-void init(Stream& modemStream, Stream& debugStream);
+TheThingsNetwork ttn(Stream& modemStream, Stream& debugStream, fp_ttn_t fp, uint8_t sf = 7, uint8_t fsb = 2);
 ```
 
-- `Stream& modemStream`: Stream to the LoRaWAN modem.
-- `Stream& debugStream`: Stream to write debug logs to.
-
-For The Things Uno and Node use `Serial1` and `Serial`.
+- `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`.
 
 ## Method: showStatus
-Writes information about the device and LoRaWAN module to `debugStream`.
+Writes information about the device and LoRa module to `debugStream`.
 
 ```c
 void showStatus();
@@ -39,96 +27,111 @@ void showStatus();
 Will write something like:
 
 ```bash
-Device Information
-
-EUI: 0004A30B001B672E
-Battery: 3304
-AppEUI: 0000000000000000
-DevEUI: 0004A30B001B672E
-DevAddr: 00000000
+EUI: 0004A30B001B7AD2
+Battery: 3223
+AppEUI: 70B3D57EF000001C
+DevEUI: 0004A30B001B7AD2
+Band: 868
 Data Rate: 5
 RX Delay 1: 1000
 RX Delay 2: 2000
-
-use the device `EUI` to register the device for OTAA
+Total airtime: 0.00 s
 ```
 
-## Method: join
-Activate the device via OTAA.
+See the [DeviceInfo](https://github.com/TheThingsNetwork/arduino-device-lib/blob/master/examples/DeviceInfo/DeviceInfo.ino) example.
+
+## Method: onMessage
+Sets a function which will be called to process incoming messages.
 
 ```c
-bool join(const byte appEui[8], const byte appKey[16]);
+void onMessage(void (*cb)(const byte* payload, size_t length, port_t port));
 ```
 
-- `const byte appEui[8]`: Application EUI the device is registered to.
-- `const byte appKey[16]`: Application Key assigned to the device.
+- `const byte* payload`: Bytes received.
+- `size_t length`: Number of bytes.
+- `port_t port`: The port addressed.
+
+See the [Receive](https://github.com/TheThingsNetwork/arduino-device-lib/blob/master/examples/Receive/Receive.ino) example.
 
-Returns `true` or `false` depending on whether it received confirmation that the activation was successful. You'll probably call this method in a while to retry until it returns true:
+## Method: join
+Activate the device via OTAA (default).
 
 ```c
-while (!ttn.join(appEui, appKey)) {
-  delay(10000);
-}
+bool join(const char *appEui, const char *appKey, int8_t retries = -1, uint32_t retryDelay = 10000);
+bool join(int8_t retries = -1, uint32_t retryDelay = 10000);
 ```
 
-See [Library Usage / Activate](#activate).
+- `const char *appEui`: Application EUI the device is registered to.
+- `const char *appKey`: Application Key assigned to the device.
+- `int8_t retries = -1`: Number of times to retry after failed or unconfirmed join. Defaults to `-1` which means infinite.
+- `uint32_t retryDelay = 10000`: Delay in ms between attempts. Defaults to 10 seconds.
+
+Returns `true` or `false` depending on whether it received confirmation that the activation was successful before the maximum number of attempts.
+
+Call the method without the first two arguments if the device's LoRa module comes with pre-flashed values.
 
 ## Method: personalize
 Activate the device via ABP.
 
 ```c
-bool personalize(const byte devAddr[4], const byte nwkSKey[16], const byte appSKey[16]);
+bool personalize(const char *devAddr, const char *nwkSKey, const char *appSKey);
+bool personalize();
 ```
 
-- `const byte devAddr[4]`: Dev(ice) Address assigned to the device.
-- `const byte nwkSKey[16]`: Network Session Key assigned to the device.
-- `const byte appSKey[16]`: App(lication) Session Key assigned to the device.
+- `const char *devAddr`: Device Address assigned to the device.
+- `const char *nwkSKey`: Network Session Key assigned to the device for identification.
+- `const char *appSKey`: Application Session Key assigned to the device for encryption.
 
-See [Library Usage / Activate](#activate).
+Returns `true` or `false` depending on whether the activation was successful.
+
+Call the method with no arguments if the device's LoRa module comes with pre-flashed values.
+
+See the [ABP](https://github.com/TheThingsNetwork/arduino-device-lib/blob/master/examples/ABP/ABP.ino) example.
 
 ## Method: sendBytes
 Send a message to the application using raw bytes.
 
 ```c
-int sendBytes(const byte* buffer, int length, int port = 1, bool confirm = false);
+int8_t sendBytes(const byte* payload, size_t length, port_t port = 1, bool confirm = false);
 ```
 
-- `const byte* buffer`: Bytes to send.
-- `int length`: The number of bytes. Use `sizeof(buffer)` to get it.
-- `int port = 1`: The port to address. Defaults to `1`.
-- `bool confirm = false`: Whether to ask for confirmation.
+- `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`.
 
-	- **TODO:** How does one check the result?
+Returns a success or error code and logs the related error message:
 
-Returns the size of the message received in response, if any. Use `downlink` for the actual bytes received.
+* `-1`: Send command failed.
+* `-2`: Time-out.
+* `1`: Successful transmission.
+* `2`: Successful transmission. Received \<N> bytes
+* `-10`: Unexpected response: \<Response>
 
-## Method: sendString
-Send a message to the application using a string, which the library will encode as bytes for you.
+See the [Send](https://github.com/TheThingsNetwork/arduino-device-lib/blob/master/examples/Send/Send.ino) example.
 
-> To minimize air time we advise not to use this method and try to use a minimal amount of bytes to communicate your message.
+Also in sendBytes, due to TTN's 30 second fair access policy, we update the airtime each time we uplink a message. This airtime is based on a lot of variables but the most important ones are the spreading factor and the size of the message, the higher it is the less messages you can send in 30 seconds (SF7 around 500 messages of 8 bytes, SF12 around 20 messages of 8 bytes).
+
+## Method: poll
+Calls `sendBytes()` with `{ 0x00 }` as payload to poll for incoming messages.
 
 ```c
-int sendString(String message, int port = 1, bool confirm = false);
+int8_t poll(port_t port = 1, bool confirm = false);
 ```
 
-- `String message`: String to encode and send.
-- `int port = 1`: The port to address. Defaults to `1`.
+- `port_t port = 1`: The port to address. Defaults to `1`.
 - `bool confirm = false`: Whether to ask for confirmation.
 
-	- **TODO:** How does one check the result?
+Returns the result of `sendBytes()`.
 
-Returns the size of the message received in response, if any. Use `downlink` for the actual bytes received.
+See the [Receive](https://github.com/TheThingsNetwork/arduino-device-lib/blob/master/examples/Receive/Receive.ino) example.
 
-## Property: downlinkPort
-The port the last message received was addressed to.
+## Method: provision
+Sets the information needed to activate the device via OTAA, without actually activating. Call join() without the first 2 arguments to activate.
 
 ```c
-int downlinkPort
+bool provision(const char *appEui, const char *appKey);
 ```
 
-## Property: downlink
-The last message received.
-
-```c
-byte downlink[64];
-```
+- `const char *appEui`: Application Identifier for the device.
+- `const char *appKey`: Application Key assigned to the device.