docs: add README and AGPL-3.0 license
Add project README with development status and roadmap. Add AGPL-3.0 license file.
This commit is contained in:
170
README.md
Normal file
170
README.md
Normal file
@@ -0,0 +1,170 @@
|
||||
# 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](specs/001-modbus-relay-control/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
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```yaml
|
||||
modbus:
|
||||
host: "192.168.0.200"
|
||||
port: 502
|
||||
slave_id: 0
|
||||
timeout_secs: 5
|
||||
|
||||
relay:
|
||||
label_max_length: 50
|
||||
```
|
||||
|
||||
Override with environment variables:
|
||||
```bash
|
||||
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](specs/constitution.md) - Architectural principles and development guidelines
|
||||
- [Modbus Relay Control Spec](specs/001-modbus-relay-control/spec.md) - Feature specification
|
||||
- [CLAUDE.md](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](LICENSE.md) file.
|
||||
Reference in New Issue
Block a user