Skip to main content

Types & Configuration

This section describes Homsai’s cross‑cutting configuration entities: sensor and device types, load signatures, collected data types, and vendors associated with a plant.

Overview​

Homsai exposes several configuration “catalogs” that define how to interpret data and how to model devices and integrations:

These entities are used to:

  • classify sensors and devices correctly;
  • enable business logic and forecasts per category;
  • define which data types (W, kWh, °C, %) are collected;
  • manage integrations with external providers.

Sensor Types​

Sensor Types define the available sensor categories (e.g. power sensor, energy sensor, temperature sensor).

Main endpoints:

  • Create a sensor type

    • POST /sensor-types
    • Requires: SENSOR_TYPES CREATE permission.

  • Update a sensor type

    • PUT /sensor-types/{sensorTypeUuid}
    • Requires: SENSOR_TYPES UPDATE permission.

  • Delete a sensor type

    • DELETE /sensor-types/{sensorTypeUuid}
    • Requires: SENSOR_TYPES DELETE permission.

  • List sensor types

    • GET /sensor-types
    • Supports: pagination and search.
    • Requires: SENSOR_TYPES READ permission.

  • Get sensor type details

    • GET /sensor-types/{sensorTypeUuid}
    • Requires: SENSOR_TYPES READ permission.

Sensor Types are then referenced by individual sensors to define what they measure and how the system should interpret their values.

Device Types​

Device Types define device categories (e.g. INVERTER, BATTERY, HEAT_PUMP, EV_CHARGER).

Main endpoints:

  • Create a device type

    • POST /device-types
    • Requires: DEVICE_TYPES CREATE permission.

  • Update a device type

    • PUT /device-types/{deviceTypeUuid}
    • Requires: DEVICE_TYPES UPDATE permission.

  • Delete a device type

    • DELETE /device-types/{deviceTypeUuid}
    • Requires: DEVICE_TYPES DELETE permission.

  • List device types

    • GET /device-types
    • Supports: pagination and search.
    • Requires: DEVICE_TYPES READ permission.

  • Get device type details

    • GET /device-types/{deviceTypeUuid}
    • Requires: DEVICE_TYPES READ permission.

Assigning the correct type to each device is essential to:

  • drive views and filters;
  • apply category‑specific forecast logic (e.g. consumer‑only devices);
  • aggregate data by device category.

Load Signatures​

Load Signatures represent load profiles, i.e. typical energy consumption patterns for specific loads or devices.

Main endpoints:

  • Create a load signature

    • POST /load-signatures
    • Requires: LOAD_SIGNATURES CREATE permission.

  • Update a load signature

    • PUT /load-signatures/{loadSignatureUuid}
    • Requires: LOAD_SIGNATURES UPDATE permission.

  • Delete a load signature

    • DELETE /load-signatures/{loadSignatureUuid}
    • Requires: LOAD_SIGNATURES DELETE permission.

  • List load signatures

    • GET /load-signatures
    • Supports: pagination, search, includeRelationships.
    • Requires: LOAD_SIGNATURES READ permission.

  • Get load signature details

    • GET /load-signatures/{loadSignatureUuid}
    • Parameters: includeRelationships.
    • Requires: LOAD_SIGNATURES READ permission.

Load Signatures can be used by analytics and forecasting algorithms to identify consumption patterns and estimate loads that are not directly measured.

Data Types Collects​

Data Types Collects define which data types can be collected by sensors (e.g. W, kWh, °C, %, W/m²).

Main endpoint:

  • List data types collects
    • GET /data-types-collects
    • Supports: pagination and search.
    • Requires: DATA_TYPES_COLLECT READ permission.

These entries are associated with sensors to indicate:

  • which measurements they provide (e.g. only power, power + energy, temperature, state of charge);
  • how they should be aggregated and displayed (power charts, energy charts, status indicators, etc.).

Vendors​

Vendors represent vendors/integrations that can be configured for a plant (device brands, external platforms, etc.).

Main endpoint:

  • List vendors for a plant
    • GET /plants/{plantUuid}/vendors
    • Parameters:
      • mode:
        • config → vendors already configured for the plant;
        • not_config → vendors available but not yet configured;
      • search for text filtering;
      • pagination parameters (page, size, sort).
    • Requires: valid JWT (with permissions consistent with plant visibility).

This API is useful to:

  • show which integrations are already active on a plant;
  • guide users through enabling new vendors or services.