Metadata-Version: 2.1
Name: diesel-heater-ble
Version: 0.2.0
Summary: BLE protocol library for diesel heaters (Vevor, Hcalory, Sunster, HeaterCC)
Author: Spettacolo83
License: MIT
Project-URL: Homepage, https://github.com/Spettacolo83/diesel-heater-ble
Project-URL: Repository, https://github.com/Spettacolo83/diesel-heater-ble
Project-URL: Documentation, https://github.com/Spettacolo83/diesel-heater-ble#readme
Project-URL: Issues, https://github.com/Spettacolo83/diesel-heater-ble/issues
Project-URL: Changelog, https://github.com/Spettacolo83/diesel-heater-ble/releases
Keywords: bluetooth,ble,diesel-heater,vevor,hcalory,sunster,heatercc,home-assistant,iot
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Home Automation
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: ruff>=0.4.0; extra == "dev"

# diesel-heater-ble

Pure Python library for parsing and controlling BLE diesel heaters.

Supports Vevor, Hcalory, Sunster, and HeaterCC diesel heater protocols
over Bluetooth Low Energy (BLE). No dependency on Home Assistant.

## Supported Protocols

| Protocol | Mode | Description |
|----------|------|-------------|
| AA55 | 1 | Unencrypted, 18-20 bytes (Vevor) |
| AA55enc | 2 | Encrypted, 48 bytes XOR (Vevor) |
| AA66 | 3 | Unencrypted, 20 bytes (BYD variant) |
| AA66enc | 4 | Encrypted, 48 bytes XOR (Vevor) |
| ABBA | 5 | HeaterCC protocol, 21+ bytes, own command format |
| CBFF | 6 | Sunster v2.1, 47 bytes, optional double-XOR encryption |
| Hcalory | 7 | MVP1/MVP2 protocol, variable length with checksum |

## Installation

```bash
pip install diesel-heater-ble
```

## Usage

```python
from diesel_heater_ble import ProtocolAA55, ProtocolCBFF

# Parse a BLE notification
protocol = ProtocolAA55()
data = bytearray(...)  # raw BLE notification bytes
result = protocol.parse(data)

print(result["running_state"])   # 0=off, 1=on
print(result["cab_temperature"]) # interior temperature
print(result["supply_voltage"])  # battery voltage

# Build a command
cmd = protocol.build_command(command=3, argument=0, passkey=1234)
# Send cmd to BLE characteristic...
```

## API

### Protocol Classes

All protocol classes implement the `HeaterProtocol` interface:

- `HeaterProtocol` - Abstract base class
- `ProtocolAA55` - AA55 unencrypted
- `ProtocolAA55Encrypted` - AA55 with XOR encryption
- `ProtocolAA66` - AA66 unencrypted (BYD variant)
- `ProtocolAA66Encrypted` - AA66 with XOR encryption
- `ProtocolABBA` - ABBA/HeaterCC protocol
- `ProtocolCBFF` - CBFF/Sunster v2.1 protocol
- `ProtocolHcalory` - Hcalory MVP1/MVP2 protocol

### Methods

- `parse(data: bytearray) -> dict | None` - Parse BLE notification data
- `build_command(command: int, argument: int, passkey: int) -> bytearray` - Build command packet

### Helper Functions

- `_decrypt_data(data)` / `_encrypt_data(data)` - XOR encryption/decryption
- `_u8_to_number(value)` - Convert unsigned 8-bit value
- `_unsign_to_sign(value)` - Convert unsigned to signed value

## License

MIT
