Support
Blues.io
Notehub.io
Shop
Support
Blues.io
Notehub.io
Shop
×
HomeTools & SDKs
Notecard CLI
Arduino LibraryInstallationUsageDetailed ReferenceNotecard Class Reference
Python Library

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.

    Installing the Blues Wireless Notecard library.

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

Notecard nc;
...

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

Serial Initialization with Baud Rate

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

Notecard nc;
...

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

I2C Initialization with Address

uint32_t i2cAddress = 0x24;

Notecard nc;
...

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

I2C Initialization with Address and Max Transaction Length

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

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.

#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.
#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.
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);
}

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

Arduino Examples

Detailed Reference

Library Classes

ClassUsageDescription
class Notecard#include "Notecard.h"Class that stores state and functions for interacting with the Blues Wireless Notecard.

Notecard Class Reference

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

Class Notecard

MethodDescription
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.

begin (I2C)

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

Arguments

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);

    begin (Serial)

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

    Arguments

    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);

      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.

      Arguments

      dbgserial

      Stream interface instance

      The Stream object to use for debug output.

        Notecard nc;
        ...
        
        nc.setDebugOutputStream(Serial);
        

        clearDebugOutputStream

        Clear the debug output source.

        Arguments
        None
          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.

          Arguments

          Adjustment

          int

          The adjustment length.

            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.

            Arguments

            request

            const char *

            The request name, for example, note.add.

              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.

              Arguments

              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);
                }
                

                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.

                Arguments

                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);
                  }
                  

                  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.

                  Arguments

                  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);
                    }
                    

                    See also

                    • requestAndResponse()

                    logDebug

                    Write a message to the serial debug stream.

                    Arguments

                    message

                    const char *

                    A string to log to the serial debug stream.

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

                      logDebugf

                      Write a formatted message to the serial debug stream.

                      Arguments

                      format

                      A format string to log to the serial debug stream.

                      ... (variadic)

                      One or more values to interpolate into the format string.

                        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.

                        Arguments

                        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);

                          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.

                          Arguments

                          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);
                            }
                            

                            Returns

                            true if the response object contains an error.

                            Can we improve this page? Send us feedbackRate this page
                            • ★
                              ★
                            • ★
                              ★
                            • ★
                              ★
                            • ★
                              ★
                            • ★
                              ★
                            © 2021 Blues Inc.Terms & ConditionsPrivacy
                            blues.ioTwitterLinkedInGitHubHackster.io
                            Disconnected
                            Disconnected
                            Having trouble connecting?

                            Try changing your Micro USB cable as some cables do not support transferring data. If that does not solve your problem, contact us at support@blues.com and we will get you set up with another tool to communicate with the Notecard.

                            Connect a NotecardClick 'Connect' and select a USB-connected Notecard to start issuing requests from the browser.