MQTT topics and payloads field definitions

Description

The MQTT topics of the LoggerV and the JSON fields of each message, for integrators. Procedure: Set up the MQTT client. Page fields: MQTT client field definitions.

Topic Placeholders

• {serial}: the LoggerV serial number.
• {client id}: MQTT_ followed by the digits of the LoggerV serial number.
• {plant serial}: the plant control serial, for example PC_10690625.
• {battery serial}: the serial number of a BMS-Ex or BMU-H8 battery.
• {cluster id}: the battery cluster ID, for example lv_0.
• {model}: the device model name or topic group, in lower case, with no spaces. For example bmsem.

Topics the LoggerV Sends

• solarmd/v2/{serial}/bc/variables: all system variables.
• solarmd/v2/{serial}/bc/plantcontrol/{plant serial}/by-type: plant control data in a fixed format. LoggerV software 9.320 or later.
• solarmd/v2/{serial}/bc/plantcontrol/{plant serial}: plant control data in the internal format.
• solarmd/v2/{serial}/bc/storage/{battery serial}: one battery.
• solarmd/v2/{serial}/bc/storage-cluster/{cluster id}: one battery cluster.
• solarmd/v2/{serial}/bc/{model}/{serial number}: the live data of a Deye SUN-SGLP1 or a Solar MD BMS EM.
• solarmd/v2/{serial}/ack/variables/...: replies to commands.
• solarmd/clients/{client id}: the last will message.

Topics the LoggerV Receives

• solarmd/v2/{serial}/cmd/variables: commands that set a system variable. LoggerV software 9.266 or later.
• $SYS/broker/#: broker statistics for the Broker Status tab.

Send Rules

• Topics sent: only the topics that are on in Topic Settings.
• Interval: all enabled topics, once each Publish Interval.
• QoS: the QOS from Message Settings.
• Retained: no.
• Format: JSON.
• First message: after the device of the topic has data.

Message Wrapper

Each message on a bc topic is a wrapper object. The data is in data.

• name: the topic.
• desc: the topic description, usually a serial number.
• group: the topic group.
• data: the payload.
• enabled: always true.
• deprecated: true for an old topic name.

{
    "name": "solarmd/v2/10690625/bc/plantcontrol/PC_10690625",
    "desc": "PC_10690625",
    "group": "Plant Control",
    "data": {}
}

Plant Control By-Type Envelope

The data of the by-type topic.

• schemaVersion: "1.0".
• plantId: the plant serial.
• timestamp: the time of the message, ISO-8601 UTC.
• plant: the plant status.
• devices: the devices, grouped by type code. A type with no devices is not in the list.

Plant Status

• availability: true or false for grid, gen, pv, load and storage.
• alarms: the active plant alarms. Each has code, level and message.
• level: info or warning.
• message: a text for people. Do not parse it.

Device Fields

• serialNumber: the device key. It does not change.
• type: the type code.
• typeId: the type number.
• typeLabel: the type name. Do not parse it.
• label: the name that the installer gave.
• online: true when the device data is live.
• timestamp: the time of the message, ISO-8601 UTC.
• power: the device power.
• energy: the energy counters.

A device that goes offline stays in the list with online false. Do not use its values while online is false.

Device Types

• CTRLSW, CTRLATS: no power and no energy.
• STORAGE: no power and no energy. The power is in storage.power.
• EM: no energy.

Values and Units

Each value is an object with value and unit, for example {"value": -1.8, "unit": "kW"}.

• Active power: kW, 2 decimal places.
• Reactive power: kvar, 2 decimal places.
• Apparent power: kVA, 2 decimal places.
• Energy: kWh, 2 decimal places.
• Cell voltage: V, 3 decimal places.
• Cell temperature: °C, no decimal places.
• No live value: 0.

Power Sign

• GRCP: positive is import. Negative is export.
• Storage: positive is charge. Negative is discharge.

Power Block

• active: active power.
• reactive: reactive power.
• apparent: apparent power.

Energy Block

• import: energy from the grid. GRCP and converters with a grid port.
• export: energy to the grid. GRCP and converters with a grid port.
• charge: energy into the battery. Converters.
• discharge: energy out of the battery. Converters.
• production: energy produced. PV, PVM, GNCP and converters with PV.
• load: energy to the load. LCP and converters with a load port.

Storage Block

• stateOfCharge.percent: state of charge, 0 to 100.
• stateOfCharge.energy: stored energy, kWh.
• capacity: usable capacity, kWh.
• power: battery power, kW.
• chargeHeadroom: charge power still available, kW.
• dischargeHeadroom: discharge power still available, kW.
• valid: true when the battery data is valid.
• minCellVoltage, maxCellVoltage: V.
• minCellTemperature, maxCellTemperature: °C.

Converter Block

• mode: the operating mode of the converter.
• storageClusterId: the battery cluster of the converter.
• gridPower, pvPower, loadPower: the power on each port, as a power block. Only for a port that the converter has.
• offgridSwitchClosed: true when the off-grid switch is closed.
• acGridAvailable: true when the grid side has AC.
• acLoadAvailable: true when the load side has AC.

Grid Block

• target: the power target of the connection point, kW.
• acAvailable: true when the connection point has AC.
• genRequestedOn: true when plant control requests the generator. GNCP only.

Switch Block

The key is switchState.

• closed: CTRLSW: true when closed. CTRLATS: true when input 1 is selected.
• connected: true when the switch IO point is reachable.
• lastCloseTime, lastOpenTime: ISO-8601 UTC. CTRLSW only, when known.

Plant Alarms

• INFO_GRGN_PRIORITY: Grid/Gen Priority.
• INFO_ST_PRIORITY: Storage Priority.
• INFO_GRID_NOT_ACTIVE: Grid unavailable.
• INFO_GEN_ACTIVE: Gen active.
• INFO_GRGN_MIN_LIMIT: Grid/Gen Device Minimum Power Limit.
• INFO_GRGN_MAX_LIMIT: Grid/Gen Device Maximum Power Limit.
• INFO_ST_CHG_LIMIT: Storage Charge Limit.
• WARN_GRGN_DEVICE_MISSING: Grid/Gen Device Missing.

Plant Control Raw Format

The topic with no /by-type carries the internal plant control data. Its fields can change. Use the by-type topic for a new integration.

Battery Payload

The data of a storage and a storage-cluster topic.

• lastUpdate: time of the last reading.
• voltageV: battery voltage, V.
• currentA: battery current, A. On BMS-Ex and storage-cluster topics, positive is charge and negative is discharge.
• powerW: voltageV multiplied by currentA, W.
• capacityP: state of charge, %.
• capacityAh: remaining capacity, Ah.
• ratedCapacityAh: rated capacity, Ah.
• ratedVoltageV: rated voltage, V.
• ratedChargeCurrentA, ratedDischargeCurrentA: on a storage-cluster topic, the rated currents in A. On a storage topic, the rated C-rate of the battery, rounded to a whole number.
• storageName: the battery or cluster name.
• dcConnected, available: true when the battery is available.
• chgCtrlCur_A, dchCtrlCur_A: charge and discharge current limits. A on BMS-Ex and storage-cluster topics. On a BMU-H8 topic, the capacity charge and discharge limits of the BMU.
• chgCtrlVolt_V, dchCtrlVolt_V: charge and discharge voltage limits, V.
• maxCellVolt_V, minCellVolt_V: highest and lowest cell voltage, V.
• maxCellTemp_C, minCellTemp_C: highest and lowest cell temperature, °C.
• maxCellVoltIdx, minCellVoltIdx: the cell number of each voltage extreme.
• maxCellTempUnitIdx, minCellTempUnitIdx: the unit number of each temperature extreme. -1 on BMS-Ex.
• alertMap: the active battery alerts. Storage topics only.

System Variables Payload

The data of the variables topic is a map. The key is the variable ID. Each value has these fields:

• id: the variable ID.
• name, desc, unit: the name, description and unit.
• nameSpace: user, device, calc, plant or io.
• value: the current value.
• valueType: STRING, INTEGER, DOUBLE, LONG or BOOLEAN.
• valid: false when the device of the value is offline.
• editable: true when a command can set the value.
• serialNumber: the device serial. Device data points only.
• formula: the formula. Computed variables only.
• lastModified: time of the last change, ms since 1970.
• lastModNote: the reason for the last change.
• Other fields: version, type, dfDesc, options, trueLabel, falseLabel, lastModifiedBy.

For each field, see System variables field definitions.

Variable Command

Send to solarmd/v2/{serial}/cmd/variables:

{
    "id": "user.njJmjSegYuVk",
    "value": 456,
    "corrId": "req1",
    "note": "Set via MQTT"
}

• id: required. The variable ID, or a name that only one variable has.
• value: required. The new value. Null is not accepted.
• corrId: optional. The reply goes to ack/variables/{corrId}.
• note: optional. The reason for the change. Default: Changed via MQTT.

Variable Command Reply

• With corrId: a reply on solarmd/v2/{serial}/ack/variables/{corrId}.
• With no corrId: a reply only on an error, on solarmd/v2/{serial}/ack/variables/err.
• With no id: the error reply goes to ack/variables/err, also with a corrId.
• QoS: 1, not retained.
• code: 200 for success, 400 for an error.
• message: success, or the error text.
• data: the new value, or null.

Command Errors

• Field [id] must be provided and cannot be null: add id.
• Null value not supported: add a value.
• System Variable does not exist: followed by the ID. The ID or name is not on the LoggerV, or two variables have that name.
• Failed to set system variable value. [id: name] is read-only. A command cannot set this variable.
• Other error text: the JSON is not valid.

Command Guards

• Writable: variables with editable true. Only user variables can have it.
• Read-only: device data points, computed, plant and io variables.
• Access control: the broker only. The LoggerV does not check a myPower24 access level.
• Value type: the LoggerV stores the value as sent.
• Record: a new value makes a System Variable Changed event on the LoggerV.

Last Will

• Topic: solarmd/clients/{client id}.
• Payload: the client ID followed by " disconnected".
• QoS: 0.
• Retained: yes. The LoggerV does not clear it when it connects again.

Deprecated Topics

These old names carry the same data as the topic next to them.

• solarmd/v2/storage/unit/{battery serial}: use bc/storage/{battery serial}.
• solarmd/v2/storage/cluster/{cluster id}: use bc/storage-cluster/{cluster id}.
• solarmd/{device name}/{serial number}: use bc/{model}/{serial number}.

Tips

• To get the by-type topic of every LoggerV on a broker, subscribe to solarmd/v2/+/bc/plantcontrol/+/by-type.
• The wildcard solarmd/v2/+/bc/plantcontrol/# gets both plant control formats.
• Find a device by type and serialNumber, not by its position in the list.