note-python 2.3.1
Cross-platform Python Library for the Blues Wireless Notecard
License: MIT
Requires Python: >=3.10

# note-python

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

![Build](https://github.com/blues/note-python/workflows/Python%20package/badge.svg)
[![Coverage Status](https://coveralls.io/repos/github/blues/note-python/badge.svg?branch=main)](https://coveralls.io/github/blues/note-python?branch=main)
![Python Version Support](https://img.shields.io/pypi/pyversions/note-python)
![PyPi Version](https://img.shields.io/pypi/v/note-python)
![Wheel Support](https://img.shields.io/pypi/wheel/note-python)

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