Notecard Communication Without a Library

Raw serial transactions with the Notecard allow you to communicate with the Notecard in the most direct and efficient way possible. This technique can be employeed when there are memory or language constraints on the device.

These raw transactions are also the foundation of creating native language support libraries, such as those found in our firmware libraries overview

warning

When NOT using a native firmware library, you may unintentionally send requests to the Notecard so fast that you overflow the 1500 byte buffer used to receive data (whether it be I2C, Serial, or UART). The solution is to pause 250ms after every ~250 bytes sent, and to ensure the total size of each NDJSON object sent is no more than 8KB.

Basic Communications

Vocabulary

chunk - a string or "chunk" of data less than 256 bytes
polling delay - the time between consecutive Notecard requests
segment - a series of chunks less than or equal to 256 bytes

Timing

The Notecard serial transactions, both UART and I2C, are implemented without flow control. As such, certain timing requirements must be observed to ensure the integrity of serial communications with the Notecard.

Each chunk should observe a 20ms delay.
Each segment requires a 250ms delay.
A polling delay of 25ms should be respected to allow the Notecard time to process a request and generate a response.

Arduino Example

First, let's alias the Serial interfaces at the top of your program in the Arduino IDE. The first, Serial will be used to log information to the Serial Monitor of the Arduino IDE. The second, Serial1 represents the connection between your Arduino and Notecard. Paste the following code at the top of your sketch:
```
#define usbSerial Serial
#define txRxPinsSerial Serial1
```

Next, add a definition for your ProductUID using the value you specified when creating your Notehub project.


#define NOTE_PRODUCT_UID "com.your-company:your_product"

In the setup() function, initialize the usbSerial object.


usbSerial.begin(115200);
while (!usbSerial) {
   ; // wait for serial port to connect. Needed for native USB
}
usbSerial.println("Starting...");

Also in setup, initialize the txRxPinsSerial object, using a baud rate of 9600, and send a newline (\n) to clear out any pending data on the device.


txRxPinsSerial.begin(9600);
txRxPinsSerial.println("\n");
delay(250);

Now, we'll configure the Notecard. This one-time operation also belongs in the setup() function. We will use the hub.set request to associate this Notecard with the ProductUID of your project, as well as set the Notecard to operate in continuous mode (which indicates that the device should immediately make a connection to Notehub and keep it active).
```
txRxPinsSerial.println("{\"req\":\"hub.set\",\"product\":\"" NOTE_PRODUCT_UID "\",\"mode\":\"continuous\"}");
```

Finally, we'll add a while loop to setup to read the Notecard's response, and display the result to the Arduino terminal.


delay(250); // wait for the Notecard to respond
while (txRxPinsSerial.available() > 0) {
    char incomingByte = txRxPinsSerial.read();
    if (incomingByte != '\r' && incomingByte != '\n') {
       usbSerial.print(incomingByte);
    }
}
usbSerial.println();

Now, it's time to watch the logs and validate the firmware. Open the Serial Monitor, by selecting Tools > Serial Monitor from the menu. The default baud rate is 9600 baud, so be sure to select 115200 baud from the drop down menu.
Click the upload button (right arrow icon) to save and flash the firmware to your device.
If you haven't saved your file yet, you will be prompted to do so. Name your sketch (for example, nano-no-library), and click Save. Once your device is flashed and comes back online, check the serial monitor to confirm your Notecard has been properly configured.
```
Starting...
{}
```

Summary

As you can see, creating such a library is as simple as communicating with the Notecard itself. However, timing is an important consideration that cannot be easily reasoned about. This document aims to close that knowledge gap and enable the creation of these libraries and so much more.