Metadata-Version: 2.4
Name: presage-binary-decoder
Version: 0.1.0
Summary: Decode Presage sensor MQTT binary payloads into Python data.
Author: Presage Insights
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: twine>=5; extra == "dev"
Provides-Extra: mqtt
Requires-Dist: paho-mqtt<3,>=2; extra == "mqtt"
Requires-Dist: python-dotenv<2,>=1; extra == "mqtt"

# Presage Binary Decoder

This dependency-free package converts raw Presage MQTT sensor payload bytes into
the same dictionary produced by the existing MQTT listener. It does not connect
to an MQTT broker.

## Install locally

```bash
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev]"
```

After publishing, customers install it with:

```bash
python -m pip install presage-binary-decoder
```

Python 3.9 or newer is supported.

## Decode a payload

```python
from presage_binary_decoder import decode

result = decode(message.payload, sensor_type="VIB")
```

Example result:

```python
{
    "raw_data": [0.125, -0.25],
    "mac_id": "VIB_AA:BB:CC:DD:EE:FF",
    "timestamp": 1700000000.25,
    "no_of_samples": 2,
    "fs": 2560,
    "axis": "x",
    "temp": 31.5,
}
```

`sensor_type` remains required because it is supplied separately in the current
listener and is not encoded in the payload.

## Handle errors

```python
from presage_binary_decoder import PayloadDecodeError, decode

try:
    result = decode(payload, "VIB")
except PayloadDecodeError as error:
    print(error)
```

## Test and build

```bash
PYTHONPATH=src python -m unittest discover -s tests -v
python -m pytest
python -m build
python -m twine check dist/*
```

The firmware has no protocol-version field, so this layout is called V1
internally. Future `v2.py` and `v3.py` parsers can be added without exposing
internal parsing functions. A firmware version byte would later allow automatic
parser selection.

## TestPyPI and PyPI

Build a new version and upload to TestPyPI first:

```bash
python -m twine upload --repository testpypi dist/*
python -m pip install --index-url https://test.pypi.org/simple/ presage-binary-decoder
```

After verification, upload the same files to production PyPI:

```bash
python -m twine upload dist/*
```

Nothing is uploaded automatically. Before each new release, update the version
in `pyproject.toml` and `src/presage_binary_decoder/_version.py`. Use patch
versions for fixes, minor versions for compatible features, and major versions
for breaking changes. Change the future PyPI package name in `pyproject.toml`.
