Arduino Library

note-arduino is the official Arduino library for communicating with the Notecard over serial or I²C. This library works on any Arduino compatible Microcontroller, and can be installed from the Arduino Library Manager.

Installation

1. To use the note-arduino library, you’ll need to add it to the Arduino IDE.

2. Click on Tools > Manage Libraries...

3. Search for "Blues" in the input box and click the "Install" button next to the "Blues Wireless Notecard" result.

   

Usage

To use note-arduino, create a new sketch and select the Sketch > Include Library > Contributed Libraries > Blues Wireless Notecard menu option, to add the following include to your sketch:

#include <Notecard.h>

The note-arduino library requires a reference to a serial or i2c object that you pass into the library (typically the Serial or Wire object).

Serial Configuration

To initialize the Notecard over Serial, instantiate a Notecard object, then use the begin() method and provide the Serial object as a parameter. The Notecard object will initialize the serial bus on your behalf.

Default Serial Initialization

COPY
Notecard nc;
...

void setup (void) {
    # Initialize Notecard serial interface (with defaults)
    nc.begin(Serial1);
    ...

Serial Initialization with Baud Rate

COPY
Notecard nc;
...

void setup (void) {
    # Initialize Notecard serial interface
    nc.begin(Serial1, 9600);
    ...

I2C Configuration

To initialize the Notecard over I2C, instantiate a Notecard object, then use the begin() method with one, two, or three parameters. Use as many parameters as needed to match your implementation.

Default I2C Initialization

COPY
Notecard nc;
...

void setup (void) {
    # Initialize Notecard I2C interface (with defaults)
    nc.begin();
    ...

I2C Initialization with Address

COPY
uint32_t i2cAddress = 0x24;

Notecard nc;
...

void setup (void) {
    # Initialize Notecard I2C interface
    nc.begin(i2cAddress);
    ...

I2C Initialization with Address and Max Transaction Length

COPY
uint32_t i2cAddress = 0x17;
uint32_t i2cMax = 32;

Notecard nc;
...

void setup (void) {
    # Initialize Notecard I2C interface
    nc.begin(i2cAddress, i2cMax);
    ...

I2C Initialization with Address, Max Transaction Length and I2C Bus

COPY
uint32_t i2cAddress = 0x17;
uint32_t i2cMax = 32;

Notecard nc;
...

void setup (void) {
    # Initialize Notecard I2C interface
    nc.begin(i2cAddress, i2cMax, Wire);
    ...

Debug Mode

If you're connected to the Serial Monitor (located in the "Tools" menu of the IDE), you can put the Notecard library in debug mode using the setDebugOutputStream method, which will output raw JSON requests and responses.

COPY
#define serialDebug Serial
Notecard nc;
...

void setup() {
  // Initialize Debug Output
  serialDebug.begin(115200);
  while (!serialDebug) {
    ; // wait for serial port to connect. Needed for native USB
  }
  nc.setDebugOutputStream(serialDebug);

Sending Notecard Requests

Whether using Serial or I2C, sending Notecard requests and reading responses follows the same pattern:

1. Create a JSON object that includes a valid Notecard API Request.
2. Call one of the notecard methods and pass in the request JSON object.
3. If you called a method that returns a response, make sure the response contains the data you need.

COPY
#define productUID "org.coca-cola.soda.vending-machine.v2"
Notecard nc;
...

void setup() {
    ...
    if (J *req = nc.newRequest("hub.set")) {
        JAddStringToObject(req, "product", productUID);
        JAddStringToObject(req, "mode", "continuous");
        JAddBoolToObject(req, "sync", true);
        if (!nc.sendRequest(req)) {
            nc.logDebug("FATAL: Failed to configure Notecard!\n");
            while(1);
        }
    }
    ...

notecard Methods

The Notecard provides two methods for performing requests, depending on whether you need a response from the Notecard.

• newRequest() should be used to create a JSON (J) object. This method will create an object with the req key.

COPY
J *req = nc.newRequest("card.status");

• requestAndResponse() should be used if you need a response from the Notecard after a request is executed.

COPY
if (J *req = nc.newRequest("card.status")) {
    J* rsp = nc.requestAndResponse(req);
    nc.logDebug(rsp);
    nc.deleteResponse(rsp);
}

• sendRequest() should be used if you do not need a response from the Notecard after a request is executed.

COPY
if (J *req = nc.newRequest("hub.sync")) {
    nc.sendRequest(req);
}

Example Code

Several examples are also provided directly from the Arduino IDE.

• Example0_LibrarylessCommunication.ino
• Example1_NotecardBasics.ino
• Example2_PeriodicCommunications.ino
• Example3_InboundPolling.ino
• Example4_InboundInterrupts.ino
• Example5_UsingTemplates.ino
• Example6_SensorTutorial.ino

Detailed Reference

Library Classes

Notecard Class Reference

Class that stores state and functions for interacting with the Blues Wireless Notecard.

Class Notecard

begin (I2C)

Initialize the Notecard for I2C. This function configures the Notecard to use the I2C bus for communication with the host.

COPY
Notecard nc;
...

// Initialize I2C using default parameters
nc.begin();

COPY
Notecard nc;
...

// Initialize I2C specifying all parameters
nc.begin(0x17, 30, Wire);

begin (Serial)

Initialize the Notecard for Serial communication. This function configures the Notecard to use Serial for communication with the host.

COPY
Notecard nc;
...

// Initialize Serial using default parameters
nc.begin(Serial1);

COPY
Notecard nc;
...

// Initialize Serial specifying all parameters
nc.begin(Serial1, 9600);

setDebugOutputStream

Set the debug output source. This function takes a Stream object (for example, Serial) and configures it as a source for writing debug messages during development.

COPY
Notecard nc;
...

nc.setDebugOutputStream(Serial);

clearDebugOutputStream

Clear the debug output source.

COPY
Notecard nc;
...

nc.clearDebugOutputStream();

i2cTest

Adjust the I2C read length. Method enabling a developer to test the state of a known issue with the I2C HAL on some ST Microelectronics boards.

COPY
Notecard nc;
...

nc.i2cTest(8);

newRequest

Creates a new request object for population by the host. This function accepts a request string (for example, "note.add") and initializes a JSON Object to return to the host.

COPY
Notecard nc;
...

J *req = nc.newRequest("card.status");

Returns

A pointer to a J JSON Object populated with the request name.

See also

• requestAndResponse()
• sendRequest()

sendRequest

Sends a request to the Notecard. This function takes a populated J JSON request object and sends it to the Notecard.

COPY
Notecard nc;
...

if ((J *req = nc.newRequest("hub.sync"))) {
    nc.sendRequest(req);
}

Returns

true if the message was successfully sent to the Notecard, false if there was an error.

See also

• newRequest()

requestAndResponse

Sends a request to the Notecard and returns the JSON Response. This function takes a populated J JSON request object and sends it to the Notecard.

COPY
Notecard nc;
...

if ((J *req = nc.newRequest("card.status"))) {
    J *rsp = nc.requestAndResponse(req);
    nc.logDebug(rsp);
    nc.deleteResponse(rsp);
}

Returns

J * JSON object pointer with the response from the Notecard.

See also

• deleteResponse()
• newRequest()

warning

You are responsible for managing the memory associated with the JSON response object.

deleteResponse

Deletes a J JSON response object from memory.

COPY
Notecard nc;
...

if ((J *req = nc.newRequest("card.status"))) {
    J *rsp = nc.requestAndResponse(req);
    nc.deleteResponse(rsp);
}

See also

• requestAndResponse()

logDebug

Write a message to the serial debug stream.

COPY
Notecard nc;
...

nc.logDebug("Hello, World!\n");

logDebugf

Write a formatted message to the serial debug stream.

COPY
Notecard nc;
bool excited;
...

nc.logDebugf("High-%d!\n", (excited ? 10 : 5));

debugSyncStatus

Periodically show Notecard sync status, returning true if something was displayed to the debug stream.

COPY
Notecard nc;
...

// Poll for programmatic level (3) sync status every 1.5s (1500ms)
nc.debugSyncStatus(1500, 3);

Returns

true if a pending response was displayed to the debug stream.

warning

Specific log messages are NOT considered to be part of the stable API, and therefore should NEVER be programmed against. There is no guarantee of consistency of message or logging level for any given message.

responseError

Determines if there is an error string present in a response object.

COPY
Notecard nc;
...

if ((J *req = nc.newRequest("card.status"))) {
    J *rsp = nc.requestAndResponse(req);
    if (nc.responseError(rsp)) {
        nc.logDebug("Error response returned!");
    } else {
        // process response
    }
    nc.deleteResponse(rsp);
}

Returns

true if the response object contains an error.