UvosSmartHomeInterface/AGENTS.md

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