📚 课程目录第4章 ctrlX Data Layer详解

4. ctrlX Data Layer详解

ctrlX Data Layer（简称 ctrlX DL）是 ctrlX AUTOMATION 中所有应用、功能模块与外部系统共享数据的统一入口。它不是一个简单的变量表，而是一套带类型、带权限、带元数据的地址空间。理解它，关键要抓住四件事：地址空间如何组织、节点由什么构成、数据类型如何约束、访问机制如何工作。这四点决定了你能否正确读写一个数据点，也决定了上层应用能否稳定运行。

一、地址空间：从根节点出发的树形结构

ctrlX DL 的地址空间是一棵以根节点为起点的树。根节点通常写作 /，其下按功能域划分一级分支，例如 framework、motion、plc、diagnostics、admin 等。每个分支继续向下展开，形成类似文件系统的路径。一个完整地址形如：

/motion/axes/axis1/position/actual
/plc/app/Application/Global/MyVariable
/diagnostics/system/cpu/load

路径中的每一段都是一个节点名，节点名区分大小写，且不允许包含空格与斜杠。地址空间由各 Provider 在启动时注册，因此不同设备、不同固件版本下可见的节点集合可能不同。实际开发中，第一步往往不是写代码，而是先用工具浏览地址空间，确认目标节点是否存在、路径是否拼写正确。

二、节点结构：值、类型、权限与元数据

地址空间中的每个节点不仅保存一个值，还携带一组描述信息。可以把节点理解为一个结构化对象，主要包含以下字段：

value：当前值，是读写操作真正作用的对象。
type：数据类型，如 bool、int32、double、string、array、object 等。
access：访问权限，常见为 read、write、readwrite，部分节点只读。
timestamp：值的时间戳，用于判断数据新鲜度。
metadata：单位、描述、最小/最大值等附加信息。

节点分为叶子节点与容器节点。叶子节点直接持有值，容器节点只用于组织层级，本身不保存业务值。例如 /motion/axes 是容器，/motion/axes/axis1/position/actual 是叶子。读取容器节点通常返回其子节点列表，而不是一个标量值。

三、数据类型：读写必须匹配

ctrlX DL 是强类型的。读取时返回的类型由节点定义决定，写入时如果类型不匹配，操作会被拒绝并返回错误。常见类型包括：

类型	说明	示例值
bool	布尔量	true / false
int32 / int64	有符号整数	1000
uint32 / uint64	无符号整数	4000000000
double	双精度浮点	123.456
string	字符串	"AxisReady"
array	同类型数组	[1, 2, 3]
object	结构化对象	{...}

实际写入时，要注意数值范围与精度。例如把 double 节点写成整数 100 通常可以接受，但把 int32 节点写成 100.5 会被拒绝。对于数组节点，写入时通常要求整体替换，而不是只改其中一个元素。若需要修改数组中的某一项，应先读取完整数组，修改后再整体写回。

四、访问机制：读、写、订阅与批量操作

ctrlX DL 提供多种访问方式，最基础的是同步读和同步写。读操作返回节点当前值及时间戳；写操作把新值提交到节点，并触发依赖该节点的订阅者。除了单点读写，还有两类重要机制：

订阅（Subscribe）：客户端注册对某个节点的关注，当值变化时由 Data Layer 主动推送通知。订阅适合监控实时变化，避免轮询。
批量读写（Bulk）：一次请求读取或写入多个节点，减少通信往返。批量读返回多个节点的值，批量写按顺序提交。

访问还受权限控制。每个节点有 access 属性，客户端连接时携带的权限决定了能否读、能否写。如果对只读节点发起写操作，会收到权限错误，而不是静默失败。因此，在编写写入逻辑前，应先确认目标节点的访问权限。

订阅通知不是“每次写入都必然推送”，而是“值发生变化时推送”。如果写入的新值与当前值相同，通常不会触发通知。这一点在调试时容易造成误解。

五、一个可执行的读写示例

下面以读取一个轴的实际位置，并订阅其变化为例。假设目标节点为 /motion/axes/axis1/position/actual，类型为 double，权限为 read。使用 ctrlX DL 的 REST 接口读取：

GET /api/v1/datalayer/motion/axes/axis1/position/actual

返回结果类似：

{
  "type": "double",
  "value": 123.456,
  "timestamp": "2025-01-15T08:30:12.345Z",
  "access": "read"
}

若要订阅该节点，可建立 WebSocket 连接并发送订阅请求。当轴位置变化时，客户端会收到包含新值与时间戳的通知。判断订阅是否生效，可以观察：首次订阅通常返回当前值，之后每次值变化才推送。如果长时间没有推送，先确认节点是否真的在变化，再检查订阅路径与权限。

写入前务必确认数据类型与权限。对 read 节点写入会失败；对 double 节点写入字符串会失败。错误信息通常会指出类型不匹配或权限不足，不要忽略这些返回。

六、实践中的检查顺序

当你面对一个不熟悉的 ctrlX 设备时，建议按以下顺序操作：先用地址空间浏览工具确认目标节点存在；再读取一次，确认类型、权限与当前值；然后根据类型构造写入值；写入后再次读取，确认值已更新且时间戳变化；最后再考虑是否需要订阅。这个顺序能避免大多数“路径写错、类型写错、权限不够”的问题。

掌握 Data Layer 的地址空间、节点结构、数据类型与访问机制，本质上就是掌握“数据在哪里、长什么样、能不能动、怎么动”。这四件事清楚了，后续无论是做数据采集、状态监控还是与上层应用集成，都会有一个稳定的基础。