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.

See note-python in action in the accelerator projects that use Python, MicroPython, and CircuitPython.

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.

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.

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

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

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.

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

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

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

# 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:

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.

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

1. 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)

2. 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:

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) # {}

Examples

We provide a number of examples for using note-python with Python on a Raspberry Pi, CircuitPython, or MicroPython.

• Notecard Basics
  • Examples for connecting to a Notecard over I2C, using a Raspberry Pi, using CircuitPython, and more.
• Reading and Syncing Sensor Data with the Notecard
  • Use Python on a Raspberry Pi, or CircuitPython, to read from a BME680 sensor and sync those values with the cloud.
• Writing Binary Data to the Notecard
  • This example writes an array of bytes to the binary data store on a Notecard and reads them back.

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.

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.

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.

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

nCard.Command(req)

Reset

Reset the Notecard.

nCard.Reset()

OpenSerial

Notecard class for Serial communication.

__init__

Initialize the Notecard over Serial.

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

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

Serial Transaction

Perform a Notecard transaction and return the result.

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

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

Serial Command

Perform a Notecard command and exit with no response.

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

nCard.Command(req)

Serial Reset

Reset the Notecard.

nCard.Reset()

card Class Reference

Public Methods

card.attn()

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

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

print(rsp)

card.time()

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

rsp = card.time(nCard)

print(rsp)

card.status()

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

rsp = card.status(nCard)

print(rsp)

card.temp()

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

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

print(rsp)

card.version()

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

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

print(rsp)

card.voltage()

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

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

print(rsp)

card.wireless()

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

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

print(rsp)

env Class Reference

Public Methods

env.default()

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

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

print(rsp)

env.get()

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

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

print(rsp)

env.modified()

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

rsp = env.modified(nCard)

print(rsp)

env.set()

warning

The env.set API is deprecated as of v7.2.2. We recommend setting environment variables in Notehub using either the Notehub user interface or Notehub API. You may also use the env.default API to provide a default value for an environment variable, until that variable is overridden by a value from Notehub.

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

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

print(rsp)

file Class Reference

Public Methods

file.changes()

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

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

print(rsp)

file.delete()

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

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

print(rsp)

file.pendingChanges

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

rsp = file.pendingChanges(nCard)

print(rsp)

file.stats()

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

rsp = file.stats(nCard)

print(rsp)

hub Class Reference

Public Methods

hub.get()

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

rsp = hub.get(nCard)

print(rsp)

hub.log()

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

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

print(rsp)

hub.set()

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

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

print(rsp)

hub.status()

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

rsp = hub.status(nCard)

print(rsp)

hub.sync()

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

rsp = hub.sync(nCard)

print(rsp)

hub.syncStatus()

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

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

print(rsp)

note Class Reference

Public Methods

note.add()

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

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

print(rsp)

note.changes()

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

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

print(rsp)

note.delete()

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

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

print(rsp)

note.get()

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

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

print(rsp)

note.template()

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

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

print(rsp)

note.update()

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

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

print(rsp)