ebus-sdk 0.1.0__tar.gz

ebus_sdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Electrification Bus (eBus) Contributors
+
+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.

ebus_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,139 @@
+Metadata-Version: 2.4
+Name: ebus-sdk
+Version: 0.1.0
+Summary: Python SDK for Homie MQTT Convention (eBus)
+Author: eBus Contributors
+License-Expression: MIT
+Project-URL: Homepage, https://ebus.energy
+Project-URL: Repository, https://github.com/electrification-bus/python-sdk
+Keywords: mqtt,homie,iot,ebus
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Home Automation
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: paho-mqtt>=1.6.1
+Provides-Extra: mdns
+Requires-Dist: zeroconf>=0.131.0; extra == "mdns"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file
+
+# ebus-sdk
+
+Python SDK for the [Electrification Bus (eBus)](https://ebus.energy) integration framework, which adopts and supports the [Homie Convention](https://homieiot.github.io).
+
+## Installation
+
+```bash
+pip install ebus-sdk
+```
+
+## Quick Start
+
+### Device Role
+
+Create a Homie device that publishes sensor data:
+
+```python
+from ebus_sdk import Device, Node, PropertyDatatype, Unit
+
+# Create device
+device = Device('my-device-id', name='My Sensor', mqtt_cfg={
+    'host': 'mqtt.example.com',
+    'port': 1883
+})
+
+# Add a node with properties
+node = device.add_node_from_dict({
+    'id': 'sensors',
+    'name': 'Sensors',
+    'type': 'sensor'
+})
+
+# Add a temperature property
+temp = node.add_property_from_dict({
+    'id': 'temperature',
+    'name': 'Temperature',
+    'datatype': PropertyDatatype.FLOAT,
+    'unit': Unit.DEGREE_CELSIUS
+})
+
+# Start and publish
+device.start_mqtt_client()
+temp.set_value(23.5)
+```
+
+### Controller Role
+
+Discover and monitor Homie devices:
+
+```python
+from ebus_sdk import Controller, DiscoveredDevice
+
+def on_device_discovered(device: DiscoveredDevice):
+    print(f'Found: {device.device_id}')
+
+def on_property_changed(device_id, node_id, prop_id, new_val, old_val):
+    print(f'{device_id}/{node_id}/{prop_id} = {new_val}')
+
+controller = Controller(mqtt_cfg={'host': 'mqtt.example.com', 'port': 1883})
+controller.set_on_device_discovered_callback(on_device_discovered)
+controller.set_on_property_changed_callback(on_property_changed)
+controller.start_discovery()
+```
+
+## Module Structure
+
+```
+src/ebus_sdk/
+├── __init__.py     # Package exports
+├── homie.py        # Homie convention implementation
+├── mqtt.py         # MQTT client wrapper
+└── property.py     # Property abstractions
+```
+
+### homie.py
+
+Core Homie convention implementation:
+
+- **Device** - Represents a Homie device with nodes and properties
+- **Node** - Groups related properties within a device
+- **Property** - Individual data points (sensors, controls)
+- **Controller** - Discovers and monitors Homie devices on a broker
+- **DiscoveredDevice** - Represents a device found by the controller
+- **DeviceState** - Enum: `init`, `ready`, `disconnected`, `sleeping`, `lost`
+- **PropertyDatatype** - Enum: `STRING`, `INTEGER`, `FLOAT`, `BOOLEAN`, `ENUM`, `COLOR`, `DATETIME`, `DURATION`, `JSON`
+- **Unit** - Common units: `DEGREE_CELSIUS`, `PERCENT`, `WATT`, `KILOWATT_HOUR`, etc.
+
+### mqtt.py
+
+- **MqttClient** - Wrapper around paho-mqtt with automatic reconnection, TLS support, and subscription management
+
+### property.py
+
+Application-level property abstractions for bridging application state to Homie:
+
+- **Property** - Thread-safe observable property with change callbacks
+- **GroupedPropertyDict** - Two-level dictionary organizing properties by group
+- **PropertyDict** - Simple property dictionary
+- **ChangeEvent** - Enum for property change event types
+
+## Examples
+
+See [`examples/README.md`](examples/README.md) for example scripts demonstrating device and controller usage.
+
+## Requirements
+
+- Python 3.10+
+- paho-mqtt >= 1.6.1
+
+## License
+
+MIT

ebus_sdk-0.1.0/README.md

@@ -0,0 +1,112 @@
+# ebus-sdk
+
+Python SDK for the [Electrification Bus (eBus)](https://ebus.energy) integration framework, which adopts and supports the [Homie Convention](https://homieiot.github.io).
+
+## Installation
+
+```bash
+pip install ebus-sdk
+```
+
+## Quick Start
+
+### Device Role
+
+Create a Homie device that publishes sensor data:
+
+```python
+from ebus_sdk import Device, Node, PropertyDatatype, Unit
+
+# Create device
+device = Device('my-device-id', name='My Sensor', mqtt_cfg={
+    'host': 'mqtt.example.com',
+    'port': 1883
+})
+
+# Add a node with properties
+node = device.add_node_from_dict({
+    'id': 'sensors',
+    'name': 'Sensors',
+    'type': 'sensor'
+})
+
+# Add a temperature property
+temp = node.add_property_from_dict({
+    'id': 'temperature',
+    'name': 'Temperature',
+    'datatype': PropertyDatatype.FLOAT,
+    'unit': Unit.DEGREE_CELSIUS
+})
+
+# Start and publish
+device.start_mqtt_client()
+temp.set_value(23.5)
+```
+
+### Controller Role
+
+Discover and monitor Homie devices:
+
+```python
+from ebus_sdk import Controller, DiscoveredDevice
+
+def on_device_discovered(device: DiscoveredDevice):
+    print(f'Found: {device.device_id}')
+
+def on_property_changed(device_id, node_id, prop_id, new_val, old_val):
+    print(f'{device_id}/{node_id}/{prop_id} = {new_val}')
+
+controller = Controller(mqtt_cfg={'host': 'mqtt.example.com', 'port': 1883})
+controller.set_on_device_discovered_callback(on_device_discovered)
+controller.set_on_property_changed_callback(on_property_changed)
+controller.start_discovery()
+```
+
+## Module Structure
+
+```
+src/ebus_sdk/
+├── __init__.py     # Package exports
+├── homie.py        # Homie convention implementation
+├── mqtt.py         # MQTT client wrapper
+└── property.py     # Property abstractions
+```
+
+### homie.py
+
+Core Homie convention implementation:
+
+- **Device** - Represents a Homie device with nodes and properties
+- **Node** - Groups related properties within a device
+- **Property** - Individual data points (sensors, controls)
+- **Controller** - Discovers and monitors Homie devices on a broker
+- **DiscoveredDevice** - Represents a device found by the controller
+- **DeviceState** - Enum: `init`, `ready`, `disconnected`, `sleeping`, `lost`
+- **PropertyDatatype** - Enum: `STRING`, `INTEGER`, `FLOAT`, `BOOLEAN`, `ENUM`, `COLOR`, `DATETIME`, `DURATION`, `JSON`
+- **Unit** - Common units: `DEGREE_CELSIUS`, `PERCENT`, `WATT`, `KILOWATT_HOUR`, etc.
+
+### mqtt.py
+
+- **MqttClient** - Wrapper around paho-mqtt with automatic reconnection, TLS support, and subscription management
+
+### property.py
+
+Application-level property abstractions for bridging application state to Homie:
+
+- **Property** - Thread-safe observable property with change callbacks
+- **GroupedPropertyDict** - Two-level dictionary organizing properties by group
+- **PropertyDict** - Simple property dictionary
+- **ChangeEvent** - Enum for property change event types
+
+## Examples
+
+See [`examples/README.md`](examples/README.md) for example scripts demonstrating device and controller usage.
+
+## Requirements
+
+- Python 3.10+
+- paho-mqtt >= 1.6.1
+
+## License
+
+MIT

ebus_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ebus-sdk"
+version = "0.1.0"
+description = "Python SDK for Homie MQTT Convention (eBus)"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [
+    {name = "eBus Contributors"}
+]
+keywords = ["mqtt", "homie", "iot", "ebus"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Home Automation",
+    "Topic :: Internet :: WWW/HTTP",
+]
+dependencies = [
+    "paho-mqtt>=1.6.1",
+]
+
+[project.optional-dependencies]
+mdns = ["zeroconf>=0.131.0"]
+dev = ["pytest"]
+
+[project.urls]
+Homepage = "https://ebus.energy"
+Repository = "https://github.com/electrification-bus/python-sdk"
+
+[tool.setuptools.packages.find]
+where = ["src"]

ebus_sdk-0.1.0/setup.cfg

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

ebus_sdk-0.1.0/src/ebus_sdk/__init__.py

@@ -0,0 +1,67 @@
+"""
+ebus-sdk: Python SDK for Homie MQTT Convention (eBus)
+
+This SDK provides Device and Controller roles for the Homie MQTT convention.
+"""
+
+# Core Homie classes
+from .homie import (
+    Device,
+    Node,
+    Property,
+    Controller,
+    DiscoveredDevice,
+    StateTransitionContext,
+)
+
+# Enums
+from .homie import (
+    DeviceState,
+    PropertyDatatype,
+    Unit,
+)
+
+# Utility functions
+from .homie import (
+    datatype_from_type,
+    ebus_cfg_add_auth,
+)
+
+# Property abstractions
+from .property import (
+    Property as ObservableProperty,
+    GroupedPropertyDict,
+    PropertyDict,
+    ChangeEvent,
+    BulkUpdateContext,
+)
+
+# MQTT client
+from .mqtt import MqttClient
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Homie classes
+    "Device",
+    "Node",
+    "Property",
+    "Controller",
+    "DiscoveredDevice",
+    "StateTransitionContext",
+    # Enums
+    "DeviceState",
+    "PropertyDatatype",
+    "Unit",
+    # Utilities
+    "datatype_from_type",
+    "ebus_cfg_add_auth",
+    # Property abstractions
+    "ObservableProperty",
+    "GroupedPropertyDict",
+    "PropertyDict",
+    "ChangeEvent",
+    "BulkUpdateContext",
+    # MQTT
+    "MqttClient",
+]