cosalette 0.3.0

an opinionated Python framework for building IoT-to-MQTT bridge applications

cosalette

Documentation · Dev Docs (latest) · Quickstart · API Reference

---

What is cosalette?

cosalette lets you build IoT-to-MQTT bridge daemons in Python with minimal boilerplate. You define devices (telemetry pollers or command handlers), register hardware adapters, and the framework handles MQTT wiring, structured logging, health reporting, error publishing, and graceful lifecycle management.

Quick Example

import cosalette

app = cosalette.App(name="sensor2mqtt", version="0.1.0")

@app.telemetry("sensor", interval=5.0)
async def sensor() -> dict[str, object]:
    return {"temperature": 21.5, "humidity": 55.0}

if __name__ == "__main__":
    app.run()

See the full Quickstart for a complete walkthrough.

Key Features

• Declarative device registration — define telemetry and command devices with @app.telemetry(), @app.command(), and @app.device() (guide)
• Hexagonal architecture — protocol-based ports keep hardware adapters swappable and testable (concept)
• Lifespan + dependency injection — structured startup/teardown and type-based DI for adapters, settings, and shared state (guide)
• Command routing — use sub-topic handlers and ctx.commands() for clean control flows (guide)
• Flexible scheduling — combine fixed intervals, Quartz cron, and ctx.sleep_until() wall-clock timing
• Publish strategies — emit on change, on cadence, or with composed rules (concept)
• Health checks + auto-restart — monitor adapters and recover from wedged hardware automatically (concept)
• Persistence — store state with JSON, SQLite, or in-memory backends plus save policies (concept)
• Schema-aware integrations — validate payloads and generate consumer artifacts from AsyncAPI schemas (guide)
• AI-assisted development — optional MCP tools plus packaged instructions for Copilot and other IDE-native agents (guide)

Installation

pip install cosalette

Or with uv:

uv add cosalette

To include the optional MCP server for IDE-native AI agent integration (VS Code Copilot, Cursor, Windsurf, Claude Code):

uv add 'cosalette[mcp]'
pip install 'cosalette[mcp]'

See the MCP Server guide for setup and tool reference.

Contributing

See CONTRIBUTING.md for development setup, commands, project structure, and code quality standards.

Documentation

Full documentation is published at ff-fab.github.io/cosalette. Development docs tracking the main branch are available at Dev Docs (latest).

Section	What you'll find
Getting Started	Installation, quickstart tutorial
Concepts	Architecture, lifecycle, health checks, filters, persistence
How-To Guides	Telemetry, commands, adapters, lifespan DI, schema, testing, MCP
Reference	API docs, CLI options, payload schemas
ADRs	Architecture Decision Records

License

MIT License. See LICENSE for details.