This is an automated email from the ASF dual-hosted git repository.
zqr10159 pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/hertzbeat.git
The following commit(s) were added to refs/heads/master by this push:
new 2e791644a7 [doc] add s7 monitoring help documentation (#4412)
2e791644a7 is described below
commit 2e791644a79a98deef131a48d19fb2fd9beb0d9b
Author: P_Peaceful <[email protected]>
AuthorDate: Wed Sep 30 15:24:27 2026 +0800
[doc] add s7 monitoring help documentation (#4412)
Co-authored-by: Logic <[email protected]>
---
home/docs/help/s7.md | 80 ++++++++++++++++++++++
.../current/help/s7.md | 80 ++++++++++++++++++++++
home/sidebars.json | 1 +
3 files changed, 161 insertions(+)
diff --git a/home/docs/help/s7.md b/home/docs/help/s7.md
new file mode 100644
index 0000000000..c888258479
--- /dev/null
+++ b/home/docs/help/s7.md
@@ -0,0 +1,80 @@
+---
+id: s7
+title: Monitoring Siemens S7 PLC
+sidebar_label: S7 PLC Monitor
+keywords: [open source monitoring tool, Siemens S7 monitoring, PLC monitoring]
+---
+
+> Monitor values and response time exposed by a Siemens S7 PLC over the S7
protocol.
+
+**Protocol: S7**
+
+## Before You Begin
+
+1. Ensure the target PLC is reachable from the HertzBeat collector on the S7
TCP port (default: `102`).
+2. Ensure that the PLC permits the required S7 communication and read access
to the configured addresses.
+3. Obtain the rack ID, slot ID, controller type, and readable variable
addresses from the PLC configuration or the automation engineer.
+
+HertzBeat uses Apache PLC4X `plc4j-driver-s7` 0.12.0 to communicate with the
PLC. Address strings are passed to that driver without conversion. Use the
[PLC4X S7 address
format](https://plc4x.apache.org/plc4x/0.12.0/users/protocols/s7.html) that
matches the target PLC and its variable data types.
+
+## Configuration Parameters
+
+| Parameter | Description |
+|---|---|
+| S7 Server Host | IPv4 address, IPv6 address, or domain name of the target
PLC. Do not include a protocol prefix such as `s7://`. |
+| Port | S7 TCP port of the PLC. The template default is `102`. |
+| rackId | Remote PLC rack number. It must be numeric; the default is `0`. |
+| slotId | Remote PLC CPU slot number. It must be numeric; the default is `0`.
|
+| controllerType | PLC controller type passed to the PLC4X S7 driver. The
template default is `S7_1500`. Supported values are `ANY`, `S7_200`, `S7_300`,
`S7_400`, `S7_1200`, `S7_1500`, and `LOGO`; select the value appropriate for
the target controller. |
+| Request Timeout (ms) | Maximum time to wait for a collection request. The
template default is `6000` ms; valid values are `400` to `200000`. This
advanced parameter is hidden in the UI by default. |
+| Holding Register Addresses | Required list of numeric or other non-Boolean
PLC variables to read. Each item must be a valid PLC4X S7 tag address. |
+| Coil Register Addresses | Required list of Boolean PLC variables to read.
Each item must be a valid PLC4X S7 tag address. Boolean results are reported as
`1` for `true` and `0` for `false`. |
+
+Although the UI uses the names “holding register” and “coil” to group metrics
consistently with the PLC collector, the values entered in both lists are
native S7 tag addresses, not Modbus addresses.
+
+### Address Examples
+
+The address must include the S7 memory location and data type. Common PLC4X S7
examples are:
+
+| Purpose | Example address |
+|---|---|
+| Boolean in data block 1 | `%DB1.DBX0.0:BOOL` |
+| 16-bit signed integer in data block 10 | `%DB10.DBW20:INT` |
+| Boolean input | `%I0.0:BOOL` |
+| 32-bit signed integer in marker memory | `%MD100:DINT` |
+
+For a straightforward configuration, add four single-value addresses to each
address list. The two metric sets each have four fixed output fields. HertzBeat
checks that the number of values produced by each address list is exactly four.
If an address uses the template's batch notation such as `[n]`, it counts as
`n` values; ensure the total expanded count is still four.
+
+## Collected Metrics
+
+### Metric Set: holding-register
+
+This availability metric set runs first. A collection failure prevents the
lower-priority `coil` metric set from running in that collection cycle.
+
+| Metric | Unit | Description |
+|---|---|---|
+| responseTime | ms | Time required to complete the S7 read request. |
+| address-0 | none | First value resolved from the Holding Register Addresses
list. |
+| address-1 | none | Second value resolved from the Holding Register Addresses
list. |
+| address-2 | none | Third value resolved from the Holding Register Addresses
list. |
+| address-3 | none | Fourth value resolved from the Holding Register Addresses
list. |
+
+### Metric Set: coil
+
+| Metric | Unit | Description |
+|---|---|---|
+| responseTime | ms | Time required to complete the S7 read request. |
+| address-0 | none | First value resolved from the Coil Register Addresses
list; Boolean values are converted to `0` or `1`. |
+| address-1 | none | Second value resolved from the Coil Register Addresses
list; Boolean values are converted to `0` or `1`. |
+| address-2 | none | Third value resolved from the Coil Register Addresses
list; Boolean values are converted to `0` or `1`. |
+| address-3 | none | Fourth value resolved from the Coil Register Addresses
list; Boolean values are converted to `0` or `1`. |
+
+## Troubleshooting
+
+| Symptom | Check |
+|---|---|
+| Connection or timeout error | Verify network reachability to the configured
host and port, then confirm that S7 communication is enabled on the PLC. |
+| Connection established but reads fail | Check the rack ID, slot ID,
controller type, and the PLC account or PLC project permissions. |
+| Invalid address or tag read error | Verify the address syntax and data type
against the PLC project and PLC4X S7 address format. |
+| Template validation error about alias fields and addresses | Make sure each
address list expands to exactly four values. |
+| Only holding-register metrics are available | Resolve the holding-register
collection error first; it is the priority-0 availability metric set. |
diff --git a/home/i18n/zh-cn/docusaurus-plugin-content-docs/current/help/s7.md
b/home/i18n/zh-cn/docusaurus-plugin-content-docs/current/help/s7.md
new file mode 100644
index 0000000000..3195b32fda
--- /dev/null
+++ b/home/i18n/zh-cn/docusaurus-plugin-content-docs/current/help/s7.md
@@ -0,0 +1,80 @@
+---
+id: s7
+title: 监控西门子 S7 PLC
+sidebar_label: S7 PLC 监控
+keywords: [开源监控工具, 西门子 S7 监控, PLC 监控]
+---
+
+> 通过 S7 协议采集并监控西门子 S7 PLC 的变量值和响应时间。
+
+**协议：S7**
+
+## 监控前准备
+
+1. 确保 HertzBeat 采集器能够通过 S7 TCP 端口访问目标 PLC，默认端口为 `102`。
+2. 确保 PLC 已启用所需的 S7 通信，并允许读取待监控的变量地址。
+3. 从 PLC 配置或自动化工程师处获取机架号、槽号、控制器类型及可读变量地址。
+
+HertzBeat 使用 Apache PLC4X `plc4j-driver-s7` 0.12.0 与 PLC
通信，地址文本会原样传递给该驱动，不会进行转换。请按目标 PLC 的变量类型使用 [PLC4X S7
地址格式](https://plc4x.apache.org/plc4x/0.12.0/users/protocols/s7.html)。
+
+## 配置参数
+
+| 参数 | 说明 |
+|---|---|
+| S7 服务 Host | 目标 PLC 的 IPv4、IPv6 地址或域名。无需、也不要填写 `s7://` 等协议前缀。 |
+| 端口 | PLC 的 S7 TCP 端口，模板默认值为 `102`。 |
+| rackId | 目标 PLC 的机架号，必须为数字，默认值为 `0`。 |
+| slotId | 目标 PLC CPU 的槽号，必须为数字，默认值为 `0`。 |
+| controllerType | 传递给 PLC4X S7 驱动的 PLC 控制器类型。模板默认值为 `S7_1500`；支持
`ANY`、`S7_200`、`S7_300`、`S7_400`、`S7_1200`、`S7_1500` 和 `LOGO`，应按实际控制器填写。 |
+| 请求超时时间（ms） | 单次采集请求允许等待的最长时间。模板默认值为 `6000` ms，取值范围为 `400` 至
`200000`。该高级参数默认在界面中隐藏。 |
+| 保持寄存器地址 | 必填。用于读取数值型或其他非布尔型 PLC 变量的地址列表；每一项均需为合法的 PLC4X S7 标签地址。 |
+| 线圈寄存器地址 | 必填。用于读取布尔型 PLC 变量的地址列表；每一项均需为合法的 PLC4X S7 标签地址。布尔结果会转换为
`true=1`、`false=0`。 |
+
+界面沿用 PLC 采集器的“保持寄存器”和“线圈”名称来组织指标，但两个列表中填写的都是原生 S7 标签地址，而不是 Modbus 地址。
+
+### 地址示例
+
+地址应包含 S7 内存位置和数据类型。以下为常见 PLC4X S7 地址示例：
+
+| 用途 | 地址示例 |
+|---|---|
+| 数据块 1 中的布尔值 | `%DB1.DBX0.0:BOOL` |
+| 数据块 10 中的 16 位有符号整数 | `%DB10.DBW20:INT` |
+| 布尔输入 | `%I0.0:BOOL` |
+| 标志（Marker）内存中的 32 位有符号整数 | `%MD100:DINT` |
+
+最直接的配置方式是在每个地址列表中填写 4 个单值地址。两个指标集合各自只有 4 个固定输出字段，HertzBeat
会校验每个地址列表产生的读取值数量必须恰好为 4。若某个地址使用模板支持的 `[n]` 批量读取表示法，则会按 `n` 个值计数；请确保展开后的总数仍为 4。
+
+## 采集指标
+
+### 指标集合：holding-register
+
+该指标集合优先级为 `0`，会最先执行。若它采集失败，本次采集不会继续执行优先级较低的 `coil` 指标集合。
+
+| 指标 | 单位 | 说明 |
+|---|---|---|
+| responseTime | ms | 完成一次 S7 读取请求所需的时间。 |
+| address-0 | 无 | 保持寄存器地址列表解析得到的第 1 个值。 |
+| address-1 | 无 | 保持寄存器地址列表解析得到的第 2 个值。 |
+| address-2 | 无 | 保持寄存器地址列表解析得到的第 3 个值。 |
+| address-3 | 无 | 保持寄存器地址列表解析得到的第 4 个值。 |
+
+### 指标集合：coil
+
+| 指标 | 单位 | 说明 |
+|---|---|---|
+| responseTime | ms | 完成一次 S7 读取请求所需的时间。 |
+| address-0 | 无 | 线圈寄存器地址列表解析得到的第 1 个值；布尔值会转换为 `0` 或 `1`。 |
+| address-1 | 无 | 线圈寄存器地址列表解析得到的第 2 个值；布尔值会转换为 `0` 或 `1`。 |
+| address-2 | 无 | 线圈寄存器地址列表解析得到的第 3 个值；布尔值会转换为 `0` 或 `1`。 |
+| address-3 | 无 | 线圈寄存器地址列表解析得到的第 4 个值；布尔值会转换为 `0` 或 `1`。 |
+
+## 常见问题排查
+
+| 现象 | 排查方法 |
+|---|---|
+| 连接失败或超时 | 检查采集器到目标 Host 和端口的网络连通性，并确认 PLC 已启用 S7 通信。 |
+| 已建立连接但读取失败 | 检查 rackId、slotId、controllerType，以及 PLC 账户或 PLC 工程中的读取权限。 |
+| 地址无效或标签读取失败 | 根据 PLC 工程和 PLC4X S7 地址格式检查地址语法与数据类型。 |
+| 出现别名字段与地址数量不匹配的校验错误 | 确认每个地址列表展开后均恰好得到 4 个值。 |
+| 仅有 holding-register 指标 | 先处理 holding-register 的采集错误；它是优先级为 `0` 的可用性指标集合。 |
diff --git a/home/sidebars.json b/home/sidebars.json
index 0fc225382f..ef3c6e90e7 100755
--- a/home/sidebars.json
+++ b/home/sidebars.json
@@ -159,6 +159,7 @@
"help/websocket",
"help/mqtt",
"help/modbus",
+ "help/s7",
"help/jenkins",
"help/push",
"help/registry"
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
