Passa al contenuto principale

Types & Configuration

Questa sezione descrive le entità di configurazione trasversali in Homsai: tipi di sensori e dispositivi, firme di carico, tipi di dato raccolti e vendor associati a un plant.

Overview​

Le API Homsai espongono diversi “cataloghi” di configurazione che definiscono come interpretare i dati e come modellare dispositivi e integrazioni:

Queste entità sono usate:

  • per classificare correttamente sensori e dispositivi;
  • per abilitare logiche di business e previsioni specifiche per categoria;
  • per definire quali tipi di dato (W, kWh, °C, %) vengono raccolti;
  • per gestire le integrazioni con fornitori esterni.

Sensor Types​

I Sensor Types definiscono le categorie di sensori disponibili (es. sensore di potenza, sensore di energia, sensore di temperatura).

Endpoint principali:

  • Creare un tipo sensore

    • POST /sensor-types
    • Richiede: permesso SENSOR_TYPES CREATE.

  • Aggiornare un tipo sensore

    • PUT /sensor-types/{sensorTypeUuid}
    • Richiede: permesso SENSOR_TYPES UPDATE.

  • Eliminare un tipo sensore

    • DELETE /sensor-types/{sensorTypeUuid}
    • Richiede: permesso SENSOR_TYPES DELETE.

  • Elencare i tipi sensore

    • GET /sensor-types
    • Supporta: paginazione e search.
    • Richiede: permesso SENSOR_TYPES READ.

  • Dettaglio tipo sensore

    • GET /sensor-types/{sensorTypeUuid}
    • Richiede: permesso SENSOR_TYPES READ.

I Sensor Types vengono poi referenziati dai singoli sensori per definire che tipo di grandezza misurano e come devono essere interpretati dal sistema.

Device Types​

I Device Types definiscono le categorie di dispositivi (es. INVERTER, BATTERY, HEAT_PUMP, EV_CHARGER).

Endpoint principali:

  • Creare un tipo device

    • POST /device-types
    • Richiede: permesso DEVICE_TYPES CREATE.

  • Aggiornare un tipo device

    • PUT /device-types/{deviceTypeUuid}
    • Richiede: permesso DEVICE_TYPES UPDATE.

  • Eliminare un tipo device

    • DELETE /device-types/{deviceTypeUuid}
    • Richiede: permesso DEVICE_TYPES DELETE.

  • Elencare i tipi device

    • GET /device-types
    • Supporta: paginazione e search.
    • Richiede: permesso DEVICE_TYPES READ.

  • Dettaglio tipo device

    • GET /device-types/{deviceTypeUuid}
    • Richiede: permesso DEVICE_TYPES READ.

Attribuire il tipo corretto a ogni device è fondamentale per:

  • gestire viste e filtri;
  • applicare logiche di previsione specifiche (es. soli dispositivi consumatori);
  • aggregare i dati per categoria.

Load Signatures​

Le Load Signatures rappresentano firme di carico, ovvero profili tipici di consumo/uso dell’energia per determinati carichi o dispositivi.

Endpoint principali:

  • Creare una firma di carico

    • POST /load-signatures
    • Richiede: permesso LOAD_SIGNATURES CREATE.

  • Aggiornare una firma di carico

    • PUT /load-signatures/{loadSignatureUuid}
    • Richiede: permesso LOAD_SIGNATURES UPDATE.

  • Eliminare una firma di carico

    • DELETE /load-signatures/{loadSignatureUuid}
    • Richiede: permesso LOAD_SIGNATURES DELETE.

  • Elencare le firme di carico

    • GET /load-signatures
    • Supporta: paginazione, search, includeRelationships.
    • Richiede: permesso LOAD_SIGNATURES READ.

  • Dettaglio firma di carico

    • GET /load-signatures/{loadSignatureUuid}
    • Parametri: includeRelationships.
    • Richiede: permesso LOAD_SIGNATURES READ.

Le Load Signatures possono essere utilizzate da algoritmi di previsione e analisi per identificare pattern di consumo e stimare carichi non misurati direttamente.

Data Types Collects​

I Data Types Collects definiscono quali tipi di dato possono essere raccolti dai sensori (es. W, kWh, °C, %, W/m²).

Endpoint principale:

  • Elencare i tipi di raccolta dati
    • GET /data-types-collects
    • Supporta: paginazione e search.
    • Richiede: permesso DATA_TYPES_COLLECT READ.

Queste entità vengono associate ai sensori per indicare:

  • quali misure forniscono (es. solo potenza, potenza + energia, temperatura, stato di carica);
  • come devono essere aggregati e mostrati (grafici di potenza, grafici di energia, indicatori di stato, ecc.).

Vendors​

I Vendors rappresentano vendor/integrazioni configurabili per un plant (brand di dispositivi, piattaforme esterne, ecc.).

Endpoint principale:

  • Elencare i vendor di un plant
    • GET /plants/{plantUuid}/vendors
    • Parametri:
      • mode:
        • config → vendor già configurati per il plant;
        • not_config → vendor disponibili ma non ancora configurati;
      • search per filtro testuale;
      • parametri di paginazione (page, size, sort).
    • Richiede: JWT valido (permessi coerenti con la visibilità sul plant).

Questa API è utile per:

  • mostrare all’utente quali integrazioni sono già attive sul suo impianto;
  • guidare l’attivazione di nuovi vendor o servizi.