🔌 Device Inventory & Naming Convention

::: info Questa pagina definisce la metodologia per l’organizzazione dei dispositivi all’interno di Home Assistant. L’obiettivo è garantire che ogni entità sia facilmente identificabile sia dall’interfaccia grafica che tramite codice (YAML/Python). :::

1. Naming Convention Standard

Adottiamo una struttura semantica per gli entity_id. Questo permette di filtrare i dispositivi istantaneamente negli editor di automazioni.

Regola per l’Entity ID:

[Area]_[Tipo_Dispositivo]_[Descrizione]

Esempio: kitchen_light_table
Esempio: bedroom_sensor_temperature
Esempio: living_room_plug_tv

Perché questo standard?

Ordinamento: Le entità della stessa stanza appaiono vicine negli elenchi a cascata.
Searchability: Cercando “sensor” troverai tutti i sensori della casa indipendentemente dalla stanza.
Codifica: Facilita l’uso di “Templates” in Jinja2 (es. selezionare tutte le luci in un’area specifica tramite codice).

2. Entity ID vs Friendly Name

È fondamentale distinguere tra l’ID tecnico e il nome visualizzato.

Entity ID (Technical): Deve essere in inglese, tutto minuscolo, senza spazi (usare underscore). È l’ID permanente usato negli script.
Friendly Name (Display): È il nome leggibile che appare sulla Dashboard (può essere in italiano, es. “Luce Tavolo Cucina”). Può essere cambiato senza rompere le automazioni.

3. Organizzazione in Aree e Etichette

Home Assistant permette di raggruppare i dispositivi in Aree (stanze fisiche) e Etichette (metadati logici).

Aree: Cucina, Soggiorno, Camera, Studio, Esterno.
Etichette (Labels): Usate per categorie trasversali. Esempi: Battery Powered, Critical Infrastructure, Security.

📉 Gerarchia Organizzativa (Mermaid)

graph TD
    HOME[Home Assistant Instance] --> AREAS[Areas: Physical Rooms]
    AREAS --> DEVICES[Devices: Physical Hardware]
    DEVICES --> ENTITIES[Entities: Sensors/Switches]
    
    ENTITIES -.-> LABELS[Labels: Logical Tags]
    
    style ENTITIES fill:#f9f,stroke:#333,stroke-width:2px

📋 Device Inventory Table (Template)

Utilizza questa tabella per censire i nuovi dispositivi man mano che vengono aggiunti alla rete Zigbee o Wi-Fi.

Device Model	Area	Entity ID	Protocol	Note
Sonoff ZB-Curtain	Soggiorno	`living_room_cover_main`	Zigbee	Alimentazione USB
Shelly 1PM	Cucina	`kitchen_plug_fridge`	Wi-Fi	Monitoraggio consumi
Aqara TH Sensor	Camera	`bedroom_sensor_temp`	Zigbee	Batteria CR2032

🛠️ Best Practices per il mantenimento

Ridenominazione Immediata: Quando aggiungi un nuovo dispositivo, non lasciarlo con il nome di default (es. sensor.lumi_lumi_weather). Rinominalo immediatamente seguendo lo standard.
Icone Coerenti: Assegna icone standard (MDI - Material Design Icons) per rendere la Dashboard intuitiva.
Batterie: Per ogni dispositivo a batteria, assicurati che l’entità battery_level sia correttamente associata all’area di competenza.

Ultimo aggiornamento: {{UPDATE_DATE}} | Tags: #Inventory #NamingConvention #BestPractices #HomeAutomation