High-End Lighting Management (Shelly Gen3/Gen4 & Home Assistant)
Budget: €30 – €250 EUR
I tried to be as precise and clear as possible in my project description to give you a good overveiw and clear understanding of the requirements. You have better ideas or changes ... very welcome. I am open to discuss any enhancement. Looking forward hearing from you and teaming up with you to get this interessting project going and bringing it to "light" :) Best wishes from Hamburg Howard
# Project Brief: High-End Lighting Management (Shelly Gen3/Gen4 & Home Assistant) of a 2 room appartment
## 1. Project Objective
The goal is to set up a zero-latency, professional-grade lighting control system. Focus areas include: tactile operation via **Gira System 55 double momentary switches**,
intelligent and smart group logic (preventing desynchronized/opposing states),
adaptive dimming, and a centralized "Welcome" concept.
**Priority:** Maximum command execution speed (Target: < 100{ms} response time).
---
## 2. Technical Stack & Infrastructure
* **Central Controller:** Raspberry Pi 5 (Smattex) running Home Assistant OS (latest stable).
* **Connectivity:** FRITZ!Box 6860 5G, Nabu Casa Cloud (Remote Access), active Thread Border Router.
* **Hardware (Actors/Sensors):**
* 5 x Shelly i4 Gen3 (installed behind Gira double switches).
* 6 x Shelly Dimmer Gen3.
* 1 x Shelly 1PM Gen4.
* 1 x Shelly Plug S Gen3.
* **Software Status:** Latest firmware/OS versions only (V 1.4.x+ for Shelly).
> **Note on Documentation:
** To ensure a clear overview and mutual understanding, a comprehensive
**Switch Function Matrix** and a detailed
**IP Address List** will be provided as the primary working foundation.
---
## 3. Scope of Work & Technical Requirements
### 3.1 Performance & Latency Optimization (Core Task)
* **Native Shelly Integration:** Integration via gRPC/Websockets.
* **CoIoT/Unicast:** Static IP assignment and CoIoT peer configuration pointing to the HA-IP (Port 5683).
* **Shelly Scripting (mJS):** For critical switching operations (direct dimming/toggling), the freelancer must implement **Local RPC Calls** via scripting to minimize the detour through the HA-Core for standard switch actions.
### 3.2 Switch Logic & Group Control
* **Prevention of Opposing States:** For group toggles, the current state of all group members must be polled.
* *Logic:* If $>0\%$ of lamps are ON -> Turn All OFF. Otherwise -> Turn All ON.
* **Welcome-Master (Entrance):**
* **Left Toggle:** Short = Welcome Main Group (Living, Kitchen) Toggle | Double = All Main Lights OFF | Long = 80% Brightness.
* **Right Toggle:** Short = Global Toggle (All Lights) | Double = Global OFF | Long = Global 100%.
### 3.3 Adaptive Lighting (Time & Sun-Position Logic)
Upon switching ON (OFF -> ON transition), the following automatic start-brightness levels apply (manual overrides are not to be overwritten during the session):
* **Day (1h post-sunrise to 2h post-sunset): 90%
* **Evening (until +4h post-sunset): 60%
* **Late Night (until 00:00): 40%
* **Night Mode (00:00 to 1h post-sunrise): 20%.
### 3.4 Custom Logic (Frost Protection)
* **Shelly Plug S Gen3:
** Switches ON if outside temperature is < 5 celsius in 21465 Reinbek (Germany) during the time windows 01:00–02:00 and 04:00–05:00 after midnight.
---
## 4. Checklists & Project Progress
### A. Preparation Checklist (Employer)
*To be completed before remote work begins.*
* [ ] **Hardware:** All Shellys installed, wired, and powered.
* [ ] **Network:** Static IPs reserved in FRITZ!Box; all devices connected to WiFi.
* [ ] **Remote Access:** Nabu Casa account active; Admin user created for freelancer.
* [ ] **Docs:** Switch Function Matrix and IP List provided.
### B. Implementation Checklist (Freelancer)
*Implementation steps for the contractor.*
* [ ] **Integration:** All Shelly entities clearly named in HA (`light_room_lamp`).
* [ ] **Scripting:** Local RPC scripts installed on i4 modules for zero-latency dimming.
* [ ] **Logic:** Group scenes and toggle-protection implemented.
* [ ] **Automation:** Time-based brightness helpers and frost protection logic created.
* [ ] **Dashboard:** Creation of a Tablet Dashboard (Mushroom Cards) & Mobile View.
### C. Acceptance Checklist (Joint)
*Final testing via video call.*
* [ ] **Latency Check:** Does the light react "instantly" to the switch press?
* [ ] **Sync Check:** Do groups switch cleanly without "stuttering" or mixed states?
* [ ] **Dimming:** Is the transition smooth, soft and in an typically excepted speed (no jumping)?
* [ ] **Remote Test:** Does control via HA app work reliably over 5G/LTE?
---
## 5. UI/UX & Multi-User
* **Android Tablet:** Kiosk-mode dashboard with large tiles for scenes.
* **User Levels:** 1 Admin account, up to 3 resident accounts with restricted rights (Dashboard access only).
* **Sharing:** Scenes managed centrally in HA and synced across all devices (Tablets/Phones).
---
## 6. Documentation & Handover
The freelancer will provide upon completion:
1. **Entity List:** Overview of all names and groups.
2. **Quick Guide:** Instructions on how the resident can adjust time windows/brightness (Helper menu). Can be AI generated plus checked and enhanced by freelancer.
3. **Code Backup:** A copy of all utilized Shelly scripts and HA automations / configurations
7. This is a small project. If this project is done well I would like to follow up to start the next one to automatise other appartments as well with similar Shelly + HA set ups. Thank you ... best wishes :)
Required Skill Set (Must-Haves)
Advanced Shelly mJS Scripting: Profound experience in developing custom scripts directly on Shelly Gen3/Gen4 hardware. Expertise in implementing Local RPC (Remote Procedure Calls) via mJS to ensure ultra-low latency, moving beyond simple standard webhooks.
Home Assistant Expert Architecture: Master-level proficiency in YAML configuration and Jinja2 templating. Ability to design complex state machines using Helper entities (input_boolean, input_select, input_number) for dynamic user-defined settings.
Network Optimization & Industrial Protocols: Deep understanding of IoT-specific network topologies. Proficiency in configuring CoIoT via Unicast, gRPC/Websockets for Shelly Gen3, and managing deterministic Static IP structures to eliminate broadcast storms and minimize response times.
Professional Software Engineering Standards: A highly structured approach to development, including clean entity naming conventions and providing well-documented, commented code for long-term maintainability and easy handovers.
Key Technical Questions :
How do you implement a state-aware group toggle to prevent desynchronized light states across multiple dimmers?
What is your strategy for handling long-push dimming events via mJS to achieve a smooth, flicker-free transition with <100ms latency?
# Project Brief: High-End Lighting Management (Shelly Gen3/Gen4 & Home Assistant) of a 2 room appartment
## 1. Project Objective
The goal is to set up a zero-latency, professional-grade lighting control system. Focus areas include: tactile operation via **Gira System 55 double momentary switches**,
intelligent and smart group logic (preventing desynchronized/opposing states),
adaptive dimming, and a centralized "Welcome" concept.
**Priority:** Maximum command execution speed (Target: < 100{ms} response time).
---
## 2. Technical Stack & Infrastructure
* **Central Controller:** Raspberry Pi 5 (Smattex) running Home Assistant OS (latest stable).
* **Connectivity:** FRITZ!Box 6860 5G, Nabu Casa Cloud (Remote Access), active Thread Border Router.
* **Hardware (Actors/Sensors):**
* 5 x Shelly i4 Gen3 (installed behind Gira double switches).
* 6 x Shelly Dimmer Gen3.
* 1 x Shelly 1PM Gen4.
* 1 x Shelly Plug S Gen3.
* **Software Status:** Latest firmware/OS versions only (V 1.4.x+ for Shelly).
> **Note on Documentation:
** To ensure a clear overview and mutual understanding, a comprehensive
**Switch Function Matrix** and a detailed
**IP Address List** will be provided as the primary working foundation.
---
## 3. Scope of Work & Technical Requirements
### 3.1 Performance & Latency Optimization (Core Task)
* **Native Shelly Integration:** Integration via gRPC/Websockets.
* **CoIoT/Unicast:** Static IP assignment and CoIoT peer configuration pointing to the HA-IP (Port 5683).
* **Shelly Scripting (mJS):** For critical switching operations (direct dimming/toggling), the freelancer must implement **Local RPC Calls** via scripting to minimize the detour through the HA-Core for standard switch actions.
### 3.2 Switch Logic & Group Control
* **Prevention of Opposing States:** For group toggles, the current state of all group members must be polled.
* *Logic:* If $>0\%$ of lamps are ON -> Turn All OFF. Otherwise -> Turn All ON.
* **Welcome-Master (Entrance):**
* **Left Toggle:** Short = Welcome Main Group (Living, Kitchen) Toggle | Double = All Main Lights OFF | Long = 80% Brightness.
* **Right Toggle:** Short = Global Toggle (All Lights) | Double = Global OFF | Long = Global 100%.
### 3.3 Adaptive Lighting (Time & Sun-Position Logic)
Upon switching ON (OFF -> ON transition), the following automatic start-brightness levels apply (manual overrides are not to be overwritten during the session):
* **Day (1h post-sunrise to 2h post-sunset): 90%
* **Evening (until +4h post-sunset): 60%
* **Late Night (until 00:00): 40%
* **Night Mode (00:00 to 1h post-sunrise): 20%.
### 3.4 Custom Logic (Frost Protection)
* **Shelly Plug S Gen3:
** Switches ON if outside temperature is < 5 celsius in 21465 Reinbek (Germany) during the time windows 01:00–02:00 and 04:00–05:00 after midnight.
---
## 4. Checklists & Project Progress
### A. Preparation Checklist (Employer)
*To be completed before remote work begins.*
* [ ] **Hardware:** All Shellys installed, wired, and powered.
* [ ] **Network:** Static IPs reserved in FRITZ!Box; all devices connected to WiFi.
* [ ] **Remote Access:** Nabu Casa account active; Admin user created for freelancer.
* [ ] **Docs:** Switch Function Matrix and IP List provided.
### B. Implementation Checklist (Freelancer)
*Implementation steps for the contractor.*
* [ ] **Integration:** All Shelly entities clearly named in HA (`light_room_lamp`).
* [ ] **Scripting:** Local RPC scripts installed on i4 modules for zero-latency dimming.
* [ ] **Logic:** Group scenes and toggle-protection implemented.
* [ ] **Automation:** Time-based brightness helpers and frost protection logic created.
* [ ] **Dashboard:** Creation of a Tablet Dashboard (Mushroom Cards) & Mobile View.
### C. Acceptance Checklist (Joint)
*Final testing via video call.*
* [ ] **Latency Check:** Does the light react "instantly" to the switch press?
* [ ] **Sync Check:** Do groups switch cleanly without "stuttering" or mixed states?
* [ ] **Dimming:** Is the transition smooth, soft and in an typically excepted speed (no jumping)?
* [ ] **Remote Test:** Does control via HA app work reliably over 5G/LTE?
---
## 5. UI/UX & Multi-User
* **Android Tablet:** Kiosk-mode dashboard with large tiles for scenes.
* **User Levels:** 1 Admin account, up to 3 resident accounts with restricted rights (Dashboard access only).
* **Sharing:** Scenes managed centrally in HA and synced across all devices (Tablets/Phones).
---
## 6. Documentation & Handover
The freelancer will provide upon completion:
1. **Entity List:** Overview of all names and groups.
2. **Quick Guide:** Instructions on how the resident can adjust time windows/brightness (Helper menu). Can be AI generated plus checked and enhanced by freelancer.
3. **Code Backup:** A copy of all utilized Shelly scripts and HA automations / configurations
7. This is a small project. If this project is done well I would like to follow up to start the next one to automatise other appartments as well with similar Shelly + HA set ups. Thank you ... best wishes :)
Required Skill Set (Must-Haves)
Advanced Shelly mJS Scripting: Profound experience in developing custom scripts directly on Shelly Gen3/Gen4 hardware. Expertise in implementing Local RPC (Remote Procedure Calls) via mJS to ensure ultra-low latency, moving beyond simple standard webhooks.
Home Assistant Expert Architecture: Master-level proficiency in YAML configuration and Jinja2 templating. Ability to design complex state machines using Helper entities (input_boolean, input_select, input_number) for dynamic user-defined settings.
Network Optimization & Industrial Protocols: Deep understanding of IoT-specific network topologies. Proficiency in configuring CoIoT via Unicast, gRPC/Websockets for Shelly Gen3, and managing deterministic Static IP structures to eliminate broadcast storms and minimize response times.
Professional Software Engineering Standards: A highly structured approach to development, including clean entity naming conventions and providing well-documented, commented code for long-term maintainability and easy handovers.
Key Technical Questions :
How do you implement a state-aware group toggle to prevent desynchronized light states across multiple dimmers?
What is your strategy for handling long-push dimming events via mJS to achieve a smooth, flicker-free transition with <100ms latency?