Rate this page Â
- ★★
- ★★
- ★★
- ★★
- ★★
Can we improve this page? Send us feedbackRate this page
- ★★
- ★★
- ★★
- ★★
- ★★
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.
This library is supported in Python 3.5 and above. The library may work, but is not supported, in Python 2.x environments.
With pip
via PyPi:
pip install note-python
or
pip3 install note-python
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.
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.
To communicate with the Notecard from a PC or Single-Board Computer, you'll
need to first install
python-periphery
.
pip install python-periphery
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)
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)
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
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)
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)
Both Serial and I2C are accessible in MicroPython using the built-in
machine
library.
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)
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)
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)
Whether using Serial or I2C, sending Notecard requests and reading responses follows the same pattern:
notecard
methods and pass in the request JSON object.# 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}
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.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.cmd = {"cmd": "hub.sync"} nCard.Command(req)
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.
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) # {}
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. |
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. |
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. |
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.
from periphery import I2C port = I2C("/dev/i2c-1") nCard = notecard.OpenI2C(port, 0, 0, debug=True)
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}
Perform a Notecard command and exit with no response.
req = {"cmd": "note.add"} req["body"] = {"temp": 18.6} nCard.Command(req)
Reset the Notecard.
nCard.Reset()
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 Command (self,req) | Perform a Notecard command and exit with no response. |
public def Transaction (self,req) | Perform a Notecard transaction and return the result. |
public def Reset (self) | Reset the Notecard. |
__init__
Initialize the Notecard over Serial.
import serial port = serial.Serial("/dev/serial0", 9600) nCard = notecard.OpenSerial(port, debug=True)
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}
Perform a Notecard command and exit with no response.
req = {"cmd": "note.add"} req["body"] = {"temp": 18.6} nCard.Command(req)
Reset the Notecard.
nCard.Reset()
Method | Description |
---|---|
public def attn (card,mode,files,seconds,payload,start) | Configure interrupt detection between a host and Notecard. |
public def time (card) | Retrieve the current time and date from the Notecard. |
public def status (card) | Retrieve the status of the Notecard. |
public def temp (card,minutes) | Retrieve the current temperature from the Notecard. |
public def version (card) | Retrieve firmware version information from the Notecard. |
public def voltage (card,hours,offset,vmax,vmin) | Retrieve current and historical voltage info from the Notecard. |
public def wireless (card,mode,apn) | Retrieve wireless modem info or customize modem behavior. |
Configure interrupt detection between a host and Notecard. See
card.attn
in the Complete API Reference.
card
notecard
class instance
The current Notecard object.
mode
string
The attn
mode
to set.
files
array (optional)
A collection of notefiles to watch.
seconds
int (optional)
A timeout to use when arming attn mode.
payload
string (optional)
When using sleep mode, a payload of data from the host that the Notecard should hold in memory until retrieved by the host.
start
boolean (optional)
When using sleep mode and the host has reawakened, request the Notecard to return the stored payload.
rsp = card.attn(nCard, mode="arm, files", files=["data.qi"]) print(rsp)
A JSON payload containing the Notecard response.
{ "files": ["data.qi", "modified"], "set": true }
Retrieve the current time and date from the Notecard. See
card.time
in the Complete API Reference.
card
notecard
class instance
The current Notecard object.
rsp = card.time(nCard) print(rsp)
A JSON payload containing the Notecard response.
{ "time": 1599769214, "area": "Beverly, MA", "zone": "CDT,America/New York", "minutes": -300, "lat": 42.5776, "lon": -70.87134, "country": "US" }
Retrieve the status of the Notecard. See
card.status
in the Complete API Reference.
card
notecard
class instance
The current Notecard object.
rsp = card.status(nCard) print(rsp)
A JSON payload containing the Notecard response.
{ "status": "{normal}", "usb": true, "storage": 8, "time": 1599684765, "connected": "true" }
Retrieve the current temperature from the Notecard. See
card.temp
in the Complete API Reference.
card
notecard
class instance
The current Notecard object.
minutes
_integer (optional)
If specified, creates a templated _temp.qo file that gathers Notecard temperature value at the specified interval.
rsp = card.temp(nCard, minutes=10) print(rsp)
A JSON payload containing the Notecard response.
{ "value": 27.625, "calibration": -3.0 }
Retrieve firmware version information from the Notecard. See
card.version
in the Complete API Reference.
card
notecard
class instance
The current Notecard object.
rsp = card.version(nCard, minutes=10) print(rsp)
A JSON payload containing the Notecard response.
{ "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" }
Retrieve current and historical voltage info from the Notecard. See
card.voltage
in the Complete API Reference.
card
notecard
class instance
The current Notecard object.
hours
int (optional)
Number of hours to analyze.
offset
int (optional)
Number of hours to offset.
vmax
int (optional)
Maximum voltage level to report.
vmin
int (optional)
Minimum voltage level to report.
rsp = card.voltage(nCard, hours=120, offset=24, vmax=4.3, vmin=2.7) print(rsp)
A JSON payload containing the Notecard response.
{ "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 }
Retrieve wireless modem info or customize modem behavior. See
card.wireless
in the Complete API Reference.
card
notecard
class instance
The current Notecard object.
mode
string
The wireless module mode to set.
apn
string (optional)
Access Point Name (APN) when using an external SIM.
rsp = card.wireless(nCard, mode="nb") print(rsp)
A JSON payload containing the Notecard response.
{ "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 } }
Method | Description |
---|---|
public def default (card,name,text) | Perform an env.default request against a Notecard. |
public def get (card,name) | Perform an env.get request against a Notecard. |
public def modified (card) | Perform an env.modified request against a Notecard. |
public def set (card,name,text) | Perform an env.set request against a Notecard. |
Perform an env.default
request against a Notecard. See
env.default
in the Complete API Reference
card
notecard
class instance
The current Notecard object.
name
string
The name of an environment var to set a default for.
text
string (optional)
The default value. Omit to delete the default.
rsp = env.default(nCard, name="monitor-pump", text="true") print(rsp)
A JSON payload containing the Notecard response.
{}
Perform an env.get
request against a Notecard. See
env.get
in the Complete API Reference
card
notecard
class instance
The current Notecard object.
name
string
The name of an environment to get.
rsp = env.get(nCard, name="monitor-pump") print(rsp)
A JSON payload containing the Notecard response.
{ "text": "true" }
Perform an env.modified
request against a Notecard. See
env.modified
in the Complete API Reference
card
notecard
class instance
The current Notecard object.
rsp = env.modified(nCard) print(rsp)
A JSON payload containing the Notecard response.
{ "time": 1605814493 }
Perform an env.set
request against a Notecard. See
env.set
in the Complete API Reference
card
notecard
class instance
The current Notecard object.
name
string
The name of an environment var to set.
text
string (optional)
The value. Omit to delete.
rsp = env.set(nCard, name="monitor-pump" text="false") print(rsp)
A JSON payload containing the Notecard response.
{}
Method | Description |
---|---|
public def changes (card,tracker,files) | Perform individual or batch queries on Notefiles. |
public def delete (card,files) | Delete individual notefiles and their contents. |
public def pendingChanges (card) | Retrieve information about pending Notehub changes. |
public def stats (card) | Obtain statistics about local notefiles. |
Perform individual or batch queries on Notefiles. See
file.changes
in the Complete API Reference.
card
notecard
class instance
The current Notecard object.
tracker
string
A developer-defined tracker ID.
files
array (optional)
A list of Notefiles to retrieve changes for.
rsp = file.changes(nCard, tracker="multi-file-tracker", files=["my-settings.db", "other-settings.db"]) print(rsp)
A JSON payload containing the Notecard response.
{ "changes": 5, "total": 5, "info": { "my-settings.db": { "changes": 3, "total": 3 }, "other-settings.db": { "changes": 2, "total": 2 } } }
Delete individual notefiles and their contents. See
file.delete
in the Complete API Reference
card
notecard
class instance
The current Notecard object.
files
array (optional)
A list of Notefiles to delete.
rsp = file.delete(nCard, files=["my-settings.db"]) print(rsp)
A JSON payload containing the Notecard response.
{}
Retrieve information about pending Notehub changes. See
file.changes.pending
in the Complete API Reference.
card
notecard
class instance
The current Notecard object.
rsp = file.pendingChanges(nCard) print(rsp)
A JSON payload containing the Notecard response.
{ "total": 3, "changes": 3, "pending": true, "info": { "sensors.qo": { "changes": 3, "total": 3 } } }
Obtain statistics about local notefiles. See
file.stats
in the Complete API Reference
card
notecard
class instance
The current Notecard object.
rsp = file.stats(nCard) print(rsp)
A JSON payload containing the Notecard response.
{ "total": 83, "changes": 78, "sync": true }
Method | Description |
---|---|
public def get (card) | Retrieve the current Notehub configuration parameters. |
public def log (card,text,alert,sync) | Send a log request to the Notecard. |
public def set (card,product,sn,mode,outbound,inbound, duration,sync,align,voutbound,vinbound,host) | Configure Notehub behavior on the Notecard. |
public def status (card) | Retrieve the status of the Notecard's connection. |
public def sync (card) | Initiate a sync of the Notecard to Notehub. |
public def syncStatus (card,sync) | Retrieve the status of a sync request. |
Retrieve the current Notehub configuration parameters. See
hub.get
in the Complete API Reference.
card
notecard
class instance
The current Notecard object.
rsp = hub.get(nCard) print(rsp)
A JSON payload containing the Notecard response.
{ "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" }
Send a log request to the Notecard. See
hub.log
in the Complete API Reference.
card
notecard
class instance
The current Notecard object.
text
The text of the log message.
alert
boolean
True if the message is urgent.
sync
boolean
Whether to sync right away.
rsp = hub.log(nCard text="something is wrong!", alert=True, sync=True) print(rsp)
A JSON payload containing the Notecard response.
{}
Configure Notehub behavior on the Notecard. See
hub.set
in the Complete API Reference
card
notecard
class instance
The current Notecard object.
product
string (optional)
The ProductUID of the project.
sn
string (optional)
The Serial Number of the device.
mode
string (optional)
The sync mode to use.
outbound
int (optional)
Max time to wait to sync outgoing data.
inbound
int (optional)
Max time to wait to sync incoming data.
duration
int (optional)
If in continuous mode, the amount of time, in minutes, of each session.
sync
boolean (optional)
If in continuous mode, whether to automatically sync each time a change is detected on the device or Notehub.
align
boolean (optional)
To align syncs to a regular time-interval, as opposed to using max time values.
voutbound
string (optional)
Overrides "outbound" with a voltage-variable value.
vinbound
string (optional)
Overrides "inbound" with a voltage-variable value.
host
string (optional)
URL of an alternative or private Notehub instance.
rsp = hub.set(nCard, mode="continuous", outbound=30, inbound=120, duration=240, sync=True) print(rsp)
A JSON payload containing the Notecard response.
{}
Retrieve the status of the Notecard's connection. See
hub.status
in the Complete API Reference.
card
notecard
class instance
The current Notecard object.
rsp = hub.status(nCard) print(rsp)
A JSON payload containing the Notecard response.
{ "status": "connected (session open) {connected}", "connected": true }
Initiate a sync of the Notecard to Notehub. See
hub.sync
in the Complete API Reference.
card
notecard
class instance
The current Notecard object.
rsp = hub.sync(nCard) print(rsp)
A JSON payload containing the Notecard response.
{}
Retrieve the status of a sync request. See
hub.sync.status
in the Complete API Reference.
card
notecard
class instance
The current Notecard object.
sync
boolean (optional)
True if sync should be auto-initiated pending outbound data.
rsp = hub.syncStatus(nCard, sync=True) print(rsp)
A JSON payload containing the Notecard response.
{ "status": "completed {sync-end}", "time": 1598367163, "sync": true, "completed": 1648 }
Method | Description |
---|---|
public def add (card,file,body,sync) | Add Note to a Notefile. |
public def changes (card,file,tracker,maximum,start,stop,deleted,delete) | Incrementally retrieve changes within a Notefile. |
public def delete (card,file,note_id) | Delete a DB note in a Notefile by its ID. |
public def get (card,file,note_id,delete,deleted) | Retrieve a note from an inbound or DB Notefile. |
public def template (card,file,body,length) | Create a template for new Notes in a Notefile. |
public def update (card,file,note_id,body,payload) | Update a note in a DB Notefile by ID. |
Add a Note to a Notefile. See
note.add
in the Complete API Reference.
card
notecard
class instance
The current Notecard object.
file
string (optional)
Name of a Notefile in which to place the Note.
note
string (optional)
If the Notefile has a .db
or .dbx
extension, specifies a unique Note ID.
body
JSON Object (optional)
A JSON object to be enqueued.
payload
base64 string (optional)
A base64-encoded binary payload
sync
boolean (optional)
True
to sync immediately.
rsp = note.add(nCard, file="sensors.qo", body={"temp":72.22}, sync=True) print(rsp)
A JSON payload containing the Notecard response.
{ "total": 12 }
Incrementally retrieve changes within a Notefile. See
note.changes
in the Complete API Reference.
card
notecard
class instance
The current Notecard object.
file
string (optional)
The notefile to inspect for changes.
tracker
string (optional)
A developer-defined tracker ID.
maximum
integer (optional)
Maximum number of notes to return.
start
boolean (optional)
True
to reset the tracker to the beginning before a get.
stop
boolean (optional)
True
to delete the tracker after get.
deleted
boolean (optional)
True
if deleted Notes should be returned.
delete
boolean (optional)
True
if Notes in the response should be auto-deleted.
rsp = note.changes(nCard, file="my-settings.db", tracker="inbound-tracker", start=True) print(rsp)
A JSON payload containing the Notecard response.
{ "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 a DB note in a Notefile by its ID. See
note.delete
in the Complete API Reference.
card
notecard
class instance
The current Notecard object.
file
string
The file name of the DB notefile.
note_id
string
The id of the note to delete.
rsp = note.delete(nCard, file="my-settings.db", note="measurements") print(rsp)
A JSON payload containing the Notecard response.
{}
Retrieve a note from an inbound or DB Notefile. See
note.get
in the Complete API Reference.
card
notecard
class instance
The current Notecard object.
file
string
The inbound or DB notefile to retrieve a Notefile from.
note_id
string
(DB files only) The ID of the note to retrieve.
delete
boolean (optional)
True
to delete the note after retrieval.
deleted
boolean (optional)
True
to allow retrieval of a deleted note.
rsp = note.get(nCard, file="requests.qi", ) print(rsp)
A JSON payload containing the Notecard response.
{ "body": { "api-key1": "api-val1" }, "time": 1598909219 }
Create a template for new Notes in a Notefile. See
note.template
in the Complete API Reference.
card
notecard
class instance
The current Notecard object.
file
string
The file name of the Notefile on which to set a template.
body
_JSON object (optional)
A sample JSON body that specifies field names and values as "hints" for the data type.
length
integer (optional)
If provided, the maximum length of a payload that can be sent in Notes for the template Notefile.
rsp = note.template(nCard, file="readings.qo", body={"new_vals": true,"temperature": 1.1,"humidity": 1,"pump_state": "aaaa"}, length=32) print(rsp)
A JSON payload containing the Notecard response.
{ "bytes": 40 }
Update a note in a DB Notefile by ID. See
note.update
in the Complete API Reference.
card
notecard
class instance
The current Notecard object.
file
string
The file name of the DB notefile.
note_id
string (optional)
The id of the note to update.
body
JSON object (optional)
The JSON object to add to the note.
payload
base64 string (optional)
The base64-encoded JSON payload to add to the note.
rsp = note.update(nCard, file="my-settings.db", note_id="measurements", body={"internal":60}) print(rsp)
A JSON payload containing the Notecard response.
{}