这份指南把原始接口文档整理成"先跑通，再扩展"的顺序：先找设备，再读状态，最后再做控制和透传。最适合第一次接入的人：只想快速把 EMS 数据接进自己的程序、看板、网关或平台。

• 适用于 AECC EMS 本地接口接入场景。
• 支持 HA JSON 数据接口、能源控制参数接口、Modbus RTU 透传接口、Modbus TCP 接口。
• 第一次联调建议只开一个接口，先把读取跑通，再扩展到设置和透传。

如果不知道先接哪个接口，按下面这个顺序走，最省时间。

• 设备已上电并成功联网。
• 开发机或网关与 EMS 设备在同一局域网。
• 先拿到设备 IP，默认端口为 TCP 8080。
• 先做读取，确认报文格式和返回结构，再做写入。
• 建议准备 TCP 调试工具、mDNS 工具和 Modbus 工具。

1. 通过 mDNS 发现设备，记录 s_ip 和 s_port。
2. 建立 TCP 连接，默认端口 8080。
3. 先发一个只读 JSON 请求，例如获取设备参数。
4. 检查响应里是否有 Response、SerialNumber、Target 等关键字段。
5. 确认读取正常后，再尝试能源控制参数。
6. 最后再做设置或 Modbus 透传。

JSON 请求里最重要的是几个固定字段：Get / Set / Response / SerialNumber / CommandSource / Target。

请求示例：

{
  "Get": "EnergyParameter",
  "SerialNumber": 1,
  "CommandSource": "Web"
}

mDNS 负责回答两个问题：设备在哪里、这台设备是什么。

7.1 mDNS 字段表

7.2 mDNS 数据示例

{
  "_http._tcp": "SXD-mDNS-IF-NKYWLTS011",
  "SXD-mDNS.local": "8080",
  "s_sn": "NKYWLTS011",
  "s_ip": "192.168.3.206",
  "s_port": "8080",
  "s_type": "131"
}

这个接口最适合做监控、看板和首次联通测试。先把"获取设备参数"跑通，再逐步扩字段。

建议先看顶层摘要字段，再展开设备列表。这样调试时最容易判断是网络问题、报文问题，还是字段解析问题。

8.1 获取设备参数的最短请求

{
  "Get": "EnergyParameter",
  "SerialNumber": 1,
  "CommandSource": "Web"
}

8.2 返回体通常是"顶层摘要 + 多个设备列表"的结构

{
  "Response": "EnergyParameter",
  "SerialNumber": 1,
  "Target": "Web",
  "Storage_list": [{
    "DevAddr": 1,
    "StorageSN": "ZL-2502250374-00039",
    "StorageStatus": 1,
    "PvChargingPower": 0,
    "AcChargingPower": 0,
    "BatterySoc": 100,
    "BatteryDischargingPower": 50,
    "AcInActivePower": -350,
    "OffGridLoadPower": 0,
    "BatteryChargingPower": 0,
    "PvStringCount": 0,
    "Pv1Power": 0,
    "Pv2Power": 0,
    "Pv3Power": 0,
    "Pv4Power": 0
  }],
  "SSumInfoList": {
    "ControlEnableStatus": 1,
    "MeterTotalActivePower": 0,
    "TotalPVPower": 4,
    "TotalPVChargePower": 0,
    "TotalACChargePower": 0,
    "TotalSmartLoadElectricalPower": 0,
    "AverageBatteryAverageSOC": 60,
    "TotalBatteryOutputPower": 9,
    "TotalGridOutputPower": -35,
    "TotalBackUpPower": 0,
    "TotalChargePower": 0
  },
  "ChargerInfoList": [{
    "DevAddr": 55,
    "lsThirdParty": 0,
    "FansDevType": 0,
    "lsInterconnect": 1,
    "ChargerSN": "SXDI78C594",
    "ChargerStatus": 1,
    "Connector1Status": 0,
    "Connector1Power": 0,
    "Connector2Status": 0,
    "Connector2Power": 0,
    "ConnectorElectricity": 0
  }],
  "PlugInfoList": [{
    "DevAddr": 110,
    "lsThirdParty": 0,
    "FansDevType": 6,
    "lsInterconnect": 1,
    "PlugSN": "NKPG1DDC40",
    "PlugStatus": 0,
    "PlugActvePower": 0,
    "PlugVol": 2359,
    "PlugCurrent": 0,
    "PlugRatePower": 2000,
    "PlugElectricity": 0
  }],
  "HotInfoList": [{
    "DevAddr": 150,
    "lsThirdParty": 0,
    "FansDevType": 6,
    "lsInterconnect": 1,
    "HotSN": "SXDI7A47B8",
    "HotStatus": 1,
    "HotActvePower": 0,
    "HotActvePowerMAX": 1200,
    "HotTEMP": 258,
    "HotTEMPMAX": 470
  }]
}

8.3 顶层关键字段

8.4 常见列表字段说明

先按列表分组理解，再按业务字段细看，最不容易迷路。

8.5 SSumInfoList 字段详细拆解

8.6 Storage_list 字段详细拆解

8.7 PlugInfoList 字段详细拆解

8.8 ChargerInfoList 字段详细拆解

8.9 HotInfoList 字段详细拆解

这个接口是"读取和设置控制策略"的入口，适合做限功率、时间段策略、SOC 控制和联动控制。

写参数前建议先读回原值并保存，尤其是功率时段、SOC 阈值和峰谷策略这类会影响现场行为的字段。

9.1 读取请求与返回

请求：

{
  "Get": "EnergycontrolparametersList",
  "SerialNumber": 1,
  "CommandSource": "Web",
  "RegControlField": [
    "PhaseRecognitionTrigger",
    "MeterSelector",
    "SystemMaxPowerLimit",
    "PowerRegulationOperatingPoint"
  ]
}

响应：

{
  "Response": "EnergycontrolparametersList",
  "SerialNumber": 1,
  "Target": "Web",
  "ControlInfoField": {
    "EnergyManagement": "0",
    "ScheduledModeEnabled": "1",
    "PhaseRecognitionTrigger": "0",
    "MeterSelector": "1",
    "SystemMaxPowerLimit": "10800,3600,3600,3600",
    "PhaseRecognitionPowerMultiplier": "50",
    "PowerRegulationOperatingPoint": "10",
    "DeviceGridInputPowerLimit": "800",
    "PeakShavingConfig": "0:0",
    "BaseDischargePower": "0",
    "PeriodValidTimestamp": "2024-09-20 00:00:00",
    "InstantControlPeriod": "255,20261231,0,00:00,23:59,800,0,6,100,10",
    "ValleyChargePowerStrategy": "0",
    "SystemAcChargePowerLimits": "4200,1400,1400,1400",
    "VppDispatchPeriod": "255,20261231,0,00:00,23:59,800,100,10,7000"
  }
}

9.2 设置请求与返回

请求：

{
  "Set": "EnergycontrolparametersList",
  "SerialNumber": 2,
  "CommandSource": "Web",
  "SetControlInfoField": {
    "PhaseRecognitionTrigger": "0",
    "MeterSelector": "1",
    "SystemMaxPowerLimit": "10800,3600,3600,3600",
    "PhaseRecognitionPowerMultiplier": "50",
    "PowerRegulationOperatingPoint": "10",
    "DeviceGridInputPowerLimit": "800"
  }
}

响应：

{
  "Response": "EnergycontrolparametersList",
  "SerialNumber": 2,
  "Target": "Web",
  "SetParametersField": {
    "PhaseRecognitionTrigger": "0",
    "MeterSelector": "1",
    "SystemMaxPowerLimit": "10800,3600,3600,3600"
  }
}

9.3 常用字段速查

9.4 时间段类字段

[时间段使能],[起始时间],[结束时间],[强制取/馈电功率限制],[允许取电功率限制],[功率控制模式],[充电最大 SOC],[放电最小 SOC]

"1,09:00,23:59,1000,500,0,100,10"

9.5 其他组合字段

如果你手里已经有标准 Modbus RTU 报文，不需要重写业务逻辑，直接透传即可。

这个接口适合把现成的 RTU 报文原样转给 EMS。注意 TransmittedData 需要是带 CRC 的完整 RTU 帧，并且字节间用空格分隔。

10.1 透传字段说明

10.2 发送示例

{
  "Set": "DataTransmission",
  "SerialNumber": 1,
  "CommandSource": "Web",
  "SetCommand": {
    "FunctionCode": 3,
    "TransmittedData": "01 03 FE 06 00 03 56 67"
  }
}

10.3 返回示例

{
  "Response": "DataTransmission",
  "SerialNumber": 1,
  "Target": "Web",
  "CommandResponse": {
    "FunctionCode": 3,
    "ControlState": "succeed",
    "TransmittedData": "01 03 06 00 01 02 03 04 05 2F CE"
  }
}

Modbus TCP 用于直接读取 EMS 接入设备寄存器，适合 PLC、网关和工业上位机。

11.1 标准报文示例

请求报文 (0x03)：

00 01 00 00 00 06 01 03 FE 06 00 03

响应报文：

00 01 00 00 00 09 01 03 06 00 01 00 02 00 03