note-python

Python library for communicating with the Blues Wireless Notecard over serial or I²C.

This library allows you to control a Notecard by coding in Python and works in a desktop setting, on Single-Board Computers like the Raspberry Pi, and on Microcontrollers with MicroPython or CircuitPython support.

Installation

With pip via PyPi:

pip install note-python

or

pip3 install note-python

For use with MicroPython or CircuitPython, copy the contents of the notecard directory into the lib directory of your device.

Usage

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 platform, so consult the examples directory for platform-specific guidance.

Serial Configuration

Linux and Raspberry Pi

# Use PySerial on a Linux desktop or Raspberry Pi
import serial
port = serial.Serial("/dev/serial0", 9600)

card = notecard.OpenSerial(port)

macOS and Windows

# Use PySerial on a desktop
import serial
#macOS
port = serial.Serial(port="/dev/tty.usbmodemNOTE1",
                     baudrate=9600)
# Windows
# port = serial.Serial(port="COM4",
#                     baudrate=9600)

card = notecard.OpenSerial(port)

I2C Configuration

# Use python-periphery on a Linux desktop or Raspberry Pi
from periphery import I2C
port = I2C("/dev/i2c-1")

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

Sending Notecard Requests

Whether using Serial or I2C, sending Notecard requests and reading responses follows the same pattern:

1. Create a JSON object that adheres to the Notecard API.
2. Call Transaction on a Notecard object and pass in the request JSON object.
3. 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 = card.Transaction(req)
print(rsp) # {"total":1}

Using the Library Fluent API

The notecard class allows complete access to the Notecard API via manual JSON object construction and the Transaction method. 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 that not all aspects of the Notecard API are available using these helpers. For a complete list of supported helpers, visit the API doc.

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 card, hub, note

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

productUID = "com.blues.brandon.tester"
rsp = hub.set(nCard, productUID, mode="continuous", sync=True)

print(rsp) # {}

Documentation

The documentation for this library can be found here.

Examples

The examples directory contains examples for using this library with:

• Serial
• I2C
• RaspberryPi
• CircuitPython
• MicroPython

Contributing

We love issues, fixes, and pull requests from everyone. By participating in this project, you agree to abide by the Blues Inc code of conduct.

For details on contributions we accept and the process for contributing, see our contribution guide.

Running the Tests

If you're planning to contribute to this repo, please be sure to run the tests before submitting a PR. First run:

pip install -r requirements.txt

Then, run the linter and tests using the included Makefile.

make

Alternatively, you can inspect the contents of the Makefile and run flake8 and pytest directly. Be aware, however, that the commands in the Makefile run against every pull request, so your best bet is to ensure these tests are successful before submitting your PR.

Installing the pre-commit Hook

Please run

pre-commit install

Before committing to this repo. It will catch a lot of common errors that you can fix locally.

You may also run the pre-commit checks before committing with

pre-commit run

Note that pre-commit run only considers staged changes, so be sure all changes are staged before running this.

More Information

For additional Notecard SDKs and Libraries, see:

• note-c for Standard C support
• note-go for Go
• note-arduino for Arduino

To learn more about Blues Wireless, the Notecard and Notehub, see:

• blues.com
• notehub.io
• wireless.dev

License

Copyright (c) 2019 Blues Inc. Released under the MIT license. See LICENSE for details.