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).
