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.
To use the
note-arduino
library, you’ll need to add it to the Arduino IDE.Click on Tools > Manage Libraries...
Search for "Blues" in the input box and click the "Install" button next to the "Blues Wireless Notecard" result.
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).
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.
Notecard nc; ... void setup (void) { # Initialize Notecard serial interface (with defaults) nc.begin(Serial1); ...
Notecard nc; ... void setup (void) { # Initialize Notecard serial interface nc.begin(Serial1, 9600); ...
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.
Notecard nc; ... void setup (void) { # Initialize Notecard I2C interface (with defaults) nc.begin(); ...
uint32_t i2cAddress = 0x24; Notecard nc; ... void setup (void) { # Initialize Notecard I2C interface nc.begin(i2cAddress); ...
uint32_t i2cAddress = 0x17; uint32_t i2cMax = 32; Notecard nc; ... void setup (void) { # Initialize Notecard I2C interface nc.begin(i2cAddress, i2cMax); ...
uint32_t i2cAddress = 0x17; uint32_t i2cMax = 32; Notecard nc; ... void setup (void) { # Initialize Notecard I2C interface nc.begin(i2cAddress, i2cMax, Wire); ...
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.
#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);
Whether using Serial or I2C, sending Notecard requests and reading responses follows the same pattern:
- Create a JSON object that includes a valid Notecard API Request.
- Call one of the
notecard
methods and pass in the request JSON object. - If you called a method that returns a response, make sure the response contains the data you need.
#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); } } ...
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 thereq
key.
J *req = nc.newRequest("card.status");
requestAndResponse()
should be used if you need a response from the Notecard after a request is executed.
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.
if (J *req = nc.newRequest("hub.sync")) { nc.sendRequest(req); }
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
Class | Usage | Description |
---|---|---|
class Notecard | #include "Notecard.h" | Class that stores state and functions for interacting with the Blues Wireless Notecard. |
Class that stores state and functions for interacting with the Blues Wireless Notecard.
Method | Description |
---|---|
public void begin (uint32_t i2cAddress,uint32_t i2cMax,TwoWire & wirePort) | Initialize the Notecard for I2C. This function configures the Notecard to use the I2C bus for communication with the host. |
public void begin (HardwareSerial & serial,int speed) | Initialize the Notecard for Serial communication. This function configures the Notecard to use Serial for communication with the host. |
public void setDebugOutputStream (Stream & dbgserial) | 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. |
public void clearDebugOutputStream (void) | Clear the debug output source. |
public void i2cTest (int Adjustment) | 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. |
public J * newRequest (const char * request) | 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. |
public bool sendRequest (J * req) | Sends a request to the Notecard. This function takes a populated J JSON request object and sends it to the Notecard. |
public J * requestAndResponse (J * req) | 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. |
public void deleteResponse (J * rsp) | Deletes a J JSON response object from memory. |
public void logDebug (const char * message) | Write a message to the serial debug stream. |
public void logDebugf (const char * format,...) | Write a formatted message to the serial debug stream. |
public bool debugSyncStatus (int pollFrequencyMs,int maxLevel) | Periodically show Notecard sync status, returning TRUE if something was displayed to the debug stream. |
public bool responseError (J * rsp) | Determines if there is an error string present in a response object. |
Initialize the Notecard for I2C. This function configures the Notecard to use the I2C bus for communication with the host.
i2caddress
uint32_t
(optional)
The I2C Address to use for the Notecard.
(default value: NOTE_I2C_ADDR_DEFAULT
)
i2cmax
uint32_t
(optional)
The max length of each message to send from the host to the Notecard. Used to ensure the messages are sized appropriately for the host.
(default value: NOTE_I2C_MAX_DEFAULT
)
wirePort
TwoWire
class instance (optional)
The TwoWire implementation to use for I2C communication.
(default value: Wire
)
Notecard nc; ... // Initialize I2C using default parameters nc.begin();
Notecard nc; ... // Initialize I2C specifying all parameters nc.begin(0x17, 30, Wire);
Initialize the Notecard for Serial communication. This function configures the Notecard to use Serial for communication with the host.
selectedSerialPort
HardwareSerial
class instance
The HardwareSerial bus to use.
selectedSpeed
int
The baud rate to use for communicating with the Notecard from the host.
(default value: 9600
) (optional)
Notecard nc; ... // Initialize Serial using default parameters nc.begin(Serial1);
Notecard nc; ... // Initialize Serial specifying all parameters nc.begin(Serial1, 9600);
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.
dbgserial
Stream
interface instance
The Stream object to use for debug output.
Notecard nc; ... nc.setDebugOutputStream(Serial);
Clear the debug output source.
Notecard nc; ... nc.clearDebugOutputStream();
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.
Adjustment
int
The adjustment length.
Notecard nc; ... nc.i2cTest(8);
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.
request
const char *
The request name, for example, note.add
.
Notecard nc; ... J *req = nc.newRequest("card.status");
A pointer to a J
JSON Object populated with the request name.
Sends a request to the Notecard. This function takes a populated J
JSON request object and sends it to the Notecard.
req
J *
class instance pointer
A pointer to a J *
JSON request object.
Notecard nc; ... if ((J *req = nc.newRequest("hub.sync"))) { nc.sendRequest(req); }
true
if the message was successfully sent to the Notecard, false
if there was an error.
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.
req
J *
class instance pointer
A pointer to a J *
JSON request object.
Notecard nc; ... if ((J *req = nc.newRequest("card.status"))) { J *rsp = nc.requestAndResponse(req); nc.logDebug(rsp); nc.deleteResponse(rsp); }
J *
JSON object pointer with the response from the Notecard.
You are responsible for managing the memory associated with the JSON response object.
Deletes a J
JSON response object from memory.
rsp
J *
class instance pointer
A pointer to a J
JSON response object.
Notecard nc; ... if ((J *req = nc.newRequest("card.status"))) { J *rsp = nc.requestAndResponse(req); nc.deleteResponse(rsp); }
Write a message to the serial debug stream.
message
const char *
A string to log to the serial debug stream.
Notecard nc; ... nc.logDebug("Hello, World!\n");
Write a formatted message to the serial debug stream.
format
A format string to log to the serial debug stream.
One or more values to interpolate into the format string.
Notecard nc; bool excited; ... nc.logDebugf("High-%d!\n", (excited ? 10 : 5));
Periodically show Notecard sync status, returning true
if something was displayed to the debug stream.
pollFrequencyMs
int
The frequency to poll the Notecard for sync status.
maxLevel
int
The maximum log level to output to the debug console. Pass -1 for all.
Supported logging levels:
0
- Major
1
- Minor
2
- Detailed
3
- Programmatic
Notecard nc; ... // Poll for programmatic level (3) sync status every 1.5s (1500ms) nc.debugSyncStatus(1500, 3);
true
if a pending response was displayed to the debug stream.
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.
Determines if there is an error string present in a response object.
rsp
J *
class instance pointer
A pointer to a J
JSON response object.
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); }
true
if the response object contains an error.