Add README and AGENTS

2026-04-09 11:55:08 +02:00 · 2026-04-09 11:55:08 +02:00 · a3a5277e5d
commit a3a5277e5d
parent cd7d44a5a5
2 changed files with 219 additions and 0 deletions
--- a/AGENTS.md
+++ b/AGENTS.md
@ -0,0 +1,129 @@
+# SHinterface - Smart Home Interface
+
+## Overview
+SHinterface is a Qt6-based smart home control application that interfaces with microcontrollers and various sensors to manage home automation devices. It supports both primary (master) and secondary (client) modes, allowing for distributed control across multiple devices.
+
+## Architecture
+
+### Core Components
+
+1. **Main Application** (`main.cpp`)
+   - Entry point with command-line argument parsing
+   - Supports three modes:
+     - `PROGRAM_MODE_UI_ONLY`: Secondary client mode
+     - `PROGRAM_MODE_PRIMARY`: Master mode with GUI
+     - `PROGRAM_MODE_HEADLESS_PRIMARY`: Master mode without GUI (server only)
+
+2. **Main Object** (`mainobject.h`, `mainobject.cpp`)
+   - Base class: `MainObject`
+   - Primary mode: `PrimaryMainObject` - Manages microcontroller, sensors, and item sources
+   - Secondary mode: `SecondaryMainObject` - Connects to primary via TCP
+
+3. **Microcontroller Interface** (`microcontroller.h`, `microcontroller.cpp`)
+   - Communicates with embedded devices via serial or TCP
+   - Handles relay control, sensor data, RGB lighting, and PWM outputs
+   - Implements a write queue to prevent buffer overflows
+
+### Key Systems
+
+#### Items System
+- **Item** (`items/item.h`, `items/item.cpp`): Base class for all controllable items
+  - Supports different value types: boolean, unsigned integer, no value
+  - Tracks update sources (user, actor, remote, loaded, backend)
+  
+- Item Types:
+  - **Relay** (`items/relay.h`, `items/relay.cpp`): Switchable outputs
+  - **PowerItem**: Power measurement items
+  - **MessageItem**: Display messages
+  - **SystemItem**: System-related controls
+  - **AuxItem**: Auxiliary PWM outputs
+  - **RGBItem**: RGB LED control
+
+- **ItemStore** (`items/itemstore.h`, `items/itemstore.cpp`): Manages collection of items
+- **ItemSource** (`items/itemsource.h`): Interface for item providers
+  - **FixedItemSource**: Static predefined items
+  - **ItemLoaderSource**: Loads items from configuration
+
+#### Actors System
+Actors trigger actions based on sensor conditions or timers:
+
+- **Actor** (`actors/actor.h`, `actors/actor.cpp`): Base actor class
+  - Can be active/inactive and exhausted (preventing repeated triggers)
+  
+- Actor Types:
+  - **FactorActor**: Triggers when a factor crosses a threshold
+  - **PolynomalActor**: Uses polynomial calculations for triggering
+  - **SensorActor**: Reacts to specific sensor states
+  - **TimerActor**: Time-based triggering
+  - **AlarmTime**: Alarm/clock functionality
+  - **Regulator**: PID-like regulation control
+
+#### Sensors System
+- **Sensor** (`sensors/sensor.h`, `sensors/sensor.cpp`): Represents physical sensors
+  - Sensor types: door, temperature, humidity, pressure, brightness, button, ADC, CO2, PM2.5, VOC, etc.
+  
+- Sensor Sources:
+  - **SunSensorSource** (`sensors/sunsensor.h`, `sensors/sunsensor.cpp`): Solar position calculations
+  - **MqttSensorSource** (`sensors/mqttsensorsource.h`, `sensors/mqttsensorsource.cpp`): MQTT-based sensor data
+
+#### Networking Services
+- **TcpServer** (`service/tcpserver.h`, `service/tcpserver.cpp`): TCP server for remote control
+- **WebSocketServer** (`service/websocketserver.h`, `service/websocketserver.cpp`): WebSocket interface
+- **TcpClient** (`service/tcpclient.h`, `service/tcpclient.cpp`): Client for secondary instances
+
+### UI Components
+- **MainWindow** (`ui/mainwindow.ui`, `ui/mainwindow.cpp`): Main application window
+- **ItemWidget**: Visual representation of items
+- **ItemScrollBox**: Scrollable container for items
+- **SensorListWidget**: Displays sensor information
+- **ItemCreationDialog**: Create new items
+- **ItemSettingsDialog**: Configure item properties
+- **ActorSettingsDialog**: Configure actor behavior
+
+## Data Flow
+
+### Primary Mode (Master)
+```
+Microcontroller ↔ Items ↔ Actors ↔ Sensors
+       ↑        ↑          ↑         ↑
+   TCP/WebSocket  │          │         │
+                 └──────┬──────┘
+                        ↓
+                   UI (MainWindow)
+```
+
+### Secondary Mode (Client)
+```
+Secondary Client ↔ TCP Server (Primary) → Items → Microcontroller
+```
+
+## Configuration
+- Settings stored in JSON format
+- Default location: `~/.config/shinterface.json`
+- Command-line options:
+  - `-m`, `--master`: Run in master mode
+  - `-H`, `--host`: Set server host IP
+  - `-p`, `--port`: Set server port (default: 38940)
+  - `-c`, `--config`: Specify config file path
+  - `-e`, `--headless`: Run without GUI (master mode only)
+
+## Build Requirements
+- CMake 4.0+
+- Qt6 (Core, Gui, Widgets, Network, Multimedia, SerialPort, Mqtt, WebSockets)
+- libpipewire-0.3
+- libnl-3.0
+
+## Communication Protocols
+- **Microcontroller**: Text-based protocol over serial or TCP
+- **Networking**: JSON messages over TCP/WebSocket
+- **Sensors**: MQTT for remote sensors, calculated values for sun position
+
+## Key Features
+1. Distributed control with primary/secondary architecture
+2. Actor-based automation system
+3. Multi-protocol sensor support (MQTT, serial, calculated)
+4. Relay and PWM control
+5. RGB lighting control
+6. WebSocket API for remote access
+7. Configurable via JSON
+8. Cross-platform Qt application