Python Library

note-python is the official Python library for communicating with the Notecard over serial or I2C. This library works in a desktop setting, on single-board computers like the Raspberry Pi, and on microcontrollers with MicroPython or CircuitPython support.

note

This library is supported in Python 3.5 and above. The library may work, but is not supported, in Python 2.x environments.

Installation

PC and Single-Board Computer Use

With pip via PyPi:

pip install note-python

or

pip3 install note-python

CircuitPython & MicroPython

For use with MicroPython or CircuitPython, clone the note-python repo to your computer. Then, copy the contents of the notecard directory into the lib directory of your device.

Usage

To use note-python, start by importing it at the top of any Python file.

COPY
import notecard

The note-python library requires a pointer to a serial or i2c object that you initialize and pass into the library. This object differs based on your platform or device.

PC & Single-Board Computer Configuration

To communicate with the Notecard from a PC or Single-Board Computer, you'll need to first install python-periphery.

pip install python-periphery

Serial Configuration

To initialize the Notecard over Serial, configure a PySerial Serial object and use the OpenSerial method. This method returns a notecard object that can be used to perform Notecard requests.

COPY
# Use pySerial on a PC or SBC
import serial
port = serial.Serial("/dev/serial0", 9600)

nCard = notecard.OpenSerial(port)

I2C Configuration

To initialize the Notecard over I2C, configure a Periphery I2C object and use the OpenI2C method. This method returns a notecard object that can be used to perform Notecard requests.

COPY
# Use python-periphery on a PC or SBC
from periphery import I2C
port = I2C("/dev/i2c-1")

nCard = notecard.OpenI2C(port, 0, 0)

CircuitPython Configuration

Both Serial and I2C are accessible in CircuitPython using the built-in busio and boards library, which should be imported at the top of your Python file.

COPY
import board
import busio

Serial Configuration

To initialize the Notecard over Serial, configure a busio UART object with the TX and RX pins on the device, and use the OpenSerial method. This method returns a notecard object that can be used to perform Notecard requests.

COPY
# Use busio on a CircuitPython Device
port = busio.UART(board.TX, board.RX, baudrate=9600)

nCard = notecard.OpenSerial(port)

I2C Configuration

To initialize the Notecard over I2C, configure a busio I2C object with the SCL and SDA pins on the device, and use the OpenI2C method. This method returns a notecard object that can be used to perform Notecard requests.

COPY
# Use busio on a CircuitPython Device
port = busio.I2C(board.SCL, board.SDA)

nCard = notecard.OpenI2C(port, 0, 0)

MicroPython Configuration

Both Serial and I2C are accessible in MicroPython using the built-in machine library.

Serial Configuration

To initialize the Notecard over Serial, configure a machine UART object and use the OpenSerial method. This method returns a notecard object that can be used to perform Notecard requests.

COPY
# Use busio on a MicroPython Device
from machine import UART
port = UART(2, 9600)
port.init(9600, bits=8, parity=None, stop=1)

nCard = notecard.OpenSerial(port)

I2C Configuration

To initialize the Notecard over I2C, configure a machine I2C object and use the OpenI2C method. This method returns a notecard object that can be used to perform Notecard requests.

COPY
# Use busio on a MicroPython Device
from machine import I2C
port = I2C()

nCard = notecard.OpenI2C(port, 0, 0)

Debug Mode

If you're connected to a Python terminal, you can put the Notecard library in debug mode, which will output raw JSON requests and responses. Set debug to True when initializing the Notecard with OpenSerial or OpenI2C:

COPY
nCard = notecard.OpenI2C(port, 0, 0, debug=True)

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
# Construct a JSON Object to add a Note to the Notecard
req = {"req": "note.add"}
req["body"] = {"temp": 18.6}

rsp = nCard.Transaction(req)
print(rsp) # {"total":1}

notecard Methods

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

• Transaction() should be used if you need a response from the Notecard after a request is executed. All requests made with this method should include the req key.

COPY
req = {"req": "card.status"}

rsp = nCard.Transaction(req)
print(rsp)

• Command() should be used if you do not need a response from the Notecard after a request is executed. All requests made with this method should include the cmd key.

COPY
cmd = {"cmd": "hub.sync"}

nCard.Command(req)

Using the Library Fluent API

The notecard class allows complete access to the Notecard API via manual JSON object construction and the Transaction, Command methods. Alternatively, you can import one or more Fluent API helpers to work with common aspects of the Notecard API without having to author JSON objects, by hand.

note

Not all aspects of the Notecard API are available using these helpers. For a complete list of supported helpers, see the detailed reference below.

Here's an example that uses the hub helper to set the Notecard Product UID in CircuitPython:

COPY
import board
import busio

import notecard
from notecard import hub

port = busio.I2C(board.SCL, board.SDA)
nCard = notecard.OpenI2C(port, 0, 0, debug=True)

productUID = "com.your-company.your-name:your_product"
rsp = hub.set(nCard, productUID, mode="continuous", sync=True)

print(rsp) # {}

Detailed Reference

Library Classes

notecard Class Reference

Members

Notecard Class

Base Notecard class. Provides a shared init to reset the Notecard via Serial or I2C.

OpenI2C Class

Notecard subclass for I2C communication.

__init__

Initialize the Notecard over I2C.

COPY
from periphery import I2C
port = I2C("/dev/i2c-1")

nCard = notecard.OpenI2C(port, 0, 0, debug=True)

Transaction

Perform a Notecard transaction and return the result.

COPY
req = {"req": "note.add"}
req["body"] = {"temp": 18.6}

rsp = nCard.Transaction(req)
print(rsp) # {"total":1}

Command

Perform a Notecard command and exit with no response.

COPY
req = {"cmd": "note.add"}
req["body"] = {"temp": 18.6}

nCard.Command(req)

Reset

Reset the Notecard.

COPY
nCard.Reset()

OpenSerial

Notecard class for Serial communication.

__init__

Initialize the Notecard over Serial.

COPY
import serial
port = serial.Serial("/dev/serial0", 9600)

nCard = notecard.OpenSerial(port, debug=True)

Transaction

Perform a Notecard transaction and return the result.

COPY
req = {"req": "note.add"}
req["body"] = {"temp": 18.6}

rsp = nCard.Transaction(req)
print(rsp) # {"total":1}

Command

Perform a Notecard command and exit with no response.

COPY
req = {"cmd": "note.add"}
req["body"] = {"temp": 18.6}

nCard.Command(req)

Reset

Reset the Notecard.

COPY
nCard.Reset()

card Class Reference

Public Methods

attn()

Configure interrupt detection between a host and Notecard. See card.attn in the Complete API Reference.

COPY
rsp = card.attn(nCard,
                mode="arm, files",
                files=["data.qi"])

print(rsp)

Returns

A JSON payload containing the Notecard response.

COPY
{
  "files": ["data.qi", "modified"],
  "set": true
}

time()

Retrieve the current time and date from the Notecard. See card.time in the Complete API Reference.

COPY
rsp = card.time(nCard)

print(rsp)

Returns

A JSON payload containing the Notecard response.

COPY
{
  "time": 1599769214,
  "area": "Beverly, MA",
  "zone": "CDT,America/New York",
  "minutes": -300,
  "lat": 42.5776,
  "lon": -70.87134,
  "country": "US"
}

status()

Retrieve the status of the Notecard. See card.status in the Complete API Reference.

COPY
rsp = card.status(nCard)

print(rsp)

Returns

A JSON payload containing the Notecard response.

COPY
{
  "status": "{normal}",
  "usb": true,
  "storage": 8,
  "time": 1599684765,
  "connected": "true"
}

temp()

Retrieve the current temperature from the Notecard. See card.temp in the Complete API Reference.

COPY
rsp = card.temp(nCard, minutes=10)

print(rsp)

Returns

A JSON payload containing the Notecard response.

COPY
{
  "value": 27.625,
  "calibration": -3.0
}

version()

Retrieve firmware version information from the Notecard. See card.version in the Complete API Reference.

COPY
rsp = card.version(nCard, minutes=10)

print(rsp)

Returns

A JSON payload containing the Notecard response.

COPY
{
  "body": {
    "org": "Blues Wireless",
    "product": "Notecard",
    "version": "notecard-1.6.0",
    "ver_major": 1,
    "ver_minor": 6,
    "ver_patch": 0,
    "ver_build": 12200,
    "built": "Jan 2 2021 08:45:10"
  },
  "version": "notecard-1.6.0.12200",
  "device": "dev:000000000000000",
  "name": "Blues Wireless Notecard",
  "type": 11,
  "sku": "NOTE-WBNA500"
}

voltage()

Retrieve current and historical voltage info from the Notecard. See card.voltage in the Complete API Reference.

COPY
rsp = card.voltage(nCard,
                   hours=120,
                   offset=24,
                   vmax=4.3,
                   vmin=2.7)

print(rsp)

Returns

A JSON payload containing the Notecard response.

COPY
{
  "mode": "usb",
  "value": 5.2791994059442461,
  "hours": 772,
  "vmin": 4.48,
  "vmax": 5.28,
  "vavg": 4.9106748466257669,
  "daily": 0.13,
  "weekly": 0.12,
  "monthly": 0.11
}

wireless()

Retrieve wireless modem info or customize modem behavior. See card.wireless in the Complete API Reference.

COPY
rsp = card.wireless(nCard, mode="nb")

print(rsp)

Returns

A JSON payload containing the Notecard response.

COPY
{
  "status": "{modem-off}",
  "count": 1,
  "net": {
    "iccid": "00000000000000000000",
    "imsi": "000000000000000",
    "imei": "000000000000000",
    "modem": "EG91NAXGAR07A03M1G_BETA0415_01.001.01.001",
    "band": "LTE BAND 2",
    "rat": "lte",
    "rssir": -69,
    "rssi": -70,
    "rsrp": -105,
    "sinr": 86,
    "rsrq": -17,
    "bars": 1,
    "mcc": 310,
    "mnc": 410,
    "lac": 28681,
    "cid": 211150856,
    "updated": 1599225076
  }
}

env Class Reference

Public Methods

default()

Perform an env.default request against a Notecard. See env.default in the Complete API Reference

COPY
rsp = env.default(nCard,
                  name="monitor-pump",
                  text="true")

print(rsp)

Returns

A JSON payload containing the Notecard response.

COPY
{}

get()

Perform an env.get request against a Notecard. See env.get in the Complete API Reference

COPY
rsp = env.get(nCard,
              name="monitor-pump")

print(rsp)

Returns

A JSON payload containing the Notecard response.

COPY
{
  "text": "true"
}

modified()

Perform an env.modified request against a Notecard. See env.modified in the Complete API Reference

COPY
rsp = env.modified(nCard)

print(rsp)

Returns

A JSON payload containing the Notecard response.

COPY
{
  "time": 1605814493
}

set()

Perform an env.set request against a Notecard. See env.set in the Complete API Reference

COPY
rsp = env.set(nCard,
              name="monitor-pump"
              text="false")

print(rsp)

Returns

A JSON payload containing the Notecard response.

COPY
{}

file Class Reference

Public Methods

changes()

Perform individual or batch queries on Notefiles. See file.changes in the Complete API Reference.

COPY
rsp = file.changes(nCard,
                   tracker="multi-file-tracker",
                   files=["my-settings.db", "other-settings.db"])

print(rsp)

Returns

A JSON payload containing the Notecard response.

COPY
{
  "changes": 5,
  "total": 5,
  "info": {
    "my-settings.db": { "changes": 3, "total": 3 },
    "other-settings.db": { "changes": 2, "total": 2 }
  }
}

delete()

Delete individual notefiles and their contents. See file.delete in the Complete API Reference

COPY
rsp = file.delete(nCard,
                  files=["my-settings.db"])

print(rsp)

Returns

A JSON payload containing the Notecard response.

COPY
{}

pendingChanges

Retrieve information about pending Notehub changes. See file.changes.pending in the Complete API Reference.

COPY
rsp = file.pendingChanges(nCard)

print(rsp)

Returns

A JSON payload containing the Notecard response.

COPY
{
  "total": 3,
  "changes": 3,
  "pending": true,
  "info": {
    "sensors.qo": { "changes": 3, "total": 3 }
  }
}

stats()

Obtain statistics about local notefiles. See file.stats in the Complete API Reference

COPY
rsp = file.stats(nCard)

print(rsp)

Returns

A JSON payload containing the Notecard response.

COPY
{
  "total": 83,
  "changes": 78,
  "sync": true
}

hub Class Reference

Public Methods

get()

Retrieve the current Notehub configuration parameters. See hub.get in the Complete API Reference.

COPY
rsp = hub.get(nCard)

print(rsp)

Returns

A JSON payload containing the Notecard response.

COPY
{
  "device": "dev:000000000000000",
  "product": "com.your-company.your-name:your_product",
  "mode": "periodic",
  "outbound": 60,
  "inbound": 240,
  "host": "a.notefile.net",
  "sn": "your-serial-number"
}

log()

Send a log request to the Notecard. See hub.log in the Complete API Reference.

COPY
rsp = hub.log(nCard
              text="something is wrong!",
              alert=True,
              sync=True)

print(rsp)

Returns

A JSON payload containing the Notecard response.

COPY
{}

set()

Configure Notehub behavior on the Notecard. See hub.set in the Complete API Reference

COPY
rsp = hub.set(nCard,
              mode="continuous",
              outbound=30,
              inbound=120,
              duration=240,
              sync=True)

print(rsp)

Returns

A JSON payload containing the Notecard response.

COPY
{}

status()

Retrieve the status of the Notecard's connection. See hub.status in the Complete API Reference.

COPY
rsp = hub.status(nCard)

print(rsp)

Returns

A JSON payload containing the Notecard response.

COPY
{
  "status": "connected (session open) {connected}",
  "connected": true
}

sync()

Initiate a sync of the Notecard to Notehub. See hub.sync in the Complete API Reference.

COPY
rsp = hub.sync(nCard)

print(rsp)

Returns

A JSON payload containing the Notecard response.

COPY
{}

syncStatus()

Retrieve the status of a sync request. See hub.sync.status in the Complete API Reference.

COPY
rsp = hub.syncStatus(nCard, sync=True)

print(rsp)

Returns

A JSON payload containing the Notecard response.

COPY
{
  "status": "completed {sync-end}",
  "time": 1598367163,
  "sync": true,
  "completed": 1648
}

note Class Reference

Public Methods

add()

Add a Note to a Notefile. See note.add in the Complete API Reference.

COPY
rsp = note.add(nCard,
               file="sensors.qo",
               body={"temp":72.22},
               sync=True)

print(rsp)

Returns

A JSON payload containing the Notecard response.

COPY
{ "total": 12 }

changes()

Incrementally retrieve changes within a Notefile. See note.changes in the Complete API Reference.

COPY
rsp = note.changes(nCard,
                   file="my-settings.db",
                   tracker="inbound-tracker",
                   start=True)

print(rsp)

Returns

A JSON payload containing the Notecard response.

COPY
{
  "changes":4,
  "total":4
  "notes":{
    "setting-one":   {"body":{"foo": "bar"},"time":1598918235},
    "setting-two":   {"body":{"foo": "bat"},"time":1598918245},
    "setting-three": {"body":{"foo": "baz"},"time":1598918225},
    "setting-four":  {"body":{"foo": "foo"},"time":1598910532}
  }
}

delete()

Delete a DB note in a Notefile by its ID. See note.delete in the Complete API Reference.

COPY
rsp = note.delete(nCard,
                 file="my-settings.db",
                 note="measurements")

print(rsp)

Returns

A JSON payload containing the Notecard response.

COPY
{}

get()

Retrieve a note from an inbound or DB Notefile. See note.get in the Complete API Reference.

COPY
rsp = note.get(nCard,
              file="requests.qi",
              )

print(rsp)

Returns

A JSON payload containing the Notecard response.

COPY
{
  "body": {
    "api-key1": "api-val1"
  },
  "time": 1598909219
}

template()

Create a template for new Notes in a Notefile. See note.template in the Complete API Reference.

COPY
rsp = note.template(nCard,
                   file="readings.qo",
                   body={"new_vals": true,"temperature": 1.1,"humidity": 1,"pump_state": "aaaa"},
                   length=32)

print(rsp)

Returns

A JSON payload containing the Notecard response.

COPY
{
  "bytes": 40
}

update()

Update a note in a DB Notefile by ID. See note.update in the Complete API Reference.

COPY
rsp = note.update(nCard,
                  file="my-settings.db",
                  note_id="measurements",
                  body={"internal":60})

print(rsp)

Returns

A JSON payload containing the Notecard response.

COPY
{}