chore: Refactor binary example code (#108)

* chore: Refactor binary example code
* fix: demo termination behavior

Author: zfields

.github/workflows/note-arduino-ci.yml

@@ -38,6 +38,8 @@ jobs:
           - ./examples/Example5_UsingTemplates/Example5_UsingTemplates.ino
           - ./examples/Example6_SensorTutorial/Example6_SensorTutorial.ino
           - ./examples/Example7_PowerControl/Example7_PowerControl.ino
+          - ./examples/Example8_BinarySendReceive/Example8_BinarySendReceive.ino
+          - ./examples/Example9_BinarySendReceiveChunked/Example9_BinarySendReceiveChunked.ino
         fully-qualified-board-name:
           - STMicroelectronics:stm32:BluesW:pnum=SWAN_R5
           - esp32:esp32:featheresp32

examples/Example0_LibrarylessCommunication/Example0_LibrarylessCommunication.ino

@@ -90,6 +90,8 @@ void loop()
     static unsigned eventCounter = 0;
     if (++eventCounter > 25)
     {
+        txRxPinsSerial.println("Demo cycle complete. Program stopped. Press RESET to restart.");
+        delay(10000); // 10 seconds
         return;
     }
 

examples/Example1_NotecardBasics/Example1_NotecardBasics.ino

@@ -127,6 +127,8 @@ void loop()
     static unsigned eventCounter = 0;
     if (++eventCounter > 25)
     {
+        notecard.logDebug("Demo cycle complete. Program stopped. Press RESET to restart.");
+        delay(10000); // 10 seconds
         return;
     }
 

examples/Example2_PeriodicCommunications/Example2_PeriodicCommunications.ino

@@ -173,6 +173,8 @@ void loop()
     static unsigned eventCounter = 0;
     if (++eventCounter > 25)
     {
+        notecard.logDebug("Demo cycle complete. Program stopped. Press RESET to restart.");
+        delay(10000); // 10 seconds
         return;
     }
 

examples/Example5_UsingTemplates/Example5_UsingTemplates.ino

@@ -155,6 +155,8 @@ void loop()
     static unsigned eventCounter = 0;
     if (++eventCounter > 25)
     {
+        notecard.logDebug("Demo cycle complete. Program stopped. Press RESET to restart.");
+        delay(10000); // 10 seconds
         return;
     }
 

examples/Example6_SensorTutorial/Example6_SensorTutorial.ino

@@ -66,6 +66,8 @@ void loop()
     static unsigned eventCounter = 0;
     if (++eventCounter > 25)
     {
+        notecard.logDebug("Demo cycle complete. Program stopped. Press RESET to restart.");
+        delay(10000); // 10 seconds
         return;
     }
 

examples/Example7_PowerControl/Example7_PowerControl.ino

@@ -134,6 +134,8 @@ void loop()
     // Bump the number of cycles
     if (++globalState.cycles > 25)
     {
+        notecard.logDebug("Demo cycle complete. Program stopped. Press RESET to restart.");
+        delay(10000); // 10 seconds
         return;
     }
 

examples/Example8_BinarySendReceive/Example8_BinarySendReceive.ino

@@ -0,0 +1,147 @@
+// Copyright 2023 Blues Inc. All rights reserved.
+//
+// Use of this source code is governed by licenses granted by the
+// copyright holder including that found in the LICENSE file.
+//
+// This example exercises the Notecard's ability to send and receive a binary
+
+#include <stddef.h>
+#include <stdint.h>
+#include <stdlib.h>
+#include <string.h>
+
+#include <Notecard.h>
+
+// Note that both of these definitions are optional; just prefix either line
+// with `//` to remove it.
+// - Remove txRxPinsSerial if you wired your Notecard using I2C SDA/SCL pins
+//   instead of serial RX/TX
+// - Remove usbSerial if you don't want the Notecard library to output debug
+//   information
+
+// #define txRxPinsSerial Serial1
+#define usbSerial Serial
+
+// This is the unique Product Identifier for your device
+#ifndef PRODUCT_UID
+#define PRODUCT_UID "" // "com.my-company.my-name:my-project"
+#pragma message "PRODUCT_UID is not defined in this example. Please ensure your Notecard has a product identifier set before running this example or define it in code here. More details at https://dev.blues.io/tools-and-sdks/samples/product-uid"
+#endif
+
+#define myProductID PRODUCT_UID
+Notecard notecard;
+
+// One-time Arduino initialization
+void setup()
+{
+    // Set up for debug output (if available).
+#ifdef usbSerial
+    // If you open Arduino's serial terminal window, you'll be able to watch
+    // JSON objects being transferred to and from the Notecard for each request.
+    usbSerial.begin(115200);
+    const size_t usb_timeout_ms = 3000;
+    for (const size_t start_ms = millis(); !usbSerial && (millis() - start_ms) < usb_timeout_ms;)
+        ;
+    notecard.setDebugOutputStream(usbSerial);
+#endif
+
+    // Initialize the physical I/O channel to the Notecard
+#ifdef txRxPinsSerial
+    notecard.begin(txRxPinsSerial, 9600);
+#else
+    notecard.begin();
+#endif
+
+    // Configure the productUID, and instruct the Notecard to stay connected to
+    // the service.
+    J *req = notecard.newRequest("hub.set");
+    if (myProductID[0])
+    {
+        JAddStringToObject(req, "product", myProductID);
+    }
+    JAddStringToObject(req, "mode", "continuous");
+    notecard.sendRequestWithRetry(req, 5); // 5 seconds
+
+    // Reset the state of the Notecard's binary data store to a known value.
+    NoteBinaryReset();
+}
+
+// In the Arduino main loop which is called repeatedly, add outbound data every
+// 30 seconds
+void loop()
+{
+    // Stop the demo after five iterations to conserve data
+    static unsigned event_counter = 0;
+    if (++event_counter > 5)
+    {
+        notecard.logDebug("Demo cycle complete. Program stopped. Press RESET to restart.");
+        delay(10000); // 10 seconds
+        return;
+    }
+
+    // Send data to the Notecard storage and pull it back
+    {
+        /////////////////////////////////////////////////
+        // Transmit that beautiful bean footage
+        /////////////////////////////////////////////////
+        char data[64] = "https://youtu.be/0epWToAOlFY?t=21";
+        size_t data_len = strlen(data);
+        const size_t notecard_binary_area_offset = 0;
+        NoteBinaryTransmit(reinterpret_cast<uint8_t *>(data), data_len, sizeof(data), notecard_binary_area_offset);
+        notecard.logDebugf("\n[INFO] Transmitted %d bytes.\n", data_len);
+
+        // Log for the sake of curiosity
+        notecard.logDebug("\n*** Encoded Binary Transmission ***\n");
+        size_t tx_len = NoteBinaryEncodedLength(reinterpret_cast<uint8_t *>(data), data_len);
+        for (size_t i = 0 ; i < tx_len ; ++i) {
+            notecard.logDebugf("%02x ", data[i]);
+            if ((i + 1) % 16 == 0) {
+                notecard.logDebug("\n");
+            }
+        }
+        notecard.logDebug("\n*** Encoded Binary Transmission ***\n\n");
+
+        /////////////////////////////////////////////////
+        // Receive data from the Notecard binary data store
+        /////////////////////////////////////////////////
+        size_t rx_buffer_len = 0;
+        NoteBinaryRequiredRxMaxBuffer(&rx_buffer_len);
+        uint8_t *rx_buffer = (uint8_t *)malloc(rx_buffer_len);
+        data_len = NOTE_C_BINARY_RX_ALL; // NOTE_C_BINARY_RX_ALL is a special value
+                                         // meaning "return all bytes from offset"
+        NoteBinaryReceive(reinterpret_cast<uint8_t *>(rx_buffer), rx_buffer_len, notecard_binary_area_offset, &data_len);
+        notecard.logDebugf("\n[INFO] Received %d bytes.\n", data_len);
+
+        // Display received buffer
+        notecard.logDebug("\n*** Decoded Data ***\n");
+        for (size_t i = 0 ; i < data_len ; ++i) {
+            notecard.logDebugf("%c", rx_buffer[i]);
+        }
+        notecard.logDebug("\n*** Decoded Data ***\n\n");
+
+        // NOTE: The binary data store is not cleared on receive, which
+        //       allows us to submit it to Notehub in the next step.
+    }
+
+    // Send it to Notehub
+    {
+        // Submit binary object to the Notehub using `note.add`. This will send
+        // the binary to Notehub in the payload field of the Note. The payload
+        // will not be visible in the Notehub UI, but the data will be forwarded
+        // to any pre-configured routes.
+        if (J *req = notecard.newRequest("note.add"))
+        {
+            JAddStringToObject(req, "file", "cobs.qo");
+            JAddBoolToObject(req, "binary", true);
+            JAddBoolToObject(req, "live", true);
+            if (!notecard.sendRequest(req)) {
+                // The binary data store is cleared on successful transmission,
+                // but we need to reset it manually if the request failed.
+                NoteBinaryReset();
+            }
+        }
+    }
+
+    // Delay between sends
+    delay(30 * 1000); // 30 seconds
+}