https://github.com/blues/note-python
Python API for Notecard
https://github.com/blues/note-python
Last synced: 5 months ago
JSON representation
Python API for Notecard
- Host: GitHub
- URL: https://github.com/blues/note-python
- Owner: blues
- License: mit
- Created: 2019-02-26T20:39:39.000Z (over 7 years ago)
- Default Branch: main
- Last Pushed: 2025-12-06T04:50:35.000Z (6 months ago)
- Last Synced: 2025-12-26T17:50:42.037Z (6 months ago)
- Language: Python
- Homepage:
- Size: 753 KB
- Stars: 18
- Watchers: 10
- Forks: 6
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# note-python
Python library for communicating with the Blues Wireless Notecard over serial
or I²C.
[](https://coveralls.io/github/blues/note-python?branch=main)
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:
```bash
pip install note-python
```
or
```bash
pip3 install note-python
```
For use with MicroPython or CircuitPython, copy the contents of the `notecard`
directory into the `lib/notecard` directory of your device.
## Usage
```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 platform, so
consult the [examples](examples/) directory for platform-specific guidance.
### Serial Configuration
#### Linux and Raspberry Pi
```python
# Use PySerial on a Linux desktop or Raspberry Pi
import serial
port = serial.Serial("/dev/serial0", 9600)
card = notecard.OpenSerial(port)
```
#### macOS and Windows
```python
# 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
```python
# 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
```python
# 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](API.md) doc.
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 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](https://dev.blues.io/tools-and-sdks/python-library/).
## Examples
The [examples](examples/) directory contains examples for using this
library with:
- [Serial](examples/notecard-basics/serial_example.py)
- [I2C](examples/notecard-basics/i2c_example.py)
- [RaspberryPi](examples/notecard-basics/rpi_example.py)
- [CircuitPython](examples/notecard-basics/cpy_example.py)
- [MicroPython](examples/notecard-basics/mpy_example.py)
## 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](CONTRIBUTING.md).
## Development Setup
If you're planning to contribute to this repo, please be sure to run the tests, linting and style checks before submitting a PR.
1. Install Pipenv if you haven't already:
```bash
pip install pipenv
```
2. Clone the repository and install dependencies:
```bash
git clone https://github.com/blues/note-python.git
cd note-python
pipenv install --dev
```
3. Activate the virtual environment:
```bash
pipenv shell
```
4. Run the tests:
```bash
make test
```
5. Run linting and style checks:
```bash
make precommit
```
## 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](https://github.com/blues/note-c) for Standard C support
* [note-go](https://github.com/blues/note-go) for Go
* [note-arduino](https://github.com/blues/note-arduino) for Arduino
## To learn more about Blues Wireless, the Notecard and Notehub, see:
* [blues.com](https://blues.com)
* [notehub.io][Notehub]
* [wireless.dev](https://wireless.dev)
## License
Copyright (c) 2019 Blues Inc. Released under the MIT license. See
[LICENSE](LICENSE) for details.
[code of conduct]: https://blues.github.io/opensource/code-of-conduct
[Notehub]: https://notehub.io