Skip to content

Commit c2394d8

Browse files
webosawebosa
committed
site structure
1 parent fae7aa9 commit c2394d8

3 files changed

Lines changed: 135 additions & 217 deletions

File tree

‎docs/smart-home/packages/office._pc.md‎

Lines changed: 0 additions & 140 deletions
This file was deleted.

‎docs/smart-home/packages/office_pc.md‎

Lines changed: 118 additions & 69 deletions
Original file line numberDiff line numberDiff line change
@@ -1,39 +1,86 @@
1-
# Package: Office PC
1+
---
2+
tags:
3+
- package
4+
- automated
5+
version: 1.0.0
6+
---
7+
8+
# Package: Office. Pc
9+
10+
**Version:** 1.0.0
11+
**Description:** Office PC control (Audio, Displays, Power)
12+
13+
<!-- START_IMAGE -->
14+
![Package Diagram](../../../assets/images/packages/office._pc.png)
15+
<!-- END_IMAGE -->
216

317
## Executive Summary
4-
This package controls the Office PC's peripheral state using `Wake-on-LAN` for power and a set of **Template Switches** that wrap button entities (likely from an agent like *IOTLink* or similar running on the PC). It allows toggling Audio Output (Speakers vs. Headphones), Muting, and Monitor Power via the Home Assistant dashboard.
18+
<!-- START_SUMMARY -->
19+
This package provides a control interface for the Office PC, enabling "Smart Wake" capabilities and peripheral management. It uses Wake-on-LAN to power on the machine and a set of helper switches to control audio output (Headphones vs. Speakers), mute status, and monitor power. These switches trigger button presses on the local PC via an agent (IoT Link).
20+
<!-- END_SUMMARY -->
21+
22+
## Process Description (Non-Technical)
23+
<!-- START_DETAILED -->
24+
1. **Power On**: usage of the 'Power' switch sends a magic packet (WoL) to turn on the PC.
25+
2. **Audio Control**: Toggling the "Audio Device" switch sends a command to the PC to swap the default playback device between Speakers and Headphones.
26+
3. **Monitors**: The "Displays" switch allows you to remotely wake up or put the monitors to sleep without touching the mouse/keyboard.
27+
<!-- END_DETAILED -->
28+
29+
## Integration Dependencies
30+
<!-- START_DEPENDENCIES -->
31+
* **IoT Link**: A Windows agent running on the PC to execute commands (button presses).
32+
* **Wake-on-LAN**: Standard network integration to boot the PC.
33+
<!-- END_DEPENDENCIES -->
534

6-
## Architecture
35+
## Dashboard Connections
36+
<!-- START_DASHBOARD -->
37+
This package powers the following dashboard views:
38+
39+
* **[Office](../dashboards/main/office.md)** (Uses 3 entities)
40+
<!-- END_DASHBOARD -->
41+
42+
## Architecture Diagram
43+
<!-- START_MERMAID_DESC -->
44+
The architecture bridges Home Assistant with the Windows OS. Commands initiated in the Dashboard (e.g., "Toggle Audio") flip a Template Switch in HA. This switch calls a `button.press` service, which talks to the MQTT-connected IoT Link agent installed on the PC. The agent then executes the local script/command to change the audio device or monitor state. State feedback travels back via MQTT sensors to update the Dashboard icon.
45+
<!-- END_MERMAID_DESC -->
46+
47+
<!-- START_MERMAID -->
748
```mermaid
849
sequenceDiagram
9-
participant UI as Dashboard Switch
10-
participant Template as HA Switch
11-
participant Button as IOTLink Button
12-
participant PC as Windows PC
13-
14-
UI->>Template: Toggle Audio
15-
Template->>Button: Press button.officepc_speakers
16-
Button->>PC: Exceute Script
17-
PC-->>Template: Update Sensor State
50+
participant User as Dashboard
51+
participant HA as Home Assistant
52+
participant MQTT as MQTT Broker
53+
participant Agent as IoT Link (PC)
54+
participant OS as Windows OS
55+
56+
User->>HA: Turn "Audio Device" ON
57+
HA->>MQTT: Publish command (button.press)
58+
MQTT->>Agent: Receive Command
59+
Agent->>OS: Execute "Set Audio to Speakers"
60+
OS-->>Agent: Confirm Change
61+
Agent-->>MQTT: Update Sensor State
62+
MQTT-->>HA: Update Switch State
1863
```
64+
<!-- END_MERMAID -->
1965

20-
## Backend Configuration
21-
*(Snippet)*
66+
## Configuration (Source Code)
2267
```yaml
23-
switch:
24-
- platform: wake_on_lan
25-
name: "Office PC Power"
26-
mac: 24:4B:FE:B7:52:DD
27-
host: 10.0.0.140
28-
turn_off:
29-
service: button.press
30-
target:
31-
entity_id: button.officepc_sleep
32-
68+
# ------------------------------------------------------------------------------
69+
# Package: Office PC
70+
# Version: 1.0.0
71+
# Description: Office PC control (Audio, Displays, Power)
72+
# Dependencies: IoT Link (switch.officepc_*, button.officepc_*)
73+
# ------------------------------------------------------------------------------
3374
template:
3475
- switch:
3576
- name: "Office PC Audio Device"
3677
unique_id: officepc_audio_device
78+
icon: >
79+
{% if is_state('switch.officepc_audio_device', 'on') %}
80+
mdi:speaker
81+
{% else %}
82+
mdi:headphones
83+
{% endif %}
3784
state: "{{ is_state('sensor.officepc_audio_default_device', 'Speakers (Realtek High Definition Audio)') }}"
3885
turn_on:
3986
service: button.press
@@ -43,49 +90,51 @@ template:
4390
service: button.press
4491
target:
4592
entity_id: button.officepc_headphones
46-
```
4793

48-
## Frontend Connection
49-
**Key Entities**:
50-
- `switch.office_pc_power`
51-
- `switch.officepc_audio_device`
52-
- `switch.officepc_audio_mute`
53-
- `switch.officepc_displays`
54-
55-
**Dashboard Usage**:
56-
These switches are arranged in a grid in `dashboard_dev` (lines 1514+), allowing for a quick control panel for the workstation.
57-
58-
### UI Simulation
59-
<div style="border: 1px solid #444; border-radius: 12px; padding: 16px; width: 300px; background: #222; color: white; font-family: sans-serif;">
60-
<h3>🖥️ Office Station</h3>
61-
<div style="display: grid; grid-template-columns: 1fr 1fr; gap: 12px;">
62-
63-
<!-- Power -->
64-
<div style="background: #333; padding: 12px; border-radius: 8px; text-align: center;">
65-
<div style="font-size: 24px; margin-bottom: 4px; color: #4caf50;">⚡</div>
66-
<div style="font-weight: bold;">Power</div>
67-
<div style="font-size: 0.8em; color: #aaa;">On</div>
68-
</div>
69-
70-
<!-- Audio Output -->
71-
<div style="background: #333; padding: 12px; border-radius: 8px; text-align: center;">
72-
<div style="font-size: 24px; margin-bottom: 4px;">🎧</div>
73-
<div style="font-weight: bold;">Audio</div>
74-
<div style="font-size: 0.8em; color: #aaa;">Headphones</div>
75-
</div>
76-
77-
<!-- Monitors -->
78-
<div style="background: #333; padding: 12px; border-radius: 8px; text-align: center;">
79-
<div style="font-size: 24px; margin-bottom: 4px; color: #4caf50;">🖥️</div>
80-
<div style="font-weight: bold;">Displays</div>
81-
<div style="font-size: 0.8em; color: #aaa;">Awake</div>
82-
</div>
83-
84-
<!-- Mute -->
85-
<div style="background: #333; padding: 12px; border-radius: 8px; text-align: center;">
86-
<div style="font-size: 24px; margin-bottom: 4px; color: #aaa;">🔊</div>
87-
<div style="font-weight: bold;">Mute</div>
88-
<div style="font-size: 0.8em; color: #aaa;">Off</div>
89-
</div>
90-
</div>
91-
</div>
94+
- name: "Office PC Audio Mute"
95+
unique_id: officepc_audio_mute
96+
icon: >
97+
{% if is_state('sensor.officepc_audio_default_device_muted', 'True') %}
98+
mdi:volume-mute
99+
{% else %}
100+
mdi:volume-high
101+
{% endif %}
102+
state: "{{ is_state('sensor.officepc_audio_default_device_muted', 'True') }}"
103+
turn_on:
104+
service: button.press
105+
target:
106+
entity_id: button.officepc_mute
107+
turn_off:
108+
service: button.press
109+
target:
110+
entity_id: button.officepc_mute
111+
112+
- name: "Office PC Displays"
113+
unique_id: officepc_displays
114+
icon: >
115+
{% if is_state('sensor.officepc_monitorpowerstate', 'PowerOn') %}
116+
mdi:monitor
117+
{% else %}
118+
mdi:monitor-off
119+
{% endif %}
120+
state: "{{ is_state('sensor.officepc_monitorpowerstate', 'PowerOn') }}"
121+
turn_on:
122+
service: button.press
123+
target:
124+
entity_id: button.officepc_monitorwake
125+
turn_off:
126+
service: button.press
127+
target:
128+
entity_id: button.officepc_monitorsleep
129+
130+
switch:
131+
- platform: wake_on_lan
132+
name: "Office PC Power"
133+
mac: 24:4B:FE:B7:52:DD
134+
host: 10.0.0.140
135+
turn_off:
136+
service: button.press
137+
target:
138+
entity_id: button.officepc_sleep
139+
140+
```

‎docs/system_manual/tools.md‎

Lines changed: 17 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,7 @@ git pull
4444
```
4545
3. **Regenerate Docs (The V2 Shim):**
4646
```
47-
cd /; python ag_v2_update.py
47+
cd /; python .ag_scripts/orchestrator/update_all.py
4848
```
4949
4. **Publish Docs (Public Repo B):**
5050
```
@@ -77,7 +77,7 @@ cd docs_site; git add .; git commit -m "Routine update"; git push
7777
7878
**Task: Update Package Boilerplate (Automation)**
7979
*Use this prompt first to ensure the documentation structure is correct and versioned.*
80-
> "Run `cd /; python ag_v2_package.py [package_name]`."
80+
> "Run `python .ag_scripts/package_manager/main.py [package_name]`."
8181
8282
**Task: Deep Package Analysis (Intelligence Injection)**
8383
*Use this prompt AFTER running the Python script to fill the intelligent content slots.*
@@ -129,14 +129,23 @@ cd docs_site; git add .; git commit -m "Routine update"; git push
129129
130130
## 3. Tool Reference
131131
132-
### `ag_v2_update.py`
133-
The Master Orchestrator. Calls the other tools to update packages and dashboards in one go.
132+
### `.ag_scripts/orchestrator/update_all.py`
133+
The Master Orchestrator. Coordinates the update of all documentation components (Packages, Dashboards, Structure, Indices).
134+
* **Command:** `python .ag_scripts/orchestrator/update_all.py [optional_package_name]`
134135
135-
### `ag_v2_dashboard.py`
136-
The Privacy Engine. Reads `.storage/lovelace_dashboards`, performs regex-based name redaction (Jukka->Evis), and outputs clean YAML blocks. Logic lives in `.ag_scripts/dashboard_manager`.
136+
### `.ag_scripts/dashboard_manager/main.py`
137+
The Dashboard Engine. Reads `.storage/lovelace_dashboards`, performs name redaction (Jukka->Evis), and generates dashboard documentation.
138+
* **Command:** `python .ag_scripts/dashboard_manager/main.py [optional_dashboard_slug]`
137139
138-
### `ag_v2_package.py`
139-
The Package Doc Generator. Reads a specific package YAML, extracts header metadata (Version/Desc), and updates the specific Markdown file. Logic lives in `.ag_scripts/package_manager`.
140+
### `.ag_scripts/package_manager/main.py`
141+
The Package Engine. Reads specific package YAML files, extracts metadata, and ensures the markdown skeleton exists.
142+
* **Command:** `python .ag_scripts/package_manager/main.py [package_name]`
143+
144+
### Structure & Index Generators
145+
New tools to keep the site structure automated.
146+
* **Structure:** `.ag_scripts/structure_manager/generate_structure.py` (Maintains `structure.md`)
147+
* **Automations:** `.ag_scripts/structure_manager/generate_automations_doc.py` (Maintains `automations.md` for UI logic)
148+
* **Package Index:** `.ag_scripts/package_manager/generate_index.py` (Maintains `packages/index.md`)
140149
141150
---
142151

0 commit comments

Comments
 (0)