Skip to content

suncast

License: GPL-3.0-or-later Python cosalette

Solar shadow visualization service

suncast is a cosalette-based IoT service that computes solar positions from GPS coordinates and generates shadow visualizations of building footprints. It publishes SVG (and optionally PNG) images via MQTT and filesystem output, enabling both OpenHAB and Home Assistant dashboards to display real-time shadow maps.

Noon shadows Afternoon shadows Night — no shadows

Features

  • Real-time solar position — computes azimuth, elevation, sunrise/sunset from GPS coordinates
  • Building shadow projection — parallel shadow casting from arbitrary convex polygons
  • SVG and PNG output — publishes images via MQTT, filesystem, and optional HTTP server
  • Configurable geometry — YAML or SVG-based building footprint definitions
  • Sundial ring and day/night arc — visual indicators of sun path and direction
  • Health reporting — automatic heartbeats, per-device availability, and LWT
  • Docker-ready — single docker compose up deployment with nginx sidecar

  • Getting Started

    Install suncast and see your first MQTT messages.

    Get started

  • Configuration

    All settings — environment variables, .env files, and CLI flags.

    Configure

  • MQTT Topics

    Topic reference with payload schemas, directions, and retain flags.

    Topics

  • Architecture

    Rendering pipeline, domain layers, and cosalette framework integration.

    Architecture

  • Geometry Guide

    Define building footprints in YAML or import from SVG.

    Geometry

  • ADRs

    Architecture decision records documenting design choices.

    Decisions