Module Development for SelenaCore

🇺🇦 Українська версія

What is a Module

A user module is an isolated microservice in a Docker container that communicates with the core only through Core API (http://localhost:7070/api/v1).

A module can: register devices, subscribe to Event Bus events, publish events (except core.*), store OAuth tokens through Secrets Vault.

A module cannot: read /secure/, access SQLite directly, publish core.* events, obtain OAuth tokens directly, stop other modules.

Module Structure

my-module.zip
  manifest.json          ← required
  main.py                ← entry point
  requirements.txt       ← Python dependencies
  Dockerfile             ← how to run
  icon.svg               ← UI icon (if type: UI)

manifest.json

{
  "name": "my-module",
  "version": "1.0.0",
  "description": "Brief module description",
  "type": "UI",
  "ui_profile": "FULL",
  "api_version": "1.0",
  "runtime_mode": "always_on",
  "port": 8100,
  "permissions": ["device.read", "device.write", "events.subscribe", "events.publish"],
  "ui": { "icon": "icon.svg", "widget": { "file": "widget.html", "size": "2x1" }, "settings": "settings.html" },
  "resources": { "memory_mb": 128, "cpu": 0.25 },
  "author": "Your Name",
  "license": "MIT"
}

Permissions

Permission	Available for	Description
device.read	all	GET /devices
device.write	all	POST/PATCH/DELETE /devices
events.subscribe	all	Subscribe to events
events.publish	all	Publish events
secrets.oauth	INTEGRATION only	Start OAuth flow
secrets.proxy	INTEGRATION only	API proxy through vault

SDK — base_module.py

from sdk.base_module import SmartHomeModule, on_event, scheduled

class MyModule(SmartHomeModule):
    name = "my-module"
    version = "1.0.0"

    async def on_start(self):
        self.logger.info("Module started")

    @on_event("device.state_changed")
    async def handle_state(self, payload: dict):
        device = await self.get_device(payload["device_id"])

    @scheduled("every:5m")
    async def periodic_sync(self):
        devices = await self.list_devices()

Local Development

1. smarthome new-module my-module — create structure
2. smarthome dev — run mock Core API on :7070
3. Develop your module using FastAPI
4. smarthome test — run pytest
5. smarthome publish --core http://localhost:7070 — deploy

Webhooks from Event Bus

When subscribed, the core POSTs to your webhook URL with X-Selena-Signature: sha256=<hmac>. SDK verifies HMAC automatically.

OAuth Integration

POST /api/v1/secrets/oauth/start
{ "module": "gmail-integration", "provider": "google", "scopes": ["gmail.readonly"] }

POST /api/v1/secrets/proxy
{ "module": "gmail-integration", "url": "https://gmail...", "method": "GET" }
# Token NEVER leaves the core