# Hoymiles MSA Micro Storage MQTT Protocol Development Guide

### 1. Basic Configuration information (Device Publish)
*Note: The device publishes immediately after connecting, for device discovery.*

**topic:**  
`homeassistant/switch/<dev_id>/config`

**payload:**  
```json
{
    "state_topic": "homeassistant/sensor/<dev_id>/device/state",
    "command_topic": "homeassistant/switch/<dev_id>/set",
    "json_attributes_topic": "homeassistant/sensor/<dev_id>/attributes",
    "unique_id": "<dev_id>",
    "device": {
        "identifiers": ["<id>"], 
        "name": "<dev_id>", 
        "manufacturer": "Hoymiles", 
        "model": "MS-A2",
        "sw_version": "1.0.0" 
    }
}
```

**qos:**  
`1`

**retain:**  
`true`

### 2. Basic Attribute Information (Device Publish)
*Note: Upon establishing the connection, the device immediately publishes this message to enable topic synchronization.*

**topic:**  
`homeassistant/sensor/<dev_id>/attributes`

**payload:**  
```json
{
    "supported_topics": {
    "quick_state": "homeassistant/sensor/<dev_id>/quick/state",
    "device_state": "homeassistant/sensor/<dev_id>/device/state",
    "system_state": "homeassistant/sensor/<dev_id>/system/state",
    "switch_ctrl": "homeassistant/switch/<dev_id>/set",
    "ems_mode": "homeassistant/select/<dev_id>/ems_mode/command",
    "power_ctrl": "homeassistant/number/<dev_id>/power_ctrl/set" 
 }
}
```

**qos:**  
`1`

**retain:**  
`true`

**note:**  
`supported_topics` : Indicates the topics the device supports for publishing and subscribing.
`quick_state` : A topic published by the device for rapid updates of device and system status. See Chapter 10 for details.
`device_state` : A topic published by the device for periodic updates of its own status. See Chapter 11 for details.
`system_state` : A topic published by the device for periodic updates of system status. See Chapter 12 for details.
`switch_ctrl` : A topic subscribed to by the device for power on/off control. See Chapter 7 for details. 
`ems_mode` : A topic subscribed to by the device for EMS mode configuration. See Chapter 8 for details. 
`power_ctrl` : A topic subscribed to by the device for power control commands. See Chapter 9 for details. 

### 3. EMS Mode Configuration (Device Publish)
*Note: The device publishes this message immediately after connection to notify the power control rules. This topic is only supported by the master device and standalone units.*

**topic:**  
`homeassistant/select/<dev_id>/ems_mode/config`

**payload:**  
```json
{
    "command_topic": "homeassistant/select/<dev_id>/ems_mode/command",
    "options": ["general", "mqtt_ctrl"],
    "unique_id": "<dev_id>",
    "device": {
    "identifiers": ["<id>"], 
    "name": "<dev_id>", 
    "manufacturer": "Hoymiles", 
    "model": "MS-A2" 
 }
}
```

**qos:**  
`1`

**retain:**  
`true`

**note:**  
`options` : System EMS mode (` general` : Default mode; device manages energy using its inherent logic. `mqtt_ctrl` : Enables device to control power based on MQTT commands. Energy management can be performed via the topic`homeassistant/number/<dev_id>/power_ctrl/set` topic) 

### 4. Power Control Configuration (Device Publish)
*Note: The device publishes immediately after connection to notify the power control rules. This topic is only supported by the master device and standalone units.*

**topic:**  
`homeassistant/number/<dev_id>/power_ctrl/config`

**payload:**  
```json
{
    "name": null,
    "command_topic": "homeassistant/number/<dev_id>/power_ctrl/set",
    "device_class": "power",
    "unit_of_measurement": "w",
    "min": -1000,
    "max": 1000,
    "step": 0.1,
    "unique_id": "<dev_id>",
    "device": {
    "identifiers": ["<id>"], 
    "name": "<dev_id>", 
    "manufacturer": "Hoymiles", 
    "model": "MS-A2" 
 }
}
```

**qos:**  
`1`

**retain:**  
`true`

### 5. State of Charge Display Configuration (Device Publish)
*Note: The device publishes immediately after connection to configure the display of battery state of charge information.*

**topic:**  
`homeassistant/sensor/<dev_id>/soc/config`

**payload:**  
```json
{
    "name": "soc", 
    "state_topic": "homeassistant/sensor/<dev_id>/quick/state", 
    "value_template": "{{ value_json.soc }}",
    "device_class": "battery",
    "unit_of_measurement": "%",
    "device": {
    "identifiers": ["<id>"], 
    "name": "<dev_id>", 
    "manufacturer": "Hoymiles", 
    "model": "MS-A2" 
 }
}
```

**qos:**  
`1`

**retain:**  
`true`

### 6. Battery Charge/Discharge Power Display Configuration (Device Publish)
*Note: The device publishes immediately after connection to configure power display information.*

**topic:**  
`homeassistant/sensor/<dev_id>/bat_p/config`

**payload:**  
```json
{
    "name": "bat_power", 
    "state_topic": "homeassistant/sensor/<dev_id>/quick/state", 
    "value_template": "{{ value_json.bat_p }}",
    "device_class": "power",
    "unit_of_measurement": "W",
    "device": {
    "identifiers": ["<id>"], 
    "name": "<dev_id>", 
    "manufacturer": "Hoymiles", 
    "model": "MS-A2" 
 }
}
```

**qos:**  
`1`

**retain:**  
`true`

### 7. Power On/Off Control (Device Subscribe) [Reserved Feature]
*Note: The device subscribes and responds, but this feature is currently not supported.*

**topic:**  
`homeassistant/switch/<dev_id>/set`

**payload:**  
`ON`

**qos:**  
`1`

**retain:**  
`false`

**note:**  
The payload can be set to types including `ON` and `OFF`.

### 8. EMS mode (Device Subscribe)
*Note: The device subscribes and responds. This topic is only supported by the master device and standalone units.*

**topic:**  
`homeassistant/select/<dev_id>/ems_mode/command`

**payload:**  
`mqtt_ctrl`

**qos:**  
`1`

**retain:**  
`false`

**note:**  
The payload types can be set as specified in the options field under the topic homeassistant/select/<dev_id>/ems_mode/config.

### 9. Power Control (Device Subscribe)
*Note: The device subscribes and responds. This topic is only supported by the master device and standalone units.*

**topic:**  
`homeassistant/number/<dev_id>/power_ctrl/set`

**payload:**  
`80.0`

**qos:**  
`1`

**retain:**  
`false`

**note:**  
The payload range can be set as specified by the min and max fields under the topic homeassistant/number/<dev_id>/power_ctrl/config.

### 10. Second-level Data (Device Publish)
*Note: The device publishes every 1 second, including device and system data.*

**topic:**  
`homeassistant/sensor/<dev_id>/quick/state`

**payload:**  
```json
{
 "grid_on_p": 0.1,
 "grid_off_p": 0.1,
 "bat_sts": "standby",
 "bat_p": 0.1,
 "soc": 0.01,
 "sys_pv_p": 0.1,
 "sys_plug_p": 0.1,
 "sys_bat_p": 0.1,
 "sys_grid_p": 0.1,
 "sys_load_p": 0.1,
 "sys_sp_p": 0.1,
 "sys_soc": 0.01
}
```

**qos:**  
` 0 `

**retain:**  
`false`

**note:**  
`grid_on_p` : Active power at the device’s on-grid port (minimum unit: 0.1 W)
`grid_off_p` : Active power at the device’s off-grid port (minimum unit: 0.1 W) 
`bat_sts` : Battery status of the device (standby: standby, charge: charging, discharge: discharging, lock: locked)  
`bat_p` : Battery power of the device (minimum unit: 0.1 W) 
`soc` : Remaining state of charge of the device (minimum unit: 0.01%)
`sys_pv_p` : System photovoltaic power (minimum unit: 0.1W)  
`sys_plug_p` : System socket power (minimum unit: 0.1W)  
`sys_bat_p` : System battery power (minimum unit: 0.1W)  
`sys_grid_p` : System grid power (minimum unit: 0.1W)  
`sys_load_p` : System load power (minimum unit: 0.1W)  
`sys_sp_p` : System smart socket power (minimum unit: 0.1W)  
`sys_soc` : System battery state of charge (minimum unit: 0.01%)  

### 11. Real-Time Device Data (Device Publish)
*Note: The device publishes every 5 minutes.*

**topic:**  
`homeassistant/sensor/<dev_id>/device/state`

**payload:**  
```json
{
    "grid":[
    {
        "type": "grid_on",
        "v": 0.1,
        "i": 0.01,
        "f": 0.01,
        "p": 0.1,
        "q": 0.1,
        "ein": 1,
        "eout": 1,
        "etin": 1,
        "etout": 1
    },
    {
        "type": "grid_off",
        "v": 0.1,
        "i": 0.01,
        "f": 0.01,
        "p": 0.1,
        "q": 0.1,
        "ein": 1,
        "eout": 1,
        "etin": 1,
        "etout": 1
    },
    {
        "type": "inv",
        "v": 0.1,
        "i": 0.01,
        "p": 0.1,
        "q": 0.1,
        "ein": 1,
        "eout": 1,
        "etin": 1,
        "etout": 1
    }],

    "bat_sts": "standby",
    "bat_v": 0.01,
    "bat_i": 0.01,
    "bat_p": 0.1,
    "bat_temp": 0.1,
    "soc": 0.01,
    "rssi": -10
}
```

**qos:**  
`1`

**retain:**  
`false`

**note:**  
`type` : Device port type (grid_on: on-grid port, grid_off: off-grid port, inv: inverter port)  
`v` : Device port voltage (minimum unit: 0.1V)  
`i` : Device port current (minimum unit: 0.01A)  
`f` : Device port frequency (minimum unit: 0.01Hz)  
`p` : Device port active power (minimum unit: 0.1W)  
`q` : Device port reactive power (minimum unit: 0.1VAR)  
`ein` : Device port input energy of the day (minimum unit: 1Wh)  
`eout` : Device port output energy of the day (minimum unit: 1Wh)  
`etin` : Device port historical cumulative input energy (minimum unit: 1Wh)  
`etout` : Device port historical cumulative output energy (minimum unit: 1Wh)  
`bat_sts` : Device battery status (standby: standby, charge: charging, discharge: discharging, lock: locked)  
`bat_v` : Device battery voltage (minimum unit: 0.01V)  
`bat_i` : Device battery current (minimum unit: 0.01A)  
`bat_p` : Device battery power (minimum unit: 0.1W)  
`bat_temp` : Device battery temperature (minimum unit: 0.1 ° C)  
`soc` : Device remaining state of charge (minimum unit: 0.01%)
`rssi` : Device signal strength (minimum unit: 1dBm)  

### 12. Real-Time System Data (Device Publish)
*Note: The device publishes every 5 minutes. This topic is only supported by the master device and standalone units.*

**topic:**  
`homeassistant/sensor/<dev_id>/system/state`

**payload:**  
```json
{
    "pv_p": 0.1,
    "plug_p": 0.1,
    "bat_p": 0.1,
    "grid_p": 0.1,
    "load_p": 0.1,
    "sp_p": 0.1,
    "soc": 0.01,
    "pv_e": 1,
    "dchg_e": 1,
    "chg_e": 1,
    "plug_out_e": 1,
    "plug_in_e": 1,
 
    "ems_mode": "general"
}
```

**qos:**  
`1`

**retain:**  
`false`

**note:**  
`pv_p` : System photovoltaic power (minimum unit: 0.1W)  
`plug_p` : System socket power (minimum unit: 0.1W)  
`bat_p` : System battery power (minimum unit: 0.1W)  
`grid_p` : System grid power (minimum unit: 0.1W)  
`load_p` : System load power (minimum unit: 0.1W)  
`sp_p` : System smart socket power (minimum unit: 0.1W)  
`soc` : System battery state of charge (minimum unit: 0.01%) 
`pv_e` : System daily photovoltaic energy generation (minimum unit: 1 Wh)  
`dchg_e` : System daily battery-side discharge energy (minimum unit: 1 Wh)
`chg_e` : System daily battery-side charge energy (minimum unit: 1 Wh)  
`plug_out_e` : System daily grid-connected socket output energy (minimum unit: 1 Wh)
`plug_in_e` : System daily grid-connected socket input energy (minimum unit: 1 Wh)
`ems_mode` : Current EMS mode of the system (general: device self-controlled power, mqtt_ctrl: power controlled by MQTT commands)