homechevron_rightDocschevron_rightTools & SDKschevron_rightFirmware Librarieschevron_rightPython Library

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:

Bash

pip install note-python

Bash

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.

Python

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.

Bash

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.

Python

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

Python

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

Python

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.

Python

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

Python

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

Python

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

Python

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

Python

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:

Create a JSON object that includes a valid Notecard API Request.
Call one of the notecard methods and pass in the request JSON object.
If you called a method that returns a response, make sure the response contains the data you need.

Python

# 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.
Python
```
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.
Python
```
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:

Python

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

Class	Usage	Description
`notecard`	`import notecard`	Main Library class for initializing Notecard connections and performing requests.
`card`	`from notecard import card`	Fluent API Class for `card.*` requests.
`env`	`from notecard import env`	Fluent API Class for `env.*` requests.
`file`	`from notecard import file`	Fluent API Class for `file.*` requests.
`hub`	`from notecard import hub`	Fluent API Class for `hub.*` requests.
`note`	`from notecard import note`	Fluent API Class for `note.*` requests.

notecard Class Reference

Members

Member	Description
`def serialReadByte(port)`	Read a single byte from a Notecard. Internal method utilized by class methods.
`def serialReset(port)`	Send a reset command to a Notecard. Internal method utilized by class methods.
`def serialTransaction(port,req,debug)`	Perform a single write to and read from a Notecard. Internal method utilized by class methods.
`def serialCommand(port,req,debug)`	Perform a single write to and read from a Notecard. Internal method utilized by class methods.
`class` `notecard::Notecard`	Base Notecard class.
`class` `notecard::OpenI2C`	Notecard class for I2C communication.
`class` `notecard::OpenSerial`	Notecard class for Serial communication.

Notecard Class

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

Method	Description
`public def __init__(self)`	Initialize the Notecard through a reset.

OpenI2C Class

Notecard subclass for I2C communication.

Member	Description
`public i2c`	An instance of the host (PC, MCU) I2C bus controller.
`public addr`	The I2C Address to use for Notecard communications.
`public max`	Maximum length of I2C data segments.
`public def __init__(self,i2c,address,max_transfer,debug)`	Initialize the Notecard over I2C.
`public def` `Transaction(self,req)`	Perform a Notecard transaction and return the result.
`public def` `Command(self,req)`	Perform a Notecard command and exit with no response.
`public def` `Reset(self)`	Reset the Notecard.
`public def lock(self)`	Lock the I2C port so the host can interact with the Notecard. Internal method utilized by class methods.
`public def unlock(self)`	Unlock the I2C port. Internal method utilized by class methods.

`init`

Initialize the Notecard over I2C.

Python

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.

Python

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.

Python

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

nCard.Command(req)

Reset

Reset the Notecard.

Python

nCard.Reset()

OpenSerial

Notecard class for Serial communication.

Members	Descriptions
`public uart`	An instance of the host (PC, MCU) UART bus controller.
`public lock`	A filelock object for locking access to the Serial port in a PC or SBC environment.
`public def __init__(self,uart_id,debug)`	Initialize the Notecard before a reset.
`public def` `Transaction(self,req)`	Perform a Notecard transaction and return the result.
`public def` `Command(self,req)`	Perform a Notecard command and exit with no response.
`public def` `Reset(self)`	Reset the Notecard.

`init`

Initialize the Notecard over Serial.

Python

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

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

Serial Transaction

Perform a Notecard transaction and return the result.

Python

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.

Python

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

nCard.Command(req)

Serial Reset

Reset the Notecard.

Python

nCard.Reset()

card Class Reference

Public Methods

Method	Description
`public def` `card.attn(card,mode,files,seconds,payload,start)`	Configure interrupt detection between a host and Notecard.
`public def` `card.time(card)`	Retrieve the current time and date from the Notecard.
`public def` `card.status(card)`	Retrieve the status of the Notecard.
`public def` `card.temp(card,minutes)`	Retrieve the current temperature from the Notecard.
`public def` `card.version(card)`	Retrieve firmware version information from the Notecard.
`public def` `card.voltage(card,hours,offset,vmax,vmin)`	Retrieve current and historical voltage info from the Notecard.
`public def` `card.wireless(card,mode,apn)`	Retrieve wireless modem info or customize modem behavior.

card.attn()

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

Python

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.

Python

rsp = card.time(nCard)

print(rsp)

card.status()

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

Python

rsp = card.status(nCard)

print(rsp)

card.temp()

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

Python

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.

Python

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.

Python

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.

Python

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

print(rsp)

env Class Reference

Public Methods

Method	Description
`public def` `env.default(card,name,text)`	Perform an env.default request against a Notecard.
`public def` `env.get(card,name)`	Perform an env.get request against a Notecard.
`public def` `env.modified(card)`	Perform an env.modified request against a Notecard.
`public def` `env.set(card,name,text)`	Perform an env.set request against a Notecard (this API is deprecated).

env.default()

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

Python

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

Python

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

Python

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

Python

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

print(rsp)

file Class Reference

Public Methods

Method	Description
`public def` `file.changes(card,tracker,files)`	Perform individual or batch queries on Notefiles.
`public def` `file.delete(card,files)`	Delete individual notefiles and their contents.
`public def` `file.pendingChanges(card)`	Retrieve information about pending Notehub changes.
`public def` `file.stats(card)`	Obtain statistics about local notefiles.

file.changes()

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

Python

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

Python

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.

Python

rsp = file.pendingChanges(nCard)

print(rsp)

file.stats()

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

Python

rsp = file.stats(nCard)

print(rsp)

hub Class Reference

Public Methods

Method	Description
`public def` `hub.get(card)`	Retrieve the current Notehub configuration parameters.
`public def` `hub.log(card,text,alert,sync)`	Send a log request to the Notecard.
`public def` `hub.set(card,product,sn,mode,outbound,inbound, duration,sync,align,voutbound,vinbound,host)`	Configure Notehub behavior on the Notecard.
`public def` `hub.status(card)`	Retrieve the status of the Notecard's connection.
`public def` `hub.sync(card)`	Initiate a sync of the Notecard to Notehub.
`public def` `hub.syncStatus(card,sync)`	Retrieve the status of a sync request.

hub.get()

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

Python

rsp = hub.get(nCard)

print(rsp)

hub.log()

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

Python

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

Python

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.

Python

rsp = hub.status(nCard)

print(rsp)

hub.sync()

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

Python

rsp = hub.sync(nCard)

print(rsp)

hub.syncStatus()

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

Python

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

print(rsp)

note Class Reference

Public Methods

Method	Description
`public def` `note.add(card,file,body,sync)`	Add Note to a Notefile.
`public def` `note.changes(card,file,tracker,maximum,start,stop,deleted,delete)`	Incrementally retrieve changes within a Notefile.
`public def` `note.delete(card,file,note_id)`	Delete a DB note in a Notefile by its ID.
`public def` `note.get(card,file,note_id,delete,deleted)`	Retrieve a note from an inbound or DB Notefile.
`public def` `note.template(card,file,body,length)`	Create a template for new Notes in a Notefile.
`public def` `note.update(card,file,note_id,body,payload)`	Update a note in a DB Notefile by ID.

note.add()

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

Python

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.

Python

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.

Python

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.

Python

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.

Python

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.

Python

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

print(rsp)

__init__

__init__

`init`

`init`