otensor-sdk 0.1.0__py3-none-any.whl

otensor_sdk/__init__.py

@@ -0,0 +1,29 @@
+"""
+Otensor Python SDK — para makers com hardware Linux/Raspberry Pi.
+
+Import: from otensor_sdk import OtensorSDK
+
+Diferença em relação à lib de automação (pip install otensor):
+  otensor_sdk  →  roda NO hardware (RPi), publica telemetria, recebe comandos
+  otensor      →  roda EM QUALQUER LUGAR, reage a eventos, cria automações em Python
+"""
+
+from .client import OtensorSDK
+from .device import Device
+from .exceptions import OtensorAuthError, OtensorError, OtensorSessionError
+from .telemetry import TelemetryPublisher
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "OtensorSDK",
+    "Device",
+    "TelemetryPublisher",
+    "OtensorError",
+    "OtensorAuthError",
+    "OtensorSessionError",
+]
+
+# gpio.py / sensehat.py — wrappers de RPi.GPIO e sense-hat: fora de escopo até
+# haver hardware real para validar contra (ver docs/superpowers/specs/
+# 2026-07-03-sdk-python-mock-raspberry-pi-design.md).

otensor_sdk/client.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+import httpx
+
+from .device import Device, MQTTClientProtocol
+from .exceptions import OtensorAuthError, OtensorSessionError
+
+
+def _default_mqtt_client() -> MQTTClientProtocol:
+    import paho.mqtt.client as mqtt
+
+    return mqtt.Client(mqtt.CallbackAPIVersion.VERSION2)
+
+
+class OtensorSDK:
+    def __init__(
+        self,
+        api_base_url: str,
+        api_key: str,
+        device_id: str,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        self._api_key = api_key
+        self._device_id = device_id
+        self._http = http_client or httpx.Client(base_url=api_base_url.rstrip("/"), timeout=10.0)
+
+    def connect(self, device_type: str, mqtt_client: MQTTClientProtocol | None = None) -> Device:
+        response = self._http.post(
+            "/v1/sessions/mqtt",
+            headers={"Authorization": f"ApiKey {self._api_key}"},
+        )
+        if response.status_code == 401:
+            raise OtensorAuthError("API key inválida ou revogada.")
+        if response.status_code != 200:
+            raise OtensorSessionError(
+                f"Falha ao obter sessão MQTT: {response.status_code} {response.text}"
+            )
+        try:
+            data = response.json()["data"]
+            tenant_id = data["tenant_id"]
+            broker_host = data["broker_host"]
+            broker_port = data["broker_port"]
+            username = data["username"]
+            password = data["password"]
+        except (KeyError, ValueError) as exc:
+            raise OtensorSessionError(f"Resposta malformada de /v1/sessions/mqtt: {exc}") from exc
+
+        device = Device(
+            mqtt_client=mqtt_client or _default_mqtt_client(),
+            tenant_id=tenant_id,
+            device_id=self._device_id,
+            device_type=device_type,
+            broker_host=broker_host,
+            broker_port=broker_port,
+            username=username,
+            password=password,
+        )
+        device.connect()
+        return device

otensor_sdk/device.py

@@ -0,0 +1,98 @@
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any, Callable, Protocol
+
+log = logging.getLogger("otensor_sdk.device")
+
+
+class MQTTClientProtocol(Protocol):
+    on_message: Callable[[Any, Any, Any], None] | None
+
+    def username_pw_set(self, username: str, password: str | None = None) -> None: ...
+    def connect(self, host: str, port: int, keepalive: int = 60) -> None: ...
+    def disconnect(self) -> None: ...
+    def loop_start(self) -> None: ...
+    def loop_stop(self) -> None: ...
+    def subscribe(self, topic: str, qos: int = 0) -> Any: ...
+    def publish(self, topic: str, payload: str, qos: int = 0) -> Any: ...
+
+
+class Device:
+    def __init__(
+        self,
+        mqtt_client: MQTTClientProtocol,
+        tenant_id: str,
+        device_id: str,
+        device_type: str,
+        broker_host: str,
+        broker_port: int,
+        username: str,
+        password: str,
+    ) -> None:
+        self._client = mqtt_client
+        self.tenant_id = tenant_id
+        self.device_id = device_id
+        self.device_type = device_type
+        self._broker_host = broker_host
+        self._broker_port = broker_port
+        self._username = username
+        self._password = password
+        self._action_handlers: dict[str, Callable[[dict], None]] = {}
+        self._base_topic = f"ot/{tenant_id}/d/{device_id}"
+        self._client.on_message = self._dispatch_message
+
+    def connect(self) -> None:
+        """Conecta ao broker MQTT e assina o tópico de comandos (`cmd`).
+
+        Atenção — janela de corrida: a assinatura do tópico `cmd` acontece
+        aqui, antes de o chamador ter chance de registrar handlers via
+        `on_action(...)`. Um comando publicado exatamente entre o retorno
+        deste método e o registro do handler correspondente é descartado
+        silenciosamente, pois `_action_handlers` ainda estará vazio no
+        momento em que a mensagem chegar. Registre todos os `on_action`
+        antes de considerar o dispositivo pronto para receber comandos
+        (ou, idealmente, antes de chamar `connect()`).
+        """
+        self._client.username_pw_set(self._username, self._password)
+        self._client.connect(self._broker_host, self._broker_port, keepalive=60)
+        self._client.loop_start()
+        self._client.subscribe(f"{self._base_topic}/cmd", qos=1)
+
+    def disconnect(self) -> None:
+        self._client.loop_stop()
+        self._client.disconnect()
+
+    def publish_property(self, name: str, value: object) -> None:
+        payload = json.dumps({name: value})
+        self._client.publish(f"{self._base_topic}/telemetry", payload, qos=1)
+
+    def on_action(self, name: str) -> Callable[[Callable[[dict], None]], Callable[[dict], None]]:
+        def decorator(fn: Callable[[dict], None]) -> Callable[[dict], None]:
+            self._action_handlers[name] = fn
+            return fn
+
+        return decorator
+
+    def _dispatch_message(self, client: object, userdata: object, msg: object) -> None:
+        try:
+            payload = json.loads(msg.payload.decode())  # type: ignore[attr-defined]
+        except (json.JSONDecodeError, UnicodeDecodeError, AttributeError):
+            log.warning("comando MQTT inválido em %s", getattr(msg, "topic", "?"))
+            return
+        if not isinstance(payload, dict):
+            log.warning("comando MQTT inválido em %s", getattr(msg, "topic", "?"))
+            return
+        action = payload.get("action", "")
+        params = payload.get("payload") or {}
+        handler = self._action_handlers.get(action)
+        if handler is not None:
+            handler(params)
+
+    def __enter__(self) -> "Device":
+        self.connect()
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.disconnect()

otensor_sdk/exceptions.py

@@ -0,0 +1,10 @@
+class OtensorError(Exception):
+    """Erro base do SDK Otensor."""
+
+
+class OtensorAuthError(OtensorError):
+    """API key inválida ou revogada (HTTP 401 em /v1/sessions/mqtt)."""
+
+
+class OtensorSessionError(OtensorError):
+    """Falha ao obter uma sessão MQTT (qualquer status ≠ 200/401)."""

otensor_sdk/telemetry.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+import logging
+import time
+from typing import Callable
+
+from .device import Device
+
+log = logging.getLogger("otensor_sdk.telemetry")
+
+
+class TelemetryPublisher:
+    def __init__(self, device: Device, interval: float) -> None:
+        self._device = device
+        self._interval = interval
+        self._sources: dict[str, Callable[[], object]] = {}
+
+    def set_source(self, property_name: str, source: Callable[[], object]) -> None:
+        self._sources[property_name] = source
+
+    def publish_once(self) -> None:
+        for name, source in self._sources.items():
+            try:
+                self._device.publish_property(name, source())
+            except Exception as exc:  # noqa: BLE001 - falha de uma source não pode derrubar as demais
+                log.warning("falha ao ler/publicar property %s: %s", name, exc)
+
+    def run_forever(self, sleep: Callable[[float], None] = time.sleep) -> None:
+        try:
+            while True:
+                self.publish_once()
+                sleep(self._interval)
+        except KeyboardInterrupt:
+            pass

otensor_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: otensor-sdk
+Version: 0.1.0
+Summary: Otensor Python SDK — para makers com hardware Linux/Raspberry Pi
+Project-URL: Homepage, https://github.com/Oseiasdfarias/otensor-platform
+Project-URL: Repository, https://github.com/Oseiasdfarias/otensor-platform
+Project-URL: Issues, https://github.com/Oseiasdfarias/otensor-platform/issues
+License: MIT
+Keywords: iot,mqtt,otensor,raspberry-pi,sdk,sense-hat
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Home Automation
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: paho-mqtt>=2.1
+Requires-Dist: pydantic>=2.9
+Requires-Dist: python-dotenv>=1.0
+Description-Content-Type: text/markdown
+
+# otensor-sdk
+
+> **PT-BR** · SDK Python para makers com hardware Linux/Raspberry Pi — roda
+> **no dispositivo**, publica telemetria e recebe comandos da plataforma
+> [Otensor](https://github.com/Oseiasdfarias/otensor-platform).
+>
+> **EN** · Python SDK for makers running Linux/Raspberry Pi hardware — runs
+> **on the device**, publishes telemetry and receives commands from the
+> [Otensor](https://github.com/Oseiasdfarias/otensor-platform) platform.
+
+Diferença em relação à lib de automação (`pip install otensor`):
+
+| | `otensor-sdk` (este pacote) | `otensor` |
+|---|---|---|
+| Onde roda | **No hardware** (Raspberry Pi) | Em qualquer lugar |
+| O que faz | Publica telemetria, recebe comandos | Reage a eventos, cria automações |
+
+## Instalação
+
+```bash
+pip install otensor-sdk
+```
+
+Requer Python ≥ 3.11.
+
+## Configuração
+
+Gere uma **API key** no dashboard Otensor (as chaves começam com `sk-`) e
+cadastre um device do tipo `sense_hat_unit` (ou outro tipo do catálogo WoT).
+
+```dotenv
+API_BASE_URL=http://localhost:8000   # ou a URL real da sua instância
+API_KEY=sk-...
+DEVICE_ID=...
+```
+
+## Início rápido
+
+```python
+import os
+from otensor_sdk import OtensorSDK
+
+sdk = OtensorSDK(
+    api_base_url=os.environ["API_BASE_URL"],
+    api_key=os.environ["API_KEY"],
+    device_id=os.environ["DEVICE_ID"],
+)
+
+device = sdk.connect(device_type="sense_hat_unit")  # já conecta ao MQTT
+
+# publica uma leitura
+device.publish_property("temperature", 24.5)
+
+# recebe comandos da plataforma (registrar antes de qualquer publish, para
+# não perder um comando que chegue entre o connect() e o registro)
+@device.on_action("set_pixels")
+def handle_set_pixels(payload: dict) -> None:
+    print("acender LEDs:", payload)
+```
+
+### Publicando telemetria em loop (`TelemetryPublisher`)
+
+```python
+from otensor_sdk import TelemetryPublisher
+
+publisher = TelemetryPublisher(device, interval=5.0)
+publisher.set_source("temperature", lambda: sense_hat.get_temperature())
+publisher.set_source("humidity", lambda: sense_hat.get_humidity())
+publisher.run_forever()  # publica todas as sources a cada 5s, até Ctrl-C
+```
+
+Um exemplo completo, simulando um Raspberry Pi + Sense HAT sem hardware real,
+está em [`examples/mock_raspberry_pi.py`](examples/mock_raspberry_pi.py).
+
+## Desenvolvimento
+
+```bash
+cd sdk-python
+uv sync
+uv run pytest tests/ -q                      # testes unitários (sem infra real)
+RUN_E2E=1 uv run pytest tests/test_integration.py -v  # integração real (ver docstring do arquivo)
+```
+
+Processo de release (publicação no PyPI): ver [RELEASING.md](RELEASING.md).

otensor_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+otensor_sdk/__init__.py,sha256=fkazoF93OPn8B6qaUs_ujtT1cM-LuBB105u-LRoXdBA,911
+otensor_sdk/client.py,sha256=qFw1AiihBE7Jfh7uxsqUwCJMf6KJSmiGpdkNqiLJE8s,1999
+otensor_sdk/device.py,sha256=QW_63an7YwHUYoAVzs1ZcBV4bMJISmBCZ6o4QWP-WF8,3778
+otensor_sdk/exceptions.py,sha256=_eLBc_XN4y5QhcB2ujjEZM6B72_dGp0CJAYe8lUKO-s,296
+otensor_sdk/telemetry.py,sha256=DiDX1NUlfBvAOtwHIsbk7aHWW4enmY-4XjAtE1M9d74,1111
+otensor_sdk-0.1.0.dist-info/METADATA,sha256=yApFhN5FAT-RIw86834so4hQbLiFtvRBRTcTZuYA8YY,3481
+otensor_sdk-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+otensor_sdk-0.1.0.dist-info/RECORD,,

otensor_sdk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any