Notecard API Reference

The Notecard API is a collection of requests for interfacing with a Blues Wireless Notecard.

Overview

The Notecard & Notehub

The Notecard was designed with simplicity and ease of use as a fundamental goal. As such, the Notecard API exclusively consists of JSON requests to the Notecard and JSON responses from the Notecard.

Notecard Requests & Responses

JavaScript Object Notation, or JSON, is a lightweight format for storing and transporting data of most any kind. It contains 'fields' of your own choosing to convey strings, numbers, boolean values, other JSON objects, and arrays of values

JSON Fundamentals

How the Notecard works with JSON

Requests can be issued to the Notecard over USB, UART, or I2C. The Serial UART interface is fixed at a baud rate of 9600, with eight data bits, no parity bit, and one stop bit (9600/N-8-1).

Notecard Interfaces

Using the Notecard Interface with a Firmware Library

When building an embedded application with the Notecard, there are a number of essential API requests to know.

Notecard Walkthrough

Notehub Configuration

Adding Notes to Notefiles

Working with Environment Variables

Interacting with Notehub

Essential Requests

Once the Notecard is connected to a cell network or GPS, there are a number of requests available for obtaining the time, location, and using the onboard GPS module for location tracking.

Time & Location Requests

Obtaining the Current Time and Date

Using Cell Tower & Wi-Fi Triangulation

Working with GPS on the Notecard

Sampling GPS Readings with Periodic Mode

Sampling at Predefined Intervals

Always-on GPS with Continuous Mode

Determining the Current GPS Mode

Geofencing with the Notecard

Disabling GPS

All of the scenarios discussed so far in this guide are focused on performing requests directly against the Notecard from a host, and synching data from the Notecard to Notehub.

Inbound Requests & Shared Data

Sending Data Through Notehub

Creating & Handling Inbound Notes

Using Database Files for Replicated State

Using Change Trackers with Inbound Data

Handling Notecard Interrupts

Miscellaneous File Requests

If your host needs to perform web requests to a 3rd party API or service, the Notecard can facilitate these requests with the web.get, web.put, and web.post requests.

Web Transactions

The Notecard is designed to be battery operated, with low current consumption, making it an ideal choice for low power applications.

Low Power Design

Modem Power Management

Host Power Management

Voltage Monitoring

Motion Monitoring

Customizing Voltage-Variable Behaviors

When building an application that is expected to operate over a long period of time, you'll want to ensure that bandwidth is preserved and monitored, wherever possible.

Low Bandwidth Design

Working with Note Templates

Measuring Data Usage

Much of the power of the Notecard is in the fact that it can be used by any Host MCU or processor, from an 8-bit Arduino to a Raspberry Pi.

Host Firmware Update Requests

Obtaining Host Firmware Download Status

Entering DFU Mode on the Notecard

Ensuring DFU Mode is Active

Retrieving Host Firmware from the Notecard

Clearing DFU State

The Notecard provides a number of advanced configuration features that you can use to query the state and status of the Notecard, customize its behavior, set its Notehub service location, and configure the available AUX pins for use in your application.

Advanced Notecard Configuration

Performing Notecard Maintenance Requests

Changing the Notehub Service Host

Viewing and Customizing Modem Behavior

Changing the Notecard I2C Address

Working with the Notecard AUX Pins

Notecard API responses often include a set of error and status codes denoted by curly braces, e.g. `{sync-begin}`. These codes are static and will persist across API versions.

Notecard Error and Status Codes

Error Codes

Status Codes

Asset Tracking

What You Need to Get Started

Tracker Configuration Requests

Configure a Standalone Tracker

Configure a Host-Controlled Tracker

Viewing Tracker Data

Routing Tracker Data to Third-Party Services

Serial-Over-I2C Protocol

What is I2C

Transaction Structure

Data Query

Data Read

Data Write

Transaction Walkthrough

Guide for using Notehub and the Notecard for performing Host firmware updates

Updating Host Firmware

Preparing the Arduino IDE

Overview of the Host DFU Process

Adding DFU Capabilities to Firmware

Creating a Firmware Revision

Initiating a Host DFU from Notehub

Tracking DFU Progress

Updating ESP32 Host Firmware

Configuring the Notecard Attention Guide for the Adafruit Huzzah32 ESP32 Feather

Notecard Attention Guide

Notecard Interrupt

Hardware Setup

Firmware Breakdown

More on ESP32 Interrupt Handling

Additional Resources

Configuring ESP32 Attention Pin

How to configure Notehub.io and your Notecard to minimize latency

Minimizing Latency

Mechanism of Action

Configuring Notehub Interactions

Flushing Queued Notes

Overview of Environment Variables and how to use them

Understanding Environment Variables

The Hierarchy of Environment Variables

Setting Environment Variables

Session Environment Variables

Deleting Environment Variables

A guide for sending encrypted data through the Notecard and Notehub

Encrypting Data With the Notecard

Notecard Encryption Overview

Notecard Encryption Walkthrough

JSONata 1-2-3

The JSONata Exerciser

Composition

Parsing with Built-in Functions

Creating Custom Functions

Summary

Using External SIM Cards

Configuring the Notecard

Frequently Asked Questions

Notecard Guides