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.

Building Devices

  • Telemetry Device

    Build a sensor-polling device with optional publish strategies.

    Telemetry Device

  • Advanced Telemetry Techniques

    On-demand reads, coalescing groups, cron scheduling, and retry/backoff resilience.

    Advanced Telemetry Techniques

  • Command & Control Device

    Build a device that receives commands via MQTT.

    Command & Control Device

  • Streaming

    Stream continuous sensor data from a StreamablePort adapter with lifecycle and DI wired automatically.

    Streaming

  • Periodic Tasks

    Run background coroutines on a fixed interval — flush buffers, send pings, warm caches.

    Periodic Tasks

  • Multi-Device Registration

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

    Multi-Device Registration

Structuring an Application

  • Router Composition

    Organize multi-module apps with Router for testable boundaries.

    Router Composition

  • Shared State

    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

  • Hardware Adapters

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

    Hardware Adapters

  • Configure Your Application

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

    Configuration

Contracts & Schemas

  • Contract-First Route Design

    Add contract metadata to decorators for machine-readable, auditable interface declarations.

    Contract-First Route Design

  • Schema Enforcement

    Validate MQTT topics and payloads against an AsyncAPI schema. CI gate and fleet-level network schemas.

    Schema Enforcement

Testing & Errors

  • Test Your Application

    Use cosalette.testing, AppHarness, and pytest fixtures.

    Testing

  • Custom Error Types

    Map domain exceptions to structured error payloads.

    Error Types

Operating & Tooling

  • Containerize Your Application

    Package a cosalette app as a Docker image with hardware-specific and multi-arch support.

    Containerize

  • Deploy with Docker Compose

    Containerise and deploy with Docker, Compose, and Ansible.

    Deployment

  • Harden Your Deployment

    Security hardening, production logging, and runtime constraints for containerised applications.

    Harden

  • Troubleshoot a Deployment

    Diagnose and fix common problems with containerised cosalette applications.

    Troubleshoot a Deployment

  • Transport Availability

    Mark devices offline when transports fail. Standardised availability signaling with auto-recovery for SSH, BLE, serial, and HTTP adapters.

    Transport Availability

  • Version Migration

    Upgrade between cosalette versions — breaking changes, typed payloads, Router adoption, testing harness updates.

    Version Migration

  • MCP Server

    Expose fourteen structured tools for IDE-native AI agents to query registrations and generate idiomatic scaffolding.

    MCP Server