Add README and AGENTS

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

README.md

@@ -0,0 +1,90 @@
+# SHinterface - Smart Home Control Interface
+
+A Qt6-based smart home control application that interfaces with microcontrollers and sensors to manage home automation devices.
+
+## Quick Start
+
+### Building
+```bash
+mkdir build
+cd build
+cmake ..
+make
+```
+
+### Running
+
+**Primary (Master) Mode:**
+```bash
+./SHinterface -m
+```
+
+**Secondary (Client) Mode:**
+```bash
+./SHinterface -H 192.168.1.100 -p 38940
+```
+
+**Headless Server Mode:**
+```bash
+./SHinterface -m -e
+```
+
+## Features
+
+- ✅ Control relays and PWM outputs
+- ✅ Monitor various sensors (temperature, humidity, doors, etc.)
+- ✅ MQTT sensor integration
+- ✅ Actor-based automation system
+- ✅ RGB lighting control
+- ✅ WebSocket API for remote access
+- ✅ Primary/secondary architecture for distributed control
+
+## Configuration
+
+Settings are stored in JSON format. Default location:
+```
+~/.config/shinterface.json
+```
+
+You can specify a custom config file with:
+```bash
+./SHinterface -c /path/to/config.json
+```
+
+## Usage
+
+### Primary Mode (Master)
+The primary instance connects to your microcontroller and manages all devices. It can run with or without a GUI.
+
+### Secondary Mode (Client)
+Secondary instances connect to the primary via TCP and provide additional control points without needing their own microcontroller connection.
+
+## Command Line Options
+
+```
+-m, --master          Use in master mode
+-H, --host <address>  Set server host IP address (default: 0.0.0.0)
+-p, --port <port>     Set server port (default: 38940)
+-c, --config <file>   Set config file path
+-e, --headless        Don't start the GUI (master mode only)
+--help                Show help
+--version             Show version
+```
+
+## Architecture
+
+- **Items**: Represent controllable devices (relays, lights, etc.)
+- **Actors**: Automate actions based on sensors or time
+- **Sensors**: Provide data from physical sensors and calculated sources
+- **Services**: TCP and WebSocket interfaces for remote control
+
+## Dependencies
+
+- CMake 4.0+
+- Qt6 (Core, Gui, Widgets, Network, Multimedia, SerialPort, Mqtt, WebSockets)
+- libpipewire-0.3
+- libnl-3.0
+
+## License
+
+See LICENSE file for details.