🤔 Curious about the Notecard? Want to learn more about Blues Wireless? Join us at Getting Started with the Notecard on July 14th!

Search
Documentation Results
End of results
Community Results
End of results
Support
Blues.io
Notehub.io
Shop
Sign In
Search
Documentation Results
End of results
Community Results
End of results
Support
Blues.io
Notehub.io
Shop
×
HomeTools & SDKs
Notecard CLI
Libraries
Libraries Overview
Arduino LibraryInstallationUsageDetailed ReferenceNotecard Class Reference
Python Library
Samples
Samples Overview
Host MCU Samples
Rate this page  
  • ★
    ★
  • ★
    ★
  • ★
    ★
  • ★
    ★
  • ★
    ★

Arduino Library

note-arduino is the official Arduino library for communicating with the Notecard over serial or I2C. 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 library , 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 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 zero, 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() {
    J *req = nc.newRequest("hub.set");
    if (req) {
        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.
J *req = nc.newRequest("card.status");
if (req) {
    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.
J *req = nc.newRequest("hub.sync");
if (req) {
    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 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();

          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
                          • ★
                            ★
                          • ★
                            ★
                          • ★
                            ★
                          • ★
                            ★
                          • ★
                            ★
                          © 2022 Blues Inc.Terms & ConditionsPrivacy
                          blues.ioTwitterLinkedInGitHubHackster.io
                          Disconnected
                          Serial 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.

                          Advanced Usage

                          The help command gives more info.

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