Live MQTT Control

This guide will help you configure MQTT on your Sunlight Group EMS to remotely control and monitor battery and solar panel installations.

First-time Configuration (Starting point for new users)

I have a Sunlight Group EMS 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 distributor 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 Sunlight Group EMS how long it should wait for new commands. When the Sunlight Group EMS 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 Sunlight Group EMS.

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 Sunlight Group EMS 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 distributor, 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 Sunlight Group EMS'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 Sunlight Group EMS 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. The following examples use fictional identifiers and illustrative limits. Replace the site node ID, timestamp and values with those appropriate for your installation:

{
    "extraTags": {
        "nodeId": "DEMO_CONTROLLER_SiteA"
    },
    "time": 1791547200,
    "fields": {
        "storage_policy": "setpoint",
        "storage_power_setpoint_w": 5000,
        "site_policy": "limit",
        "site_import": 25000
    }
}

Fields description

• extraTags (Object):
  • nodeId (String): A unique identifier for the node within the Sunlight Group EMS's network. Use the actual site node ID from the installation. It may differ from the serial number followed by '_site_0'; do not assume that suffix.
• time (Integer): Unix timestamp in seconds indicating the time when the message is sent.
• fields (Object):
  • <Component>_policy (String): Policy type for the component. If omitted, a previous group policy can remain active until its original timeout. Use an explicit fallback policy to relinquish control.
  • <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": "DEMO_CONTROLLER_SiteA"
    },
    "time": 1791547200,
    "fields": {
        "storage_policy": "limit",
        "storage_maxChargePower_W": 10000,
        "storage_maxDischargePower_W": 10000,
        "solar_policy": "limit",
        "solar_maxProductionPower_W": 15000
    }
}

The field prefix is storage, solar or the applicable device node ID. Include the corresponding limit policy when sending limits-only commands, as above. Command limit values are non-negative magnitudes: for example, storage_maxDischargePower_W: 10000 means a discharge limit of 10 kW. This differs from feedback, where max_discharge_power_W is negative or zero.

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": "DEMO_CONTROLLER_SiteA"
    },
    "time": 1791547200,
    "fields": {
        "storage_policy": "self-consumption",
        "site_policy": "limit",
        "site_export": 10000,
        "site_import": 25000
    }
}

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

Omitting a group policy is not an immediate cancellation: a previously received group command can remain active until its original configured timeout. Use an explicit fallback command for the group or device when you want to relinquish remote control. Device-specific commands are not preserved by the same group-command cache; see the empty-command warning below.

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 Sunlight Group EMS will take over control of the installation. The executed policy depends on what is set in the Sunlight Group EMS 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": "DEMO_CONTROLLER_SiteA"
    },
    "time": 1791547200,
    "fields": {
        "storage_policy": "fallback"
    }
}

Empty Command

An empty command returns aggregate site feedback, but it is not a read-only status request. It replaces the latest received message and can remove earlier device-specific commands. Still-valid group policies may be reused until their original fallback timeout expires. Do not use this as polling while expecting device-specific control to remain unchanged.

The empty command is structured as follows:

{
    "extraTags": {
        "nodeId": "DEMO_CONTROLLER_SiteA"
    },
    "time": 1791547200,
    "fields": {}
}

Example payload

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

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

In this example, solar production is limited to 5000 watts and the negative storage setpoint requests 5000 watts of discharge. A positive storage setpoint would request charging. Omitting a group policy does not necessarily cancel its earlier command; use an explicit fallback policy when you want to return that group to local control.

MQTT Documentation for Receiving feedback

MQTT Feedback Topic

Subscribe to the feedback topic to read the site's state and the result of a processed command:

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

Replace <Controller SN> with the controller serial number. The serial number in the topic and the site's siteNodeId are different identifiers: always use the actual site node ID, which does not necessarily end in _site_0.

When feedback is sent

The standard live-control connection returns a state snapshot when it accepts a command and triggers control processing. This is not a confirmation that the physical device has already reached the new setpoint.

An empty command with "fields": {} also returns aggregate state, but it is not side-effect-free polling: it replaces the latest message and can remove previously targeted device-specific commands. Earlier group policies can remain active only within their original fallback timeout. Do not use empty commands to poll while expecting device-specific control to remain unchanged.

Some provider-specific MQTT connections also publish unsolicited feedback approximately every 30 seconds. This periodic publishing is connection-specific, not a guaranteed interval for every MQTT integration. Periodic snapshots and replies to empty commands do not include individual-device state.

Machine-readable feedback specification

Use the JSON Schema to validate feedback payloads, or the AsyncAPI document to describe the controller's feedback channel. Both describe feedback, not the complete command interface or provider-specific extensions.

Message envelope

responseCode: 0 does not prove that every device reached its requested setpoint. Read measured power, executed setpoints, constraint labels and device error codes as well.

Successful response

This illustrative snapshot uses fictional identifiers and a deliberately small selection of measurements. Other available fields are described below.

{
  "time": 1791547201,
  "requestTime": 1791547200,
  "siteNodeId": "DEMO_CONTROLLER_SiteA",
  "fields": {},
  "data": {
    "responseCode": 0,
    "errors": "",
    "state": {
      "load": { "load_power_W": 12000 },
      "grid": { "active_power_W": 7000, "import_limit_W": 25000 },
      "storage": {
        "active_power_W": -5000,
        "mean_soc_perc": 60,
        "max_charge_power_W": 10000,
        "max_discharge_power_W": -10000,
        "dynamic_max_charge_power_W": 8000,
        "dynamic_max_discharge_power_W": -9000,
        "executed_power_W": -5000,
        "executed_policy": ["setpoint"],
        "errorCodes": {},
        "nr_devices": 1
      }
    }
  }
}

Error response

On a processing error, do not try to read data.state:

{
  "time": 1791547201,
  "requestTime": 1791547200,
  "siteNodeId": "DEMO_CONTROLLER_SiteA",
  "fields": {},
  "data": {
    "responseCode": 1,
    "error": "Command could not be processed"
  }
}

Reading aggregate state

The section names are grid, load, storage, solar, heat_pump, switched_load and variable_power_load. Each asset section combines devices of that type. For example, two solar devices with a capacity of 3 kW each give an aggregate capacity of 6 kW.

solar and storage can be empty objects ({}) when there are no matching devices. The heat-pump, switched-load and variable-power-load sections retain zero counts, empty arrays/maps and applicable nullable power values in that situation.

Treat a missing field or null as unavailable, not as zero. Many measurements are omitted when unknown; some fields explicitly contain null. A total can contain only the devices for which a value is available. Do not infer complete measurement coverage from nr_devices alone.

The following common fields apply to storage, solar, heat_pump, switched_load and variable_power_load:

Grid

Every measurement or limit in state.grid is optional and is omitted when unknown. Values are numbers; power is in watts, energy in watt-hours and current in amperes.

Site load

state.load.load_power_W is a number or null. It reports other site consumption, excluding separately accounted EV charging and heat-pump consumption. It is not total site consumption or another name for grid power.

Storage

Use dynamic_max_charge_power_W and dynamic_max_discharge_power_W for the current feedback format. They replace the former realised_charge_power_W and realised_discharge_power_W fields. Dynamic capability is an estimate, not a guarantee that every requested setpoint can be executed; site and device constraints still apply.

Solar

These numeric fields are omitted when unavailable:

Heat pumps

Switched loads

EV chargers and variable-power loads

The section is named variable_power_load, not variable_load.

Charging energy counters, current limits, pause support and charging sessions belong to individual devices, not this aggregate section.

Individual-device feedback

To include a device's state, the command must contain its <nodeId>_policy field and target a recognized device. A device-specific setpoint on its own does not request individual-device feedback. Neither an empty command nor a periodic snapshot includes it.

The location is:

data.state.<section>.individual_devices.<nodeId>

For example, a command containing both "DEMO_BATTERY_1_policy": "setpoint" and "DEMO_BATTERY_1_power_setpoint_w": -5000 can produce this fragment at data.state.storage:

{
  "executed_policy": ["setpoint"],
  "errorCodes": {},
  "nr_devices": 1,
  "individual_devices": {
    "DEMO_BATTERY_1": {
      "active_power_W": -5000,
      "executed_power_W": -5000,
      "executed_policy": "setpoint",
      "constraint_ph0_label": null,
      "nr_devices": 1
    }
  }
}

Per-device policy, mode and constraint fields are single values, not aggregate lists. Unknown measurements can be null. The device's errorCodes is an array of error/status entries and is included only when that device reports entries; it is not another node-ID map.

EV-only individual fields

A populated charging-session object contains:

Separate VPP connections

vpp_id belongs to a separately configured VPP connection. Do not add it to ordinary live MQTT configuration or commands; the standard feedback state does not require it. Provider-specific additions must not be treated as part of the general live-control interface.

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.