STA - Smart Temperature & Appliance Control

Web-based Modbus relay control system for managing 8-channel relay modules over TCP.

⚠️ Development Status: This project is in early development. Core features are currently being implemented following a specification-driven approach.

Overview

STA will provide a modern web interface for controlling Modbus-compatible relay devices, eliminating the need for specialized industrial software. The goal is to enable browser-based relay control with real-time status updates.

Current Status

Implemented:

• ✅ Basic Rust web server with Poem framework
• ✅ Configuration system (YAML + environment variables)
• ✅ Modbus TCP settings structure
• ✅ Health check and metadata API endpoints
• ✅ OpenAPI documentation with Swagger UI
• ✅ Rate limiting middleware

In Progress:

• 🚧 Domain model for relay control (Phase 2)
• 🚧 Modbus TCP client implementation (Phase 3)

Planned Features:

• 📋 8-Channel Relay Control: Individual and bulk relay control (on/off/toggle)
• 📋 Real-Time Monitoring: Live relay state updates via HTTP polling
• 📋 Custom Labels: Name your relays for easy identification
• 📋 Health Monitoring: Connection status and device health tracking
• 📋 Vue 3 + TypeScript frontend

See tasks.md for detailed implementation roadmap.

Architecture

Current:

• Backend: Rust 2024 with Poem web framework
• Configuration: YAML-based with environment variable overrides
• API: RESTful HTTP with OpenAPI documentation

Planned:

• Modbus Integration: tokio-modbus for Modbus TCP communication
• Frontend: Vue 3 with TypeScript
• Deployment: Backend on Raspberry Pi, frontend on Cloudflare Pages
• Access: Traefik reverse proxy with Authelia authentication
• Persistence: SQLite for relay labels and configuration

Quick Start

Prerequisites

• Rust 1.83+ (edition 2024)
• Just command runner

Development

# Run development server
just run

# Run tests
just test

# Run linter
just lint

# Format code
just format

# Watch mode with bacon
bacon          # clippy-all (default)
bacon test     # test watcher

Configuration

Edit settings/base.yaml for Modbus device settings:

modbus:
  host: "192.168.0.200"
  port: 502
  slave_id: 0
  timeout_secs: 5

relay:
  label_max_length: 50

Override with environment variables:

APP__MODBUS__HOST=192.168.1.100 cargo run

API Documentation

The server provides OpenAPI documentation via Swagger UI:

• Swagger UI: http://localhost:8080/
• OpenAPI Spec: http://localhost:8080/openapi.json

Current Endpoints:

• GET /api/health - Health check endpoint
• GET /api/meta - Application metadata

Planned Endpoints (see spec):

• GET /api/relays - List all relay states
• POST /api/relays/{id}/toggle - Toggle relay state
• POST /api/relays/all/on - Turn all relays on
• POST /api/relays/all/off - Turn all relays off
• PUT /api/relays/{id}/label - Set relay label

Project Structure

Current:

src/
├── lib.rs           - Library entry point
├── main.rs          - Binary entry point
├── startup.rs       - Application builder and server configuration
├── settings.rs      - Configuration management
├── telemetry.rs     - Logging and tracing setup
├── route/           - HTTP endpoint handlers
│   ├── health.rs    - Health check endpoints
│   └── meta.rs      - Application metadata
└── middleware/      - Custom middleware
    └── rate_limit.rs

specs/               - Feature specifications and documentation
settings/            - YAML configuration files

Planned (Hexagonal Architecture):

src/
├── domain/          - Business logic and domain models (Phase 2)
├── application/     - Use cases and orchestration (Phase 3-4)
├── infrastructure/  - Modbus, persistence, external services (Phase 3)
└── presentation/    - API endpoints and DTOs (Phase 4)

Technology Stack

Currently Used:

• Rust 2024 edition
• Poem 3.1 (web framework with OpenAPI support)
• Tokio 1.48 (async runtime)
• config (YAML configuration)
• tracing + tracing-subscriber (structured logging)
• governor (rate limiting)
• thiserror (error handling)

Planned Dependencies:

• tokio-modbus 0.17 (Modbus TCP client)
• SQLx 0.8 (async SQLite database access)
• mockall 0.13 (mocking for tests)

Frontend (planned):

• Vue 3 + TypeScript
• Vite build tool
• Axios (HTTP client)

Documentation

• Project Constitution - Architectural principles and development guidelines
• Modbus Relay Control Spec - Feature specification
• CLAUDE.md - Developer guide and code style rules

License

This project is under the AGPL-3.0 license. You can find it in the LICENSE.md file.