Skip to content

How-To Guides

Step-by-step instructions for common tasks.

These guides assume you've read the Getting Started section and are familiar with the basic concepts.

  • Telemetry Device

    Build a sensor-polling device with optional publish strategies.

    Telemetry Device

  • Command & Control Device

    Build a device that receives commands via MQTT.

    Command Device

  • Configuration

    Extend Settings, use .env files, override via CLI.

    Configuration

  • Hardware Adapters

    Register adapters: direct, lazy import, dry-run swapping.

    Adapters

  • Share State Between Handlers

    Use adapters-as-state to share data between command and telemetry handlers.

    Shared State

  • Lifespan

    Run startup and shutdown code with the lifespan context manager.

    Lifespan

  • Multi-Device Registration

    Register multiple similar devices from settings with @app.on_configure and dict-name decorators.

    Multi-Device Registration

  • Testing

    Use cosalette.testing, AppHarness, and pytest fixtures.

    Testing

  • Custom Error Types

    Map domain exceptions to structured error payloads.

    Error Types

  • Deployment

    Containerise and deploy with Docker, Compose, and Ansible.

    Deployment

  • Build a Full App

    Capstone guide — combines everything above into a complete application.

    Full App Guide