Initial commit: Home automation docs and CODESYS project
- Reorganized project: codesys/, docs/codesys|redesign|integration|reference/, scripts/ - CODESYS project and exports in codesys/ - Documentation index in docs/README.md - Redesign and light naming configuration - Water boiler control and safety design Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
115
docs/integration/homeassistant.md
Normal file
115
docs/integration/homeassistant.md
Normal file
@@ -0,0 +1,115 @@
|
||||
# Home Assistant Configuration
|
||||
|
||||
## Overview
|
||||
|
||||
Home Assistant provides the user interface (dashboard) and additional automation capabilities for the home automation system.
|
||||
|
||||
## Installation
|
||||
|
||||
- **Version**: [To be filled]
|
||||
- **Installation Type**: [HassOS, Docker, Python venv, etc.]
|
||||
- **Host**: [To be filled]
|
||||
- **Port**: [To be filled]
|
||||
- **URL**: [To be filled]
|
||||
|
||||
## Integrations
|
||||
|
||||
### MQTT Integration
|
||||
|
||||
- **Broker**: [IP/URL]
|
||||
- **Port**: [To be filled]
|
||||
- **Discovery**: [Enabled/Disabled]
|
||||
- **Topics**: [To be filled]
|
||||
|
||||
### Node-RED Integration
|
||||
|
||||
- **Integration Method**: [MQTT, HTTP, API, etc.]
|
||||
- **Configuration**: [To be filled]
|
||||
|
||||
### Zigbee Integration
|
||||
|
||||
- **Direct Zigbee**: [If Home Assistant has direct Zigbee integration]
|
||||
- **Via Zigbee2MQTT**: [Configuration]
|
||||
|
||||
## Entities
|
||||
|
||||
### Lighting Entities
|
||||
|
||||
| Entity ID | Name | Source | Control Method |
|
||||
|-----------|------|--------|----------------|
|
||||
| [ID] | [Name] | [Source] | [Method] |
|
||||
|
||||
### Water Boiler Entity
|
||||
|
||||
| Entity ID | Name | Source | Control Method |
|
||||
|-----------|------|--------|----------------|
|
||||
| [ID] | [Name] | [Source] | [Method] |
|
||||
|
||||
### Other Entities
|
||||
|
||||
[Add other entities]
|
||||
|
||||
## Dashboards
|
||||
|
||||
### Main Dashboard
|
||||
|
||||
- **Layout**: [Description or screenshot reference]
|
||||
- **Cards**: [List of cards/widgets]
|
||||
- **Views**: [Different views/pages]
|
||||
|
||||
### Mobile Dashboard
|
||||
|
||||
[If different from main]
|
||||
|
||||
## Automations
|
||||
|
||||
### Automation 1: [Name]
|
||||
|
||||
- **Trigger**: [Description]
|
||||
- **Condition**: [Description]
|
||||
- **Action**: [Description]
|
||||
|
||||
### Automation 2: [Name]
|
||||
|
||||
[Similar structure]
|
||||
|
||||
## Scripts
|
||||
|
||||
[Document any Home Assistant scripts]
|
||||
|
||||
## Scenes
|
||||
|
||||
[Document scenes if used]
|
||||
|
||||
## Custom Components
|
||||
|
||||
- **Custom Components**: [List if any]
|
||||
- **Add-ons**: [List if any]
|
||||
|
||||
## Configuration Files
|
||||
|
||||
- **Configuration Location**: [Path]
|
||||
- **Main Config File**: [Path]
|
||||
- **Automation Files**: [Path]
|
||||
- **Dashboard Files**: [Path]
|
||||
|
||||
## Access Control
|
||||
|
||||
- **Users**: [To be filled]
|
||||
- **API Tokens**: [To be filled - stored securely]
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
- [Issue]: [Solution]
|
||||
|
||||
### Debugging
|
||||
|
||||
- Enable debug logging
|
||||
- Check integration status
|
||||
- Review logs
|
||||
|
||||
---
|
||||
|
||||
**Status**: Template - needs configuration details
|
||||
94
docs/integration/mqtt.md
Normal file
94
docs/integration/mqtt.md
Normal file
@@ -0,0 +1,94 @@
|
||||
# MQTT Broker Configuration
|
||||
|
||||
## Overview
|
||||
|
||||
The MQTT broker runs in a separate LXC container and serves as the central message bus for the automation system.
|
||||
|
||||
## Installation
|
||||
|
||||
- **Software**: [Mosquitto, Eclipse, etc.]
|
||||
- **Version**: [To be filled]
|
||||
- **Host**: [LXC container name/IP]
|
||||
- **Port**: [To be filled, typically 1883/8883]
|
||||
|
||||
## LXC Container
|
||||
|
||||
- **Container Name**: [To be filled]
|
||||
- **OS**: [To be filled]
|
||||
- **Resources**: [CPU, RAM, Disk]
|
||||
- **Network**: [To be filled]
|
||||
|
||||
## Configuration
|
||||
|
||||
### Broker Settings
|
||||
|
||||
- **Port**: [To be filled]
|
||||
- **TLS/SSL**: [Enabled/Disabled]
|
||||
- **WebSocket**: [Enabled/Disabled]
|
||||
- **Persistence**: [Enabled/Disabled]
|
||||
- **Log Level**: [To be filled]
|
||||
|
||||
### Authentication
|
||||
|
||||
- **Authentication Method**: [Username/Password, Certificates, etc.]
|
||||
- **Users**: [List of users if applicable]
|
||||
- **ACLs**: [Access Control Lists]
|
||||
|
||||
## Topic Structure
|
||||
|
||||
### Topic Naming Convention
|
||||
|
||||
[Document the topic naming convention used]
|
||||
|
||||
### Main Topics
|
||||
|
||||
| Topic Pattern | Publisher | Subscriber | Description |
|
||||
|--------------|-----------|------------|-------------|
|
||||
| `zigbee2mqtt/#` | Zigbee2MQTT | Node-RED, Home Assistant | Zigbee device messages |
|
||||
| `codesys/#` | Node-RED | CODESYS | CODESYS control messages |
|
||||
| `homeassistant/#` | Home Assistant | Node-RED | Home Assistant messages |
|
||||
| `nodered/#` | Node-RED | Various | Node-RED messages |
|
||||
|
||||
## QoS Levels
|
||||
|
||||
- **Default QoS**: [To be filled]
|
||||
- **Retained Messages**: [Policy]
|
||||
|
||||
## Clients
|
||||
|
||||
### Connected Clients
|
||||
|
||||
| Client | Type | Topics Subscribed | Topics Published |
|
||||
|--------|------|-------------------|------------------|
|
||||
| Zigbee2MQTT | Bridge | [Topics] | `zigbee2mqtt/#` |
|
||||
| Node-RED | Automation | [Topics] | [Topics] |
|
||||
| Home Assistant | Dashboard | [Topics] | [Topics] |
|
||||
|
||||
## Security
|
||||
|
||||
- **Network Isolation**: [To be filled]
|
||||
- **Firewall Rules**: [To be filled]
|
||||
- **TLS Configuration**: [If applicable]
|
||||
|
||||
## Monitoring
|
||||
|
||||
- **Metrics**: [To be filled]
|
||||
- **Logging**: [To be filled]
|
||||
- **Health Checks**: [To be filled]
|
||||
|
||||
## Backup and Recovery
|
||||
|
||||
- **Configuration Backup**: [Procedure]
|
||||
- **Message Persistence**: [If enabled]
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
- **Connection failures**: [Solution]
|
||||
- **Message delivery issues**: [Solution]
|
||||
- **Performance problems**: [Solution]
|
||||
|
||||
---
|
||||
|
||||
**Status**: Template - needs configuration details
|
||||
95
docs/integration/nodered.md
Normal file
95
docs/integration/nodered.md
Normal file
@@ -0,0 +1,95 @@
|
||||
# Node-RED Configuration
|
||||
|
||||
## Overview
|
||||
|
||||
Node-RED provides flow-based programming for automation logic and acts as a bridge between CODESYS, MQTT, and Home Assistant.
|
||||
|
||||
## Installation
|
||||
|
||||
- **Version**: [To be filled]
|
||||
- **Installation Method**: [To be filled]
|
||||
- **Host**: [To be filled]
|
||||
- **Port**: [To be filled]
|
||||
|
||||
## Main Flows
|
||||
|
||||
### Flow 1: [Name]
|
||||
|
||||
**Purpose**: [Description]
|
||||
|
||||
**Nodes Used**:
|
||||
- [Node type]: [Function]
|
||||
|
||||
**Logic**: [Description]
|
||||
|
||||
### Flow 2: [Name]
|
||||
|
||||
[Similar structure]
|
||||
|
||||
## CODESYS Integration
|
||||
|
||||
### Network Variable Nodes
|
||||
|
||||
- **Connection Method**: [To be filled]
|
||||
- **Variables Mapped**: [To be filled]
|
||||
- **Update Frequency**: [To be filled]
|
||||
|
||||
## MQTT Integration
|
||||
|
||||
### Subscribed Topics
|
||||
|
||||
| Topic | QoS | Function | Description |
|
||||
|-------|-----|----------|-------------|
|
||||
| [Topic] | [QoS] | [Function] | [Description] |
|
||||
|
||||
### Published Topics
|
||||
|
||||
| Topic | QoS | Function | Description |
|
||||
|-------|-----|----------|-------------|
|
||||
| [Topic] | [QoS] | [Function] | [Description] |
|
||||
|
||||
## Home Assistant Integration
|
||||
|
||||
- **Integration Method**: [MQTT, HTTP, API, etc.]
|
||||
- **Entities Created**: [To be filled]
|
||||
- **Automations**: [To be filled]
|
||||
|
||||
## Custom Functions
|
||||
|
||||
### JavaScript Functions
|
||||
|
||||
```javascript
|
||||
// [Function name and description]
|
||||
// [Code if available]
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
- **Error Nodes**: [To be filled]
|
||||
- **Retry Logic**: [To be filled]
|
||||
- **Fallback Behaviors**: [To be filled]
|
||||
|
||||
## Flow Export
|
||||
|
||||
[If available, include flow export or reference to flow file]
|
||||
|
||||
## Dashboard (if used)
|
||||
|
||||
- **Dashboard Nodes**: [To be filled]
|
||||
- **UI Components**: [To be filled]
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
- [Issue]: [Solution]
|
||||
|
||||
### Debugging
|
||||
|
||||
- How to enable debug messages
|
||||
- Flow validation
|
||||
- Message inspection
|
||||
|
||||
---
|
||||
|
||||
**Status**: Template - needs flow details
|
||||
93
docs/integration/zigbee2mqtt.md
Normal file
93
docs/integration/zigbee2mqtt.md
Normal file
@@ -0,0 +1,93 @@
|
||||
# Zigbee2MQTT Configuration
|
||||
|
||||
## Overview
|
||||
|
||||
Zigbee2MQTT bridges Zigbee wireless devices to the MQTT ecosystem, allowing Zigbee switches to communicate with the rest of the automation system.
|
||||
|
||||
## Installation
|
||||
|
||||
- **Version**: [To be filled]
|
||||
- **Host**: [To be filled]
|
||||
- **Installation Method**: [Docker, native, etc.]
|
||||
- **Configuration File**: [Path to be filled]
|
||||
|
||||
## Coordinator
|
||||
|
||||
- **Model**: [To be filled]
|
||||
- **Firmware**: [To be filled]
|
||||
- **Port**: [To be filled]
|
||||
|
||||
## Zigbee Devices
|
||||
|
||||
### Light Switches
|
||||
|
||||
| Device Name | Model | IEEE Address | MQTT Topic | Functions |
|
||||
|------------|-------|--------------|------------|-----------|
|
||||
| [Name] | [Model] | [Address] | [Topic] | [Functions] |
|
||||
|
||||
### Other Devices
|
||||
|
||||
[Add other Zigbee devices if applicable]
|
||||
|
||||
## MQTT Topics
|
||||
|
||||
### Topic Structure
|
||||
|
||||
- **Base Topic**: [To be filled, typically `zigbee2mqtt`]
|
||||
- **Device Topics**: `[base_topic]/[device_name]`
|
||||
- **Bridge Topics**: `[base_topic]/bridge/*`
|
||||
|
||||
### Common Topics
|
||||
|
||||
| Topic | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `zigbee2mqtt/[device]/set` | Publish | Control device |
|
||||
| `zigbee2mqtt/[device]` | Subscribe | Device state |
|
||||
| `zigbee2mqtt/bridge/state` | Subscribe | Bridge status |
|
||||
| `zigbee2mqtt/bridge/log` | Subscribe | Bridge logs |
|
||||
|
||||
## Device Configuration
|
||||
|
||||
### Switch Configuration
|
||||
|
||||
[Configuration details for switches]
|
||||
|
||||
### Pairing Process
|
||||
|
||||
1. [Step 1]
|
||||
2. [Step 2]
|
||||
3. [Step 3]
|
||||
|
||||
## Network Security
|
||||
|
||||
- **Network Key**: [Stored securely - location to be documented]
|
||||
- **PAN ID**: [To be filled]
|
||||
- **Channel**: [To be filled]
|
||||
|
||||
## Integration with Node-RED
|
||||
|
||||
- **How switches trigger flows**: [To be filled]
|
||||
- **Topic mappings**: [To be filled]
|
||||
|
||||
## Integration with Home Assistant
|
||||
|
||||
- **Auto-discovery**: [Enabled/Disabled]
|
||||
- **Manual configuration**: [If applicable]
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
- **Device not responding**: [Solution]
|
||||
- **Pairing failures**: [Solution]
|
||||
- **Network instability**: [Solution]
|
||||
|
||||
### Debugging
|
||||
|
||||
- Enable debug logging
|
||||
- Check MQTT messages
|
||||
- Monitor Zigbee network map
|
||||
|
||||
---
|
||||
|
||||
**Status**: Template - needs device list and configuration
|
||||
Reference in New Issue
Block a user