NumericRange — 数组 / 矩阵子段读写
概述
OPC UA Part 4 §7.27 NumericRange 表示 Value 属性的数组 / 矩阵子范围:
| 字符串 | 含义 |
|---|---|
| "" | 整段 |
| "5" | 第 5 个元素 |
| "3:7" | 第 3-7 个 |
| "1:3,2:4" | 二维: 第一维 [1..3], 第二维 [2..4] |
API
| 成员 | 类别 | 读写 | 说明 |
|---|---|---|---|
| NumericRange.ALL | 静态 | 读 | 整段 |
| NumericRange.single(int) | 工厂 | — | 单一索引 |
| NumericRange.span(start, end) | 工厂 | — | 区间 |
| NumericRange.multi(*dims) | 工厂 | — | 多维 |
| NumericRange.parse(s) | 静态 | — | 解析 |
| NumericRange.try_parse(s) | 静态 | — | 安全解析 |
| range.to_string() / str(r) | — | — | 序列化 |
| range.start / end / sub_ranges / is_all | 属性 | 读 | 字段 |
| ua.read_range(nid, range, attr) | 扩展 | 读 | 读子段 |
| ua.write_range(nid, range, value) | 扩展 | 写 | 写子段 |
代码示例
from opcua import DarraOpcUa, NumericRange, Variant, StatusCode
with DarraOpcUa("opc.tcp://localhost:4840") as ua:
ua.connect()
# 1) 读单个元素
with ua.read_range("ns=2;s=Arr", NumericRange.single(3)) as dv:
print(f"Arr[3] = {dv.value}")
# 2) 读区间
with ua.read_range("ns=2;s=Arr", NumericRange.span(0, 99)) as dv:
for v in dv.value.as_array():
print(v)
# 3) 二维矩阵子段
range_2d = NumericRange.multi(NumericRange.span(0, 9), NumericRange.span(0, 9))
with ua.read_range("ns=2;s=Matrix", range_2d) as dv:
print(f"10×10 子矩阵, 共 {len(dv.value.as_array())} 元素")
# 4) 写单个元素
rc = ua.write_range("ns=2;s=Arr", NumericRange.single(0), Variant(42.5))
if rc != StatusCode.GOOD:
print(f"写失败: {rc}")
# 5) 字符串解析
r = NumericRange.parse("3:7")
print(str(r)) # "3:7"
# 6) 整段
with ua.read_range("ns=2;s=Arr", NumericRange.ALL) as dv:
print(f"全部 {len(dv.value.as_array())} 元素")
实现说明
- Stack 不提供 *WithRange PInvoke 时 read_range/write_range 抛
NotImplementedError range.is_all时直接转发 read, 不依赖 Stack 扩展- write_range 只支持数组 / 矩阵节点
错误处理
| StatusCode | 含义 |
|---|---|
| GOOD | 成功 |
| BAD_INDEX_RANGE_INVALID | range 字符串非法 / 节点非数组 |
| BAD_INDEX_RANGE_NO_DATA | range 在数据范围外 |
| BAD_TYPE_MISMATCH | 写入类型不符 |
最佳实践
- 大数组只取片, 省流量
- 矩阵按行 / 列拆:
NumericRange.multi(span(i, i), span(0, cols-1)) - 写入只动改了的索引, 用 single
- 不要每次都 parse, 用 span / single 工厂
跨语言对照
| C# | Python | Java | C++ | Rust | C |
|---|---|---|---|---|---|
| NumericRange | NumericRange | NumericRange | NumericRange | NumericRange | DarraUa_NumericRange |
| ReadRange | read_range | readRange | ReadRange | read_range | DarraUa_Session_ReadRange |
| WriteRange | write_range | writeRange | WriteRange | write_range | DarraUa_Session_WriteRange |