目录
1. 前言
2. 产品与接口概述
3. 前置准备与设备接入
4. API 通用规范（请求头、签名、编码、错误码）
5. 核心接口详细说明（获取设备地址、单点读变量、单点写变量、批量读取变量）
6. C# 开发实例（配套源码工程说明）
7. PLC 变量点位定义对照表（对应附表变量清单）
8. 常见故障排查
9. 附录（MD5 加密源码、错误码全表）
1 前言
1.1 文档目的
本文档用于指导第三方系统、上位机软件、MES、SCADA 系统通过HTTP/HTTPS Restful API对接辰控智能云组态远程 S7-1200 采集模块，实现 PLC 寄存器变量（M 区、Q 区、DB 块）远程读写采集；文档排版、术语、章节结构参考华为物联网设备 API 说明书标准，规范接口调用逻辑、参数定义、异常处理。
1.2 适用范围
• 硬件：辰控远程采集网关模块（对接西门子 S7-1200 PLC）
• 软件：辰控智能云组态平台、第三方 C#/Java/Python 上位机、MES 生产系统、数据中台
• 接口协议：HTTPS POST/GET，JSON 数据交互格式
1.3 术语定义
术语 | 释义 |
设备 ID | 云平台分配的唯一硬件标识（例：HNEPDQ2SUBZ1），设备入网后固定不变 |
设备 Key | 设备鉴权密钥（例：YA3CQWVOEW1W），用于 MD5 签名加密，建议妥善保管不泄露 |
变量 ID | 云组态数据表中变量的主键 ID（第一张表格 ID 列 1~10），每个 PLC 点位对应唯一 ID |
节点服务器 | 辰控云 API 网关域名地址，全平台统一接入域名 |
当前状态 | PLC 寄存器实时数值（Bit：0/1；Float：0.000；Int：整型数字） |
2 产品与接口概述
2.1 产品简介
辰控云组态远程模块实现西门子 S7-1200 PLC 网口数据上云，将 PLC 内部M 中间寄存器、Q 输出寄存器、DB 数据块寄存器映射至云组态变量表（见第一张业务数据表）；用户通过平台开放 HTTP API，远程读写 PLC 变量，无需现场组态、穿透内网。
已映射点位清单（共 10 路变量）： |
2.2 API 接口能力总览
1. 获取设备网关地址：根据设备 ID+Key，从云平台获取当前设备在线接入节点地址
2. 单点读取变量：输入变量 ID，实时读取 PLC 寄存器当前状态数值
3. 单点写入变量：输入变量 ID + 目标数值，下发指令修改 PLC 对应寄存器
4. 批量读取变量：一次性传入多个变量 ID，批量返回多路 PLC 点位实时数据
3 前置准备与设备接入
3.1 设备入网步骤
1. 辰控远程模块上电，网口接入 S7-1200 PLC 以太网口，PLC 配置对应 DB/M/Q 寄存器；
2. 模块联网接入公网，自动注册至辰控云平台，平台生成设备 ID、设备 Key（Form1 窗体中参数）；
3. 在云组态后台录入变量清单，完成 PLC 地址与变量 ID 绑定，生成变量主键 ID；
4. 记录三项关键参数：设备ID、设备Key、节点服务器域名（窗体中已预置示例：HNEPDQ2SUBZ1 / YA3CQWVOEW1W）。
3.2 开发环境准备
配套 C# 示例工程：API案例.csproj，包含 4 个核心代码文件：
文件名 | 功能说明 |
Form1.cs | 主窗体逻辑（读、写、批量按钮事件） |
Form1.Designer.cs | UI 界面布局 |
HttpClient.cs | HTTP 请求封装类，统一处理 HTTPS 报文 |
MD5Encrypt.cs | MD5 签名加密工具类（鉴权必备） |
开发环境：.NET Framework 4.8，VS2019 及以上版本 |
4 API 通用规范
4.1 通信协议
全接口统一：HTTPS，请求编码：UTF-8，报文格式：JSON；
4.2 通用鉴权规则
所有接口请求必须携带MD5 签名参数，签名算法：
Sign=MD5(设备ID+设备Key+时间戳)
1. 时间戳：Unix 时间戳（秒级，防重放攻击，接口校验时间误差 ±30s）；
2. MD5 结果：32 位小写密文，放入请求 Body/Header；
3. 设备 Key 为私密密钥，禁止明文传输至第三方。
4.3 通用请求 Header
http |
4.4 通用返回 JSON 格式
json |
返回码 code | 说明 |
200 | 接口业务正常 |
401 | 签名错误 / 设备 ID 或 Key 错误 |
404 | 设备离线 / 变量 ID 不存在 |
500 | 云服务器内部异常 |
403 | 设备密钥被冻结 |
5 核心接口详细说明
接口 1：获取设备接入地址
接口信息
• 请求方式：POST
• 请求 URL：{节点服务器}/api/device/GetDeviceAddr
• 功能：根据设备 ID 和密钥，获取设备当前在线网关地址（后续读写接口基于该地址访问）
请求入参（JSON Body）
json |
返回示例
json |
GatewayUrl 为后续读写变量接口基础 URL |
接口 2：单点读取 PLC 变量
接口信息
• 请求方式：POST
• 请求 URL：{GatewayUrl}/api/variable/ReadSingle
• 功能：输入变量 ID，读取对应 PLC 寄存器实时数值（对应 Form 窗体【读取数据】按钮）
请求入参
json |
返回示例（变量 ID=1，M30.1 点位）
json |
接口 3：单点写入 PLC 变量
接口信息
• 请求方式：POST
• 请求 URL：{GatewayUrl}/api/variable/WriteSingle
• 功能：下发数值修改 PLC 寄存器（对应【写入数据】按钮）
请求入参
json |
数据类型约束：Bool 仅支持 0/1；Real 传入浮点如 12.5；Int 传入整数如 100 |
返回示例
json |
接口 4：批量读取多变量
接口信息
• 请求方式：POST
• 请求 URL：{GatewayUrl}/api/variable/ReadBatch
• 功能：一次性读取多个变量 ID（对应【批量读取】按钮）
请求入参
json |
返回示例
json |
6 C# 配套开发实例（基于工程 API 案例.csproj）
6.1 界面对应逻辑（Form1 窗体）
1. 获取设备地址按钮：调用接口 1，回填网关地址至内存；
2. 读取数据按钮：取左侧变量 ID 文本框内容，调用接口 2，结果填充至变量内容；
3. 写入数据按钮：取变量 ID + 变量内容，调用接口 3 下发至 PLC；
4. 批量读取按钮：下方输入框逗号分隔多个 ID，调用接口 4 批量采集。
6.2 关键代码片段
MD5 加密（MD5Encrypt.cs）
csharp |
HttpClient 请求（HttpClient.cs）
封装 PostJson 通用方法，自动拼接请求头，统一收发 JSON 报文。
7 PLC 变量点位映射规范
7.1 寄存器类型说明
1. M 区（中间继电器）：M30.1/M30.2/M30.3 → Bit 型，取值 0/1；
2. Q 区（输出线圈）：Q0.1/Q0.2 → Bit 型，取值 0/1；
3. DB 块（数据块）：
￮ DB1.0/DB1.8/DB1.12：S7 Real (4 字节浮点，保留 3 位小数 0.000)
￮ DB1.20/DB1.24：S7 Int (2 字节有符号整数)
7.2 新增变量扩展规则
云组态后台新增 PLC 点位后，系统自动分配新变量 ID，API 无需修改代码，仅填入新增 ID 即可读写。
8 故障排查指南
故障现象 | 排查方案 |
接口返回 401 签名错误 | 1. 核对设备 ID/Key；2. 校验本地时间戳与服务器时差≤30s；3. 确认 MD5 为 32 位小写 |
返回 404 设备离线 | 1. 检查辰控远程模块供电、PLC 网口接线；2. 确认模块联网接入公网 |
写入数值无变化 | 1. 核对变量 ID 对应 PLC 地址；2.PLC 程序无寄存器被程序强制赋值覆盖 |
浮点读取始终 0.000 | 检查 PLC DB 块属性：取消【优化的块访问】，否则偏移地址 DB1.0 失效 |
9 附录
附录 A：全量错误码清单
| 错误码 | 描述 | 解决方案 |
|401 | 签名鉴权失败 | 核对密钥、时间戳、MD5 算法 |
|404 | 设备不存在 / 离线 | 检查设备入网状态 |
|406 | 变量 ID 无效 | 核对云组态变量 ID 清单 |
|500 | 云端服务异常 | 联系辰控技术支持4008078997 |
附录 B：Python/Java 简易调用示例（可选拓展）
如需其他语言示例可向辰控研发索取 SDK |
附录 C：版本更新记录
| 版本 | 更新日期 | 更新内容 |
|V1.0|2026.06.06 | 初版文档，适配 S71200 云模块 API、配套 C# 案例 |
