easee-ble 0.1.0__tar.gz

easee_ble-0.1.0/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+Notable changes per release. Versions follow [SemVer](https://semver.org).
+
+## Unreleased

easee_ble-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 parrel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

easee_ble-0.1.0/MANIFEST.in

@@ -0,0 +1,5 @@
+# The sdist ships the tests, so include the data they need - without this,
+# `pytest` against an unpacked sdist fails on a missing vector file.
+recursive-include tests *.json
+
+include CHANGELOG.md

easee_ble-0.1.0/PKG-INFO

@@ -0,0 +1,226 @@
+Metadata-Version: 2.4
+Name: easee-ble
+Version: 0.1.0
+Summary: Local Bluetooth control for Easee EV chargers
+Author: parrel
+License-Expression: MIT
+Project-URL: Repository, https://github.com/parrel/easee-ble
+Project-URL: Bug Tracker, https://github.com/parrel/easee-ble/issues
+Keywords: easee,ev,charger,bluetooth,ble,home-assistant
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Framework :: AsyncIO
+Classifier: Topic :: Home Automation
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pycryptodome>=3.20
+Requires-Dist: ecdsa>=0.19
+Requires-Dist: bleak>=0.22
+Requires-Dist: bleak-retry-connector>=3.5.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: pytest-cov>=5; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: mypy>=1.11; extra == "dev"
+Dynamic: license-file
+
+# easee-ble
+
+Local **Bluetooth** control for [Easee](https://easee.com) EV chargers. Talk to the charger directly with the PIN printed on the unit.
+
+```bash
+pip install easee-ble
+```
+
+Requires Python 3.11+. For Home Assistant, use
+[ha-easee-ble](https://github.com/parrel/ha-easee-ble), which is built on this.
+
+## Quick start
+
+```python
+import asyncio
+from bleak import BleakScanner
+from easee_ble import EaseeCharger, PhaseMode
+
+async def main():
+    device = await BleakScanner.find_device_by_address("AA:BB:CC:DD:EE:FF")
+    charger = EaseeCharger(device, pin="1234", serial="EMX00000")
+
+    await charger.connect()                # handshake; the link is held open
+    print(await charger.poll())            # {'chargerOpMode': 3, 'totalPower': 2.69, ...}
+
+    await charger.perform(lambda s: s.set_charger_enabled(True))
+    await charger.perform(lambda s: s.set_phase_mode(PhaseMode.AUTO))
+
+    await charger.disconnect()
+
+asyncio.run(main())
+```
+
+You need two things from the charger: the **PIN** printed on the unit, and its
+**serial** (`EMXXXXXX`, also on the unit and in the Easee app).
+
+### Finding your charger
+
+Scan by service UUID if you do not know the address:
+
+```python
+from easee_ble import SERVICE_UUID
+
+device = await BleakScanner.find_device_by_filter(
+    lambda d, adv: SERVICE_UUID in adv.service_uuids
+)
+```
+
+Chargers usually advertise only **intermittently**. To get one to show up,
+either set Bluetooth to always-on in the Easee app, or open a window with a long
+press of the charger's touch button.
+
+## Reading
+
+`poll()` merges State and Config into one dict of named fields:
+
+```python
+data = await charger.poll()
+data["chargerOpMode"]        # 3
+data["totalPower"]           # 2.69
+data["maxChargerCurrent"]    # 16
+charger.unknown              # fields we have no name for yet, by number
+```
+
+Two fields belong together. `chargerOpMode` describes the **car and cable** - it
+still reads `AWAITING_START` for a charger that has been switched off.
+`reasonForNoCurrent` says **why** no current flows, and reads 53
+(*charger disabled*) in exactly that case. Show both:
+
+```python
+from easee_ble import charger_op_mode, reason_for_no_current
+
+charger_op_mode(data["chargerOpMode"])                # ChargerOpMode.CHARGING
+reason_for_no_current(data.get("reasonForNoCurrent")) # 'Charger disabled'
+```
+
+Both return `None` on a value this library has not seen, where `ChargerOpMode()`
+and `NetworkStatus()` raise. The descriptions are display text; key on
+`reason_for_no_current_slug()` if you need something stable.
+
+Fields at their default value are **absent** from the wire, not zero. `poll()`
+already fills a curated set back in as `0`, so treat a missing field as unknown
+rather than surprising.
+
+## Commands
+
+Every command goes through `perform()`, which builds the request and checks the
+answer:
+
+```python
+await charger.perform(lambda s: s.set_charger_enabled(True))
+await charger.perform(lambda s: s.set_max_charger_current(16))
+await charger.perform(lambda s: s.set_dynamic_charger_current(10))
+await charger.perform(lambda s: s.set_circuit_max_current(20))          # or (p1, p2, p3)
+await charger.perform(lambda s: s.set_offline_max_circuit_current(10))
+await charger.perform(lambda s: s.set_phase_mode(PhaseMode.LOCKED_3_PHASE))
+await charger.perform(lambda s: s.set_led_brightness(75))               # 0-100
+await charger.perform(lambda s: s.set_cable_locked(True))
+await charger.perform(lambda s: s.set_access_control(True))
+```
+
+`PhaseMode` is `LOCKED_1_PHASE`, `AUTO` or `LOCKED_3_PHASE`.
+
+### RFID / account keys
+
+```python
+from easee_ble import command_payload
+
+reply = await charger.perform(lambda s: s.list_user_tokens())
+keys = command_payload(reply)
+await charger.perform(lambda s: s.get_user_token(slot, name))
+await charger.perform(lambda s: s.set_user_token(slot, name, token))
+```
+
+### Other reads
+
+Besides `poll()`, individual frames are available through `perform()`:
+
+```python
+await charger.perform(lambda s: s.poll_state())
+await charger.perform(lambda s: s.poll_config())
+await charger.perform(lambda s: s.poll_structure())
+await charger.perform(lambda s: s.poll_debug())
+```
+
+A reply only arrives on a subscribed channel, and the last two are not
+subscribed to by default. Ask for them at connect - `EaseeCharger(...,
+channels=DEFAULT_CHANNELS | {Channel.DEBUG})` - or the call raises. `poll()`
+takes the same argument to read them alongside Config and State.
+
+## Errors
+
+```python
+from easee_ble import EaseeCommandRefused, EaseeConnectionError, JPakeError
+
+try:
+    await charger.connect()
+    await charger.perform(lambda s: s.set_max_charger_current(32))
+except JPakeError:            # almost always the wrong PIN
+    ...
+except EaseeCommandRefused:   # the charger answered, and said no
+    ...
+except EaseeConnectionError:  # connecting or talking to it failed
+    ...
+```
+
+A reply is **not** an acknowledgement - the charger answers a command it refuses
+just as promptly as one it accepts. `perform()` checks for you and raises
+`EaseeCommandRefused`; anything else, `command_accepted()` and
+`command_refusal()` check by hand.
+
+## Connection notes
+
+- The connection is **long-lived**: connect once and keep polling. Connecting is
+  the expensive, failure-prone part.
+- **Not safe for concurrent use.** One request may be in flight at a time -
+  serialise with a lock if several tasks share a charger.
+- Pass `on_disconnect=` to be told the moment the link drops rather than at your
+  next poll; check `charger.connected` before using it.
+- The charger has a single connection slot. Always `disconnect()` when done.
+
+```python
+charger = EaseeCharger(device, pin="1234", serial="EMX00000",
+                       on_disconnect=lambda c: print("link lost"))
+```
+
+## Without bleak
+
+`Session` is sans-io: it builds requests and parses replies and does no I/O, so
+you can drive it over any transport.
+
+```python
+from easee_ble import Session
+
+s = Session(pin="1234", serial="EMX00000")
+req = s.start_handshake()          # write req.data to req.channel, feed the reply back
+req = s.read_round_one(reply)
+s.read_round_two(reply)            # s.established is now True
+frame = s.parse(req.channel, reply)
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+Tests run against captured bytes from a real charger, so they need no hardware.
+
+## Notes
+
+**Unofficial.** Reverse-engineered. Not affiliated with or endorsed by Easee. No warranty, changing charger settings is at your own risk. Barely tested.
+

easee_ble-0.1.0/README.md

@@ -0,0 +1,194 @@
+# easee-ble
+
+Local **Bluetooth** control for [Easee](https://easee.com) EV chargers. Talk to the charger directly with the PIN printed on the unit.
+
+```bash
+pip install easee-ble
+```
+
+Requires Python 3.11+. For Home Assistant, use
+[ha-easee-ble](https://github.com/parrel/ha-easee-ble), which is built on this.
+
+## Quick start
+
+```python
+import asyncio
+from bleak import BleakScanner
+from easee_ble import EaseeCharger, PhaseMode
+
+async def main():
+    device = await BleakScanner.find_device_by_address("AA:BB:CC:DD:EE:FF")
+    charger = EaseeCharger(device, pin="1234", serial="EMX00000")
+
+    await charger.connect()                # handshake; the link is held open
+    print(await charger.poll())            # {'chargerOpMode': 3, 'totalPower': 2.69, ...}
+
+    await charger.perform(lambda s: s.set_charger_enabled(True))
+    await charger.perform(lambda s: s.set_phase_mode(PhaseMode.AUTO))
+
+    await charger.disconnect()
+
+asyncio.run(main())
+```
+
+You need two things from the charger: the **PIN** printed on the unit, and its
+**serial** (`EMXXXXXX`, also on the unit and in the Easee app).
+
+### Finding your charger
+
+Scan by service UUID if you do not know the address:
+
+```python
+from easee_ble import SERVICE_UUID
+
+device = await BleakScanner.find_device_by_filter(
+    lambda d, adv: SERVICE_UUID in adv.service_uuids
+)
+```
+
+Chargers usually advertise only **intermittently**. To get one to show up,
+either set Bluetooth to always-on in the Easee app, or open a window with a long
+press of the charger's touch button.
+
+## Reading
+
+`poll()` merges State and Config into one dict of named fields:
+
+```python
+data = await charger.poll()
+data["chargerOpMode"]        # 3
+data["totalPower"]           # 2.69
+data["maxChargerCurrent"]    # 16
+charger.unknown              # fields we have no name for yet, by number
+```
+
+Two fields belong together. `chargerOpMode` describes the **car and cable** - it
+still reads `AWAITING_START` for a charger that has been switched off.
+`reasonForNoCurrent` says **why** no current flows, and reads 53
+(*charger disabled*) in exactly that case. Show both:
+
+```python
+from easee_ble import charger_op_mode, reason_for_no_current
+
+charger_op_mode(data["chargerOpMode"])                # ChargerOpMode.CHARGING
+reason_for_no_current(data.get("reasonForNoCurrent")) # 'Charger disabled'
+```
+
+Both return `None` on a value this library has not seen, where `ChargerOpMode()`
+and `NetworkStatus()` raise. The descriptions are display text; key on
+`reason_for_no_current_slug()` if you need something stable.
+
+Fields at their default value are **absent** from the wire, not zero. `poll()`
+already fills a curated set back in as `0`, so treat a missing field as unknown
+rather than surprising.
+
+## Commands
+
+Every command goes through `perform()`, which builds the request and checks the
+answer:
+
+```python
+await charger.perform(lambda s: s.set_charger_enabled(True))
+await charger.perform(lambda s: s.set_max_charger_current(16))
+await charger.perform(lambda s: s.set_dynamic_charger_current(10))
+await charger.perform(lambda s: s.set_circuit_max_current(20))          # or (p1, p2, p3)
+await charger.perform(lambda s: s.set_offline_max_circuit_current(10))
+await charger.perform(lambda s: s.set_phase_mode(PhaseMode.LOCKED_3_PHASE))
+await charger.perform(lambda s: s.set_led_brightness(75))               # 0-100
+await charger.perform(lambda s: s.set_cable_locked(True))
+await charger.perform(lambda s: s.set_access_control(True))
+```
+
+`PhaseMode` is `LOCKED_1_PHASE`, `AUTO` or `LOCKED_3_PHASE`.
+
+### RFID / account keys
+
+```python
+from easee_ble import command_payload
+
+reply = await charger.perform(lambda s: s.list_user_tokens())
+keys = command_payload(reply)
+await charger.perform(lambda s: s.get_user_token(slot, name))
+await charger.perform(lambda s: s.set_user_token(slot, name, token))
+```
+
+### Other reads
+
+Besides `poll()`, individual frames are available through `perform()`:
+
+```python
+await charger.perform(lambda s: s.poll_state())
+await charger.perform(lambda s: s.poll_config())
+await charger.perform(lambda s: s.poll_structure())
+await charger.perform(lambda s: s.poll_debug())
+```
+
+A reply only arrives on a subscribed channel, and the last two are not
+subscribed to by default. Ask for them at connect - `EaseeCharger(...,
+channels=DEFAULT_CHANNELS | {Channel.DEBUG})` - or the call raises. `poll()`
+takes the same argument to read them alongside Config and State.
+
+## Errors
+
+```python
+from easee_ble import EaseeCommandRefused, EaseeConnectionError, JPakeError
+
+try:
+    await charger.connect()
+    await charger.perform(lambda s: s.set_max_charger_current(32))
+except JPakeError:            # almost always the wrong PIN
+    ...
+except EaseeCommandRefused:   # the charger answered, and said no
+    ...
+except EaseeConnectionError:  # connecting or talking to it failed
+    ...
+```
+
+A reply is **not** an acknowledgement - the charger answers a command it refuses
+just as promptly as one it accepts. `perform()` checks for you and raises
+`EaseeCommandRefused`; anything else, `command_accepted()` and
+`command_refusal()` check by hand.
+
+## Connection notes
+
+- The connection is **long-lived**: connect once and keep polling. Connecting is
+  the expensive, failure-prone part.
+- **Not safe for concurrent use.** One request may be in flight at a time -
+  serialise with a lock if several tasks share a charger.
+- Pass `on_disconnect=` to be told the moment the link drops rather than at your
+  next poll; check `charger.connected` before using it.
+- The charger has a single connection slot. Always `disconnect()` when done.
+
+```python
+charger = EaseeCharger(device, pin="1234", serial="EMX00000",
+                       on_disconnect=lambda c: print("link lost"))
+```
+
+## Without bleak
+
+`Session` is sans-io: it builds requests and parses replies and does no I/O, so
+you can drive it over any transport.
+
+```python
+from easee_ble import Session
+
+s = Session(pin="1234", serial="EMX00000")
+req = s.start_handshake()          # write req.data to req.channel, feed the reply back
+req = s.read_round_one(reply)
+s.read_round_two(reply)            # s.established is now True
+frame = s.parse(req.channel, reply)
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+Tests run against captured bytes from a real charger, so they need no hardware.
+
+## Notes
+
+**Unofficial.** Reverse-engineered. Not affiliated with or endorsed by Easee. No warranty, changing charger settings is at your own risk. Barely tested.
+

easee_ble-0.1.0/pyproject.toml

@@ -0,0 +1,86 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "easee-ble"
+dynamic = ["version"]
+description = "Local Bluetooth control for Easee EV chargers"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+authors = [{ name = "parrel" }]
+keywords = ["easee", "ev", "charger", "bluetooth", "ble", "home-assistant"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Framework :: AsyncIO",
+  "Topic :: Home Automation",
+]
+dependencies = [
+  # A 4-byte GCM nonce is legal but `cryptography` refuses any IV under 8
+  # bytes, so this cannot be swapped for it. See easee_ble/crypto.py.
+  "pycryptodome>=3.20",
+  # EC-JPAKE needs raw P-256 point arithmetic, which `cryptography` does not
+  # expose. Note ecdsa's own README: it is not side-channel hardened.
+  "ecdsa>=0.19",
+  "bleak>=0.22",
+  "bleak-retry-connector>=3.5.0",
+]
+
+[project.urls]
+Repository = "https://github.com/parrel/easee-ble"
+"Bug Tracker" = "https://github.com/parrel/easee-ble/issues"
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8",
+  "pytest-asyncio>=0.23",
+  "pytest-cov>=5",
+  "ruff>=0.6",
+  "mypy>=1.11",
+]
+
+[tool.setuptools.dynamic]
+version = { attr = "easee_ble.__version__" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+easee_ble = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+# The client tests are async; without this every one of them needs a decorator.
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+
+# `py.typed` promises callers that these annotations are checked, so check them.
+[tool.mypy]
+python_version = "3.11"
+mypy_path = "src"
+packages = ["easee_ble"]
+strict = true
+# The library is annotated; its dependencies are not all shipped with types.
+[[tool.mypy.overrides]]
+module = ["Crypto.*", "ecdsa.*", "bleak_retry_connector.*"]
+ignore_missing_imports = true
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+# Pinned explicitly rather than left to ruff's defaults, which shift between
+# releases - CI should not start failing because a new ruff was published.
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "RUF"]
+ignore = [
+  # __all__ is grouped by role, with comments. Alphabetising it would destroy
+  # the only structure it has.
+  "RUF022",
+]

easee_ble-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

easee_ble-0.1.0/src/easee_ble/__init__.py

@@ -0,0 +1,107 @@
+"""Local BLE control for Easee EV chargers."""
+
+from __future__ import annotations
+
+from . import commands, crypto, frames, protocol
+from .client import DEFAULT_CHANNELS, DEFAULT_POLL_CHANNELS, EaseeCharger
+from .commands import BtEnableMode, Command, NetworkStatus, PhaseMode, network_status
+from .const import HANDSHAKE_MTU
+from .crypto import decrypt, encrypt
+from .exceptions import (
+    EaseeCommandRefused,
+    EaseeConnectionError,
+    EaseeError,
+    FrameError,
+    IncompleteFrame,
+    JPakeError,
+    ProtocolError,
+    RecordError,
+    SessionError,
+)
+from .frames import (
+    CONFIRMED_REASON_CODES,
+    FIELD_ALIASES,
+    FIELD_UNITS,
+    REASON_FOR_NO_CURRENT,
+    REASON_FOR_NO_CURRENT_SLUGS,
+    ZERO_WHEN_ABSENT,
+    ChargerOpMode,
+    Frame,
+    MessageType,
+    charger_op_mode,
+    command_accepted,
+    command_payload,
+    command_refusal,
+    declared_length,
+    parse_command_response,
+    parse_response,
+    reason_for_no_current,
+    reason_for_no_current_slug,
+    with_aliases,
+)
+from .jpake import ECJPake
+from .protocol import CHANNEL_BY_UUID, MANUFACTURER_ID, SERVICE_UUID, Channel
+from .session import Request, Session
+
+__all__ = [
+    # client
+    "EaseeCharger",
+    # sans-io core
+    "Session",
+    "Request",
+    "ECJPake",
+    "encrypt",
+    "decrypt",
+    # commands and their value types
+    "Command",
+    "PhaseMode",
+    "BtEnableMode",
+    "NetworkStatus",
+    "network_status",
+    # responses
+    "Frame",
+    "MessageType",
+    "ChargerOpMode",
+    "charger_op_mode",
+    "REASON_FOR_NO_CURRENT",
+    "REASON_FOR_NO_CURRENT_SLUGS",
+    "CONFIRMED_REASON_CODES",
+    "FIELD_UNITS",
+    "reason_for_no_current",
+    "reason_for_no_current_slug",
+    "ZERO_WHEN_ABSENT",
+    # renaming a shipped field name; see "Field name stability" in the README
+    "FIELD_ALIASES",
+    "with_aliases",
+    "declared_length",
+    "parse_response",
+    "parse_command_response",
+    "command_accepted",
+    "command_payload",
+    "command_refusal",
+    # transport constants worth knowing about
+    "SERVICE_UUID",
+    "MANUFACTURER_ID",
+    "CHANNEL_BY_UUID",
+    "Channel",
+    "HANDSHAKE_MTU",
+    "DEFAULT_CHANNELS",
+    "DEFAULT_POLL_CHANNELS",
+    # exceptions
+    "EaseeError",
+    "EaseeConnectionError",
+    "EaseeCommandRefused",
+    "ProtocolError",
+    "FrameError",
+    "IncompleteFrame",
+    "RecordError",
+    "SessionError",
+    "JPakeError",
+    # submodules
+    "commands",
+    "crypto",
+    "frames",
+    "protocol",
+]
+
+__version__ = "0.1.0"