SIEMENS PLC Web API 学习记录

SIEMENS PLC Web API 学习记录

为顺应时代发展，西门子为 S7-200SMART/1200/1500 PLC 添加IT通讯所需要的 Web API。（由于S7-200 SMART 新固件必须配合新的硬件才能使用，手头没有），打赏可获取文中测试源代码，部署自己电脑或PLC中测试相关API。

序号	PLC类型	固件开始支持版本	当前API 版本
1	S7-200 SMART	V2.7	未知
2	S7-1200	V4.5	V1.46
3	S7-1500	V2.8	V2.00

Web Api 概述

Web Api 是基于PLC Web Server 实现的，Web Server 是西门子PLC很早就开始支持的特性，提供基础数据查看，诊断、故障更新、变量监测、文件浏览下载等功能，并提供一套 AWP 语法实现自定义网页数据读写监控；从新版本开始支持 Web Api 功能，所谓Web Api就是通讯定义的接口和方法，直接获取PLC运行数据，而不需要登陆网页。具体可以干嘛？官方文档如下：

CPU 提供基于 Web 的 API (​Web API​) 作为读取和写入 CPU 数据的界面。Web API ​可用于：
​- 使用最新的先进技术实现 Web 应用程序
​- 通过脚本和编程语言与 CPU 的 Web 服务器通信
​- 创建可同时连接到多个 CPU 的 Web 应用程序，例如，创建可显示多个 CPU 状态的仪表板

具体包括读写PLC数据，远程监控PLC运行状态等等；

S7-1200/1500 所实现的 Web API 是一个标准的 JSON-RPC 规范的 API 特性，遵循 JSON-RPC 2.0 规范。API 基于 HTTP URL POST方法，即发送 POST 请求到 https://[ip]/api/jsonrpc，CPU 根据权限及请求方法回应相关数据或错误指示。Web API​ 支持 JSON-RPC 2.0 中定义的批量操作。

JSON-RPC API格式

{
    "id": $(in_request),
    "jsonrpc": "2.0",
    "method": $(method), // 方法名称
    "params": $(params) // 方法对应的参数，如果不需要，可忽略
}
// 处理成功返回
{
    "id": $id_in_request,
    "jsonrpc": "2.0",
    "result":"$(data)"
}

// 处理失败返回
{
   "id": $id_in_request,
    "jsonrpc": "2.0",
    "error":{
    	"code": $(error),
    	"message": $(error_message)
    }
}

已经测试的支持的客户端包括 Chrome，Firefox，Edge，Safari 等主流浏览器，Python，GNU Wget，cURL等工具及库。

Web Api 测试

测试 S7-1500 为 CPU 1511-1 PN , 固件版本 2.9.4，最新 V3.0 并没有更新1511。S7-1200 为 CPU 1215C AC/DC/Rl，固件版本 V4.5(V4.6和V4.5相同)。测试工具包括Edge 100+版本，PostMan，JavaScript等

通过实际测试，发现S7-1200/1500 的 Web Api 因为 CPU 计算能力及API版本不同而差异较大，S7-1200 Web Api 响应速度与 S7-1500 相比明显慢，且支持的 API 有限，差异后面会列出；

启用 Web Api 功能

控制器启用 Web Api 的Web Server 方法参见参考资料所附的官方资料，此处不再展开。

值得注意的是，Web Api 的读写权限是与 Web Server 里面配置的权限相关，默认用户名为 EveryBody，默认用户的权限需要配置；管理员权限可以读写PLC数据，读取PLC启停状态，控制PLC启停状态，获取PLC时间，下载文件等等；Api.Version / Api.Browse / Api.Ping 等几个指令是不需要传递权限的，随意调用。

Api.Version/Api.Browse

// api Version
{
    "id": 5,
    "jsonrpc": "2.0",
    "method": "Api.Version"
}
// ---响应----
{
    "jsonrpc": "2.0",
    "id": 5,
    "result": 1.46
}

// api browse
{
    "id": 6,
    "jsonrpc": "2.0",
    "method": "Api.Browse"
}

//响应
{
    "jsonrpc": "2.0",
    "id": 6,
    "result": [
        {
            "name": "Api.Browse"
        },
        {
            "name": "Api.GetCertificateUrl"
        },
        {
            "name": "Api.GetPermissions"
        },
        {
            "name": "Api.Login"
        },
        {
            "name": "Api.Logout"
        },
        {
            "name": "Api.Ping"
        },
        {
            "name": "Api.Version"
        },
        {
            "name": "PlcProgram.Browse"
        },
        {
            "name": "PlcProgram.Read"
        },
        {
            "name": "PlcProgram.Write"
        }
    ]
}

通过 Edge F12 开发者工具，可以清晰看到通讯过程；

Request Head 类型必须是：Content type:application/json

Api.Login/Logout

登陆PLC用的方法并不是传统 Basic Auth 等方法，而是直接在Request_Body传递Json结构体，改变

{
     "method": "Api.Login", // 方法名称
     "params": 
			{
			"user":"UserName", 
			"password":"SecurePassword"
			"include_web_application_cookie":true // V2.9+版本支持cookie功能
			}
			// Api.Login 需要参数必要参数包括"user"，"password"
}
响应会在 "result" 返回
{
"token": "eG9mcHdhaGR0dWVsdm5teGFxcGw=", // 后续用的请求更多用的为token
"web_application_cookie":"Cb5xdhgiokr0dWVsdm5teGCncFb="
}

获取token后，需要在后续 Request Head 中包括'X-Auth-Token': "eG9mcHdhaGR0dWVsdm5teGFxcGw=" 字段，会实现认证权限的包含。

Web Server 认证有效期为 120s，如果120s内没有任何通讯，CPU 会注销事件结束会话。延长会话的方法，即定时发送 Api.Ping 可确保会话保持活动状态。

$.post({
url:"https://192.168.2.132/api/jsonrpc",
headers:{
'X-Auth-Token':"Sy8pe3VNv86rTMldzFBsYzmw12Lg"
},
data:JSON.stringify({"jsonrpc":"2.0", method:"Api.Ping", "id":1}), 
//Api.Ping 不需要任何参数
});

PLC Web Api 核心为浏览、读、写变量

PlcProgram.Browse

通过 PlcProgram.Browse 方法，可以读取变量列表。​要调用 PlcProgram.Browse 方法，需要“read_value”认证。PlcProgram.Browse 方法用到两个参数，有两种用法。

// method 1，返回所有子变量
{
	“mode”:"children",
	"var":"VarName" // 如果 var 变量为空，则返回所有PLC可访问的变量表
}
// method 2 返回变量信息，包括变量地址、DB块、PLC内部数据类型等信息
{
	“mode”:"var",
	"var":"VarName" // 如果 var 变量为空，则返回所有PLC可访问的变量表
}

PlcProgram.Read

​使用 PlcProgram.Read 方法从 CPU 读取单个变量值，要调用 PlcProgram.Read 方法，需要“read_value”认证。PlcProgram.Read 方法用到两个参数mode,var，有两种用法。

// method 1，读取变量实际值
{
	“mode”:"simple", // 默认值，可不写
	"var":"VarName" 
}
// method 2 读取变量原始值，原始值即为 由字节构成的数据底层数组
{
	“mode”:"raw",
	"var":"VarName" 
}
// 如
​以下示例显示在“​raw​”表示中读取“​dword​”类型变量的结果。
[ 1, 47, 233, 0 ]

PlcProgram.Write

PlcProgram.Write 和Read 相似，只是参数中多一个value参数

// method 1，读取变量实际值
{
	“mode”:"simple", // 默认值，可不写
	"value": "VarValue",
	"var":"VarName" 
}
// method 2 读取变量原始值，原始值即为 由字节构成的数据底层数组
{
	“mode”:"raw",
	"var":"VarName" ,
	"value": ["VarValue1", "VarValue2", "VarValue3"],
}
// 如
​以下示例显示在“​raw​”表示中读取“​dword​”类型变量的结果。
[ 1, 47, 233, 0 ]

此处需要注意的是，变量名称的写法，传递给CPU的JSON中变量名称需要和博通调用名称一致，即该加引号需要加引号，如果徒手写json，则可能需要用到转义字符，类似于 "var": "\"MyDB\".MyVariable"。写入或返回的数值类型需要与CPU内部类型对应，支持绝大部分基础数据类型，对于结构体和UDT，建议使用批量调用模式获取，无法通过变量名一次性获取。

• ​布尔 JSON 值必须为：true​ 或 false
• 整数注意数值范围
• JSON 浮点数必须使用 parseFloat 格式化为浮点数
• 日期、时间等数值写入也必须满足TIA对数据格式的要求

Plc.ReadOperatingMode​/Plc.ReadOperatingMode

使用 Plc.ReadOperatingMode 方法可以读取 CPU 的操作模式。​要调用 Plc.ReadOperatingMode 方法，需要“read_diagnostics”认证。​通过 Plc.RequestChangeOperatingMode 方法，为 CPU 请求新的操作模式。​但这只是对工作模式的请求，必须在 CPU 上给出操作模式更改的条件，例如，通过模式选择器的相应位置。可使用 ​Plc.ReadOperatingMode​ 方法检查 CPU 上的工作模式更改是否成功。​要调用 Plc.RequestChangeOperatingMode 方法，需要“change_operating_mode”认证。

ReadOperatingMode 方法无需参数，直接发送即可。

{
    "id": x,
    "jsonrpc": "2.0",
    "method": "Plc.ReadOperatingMode​"
}
// 结果返回
在result 中返回，​STOP，​STARTUP，RUN，​HOLD，unknown等几种模式

写入请求

{
	"id": ,
    "jsonrpc": "2.0",
    "method": "Plc.RequestChangeOperatingMode",
    "params": {
                "mode": "stop" // run,stop
     }
}

批量方法，就是将上述请求Body合并；

[
{"jsonrpc":"2.0", "id":1, method:"PlcProgram.Read"},
{"jsonrpc":"2.0", "id":2, method:"PlcProgram.Read",
params:{"var":"\"MyDB\".InvalidField"}},
{"jsonrpc":"2.0", "id":3, method:"PlcProgram.Read",
params:{"var":"MyDB.MyDate"} },
{"jsonrpc":"2.0", "id":4, method:"PlcProgram.Write",
params:{"var":"\"BoilerControl\".TempSetPoint", value:9001} }
]

Web Api 列表

S7-1200 Api V1.46 提供功能如下：

• Api.Browse
• Api.GetCertificateUrl
• Api.GetPermissions
• Api.Login
• Api.Logout
• Api.Ping
• Api.Version
• PlcProgram.Browse
• PlcProgram.Read
• PlcProgram.Write

S7-1500 Api V2.00 提供Api 在上述基础上，还包括
— v2.9 固件新增 ----

• 用户可以加载的 Web 应用
• Api.BrowseTickets
• Api.CloseTicket
• Plc.ReadOperatingMode
• Plc.RequestChangeOperatingMode
• 票证机制
• WebApp.Browse
• WebApp.BrowseResources
• WebApp.Create
• WebApp.CreateResource
• WebApp.Delete
• WebApp.DeleteResource
• WebApp.DownloadResource
• WebApp.Rename
• WebApp.RenameResource
• WebApp.SetDefaultPage
• WebApp.SetNotAuthorizedPage
• WebApp.SetNotFoundPage
• WebApp.SetResourceETag
• WebApp.SetResourceMediaType
• WebApp.SetResourceModificationTime
• WebApp.SetResourceVisibility
• WebApp.SetState
  — V3.0 固件新增----
• DataLogs.DownloadAndClear
• Files.Browse
• Files.Create
• Files.CreateDirectory
• Files.Delete
• Files.DeleteDirectory
• Files.Download
• Files.Rename
• Plc.CreateBackup
• Plc.ReadSystemTime
• Plc.ReadTimeSettings
• Plc.RestoreBackup

参考资料

1. S7-200 Smart Web API 开发手册
2. SIMATIC S7-1500、SIMATIC 驱动控制器、ET 200SP、ET 200pro Web 服务器
3. WebserverApi Client Library for .NET
4. smart web api初体验 西门子论坛大神贡献的Go版本