构建你的第一个应用
本指南介绍构建IronFlock应用的典型工作流程:从边缘设备采集数据并在实时仪表板上展示。完成后你将拥有数据模型、边缘逻辑、用户配置表单和实时图表 — 全部通过项目数据库连接。
1. 设计数据模型
从 .ironflock/data-template.yml 文件开始。考虑两类表:
- 实体表 — 跟踪事物的当前状态(设备、机器、连接)。每次变更时追加行;
maintainLatestFlagFor声明哪些列用于标识一个实体,从而可以按需读回每个实体的最新行。 - 时序表 — 随时间收集测量数据(传感器读数、指标)。每行是一个带时间戳的新数据点。
data:
tables:
# 实体表:每个设备一行,最新状态始终可查询
- tablename: devices
maintainLatestFlagFor: ['device_key']
columns:
- id: tsp
dataType: timestamp
- id: device_key
dataType: string
- id: status
dataType: string
- id: device_name
dataType: string
- id: deleted
dataType: boolean
# 实体表:用户配置的Modbus服务器
- tablename: modbus_servers
maintainLatestFlagFor: ['server_id']
columns:
- id: tsp
dataType: timestamp
- id: server_id
dataType: string
- id: host
dataType: string
- id: port
dataType: numeric
- id: deleted
dataType: boolean
# 时序表:来自连接硬件的周期性读数
- tablename: readings
columns:
- id: tsp
dataType: timestamp
- id: server_id
dataType: string
- id: metric
dataType: string
- id: value
dataType: numeric2. 设置测试环境
测试你的应用需要在至少有一台在线设备的项目中创建开发环境:
- 在应用详情页面点击 Develop 打开Cloud IDE。
- 从你有权限的任意项目中选择一台在线设备。
- 在侧面板中点击 Create Backend,在项目数据库中创建开发环境。
这会在项目数据库中创建 data-template.yml 中定义的表。你可以在项目的Fleet Database视图中查看它们。
Cloud IDE提供完整的VS Code环境,包括文件浏览器、编辑器、终端以及用于构建和部署到设备的Edge Development面板。
3. 编写边缘代码
你的Docker容器运行在设备上,使用IronFlock SDK与项目数据库交互。
启动时注册设备
当边缘组件启动时,向 devices 实体表追加一行,让仪表板知道设备已上线:
Python
import asyncio
from ironflock import IronFlock
async def main():
# 将此设备注册为在线
await flock.append_to_table("devices", {
"device_key": os.environ.get('DEVICE_KEY'),
"tsp": now,
"status": "online",
"device_name": os.environ.get('DEVICE_NAME'),
"deleted": False
})
# ... 其余逻辑
flock = IronFlock(mainFunc=main)
flock.run()由于 devices 使用了 maintainLatestFlagFor: ['device_key'],该设备之前的状态行会被自动取代。启用了 latest 过滤的组件始终显示当前状态。
响应用户配置
用户可以通过Board上的表单添加Modbus服务器(见步骤4)。你的边缘代码订阅 modbus_servers 表并对新条目做出响应:
Python
async def main():
# ... 设备注册 ...
# 读取现有Modbus服务器
existing = await flock.getHistory("modbus_servers", {
"limit": 1000,
"filterAnd": [
# "latest": True 只返回每个 server_id 的最新行
{"latest": True},
{"column": "deleted", "operator": "IS", "value": None}
]
})
for server in existing:
create_modbus_connection(server)
# 实时响应新服务器
def on_server_change(*args, **kwargs):
server = args[0] if args else kwargs
if server.get("deleted"):
delete_modbus_connection(server["server_id"])
else:
create_modbus_connection(server)
await flock.subscribe_to_table("modbus_servers", on_server_change)采集时序数据
Modbus连接建立后,定期轮询并将读数写入 readings 表:
Python
async def modbus_poll_loop(server_id, client):
while True:
values = client.read_registers()
for metric, value in values.items():
await flock.publish_to_table("readings", {
"server_id": server_id,
"metric": metric,
"value": value
})
await asyncio.sleep(5)4. 构建Board
打开Board Editor,添加连接到Data Backend表的组件。
显示设备状态
添加一个连接到 devices 表的 Table 组件。在组件的过滤设置中打开 latest 开关,使其始终显示每台设备的当前状态。当设备上线或离线时,表格自动更新。
让用户配置Modbus服务器
添加一个连接到 modbus_servers 表的 Form 组件。配置 host 和 port 字段。当用户填写表单并提交时,新行会自动插入到 modbus_servers 表中 — 无需后端代码处理表单提交。
你的边缘代码通过 subscribeToTable(见步骤3)检测新行并建立Modbus连接。
可视化时序数据
添加一个连接到 readings 表的 Line Chart 组件。将 tsp 映射到X轴,value 映射到Y轴。当设备发送新读数时,图表实时更新 — 无需轮询或手动刷新。
整体架构
┌─────────────────────────────────────────────────────────┐
│ Board(仪表板) │
│ ┌──────────┐ ┌──────────────┐ ┌───────────────────┐ │
│ │ Table │ │ Form │ │ Line Chart │ │
│ │ devices │ │ modbus_servers │ │ readings │ │
│ └────┬─────┘ └──────┬───────┘ └────────┬──────────┘ │
│ │ │ │ │
└───────┼───────────────┼───────────────────┼──────────────┘
│ │ │
┌────▼───────────────▼───────────────────▼────┐
│ 项目数据库 │
│ devices │ modbus_servers │ readings │
└────▲───────────────▲───────────────────▲────┘
│ │ │
┌────┴───────────────┴───────────────────┴────┐
│ 边缘代码(在设备上) │
│ 注册设备 → 读取配置 → 采集数据 │
└──────────────────────────────────────────────┘项目数据库是唯一的数据源。边缘代码向其写入数据,Board实时读取,用户通过表单的操作写回数据库。你的边缘代码可以订阅这些变更来闭合循环 — 无需自定义API端点。
提示
- 从实体表开始。 在添加时序采集之前,先让设备注册和状态表正常运作。
- 使用
maintainLatestFlagFor,适用于任何需要查询当前状态的表。它允许你追加历史记录,并在无需额外代码的情况下读回每个实体的最新行 — 通过组件上的 latest 开关,或在 SDK 过滤条件中使用{"latest": true}。 - 为实体表添加
deleted列,用于用户通过表单管理的表,这样记录可以软删除同时保留历史。 - 需要确认的写入使用
appendToTable(例如:初始设备注册)。高频遥测数据使用publishToTable,适合即发即忘的场景。 - 保持时序表简洁。 一个时间戳、一个来源标识符和测量值。使用Transform表进行聚合。
下一步
如果你的硬件提供了基于Web的HMI或配置界面,你可以使用Embed组件和设备隧道将其直接嵌入到IronFlock Board中。详见嵌入外部HMI。