aosmith-ble
Local Bluetooth LE control of A.O. Smith iCOMM heat pump water heaters -- no cloud account, no vendor credentials, no internet connection involved. This project is independent and unaffiliated with A.O. Smith.
Documentation: see the docs/ folder or the project site.
Looking for the cloud API instead? See py-aosmith.
What this is
An async client that connects directly to a water heater's BLE interface, matches it against a bundled device profile, and reads or writes only what that profile has verified. An unrecognized device is refused outright. To help add support for a new device, call AOSmithBLEClient.async_diagnose(). It connects, probes and disconnects on its own (so it works even where connect() refuses) and returns a DiagnosticReport: to_markdown() gives a human-readable report and to_fixture_entries() gives redacted, fixture-shaped captures for a profile-contribution PR.
Install
pip install git+https://github.com/stumpylog/aosmith-ble
Quickstart
import asyncio
from aosmith_ble import AOSmithBLEClient, FieldName, Mode, async_discover, pairing_code_from_name
async def main():
devices = await async_discover()
device = devices[0]
code = pairing_code_from_name(device.name)
async with AOSmithBLEClient(device, pairing_code=code) as client:
features = await client.async_get_state()
setpoint = features[FieldName.SETPOINT].value
mode = features[FieldName.MODE].value
fault = features[FieldName.FAULT].value
print(f"{setpoint}F, mode={Mode(mode.mode).name}, fault={fault.name}")
await client.async_set_setpoint(124.0)
asyncio.run(main())
Pairing
Press the Bluetooth button on the control panel once before first use. The device hands out the "assetID" it authenticates sessions against only while its pairing slot is populated. Cache AOSmithBLEClient.asset_id (for example with the device address) and pass it back as asset_id= so the button press is a one-time step.
Embedding in a long-running application
A host that owns Bluetooth scanning and wants the client to survive reconnects can pass three optional, keyword-only hooks:
client = AOSmithBLEClient(
device,
pairing_code=code,
asset_id=cached_asset_id,
device_resolver=lambda: my_scanner.latest_device(address),
client_class=MyBleakClientSubclass,
on_disconnect=lambda: schedule_reconnect(),
)
device_resolverreturns the freshestBLEDevicefor the heater, orNoneif there is nothing newer. It is called on everyconnect()and on every connection retry, so a handle that changes between connects (a different adapter or relay) is picked up. Passing aBLEDeviceasdeviceand no resolver keeps the current behavior. Passing an address string makes the library run its own scan, so a host that owns scanning should pass aBLEDeviceor a resolver instead.client_classis the bleak client class used to connect,BleakClientby default. Pass a subclass, such asbleak_retry_connector.BleakClientWithServiceCache, to change how the link behaves.on_disconnectis called with no arguments when the link is lost unexpectedly. It is not called fordisconnect(),async_release()or a failedconnect(). It runs on the event loop, must not block, and an exception it raises is logged and ignored. A drop whileconnect()is still setting up the session calls it as well, andconnect()then raises its own error.
Safety model
Every write goes through one profile-gated path: setpoint and mode are checked against the profile's verified limits (never above 140F, 130F by default), a fault-active device is read-only, and every write is read back and compared before the call succeeds. The public API cannot write an arbitrary block or parameter.
What this doesn't do (yet)
No current-tank-temperature reading (the manufacturer's app never reads it either). No Home Assistant integration; that is a separate, HACS-distributed package. No support for devices other than the bundled profile: connect() refuses an unmatched device. Diagnostics are an explicit, separate call, never part of the automatic connection flow.
License
MIT. See LICENSE.
Metadata
Release files for aosmith-ble 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| aosmith_ble-0.1.0.tar.gz | 138.5 kB | With provenance | Details for aosmith_ble-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| aosmith_ble-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for aosmith_ble-0.1.0-py3-none-any.whl |
Total release size: 172.6 kB
Release files / aosmith_ble-0.1.0.tar.gz
| Download URL | aosmith_ble-0.1.0.tar.gz |
|---|---|
| Size | 138.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
da3650a9168de0861b6ee78b72b0d6a067f582cd51d9bfcab24c93568c0034b7
|
|
BLAKE2b-256 checksum How to use checksums |
bf20e5218ac900600f50bd66ade41a2498962d4612af2ace5de188a3449030b1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 9, 2026.
Transparency logRelease files / aosmith_ble-0.1.0-py3-none-any.whl
| Download URL | aosmith_ble-0.1.0-py3-none-any.whl |
|---|---|
| Size | 34.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
89f550622c7622fec47eb6f548a5688e90f63df79a45a6703b2d4c93550349fd
|
|
BLAKE2b-256 checksum How to use checksums |
87ae64577616225bde5bd60d8fd69f5ca4fe42089f9214a689db2b45409423bb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 9, 2026.
Transparency logSecurity for aosmith-ble 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for aosmith_ble-0.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 9, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.