Skip to main content

Domain Model & Data

This section introduces the Homsai domain model and the main entities you will work with: plants, devices, sensors, and related metadata.

Overview​

In the Homsai model, an energy system is described by a set of related entities:

In short:

  • A Plant represents the whole installation (house, building, industrial site).
  • A Device is a physical or logical component attached to the plant (inverter, battery, heat pump, EV charger, etc.).
  • A Sensor is a data source that measures values over time (power, energy, temperature, %, etc.).
  • Types define the technical categories of devices and sensors, and the data types they collect.
  • Load Signatures model typical load profiles used for analysis and forecasting.
  • Vendors represent external providers and integrations associated with a plant.

Plants​

A Plant is the root entity representing a logical energy installation, for example:

  • a single family house;
  • a multi‑unit building;
  • a commercial or industrial site.

All devices and sensors belong to a plant.
The plant is the main entry point for:

  • overall system configuration;
  • access to consumption/production data;
  • forecast calculations and plant health indicators.

Devices​

A Device is a physical or logical component attached to a plant, such as:

  • PV inverters;
  • battery systems;
  • heat pumps;
  • EV chargers / charging points;
  • significant loads (HVAC units, pumps, motors, etc.).

Key characteristics:

  • each device belongs to exactly one Plant;
  • it is classified via a Device Type;
  • it can have one or more Sensors attached to measure its state and performance.

Devices are used to model the physical architecture of the plant and to group the data coming from sensors.

Sensors​

A Sensor is a time‑series data source that measures one or more values, for example:

  • instantaneous power (W);
  • energy (kWh) consumed or produced;
  • temperature (°C), state of charge (%), irradiance (W/m²);
  • other electrical or environmental quantities.

Key characteristics:

  • each sensor belongs to a Plant;
  • it may be linked to a specific Device, or directly to the plant as a whole;
  • it is classified by a Sensor Type;
  • it collects one or more Data Types Collects (data types such as W, kWh, °C, %).

Historical series and energy metrics (consumption, production, energy mix) are computed from sensor data.

Types​

Types define the semantics and categories of the main entities:

  • Device Types
    Describe the functional category of a device (e.g. INVERTER, BATTERY, HEAT_PUMP, EV_CHARGER).
    They are used to:

    • classify devices;
    • apply business logic per category (e.g. forecasts for consumer‑only devices);
    • filter and aggregate data by device type.

  • Sensor Types
    Describe the nature of a sensor (e.g. POWER_SENSOR, ENERGY_SENSOR, TEMPERATURE_SENSOR, IRRADIANCE_SENSOR).
    They are used to:

    • define what kind of quantity the sensor measures;
    • guide interpretation, units, and aggregation logic.

  • Data Types Collects
    List the measurable data types (e.g. active energy kWh, active power W, temperature °C, state of charge %, solar irradiance W/m²).
    Correctly mapping data types to sensors is essential to get consistent metrics and accurate forecasts.

Load Signatures​

Load Signatures model typical consumption patterns of a specific load or category of loads.

Example use cases:

  • describing the daily profile of a heat pump;
  • supporting load forecast algorithms;
  • estimating the consumption of a load even when it is not directly metered.

In practice, a load signature is a configuration object that represents how a given device or load “uses” energy over time.

Vendors​

Vendors represent manufacturers, brands, or external integrations associated with a plant, for example:

  • inverter or battery manufacturers;
  • third‑party cloud platforms;
  • IoT systems or energy management platforms integrated with Homsai.

For each plant you can:

  • list vendors already configured;
  • see which vendors are available but not yet enabled;
  • guide the user through activating new integrations.

Example: PV + Battery​

Here is a conceptual example for a residential PV system with battery.

  • Plant

    • “Rossi Home – PV + Battery System”

  • Devices

    • Device 1: PV inverter (Device Type: INVERTER)
    • Device 2: Battery system (Device Type: BATTERY)

  • Sensors

    • Sensor A: PV output power from inverter
      • Sensor Type: POWER_SENSOR
      • Data Type: W
    • Sensor B: daily energy produced
      • Sensor Type: ENERGY_SENSOR
      • Data Type: kWh
    • Sensor C: battery charge/discharge power
      • Sensor Type: POWER_SENSOR
    • Sensor D: battery state of charge
      • Sensor Type: specific (e.g. STATE_OF_CHARGE_SENSOR)
      • Data Type: %
    • Sensor E: total house consumption downstream of the main meter
      • Sensor Type: combination of POWER_SENSOR and ENERGY_SENSOR

  • Types & Load Signatures

    • Device Types for inverter and battery.
    • Sensor Types consistent with the measured quantities.
    • Optional Load Signature for a relevant load (e.g. heat pump) used for analysis and forecasts.

Based on this model, the backend can:

  • provide daily and hourly consumption/production metrics;
  • compute consumption and production forecasts;
  • evaluate PV plant health;
  • support optimization and energy automation scenarios.