Live MQTT Control

This guide will help you configure MQTT on your SmartgridOne Controller to remotely control and monitor battery and solar panel installations.

First-time Configuration (Starting point for new users)

I have a SmartgridOne Controller that I'd like to setup for MQTT Remote Control.

Before continuing, make sure your network and devices are ready by following the MQTT Setup guide.

Request the required Eniris MQTT username and password through the Eniris webshop before starting the configuration. Support tickets and SmartgridX/Insights are not provisioning channels for new MQTT credentials.

1. Add the MQTT external signal

2. Enable MQTT remote signal

The fallback mechanism timeout tells the SmartgridOne Controller how long it should wait for new commands. When the SmartgridOne Controller stops receiving commands, it automatically picks up the default strategy after this timeout.

After, select all devices that you'd wish to include in MQTT Remote Control.

3. Remote signal is added

The MQTT Remote Control interface has now been activated on the SmartgridOne Controller.

We are now ready to send some basics commands using a simple example. The Status column tells you if any command is active.

Python demo script

A good first starting point would be to test your newly setup integration with a simple example.

This test code does a simple job of continuously sending the following commands:

• Battery: Charge at 5 kW
• Solar: Set power to 0 kW

The SmartgridOne Controller continuously responds with a 'feedback' message containing the observed grid and asset power values. This feature is also included in this example.

Please download the file below in your preferred Python IDE. Fill in your serial number and the MQTT credentials requested through the Eniris webshop, then execute the script:

When the above is successful, you can continue with sending other type of commands. All commands are described in our MQTT Remote Control Documentation.

MQTT Documentation for Sending Commands

This section details the MQTT messaging format and payload requirements for remotely controlling power policies on devices within the SmartgridOne Controller's network.

MQTT Topic

The MQTT topic used for sending commands is structured as follows:

standard1/rp_one_s/remoteControlMetrics/'controller SN'

Where 'controller SN' should be replaced with the actual serial number of the SmartgridOne Controller you intend to control.

MQTT Payload Structure

Commands are sent as JSON payloads. The payload structure is designed to specify various power management policies and setpoints for different components of the smart grid system. Here is the outline of the payload with detailed field descriptions:

{
    "extraTags": {
        "nodeId": "<Controller SN>_site_0"
    },
    "time": "<Unix Timestamp>",
    "fields": {
        "<Component Policy>": "<Policy Type>",
        "<Component Power Setpoint>": <Setpoint in watts>,
        "site_<policy>": "<Value in watts>"
    }
}

Fields description

• extraTags (Object):
  • nodeId (String): A unique identifier for the node within the SmartgridOne Controller's network. This is equal to your serial number, followed by '_site_0' for most SmartgridOne Controller devices.
• time (Integer): Unix timestamp in seconds indicating the time when the message is sent.
• fields (Object):
  • <Component>_policy (String): Policy type for the component. It is optional and if not specified, the system will fallback to the SmartgridOne Controller's default setting.
  • <Component>_power_setpoint_w (Float): Desired power setpoint in watts for the component. This is optional and only relevant if a corresponding policy is specified.

Components and Policies

Each component in the fields object can include a policy and a power setpoint. The following components can be controlled:

• solar_policy and solar_power_setpoint_w:

  • Controls the solar power generation policy and setpoint. Supported policies:
    • Policy setpoint: Set the maximum power produced by all connected solar installations combined. Field solar_power_setpoint_w should be set to the production power limit in watts.
    • Policy feed-in-restriction: Produce at full power, following current grid limits.
    • Policy cost: Enables day-ahead price (EPEX Spot market) cost minimization on the solar production. When negative injection prices occur, we curtail production to own consumption. When both the offtake and injection price are negative, we switch off all solar installations. Field solar_power_setpoint_w is ignored.
    • Policy off: Disables all interaction for all solar assets. Warning: limits are not being guarded in this mode. Field solar_power_setpoint_w is ignored.

• storage_policy and storage_power_setpoint_w:

  • Controls the energy storage system policy and power discharge or charge rate.
    • Policy setpoint: Set the total charge power (positive setpoint) or discharge power (negative setpoint) for the group of batteries. When multiple batteries are attached, then the setpoint is split up by available charge/discharge power to equally stress the batteries. Field storage_power_setpoint_w is set to the desired battery power.
    • Policy peak-shaving-only: Enables peak shaving optimisation pn the battery. This must be combined with four peak-shaving parameters on site-level.
    • Policy cost: Enables day-ahead price (EPEX Spot market) cost optimization on the batteries, by charging it on the cheap hours and using the energy in the expensive hours. Field storage_power_setpoint_w is ignored.
    • Policy self-consumption Enables a simple self-consumption algorithm on the batteries. Excess solar production is stored to the battery during, and when the sun is down, energy is taken from the battery. Field storage_power_setpoint_w is ignored.
    • Policy off: Disables all interaction for all battery assets. Warning: limits are not being guarded in this mode. Field storage_power_setpoint_w is ignored.

• heat_pump_policy:

  • Toggles on/off heatpump systems. The minimum and maximum on times will always be respected.
    • Policy cost: Enables day-ahead price (EPEX Spot market) cost optimization on the heat pumps. The local dynamic pricing algorithm decides the best on-time periods
    • Policy self-consumption Turns on the heat pumps if an excess of solar energy is produced.
    • Policy power_off: Power off the heat pumps.
    • Policy power_on: Power on the heat pumps.

• switched_load_policy:

  • Toggles on/off relay-controlled systems. This could be the built-in relay or network-connected relays.
    • Policy cost: Enables day-ahead price (EPEX Spot market) cost optimization on the relay.
    • Policy self-consumption Turns on the relay if an excess of solar energy is produced.
    • Policy power_off
    • Policy power_on

• variable_power_load_policy and variable_power_load_power_setpoint_w:

  • Manages the electric vehicle power consumption policy and setpoint.
    • Policy setpoint: Set the total charge power for the group of EVs. Field variable_power_load_power_setpoint_w is set to the desired charge power.
    • Policy cost: Enables day-ahead price (EPEX Spot market) cost optimization on the batteries, by charging it on the cheap hours. Field variable_power_load_power_setpoint_w is ignored.
    • Policy self-consumption Enables charging if an excess of solar energy is produced. Field variable_power_load_power_setpoint_w is ignored.
    • Policy off: Disables all interaction for all EV assets. Field variable_power_load_power_setpoint_w is ignored.

Power Limits

Instead of setting control strategies and setpoint, power limits can also be set for storage and solar devices.

For example:

{
    "extraTags": {
        "nodeId": "<Controller SN>_site_0"
    },
    "time": "<Unix Timestamp>",
    "fields": {
        "{prefix}_maxChargePower_W": <Max Charge Power W>,
        "{prefix}_maxDischargePower_W": <Max Discharge Power W>,
        "{prefix}_maxProductionPower_W": <Max Production Power W>,
    }
}

where prefix is either storage, solar or the applicable device nodeID.

Site Control

The site can be controlled seperately. The following site commands can be sent to the controller:

• default or fallback Remove any active site commands
• export Set the site export limit
• import Set the site import limit
• setpoint A site setpoint can vary up to 5% in both directions
• setpoint_A Not yet implemented

The following variables are peak-shaving parameters, and will only be applied when the battery strategy is set to peak-shaving.

• startChargeBelow_W
• stopChargeAbove_W
• startDischargeAbove_W
• stopDischargeBelow_W

A site setpoint is NOT compatible with an import/export limit.

For example:

{
    "extraTags": {
        "nodeId": "<Controller SN>_site_0"
    },
    "time": "<Unix Timestamp>",
    "fields": {
        "<Component Policy>": "<Policy Type>",
        "<Component Power Setpoint>": <Setpoint in watts>,
        "site_export": <Export Limit W>,
        "site_import": <Import Limit W>,
        "site_setpoint": <Setpoint W>,
        "site_startChargeBelow_W": <Value_W>
    }
}

Device Control

Specific devices can also be controlled, instead of groups of devices based on their types. The message is identically structured:

• nodeId_policy and nodeId_power_setpoint_w

Fallback behaviour

For each component, if the _policy and _power_setpoint_w is not specified, the system will automatically use the fallback policy configured in the SmartgridOne Controller. This ensures that each device or device group operates safely and continues to function even if specific instructions are not provided.

If no command is being send at all, after 60 seconds (or configured timeout period), the default policies for assets will be reactivated.

Cancel existing commands and falling back to local control modes

An active command can be cancelled by sending a fallback command message.

Fallback Command

A fallback command will cancel the existing command immediately and the SmartgridOne Controller will take over control of the installation. The executed policy depends on what is set in the SmartgridOne Controller Settings.

This can also be used in cases where a secondary control signal, such as a schedule, is used as a fallback.

Message examples:

{
    "extraTags": {
        "nodeId": "<Controller SN>_site_0"
    },
    "time": "<Unix Timestamp>",
    "fields": {
        "<Component Policy>": "fallback",
    }
}

Empty Command

An empty command can be sent at all times to collect site information. This will not cancel the current command.

The empty command is structured as follows:

{
    "extraTags": {
        "nodeId": "<Controller SN>_site_0"
    },
    "time": "<Unix Timestamp>",
    "fields": {}
}

Example payload

Below is an example of a payload to set various policies and setpoints:

{
    "extraTags": {
        "nodeId": "OM12404080000000000_site_0"
    },
    "time": 1714652046,
    "fields": {
        "solar_policy": "setpoint",
        "solar_power_setpoint_w": 5000,
        "storage_policy": "setpoint",
        "storage_power_setpoint_w": -5000
    }
}

In this example, the solar power is set to generate up to 5000 watts, and the energy storage system is set to either charge or discharge at a rate of 5000 watts, depending on the sign of the setpoint value. If either the solar_policy or storage_policy were omitted, the respective device would revert to the default settings determined by the SmartgridOne Controller.

MQTT Documentation for Receiving feedback

This section outlines the structure and content of the feedback messages sent by the SmartgridOne Controller via MQTT. These messages are published to the topic standard1/outbound/remoteControlMetrics/feedback/<Controller SN> after a command has been processed.

MQTT Feedback Topic

The feedback MQTT topic is structured as follows:

standard1/outbound/remoteControlMetrics/feedback/<Controller SN>

Where <Controller SN> should be replaced with the serial number of the SmartgridOne Controller that is sending the feedback.

MQTT Feedback Payload Structure

Feedback messages are formatted as JSON payloads. These payloads provide detailed feedback on the state of the system after applying the setpoint commands, considering grid/device limits. Below is the structure of the feedback payload with descriptions of its fields:

{
    "time": "<Unix Timestamp>",
    "data": {
        "state": {
            "grid": {
                "active_power_W": <Grid Active Power in Watts>,
                "today_imported_energy_Wh": <Grid Imported Energy in Watt-hours>,
                "today_exported_energy_Wh": <Grid Exported Energy in Watt-hours>,
                "import_limit_W": <Grid Import Limit in Watts>,
                "export_limit_W": <Grid Export Limit in Watts>,
            },
            "storage": {
                "energy_stored_Wh": <Energy Stored in Watt-hours>,
                "energy_capacity_Wh": <Total Energy Capacity in Watt-hours>,
                "mean_soc_perc": <Mean State of Charge Percentage>,
                "active_power_W": <Active Power in Watts>,
                "executed_power_W": <Power Setpoint Sent to Devices in Watts>,
                "executed_policy": <Policy Executed by the Controller>,
                "max_charge_power_W": <Maximum Charge Power in Watts>,
                "max_discharge_power_W": <Maximum Discharge Power in Watts>,
                "today_charged_Wh": <Energy Charged Today in Watt-hours>,
                "today_discharged_Wh": <Energy Discharged Today in Watt-hours>,
                "realised_charge_power_W": <Adapted maximum charge power>,
                "realised_discharge_power_W": <Adapted maximum discharge power>,
                "constraint_ph0_label": <Constraint reason for limiting power setpoint>,
                "errorCodes": <Error status messages per device>,
                "nr_devices": <Number of Controlled Storage Devices Installed>
            },
            "solar": {
                "active_power_W": <Solar Active Power in Watts>,
                "executed_power_W": <Power Setpoint Sent to Devices in Watts>,
                "executed_policy": <Policy Executed by the Controller>,
                "capacity_W": <Solar Capacity in Watts>,
                "today_energy_Wh": <Energy Produced Today in Watt-hours>,
                "constraint_ph0_label": <Constraint reason for limiting power setpoint>,
                "errorCodes": <Error status messages per device>,
                "nr_devices": <Number of Controlled Solar Devices Installed>
            },
            "heat_pump": {
                "executed_policy": <Policy Executed by the Controller>,
                "operation_modes": <Heatpump Operation Modes>,
                "executed_power_W": <Power Setpoint Sent to Devices in Watts>,
                "constraint_ph0_label": <Constraint reason for limiting power setpoint>,
                "errorCodes": <Error status messages per device>,
                "nr_devices": <Number of Controlled Heat Pump Devices Installed>
            },
            "switched_load": {
                "executed_policy": <Policy Executed by the Controller>,
                "devices_on": <Number of Devices On>,
                "devices_off": <Number of Devices Off>,
                "executed_power_W": <Power Setpoint Sent to Devices in Watts>,
                "constraint_ph0_label": <Constraint reason for limiting power setpoint>,
                "errorCodes": <Error status messages per device>,
                "nr_devices": <Number of Controlled Switched Load Devices Installed>  
            },
            "variable_load": {
                "active_power_W": <Power of the device in Watts>,
                "ev_charging": <How many EVs are currently charging>,
                "ev_not_charging": <How many EVs are currently unconnected>,
                "executed_policy": <Policy Executed by the Controller>,
                "executed_power_W": <Power Setpoint Sent to Devices in Watts>,
                "ev_requiring_charge": <Does the EV require charge>,
                "currentL1_A": <Current of the device on phase 1 in Ampere>,
                "currentL2_A": <Current of the device on phase 2 in Ampere>,
                "currentL3_A": <Current of the device on phase 3 in Ampere>,
                "executed_current_A": <Current Setpoint Sent to Devices in Ampere>,
                "today_charged_Wh": <Energy Charged Today in Watt-hours>,
                "today_discharged_Wh": <Energy Discharged Today in Watt-hours>,
                "total_charged_Wh": <Total Energy Charged in Watt-hours>,
                "total_discharged_Wh": <Total Energy Discharged in Watt-hours>,
                "min_charge_current_A": <Minimum Charge in Ampere>,
                "max_charge_current_A": <Maximum Charge in Ampere>,
                "allow_zero_current": <Does the Charger Support Pausing>,
                "current_charging_session": {
                    "pluginTime": <The session start time>,
                    "endTime": <The session end time>,
                    "firstChargingStartTime": <The time when the vehicle first charged>,
                    "isFull": <Is the vehicle fully charged or not>,
                    "chargedEnergy_Ws": <How much energy has been charged this session>,
                    "usedPhases": <The list of phases used during charging>,
                    "historicMaxChargeCurrent_A": <The maximum current at which the vehicle was charged during the session>
                },
                "previous_charging_session": {
                    "pluginTime": <The session start time>,
                    "endTime": <The session end time>,
                    "firstChargingStartTime": <The time when the vehicle first charged>,
                    "isFull": <Is the vehicle fully charged or not>,
                    "chargedEnergy_Ws": <How much energy has been charged this session>,
                    "usedPhases": <The list of phases used during charging>,
                    "historicMaxChargeCurrent_A": <The maximum current at which the vehicle was charged during the session>
                },
                "constraint_ph0_label": <Constraint reason for limiting power setpoint>,
                "errorCodes": <Error status messages per device>,
                "nr_devices": <Number of Variable Power  Load Devices Installed>  
            }
        },
        "error": {
            <Errors occured during driver execution>
        }
        "response_code": <Response Code>
    },
    "fields": {},
    "requestTime": "<Unix Timestamp>",
    "time": "<Unix Timestamp>",
    "siteNodeId": "<Controller SN>_site_0"
}

Fields description

• time (Integer): Unix timestamp indicating the time when the feedback message was sent.
• requestTime (Integer): Unix timestamp indicating the time when the original control message was sent.
• siteNodeId (String): The nodeId of the site sending feedback.
• fields (Object): Empty object
• data (Object):
  • state (Object):
    • vpp_id (String): Identifier for the Virtual Power Plant associated with this device.
    • grid (Object):
      • active_power_W (Float): Represents the current active power on the grid in watts.
      • today_imported_energy_Wh (Float): The total energy taken from the grid today in watt hours. Note: Today is given in UTC time.
      • today_exported_energy_Wh (Float): The total energy injected back into the grid today in watt hours. Note: Today is given in UTC time.
      • import_limit_W (Float): The grid import limit in watts,
      • export_limit_W (Float): The grid export limit in watts,
    • storage (Object):
      • energy_stored_Wh (Float): Current amount of energy stored in watt-hours.
      • energy_capacity_Wh (Float): Total energy capacity of the storage system in watt-hours.
      • mean_soc_perc (Float): State of charge as a percentage. This is the weighted average among all connected batteries. (when multiple batteries are connected: e.g. battery 'a' has an energy capacity of 10 kWh and a state of charge 20%; battery 'b' has an energy capacity of 20 kWh and state of charge of 50%, then the mean_soc_perc is 40%)
      • active_power_W (Float): Current active power for the storage system in watts, showing charge or discharge rate.
      • max_charge_power_W (Float): Maximum power at which the storage can be charged.
      • max_discharge_power_W (Float): Maximum power at which the storage can be discharged.
      • executed_power_W (Float): The sum of total power requested to (dis)charged from the storage assets, being send out by our control algorithm. Only applicable if 'follow_setpoint'-policy is active.
      • executed_policy (Str): The policies that have been applied to the controllables.
      • today_charged_Wh (Float): The total energy charged in to the controllable battery asset(s) today. Note: Today is given in UTC time.
      • today_discharged_Wh (Float): The total energy discharged from the controllable battery asset(s) today. Note: Today is given in UTC time.
      • realised_charge_power_W (Float): The adapted maximum charge power, calculated from device responses,
      • realised_discharge_power_W (Float): The Adapted maximum discharge power, calculated from device responses,
      • constraint_ph0_label (List[string]): The reasons why the external setpoints were limited.
      • errorCodes (Dict[str, Dict]): Error codes received from devices.
      • nr_devices (Int): The number of controllable battery assets.
    • solar (Object):
      • active_power_W (Float): Current active power generated by solar panels in watts.
      • capacity_W (Float): Total capacity of the solar generation system in watts.
      • executed_power_W (Float): The sum of total power requested from the solar assets, being send out by our control algorithm. Only applicable if 'follow_setpoint'-policy is active.
      • executed_policy (Str): The policies that have been applied to the controllables.
      • today_energy_Wh (Float): The total energy produced from the controllable solar asset(s) today. Note: Today is given in UTC time.
      • constraint_ph0_label (List[string]): The reasons why the external setpoints were limited.
      • errorCodes (Dict[str, Dict]): Error codes received from devices.
      • nr_devices (Int): The number of controllable solar assets.
    • heat_pump (Object):
      • executed_policy (Str): The policies that have been applied to the controllables.
      • operation_modes (Str): The mode of the heatpump (Blocking mode, Boosting mode, Self control mode)
      • executed_power_W (Float): The expected power that it's currently using.
      • errorCodes (Dict[str, Dict]): Error codes received from devices.
      • constraint_ph0_label (List[string]): The reasons why the external setpoints were limited.
      • nr_devices (Int): The number of controllable heatpumps.
    • switched_load (Object):
      • executed_policy (Str): The policies that have been applied to the controllables.
      • devices_on (Int): The number of devices on.
      • devices_off (Int): The number of devices off.
      • executed_power_W (Float): The power that it's currently using (if available).
      • constraint_ph0_label (List[string]): The reasons why the external setpoints were limited.
      • errorCodes (Dict[str, Dict]): Error codes received from devices.
      • nr_devices (Int): The number of controllable on/off switched loads.
    • variable_load (Object):
      • active_power_W (Float): Represents the current active power on the grid in watts.
      • ev_charging (Int): The number of EVs currently connected and charging.
      • ev_not_charging (Int): The number of unconnected EVs.
      • executed_policy (Str): The policies that have been applied to the controllables,
      • executed_power_W (Float): The sum of total power requested from the assets, being send out by our control algorithm.
      • ev_requiring_charge (Bool): Does the EV require charge. (Is a car connected).
      • currentL1_A (Float): Current of the device on phase 1 in Ampere.
      • currentL2_A (Float): Current of the device on phase 2 in Ampere.
      • currentL3_A (Float): Current of the device on phase 3 in Ampere.
      • executed_current_A (Float): The sum of total current requested from the assets, being send out by our control algorithm.
      • today_charged_Wh (Float): The energy charged in to the EV Charger asset(s) today. Note: Today is given in UTC time.
      • today_discharged_Wh (Float): The energy charged in to the EV Charger asset(s) today. Note: Today is given in UTC time.
      • total_charged_Wh (Float): The total energy charged in to the EV Charger asset(s).
      • total_discharged_Wh (Float): The total energy charged in to the EV Charger asset(s).
      • min_charge_current_A (Float): Minimum current at which the EV can be charged.
      • max_charge_current_A (Float): Maximum current at which the EV can be charged.
      • allow_zero_current (Bool): Does the EV charger allow pausing.
      • current_charging_sessions (Dict):
        • pluginTime (Date): The session start time.W
        • endTime (Date): The session end time.
        • firstChargingStartTime (Date): The time when the vehicle first charged.
        • isFull (Bool): Is the vehicle fully charged or not.
        • chargedEnergy_Ws (Float): How much energy has been charged this session.
        • usedPhases (List[str]): The list of phases used during charging.
        • historicMaxChargeCurrent_A (float): The maximum current at which the vehicle was charged during the session.
      • constraint_ph0_label (List[string]): The reasons why the external setpoints were limited.
      • errorCodes (Dict[str, Dict]): Error codes received from devices.
      • nr_devices (Int): The number of controllable on/off switched loads.
    • nodeId (Object):
      • If a nodeId is included in the command, the feedback will contain the corresponding state of the device.
  • response_code (Int):
    • Indicates the status of the operation. A response_code of 0 typically means success, while other values may indicate different types of errors or status information (these should be detailed in a separate reference).

Storage Constraint Labels

The setpoints sent by an external signal can be internally limited by the EMS. The table below gives an overview of possible constraints for the constraint_ph0_label feedback field.

MQTT Error Codes

Error codes are grouped into ranges that indicate the general category of the problem:

The individual error codes are listed below.

Connection errors (200)

Connection issues between the EMS and the device.

Response errors (300)

The device is connected, but its responses are invalid.

Control errors (600)

Measurement & setpoint errors (1000)

Supported MQTT Versions and Behavior on Unauthorized Topics

When using MQTT, it is important to consider the differences in specifications between versions 3.1, 3.1.1, and 5.0, particularly regarding the broker’s behavior when clients publish to unauthorized topics.

According to the MQTT 3.1.1 specification (see OASIS MQTT 3.1.1 Specification, section MQTT-3.3.5-2), a broker must terminate the connection as soon as a client sends a PUBLISH to a topic for which it does not have permission. This behavior can lead to unexpected disconnections for clients attempting to publish to misconfigured or unauthorized topics.

In MQTT 3.1, this requirement is not present. When a client publishes to an unauthorized topic under this version, the broker typically ignores the message (silent drop) without terminating the connection. This makes MQTT 3.1 in some cases more suitable when robustness against configuration errors or temporarily missing permissions is more important than strict security enforcement.

Although MQTT 5.0 introduces the ability to work with reason codes (such as PUBACK with a refusal reason), this requires support on both the client and server sides. Migrating to MQTT 5.0 therefore involves additional implementation effort.

Consequences of Ignoring Compatibility: If a client connects using MQTT 3.1.1 and attempts to publish messages to unauthorized topics, the broker will abruptly terminate the session. This may lead to instability, loss of connectivity, or increased load due to repeated reconnect attempts.

Recommended Approach: For systems where clients may (temporarily) attempt to publish to unauthorized topics, or where error handling is not strictly implemented, we recommend using MQTT 3.1. This ensures more stable connections and avoids unintended disconnects during runtime.