Heating control scenarios

There are two types of control scenarios: manual scenarios on one side and automatic control scenarios on the other side.

Manual Scenarios

Manual scenarios, refer to scenarios for which the user forces the real-time remote management of his devices. For example, with the AWAY mode, when a user is not at home, he can force all his compatible heating devices to switch into their away profile. Currently available manual control scenarios :

Scenario identifier	Description
`AWAY`	The away scenario allows users to switch all their heating devices to away mode in just a click

Automatic control scenarios

Automatic control scenario, allow users to subscribe to an automatic intelligent control program. By subscribing, the user explicitly delegates to the system the responsibility of managing their compatible devices on their behalf. Each scenario comes with a clear promise. For example helping the user reduce their energy bill while maintaining an appropriate level of comfort. The program will be launched at specific moments, either based on a timely trigger (e.g. an upcoming peakday) or every day at a fixed scheduled time. For instance, having an active automatic scenario does not necessarily mean that devices are being remotely controlled at all times. A first example is a scenario that optimizes the user energy consumption of his electrical devices during peakdays. For contracts where energy prices may triple during these specific days, the system automatically lowers the heating setpoint to reduce consumption and generate savings. A second example is the daily off‑peak optimization scenario, designed for users having a contract with peak/off‑peak hours. In this scenario, the system performs a controlled overheating during off‑peak hours so that, thanks to the building’s thermal inertia, heating does not need to restart during peak hours. This routine is only applied when the algorithm determines that it will effectively reduce the user’s overall bill without compromising comfort. In both cases, by subscribing to an automatic control scenario, the user chooses to let the system manage device schedules and heating behavior intelligently, with the guarantee that optimizations will be applied only when they bring a real and measurable benefit. Currently available automatic control scenarios :

Scenario identifier	Description	Promise
`OPTIM_TEMPO`	Scenario, for customers with a TEMPO tariff offer, enabling them to reduce their heating energy concumption on Rouge days	Save money
`OPTIM_ZENFLEX`	Scenario, for customers with a ZENFLEX tariff offer, enabling them to reduce their heating energy concumption on Sobriété days	Save money
`OPTIM_HPHC`	Scenario, for customers having a tariff offer with off-peak/peak hours, enabling them to optimize their heating energy concumption with their contract	Save money without compromising comfort

Schedule control

Peakday’s optimisation

With this heating automatic control scenario, the goal is to help the user manage his electric consumption on specific days. When a peakday trigger is received, a control scenario execution is launched on all devices enrolled in this scenario and new schedules are sent for those devices. There are two types of heating devices and the algorithm applied on the planning depends on the device category :

Profile‑type devices: The profile applied during peak hours is the one with the lowest setpoint. If multiple predefined profiles share the same lowest temperature value, the first profile in alphanumeric order is selected.
Temperature‑type devices: The setpoint applied during peak hours is the current scheduled setpoint for those hours, reduced by 3°C.

Daily optimisation

This heating automatic control scenario provides a daily routine for sites whose energy contract includes peak/off‑peak hours and that have compatible connected heating equipments. Its purpose is to help customers reduce their energy bill by applying controlled overheating during an off‑peak period, just before the transition to peak hours. Thanks to the building’s thermal inertia, this approach prevents the need to restart heating devices during peak hours. Every day at fixed scheduled time, a control scenario execution is launched on all devices enrolled in this scenario and new schedules are sent for those devices. The algorithm ensures that overheating is applied only when it leads to an overall reduction in the customer’s energy bill. To make this decision, it gathers and evaluates specific site characteristics such as the dwelling type, its thermal performance (insulation quality), the outdoor temperature, the heating setpoint, the pricing structure, etc. To ensure user comfort, overheating is limited to :

A maximum +2°C compared to the current applied setpoint
A maximum of 2 hours before the start of peak hours

Schedule restoration

Once the controlled period is over, the user’s schedule is restored.

For a peakday scenario, the restoration occurs as soon as the peak hours end.
For the daily optimisation scenario with overheating, the restoration takes place at the end of the controlled day, that is, at 00:01, immediately after the optimised day ends.

The rule applied for the restoration is to keep the user’s current schedule outside the controlled day and restore the controlled day with the initial schedule values. A modification made by the user on the controlled day is overwrittend by the restoration process. However, all changes applied on non‑controlled days are preserved (cf. Fig 4 ).

Global functioning scheme

Manual scenarios

Fig 1: Functioning scheme of manual scenario activation and deactivation steps

Automatic scenarios

Fig 2: Functioning scheme of automatic control scenario activation, deactivation and settings steps

Fig 3: Functioning scheme of automatic control scenario execution

Fig 4: Functioning scheme of control and restoratiton rules

Endpoints overview

To be able to set up and execute control scenarios, 7 endpoints are available :

Endpoint	Description
`GET control-scenario`	Get all scenarios (manual and automatic) for a site and information about the scenario (name, status, availabily, etc.)
`POST control-scenario activate`	Activate a specific scenario for a site
`POST control-scenario deactivate`	Deactivate a specific scenario for a site
`GET control-scenario/settings`	Display the scenario device configuration of a site (name, provider, status, etc.)
`PUT control-scenario/settings`	Configurate the devices included in a scenario (select/ unselect)
`POST control-scenario/executions/cancel`	Cancel the execution of an automatic control scenario
`GET control-scenario/executions`	Retrieve executions for a scenario to get its execution history

1. Display available automatic control scenarios for a site

Description : This API returns all control scenarios (manual and automatic) available for a site based on the user’s contract. The API output provides information on each scenario, such as its current status (in use or not), whether it is editable, and other related details. A scenario is considered “available” for a site if the latter has at least one device eligible:

To be considered eligible for an automatic scenario, a device has to be a heating device, with read/write rights and having the capability to receive and send weekly schedules.
To be considered eligible for the AWAY scenario, a device has to be a heating device, with read/write rights and have an away mode.

Endpoint : GET /api/v1/sites/{site-id}/control-scenarios Input :

Path parameter: The site identifier (site-id)
Query parameter (optional): The scenario mode to filter scenarios on their mode AUTO or MANUAL

Output :

label	Description	Example
`id`	Unique scenario identifier	`OPTIM_TEMPO`
`mode`	Type of scenario : automatic or manual	`AUTO`
`usage`	Usage of the devices remotely controled by this scenario	`HEATING`
`active`	Scenario status: whether the scenario has been activated by the user or not. The activation is made with the [API POST/activate]	`True`
`available`	Scenario availability. This field is used to check whether the user has all the prerequisites needed to be able to execute commands remotely	`True`
`readonly`	Scenario property displaying whether it is editable or read-only	`False`
`executionStatus`	Last site executionStatus.	`RUNNING`

Example : GET /api/v1/sites/1dab569e-778b-4c46-9588-34ca3aeae293/control-scenarios

{
        "scenarios": [
        {
            "id": "AWAY",
            "mode": "MANUAL",
            "usage": "HEATING",
            "active": false,
            "available": true,
            "executionStatus": "STOPPED",
            "readOnly": false
        },
        {
            "id": "DREEV_SMART_CHARGING",
            "mode": "AUTO",
            "usage": "ELECTRIC_VEHICLE",
            "active": true,
            "available": true,
            "executionStatus": "STOPPED",
            "readOnly": true
        },
        {
            "id": "OPTIM_TEMPO",
            "mode": "AUTO",
            "usage": "HEATING",
            "active": false,
            "available": true,
            "executionStatus": "STOPPED",
            "readOnly": false
        }
    ]
}

2. Activate and Deactivate a specific scenario for a site

These two API can be used to activate or deactivate a scenario, either a manual scenario (e.g. AWAY) or an automatic scenario (e.g. OPTIM_TEMPO, OPTIM_ZENFLEX, etc.).

In case of a manual scenario, the activation/deactivation of the scenario leads to its immediate execution.
In the case of an automatic scenario, activation does not mean instantaneous execution of the control. The latter is launched with the reception of an event/trigger such as the a peakday.

For a scenario to be activated, the site needs to have the right contract and at least one device eligible for a control scenario.

To be considered eligible for an automatic scenario, a device has to be a heating device, with read/write rights and having the capability to receive and send weekly schedules.
To be considered eligible for the AWAY mode, a device should have an away mode and has to be a heating device with read/write rights.

On successful activation or deactivation, this API modifies the status (“active” field) of the scenario avalaible with the endpoint GET/control_scenario

Endpoints :
- POST /api/v1/sites/{site-id}/control-scenarios/{scenario-id}/activate
- POST /api/v1/sites/{site-id}/control-scenarios/{scenario-id}/deactivate
Input : A site identifier (site-id) and a scenario identifier (scenario-id)
Output : No output expected, just an API code. See API documentation for details.
Examples : POST /api/v1/sites/141ea311-fea6-4dda-a459-392a39ddf6a5/control-scenarios/OPTIM_TEMPO/activate

3. Equipment selection

Thoses two API are intended to be used together to define the equipment to be controlled by a scenario. The available equipments for a scenario can be displayed thanks to the first endpoint (section 3.1) and then the user can select the equipment to be controlled (section 3.2). To be considered as elligible, a device has to be a heating device, with read/write rights and having the capability to receive and send weekly schedules.

3.1. Display, for a scenario, the site eligible equipments :

Endpoint : GET /api/v1/sites/{site-id}/control-scenarios/{scenario-id}/settings
Input :
- Path parameters : the site identifier (site-id) and the scenario identifier (scenario-id)
Output : List of devices with characteristics (id, label, provider, status and if the device has been selected for this sccenario or not )
Example : GET /api/v1/sites/1dab569e-778b-4c46-9588-34ca3aeae293/control-scenarios/OPTIM_TEMPO/settings

    {
        "devices": [
            {
                "id": "21af95d5-db0f-4f26-9db3-aea2f5e1241a",
                "label": "Radiator Intuis",
                "provider": "intuis",
                "status": "ENABLED_RW",
                "active": false
            },
            {
                "id": "31af95d5-db0f-4f26-9db3-aea2f5e1241a",
                "label": "Radiator Intuis 2",
                "provider": "intuis",
                "status": "ENABLED_RW",
                "active": false
            }
        ]
    }

Fig 5: Example of a device selection menu

3.2. Select / unselect equipments for an automatic control scenario :

The devices that will be remotely controlled during automatic control scenarios are the ones set as active in the settings with this API.

Endpoint : PUT /api/v1/sites/{site-id}/control-scenarios/{scenario-id}/settings
Input :
- Query parameter : A site identifier (site-id) and a scenario identifier (scenario-id)
- Body (required): A list of devices with their identifier (id) and status (active)
Output : No output expected, just an API code. See API documentation for details
Example :
Endpoint example : PUT api/v1/sites/1dab569e-778b-4c46-9588-34ca3aeae293/control-scenarios/OPTIM_TEMPO/settings Request body example:

{
  "devices": 
  [
    {
      "id": "21af95d5-db0f-4f26-9db3-aea2f5e1241a",
      "active": true
    },
    {
      "id": "31af95d5-db0f-4f26-9db3-aea2f5e1241a",
      "active": true
    }
  ]
  }

4. Cancel the execution of an automatic control scenario on all devices

This endpoint can be made available to a user so that he can stop the execution of an automatic control scenario running for his site on all devices. If the API runs successfully, the user’s schedule is instantly restored on all the devices that had been automatically controlled. The rule applied for the cancellation is the same as the one for the restoration: keep the user’s current schedule outside the modified timeslots (i.e outside the peak hours) and restore the modified timeslots with the initial schedule values. This cancellation will be available in the execution history (see section below) thanks to the endpoint GET /api/v1/sites/{site-id}/control-scenarios/executions. The status of this site execution is set to:

OK : if all the devices have been successully cancelled
PARTIAL_OK : if at least one of the devices has not been cancelled successfully.
KO : if none of the devices were cancelled.

Note that the AWAY mode cannot be cancelled. This API is meant for automatic control scenarios only.

Endpoint : POST /api/v1/sites/{site-id}/control-scenarios/{scenario-id}/executions/{execution-id}/cancel
Input :
- Path parameters :
  - The site identifier (site-id)
  - The scenario concerned (scenario-id)
  - The site execution ID (execution-id) to cancel
Output : No output expected, just an API code. See API documentation for details.
Example : POST /api/v1/sites/ed12095b-692f-4742-a83f-ca56562b9238/control-scenarios/OPTIM_TEMPO/executions/baa2813a-43bb-4e51-a06a-5b293e740966/cancel

5. Retrieve all control scenario executions over a given period of a site

This endpoint can be used to retrieve the execution history for a scenario over a given period (“Past slots”). The output provides information about actions carried out at the device and the site level, in both manual and automatic scenarios.

Endpoint : GET /api/v1/sites/{site-id}/control-scenarios/executions
Input :
- Path parameter: A site identifier (site-id)
- Required query parameters:
  - beginTs: Begin date of the requested period (included)
  - endTs: End date of the requested period (excluded)
- Optional query parameter:
  - scenarioId: scenario identifier Note that this period is limited to a maximum of 40 days.
Output : A list of site executions with detailed information regarding the scenario, the type of execution (RUN, STOP, CANCEL), the execution status and details about the devices executions associated to this site.
Example : GET /api/v1/sites/2bd6f8f3-dcdd-47f9-abce-e32c6f4f0bcb/control-scenarios/executions?scenario-id=OPTIM_TEMPO&beginTs=2025-01-11T10:49:56Z&endTs=2025-01-31T10:49:56Z

  {
    "executions": [
        {
            "id": "5605ebf9-73b8-4282-bf58-79caaea6d079",
            "siteId": "2bd6f8f3-dcdd-47f9-abce-e32c6f4f0bcb",
            "offerFamily": "FO008",
            "scenario_id": "OPTIM_TEMPO",
            "type": "RUN",
            "status": "OK",
            "modificationTs": "2025-02-20T14:08:25.411Z",
            "trigger": {
                "type": "PEAKDAY",
                "beginTs": "2025-02-21T05:00:00Z",
                "endTs": "2025-02-21T21:00:00Z"
            },
            "devices_executions": [
                {
                    "id": "07bb01b5-4bf3-474f-b507-296ccdb96ebd",
                    "status": "OK",
                    "modificationTs": "2025-02-20T14:08:25.431Z"
                },
                {
                    "id": "018e7c1e-1e7c-4131-9042-ae8fb6ad3e68",
                    "status": "OK",
                    "modificationTs": "2025-02-20T14:08:25.431Z"
                },
                {
                    "id": "30246a24-e8cf-4749-80a6-07b54a1349e1",
                    "status": "OK",
                    "modificationTs": "2025-02-20T14:08:25.431Z"
                },
                {
                    "id": "e9b81aec-57e5-4674-83ab-9a545e695259",
                    "status": "OK",
                    "modificationTs": "2025-02-20T14:08:25.431Z"
                }
            ]
        },
        {
            "id": "6600a6e4-3afa-40b4-a850-10f54543c9c8",
            "siteId": "2bd6f8f3-dcdd-47f9-abce-e32c6f4f0bcb",
            "offerFamily": "FO008",
            "scenario_id": "OPTIM_TEMPO",
            "type": "RUN",
            "status": "KO",
            "modificationTs": "2025-02-19T13:52:11.406Z",
            "trigger": {
                "type": "PEAKDAY",
                "beginTs": "2025-02-20T05:00:00Z",
                "endTs": "2025-02-20T21:00:00Z"
            },
            "devices_executions": [
                {
                    "id": "9c7a42ab-425d-463f-8a61-80a31f61c51c",
                    "status": "KO",
                    "modificationTs": "2025-02-19T13:52:11.438Z"
                },
                {
                    "id": "ba8c0555-8e84-465d-9bad-fdbb75b1c83e",
                    "status": "KO",
                    "modificationTs": "2025-02-19T13:52:11.438Z"
                },
                {
                    "id": "aa6b28a7-c8cb-419b-8b4d-4c3516ce7e6e",
                    "status": "KO",
                    "modificationTs": "2025-02-19T13:52:11.438Z"
                },
                {
                    "id": "d14d8f5c-1ee2-41c0-a05d-c0794774d2ae",
                    "status": "KO",
                    "modificationTs": "2025-02-19T13:52:11.438Z"
                }
            ]
        }
    ]
}

Introduction

Offer catalog

Manage your users

Home Basic

Home Coaching

Home Energy Management

Home Interfaces

Manual Scenarios

Automatic control scenarios

Schedule control

Peakday’s optimisation

Daily optimisation

Schedule restoration

Global functioning scheme

Endpoints overview

1. Display available automatic control scenarios for a site

2. Activate and Deactivate a specific scenario for a site

3. Equipment selection

3.1. Display, for a scenario, the site eligible equipments :

3.2. Select / unselect equipments for an automatic control scenario :

4. Cancel the execution of an automatic control scenario on all devices

5. Retrieve all control scenario executions over a given period of a site

Introduction

Offer catalog

Manage your users

Home Basic

Home Coaching

Home Energy Management

Home Interfaces

​Manual Scenarios

​Automatic control scenarios

​Schedule control

Peakday’s optimisation

Daily optimisation

​Schedule restoration

​Global functioning scheme

​Endpoints overview

​1. Display available automatic control scenarios for a site

​2. Activate and Deactivate a specific scenario for a site

​3. Equipment selection

​3.1. Display, for a scenario, the site eligible equipments :

​3.2. Select / unselect equipments for an automatic control scenario :

​4. Cancel the execution of an automatic control scenario on all devices

​5. Retrieve all control scenario executions over a given period of a site

Manual Scenarios

Automatic control scenarios

Schedule control

Schedule restoration

Global functioning scheme

Endpoints overview

1. Display available automatic control scenarios for a site

2. Activate and Deactivate a specific scenario for a site

3. Equipment selection

3.1. Display, for a scenario, the site eligible equipments :

3.2. Select / unselect equipments for an automatic control scenario :

4. Cancel the execution of an automatic control scenario on all devices

5. Retrieve all control scenario executions over a given period of a site