Skip to Content
IoT 应用开发构建你的第一个应用

构建你的第一个应用

本指南介绍构建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: numeric

2. 设置测试环境

测试你的应用需要在至少有一台在线设备的项目中创建开发环境:

  1. 在应用详情页面点击 Develop 打开Cloud IDE。
显示Develop按钮的应用详情页面
  1. 从你有权限的任意项目中选择一台在线设备。
显示不同项目中可用设备的设备选择器
  1. 在侧面板中点击 Create Backend,在项目数据库中创建开发环境。
带有Edge Development控制和创建后端按钮的侧面板

这会在项目数据库中创建 data-template.yml 中定义的表。你可以在项目的Fleet Database视图中查看它们。

Cloud IDE提供完整的VS Code环境,包括文件浏览器、编辑器、终端以及用于构建和部署到设备的Edge Development面板。

带有代码编辑器和Edge Development面板的Cloud IDE

3. 编写边缘代码

你的Docker容器运行在设备上,使用IronFlock SDK与项目数据库交互。

启动时注册设备

当边缘组件启动时,向 devices 实体表追加一行,让仪表板知道设备已上线:

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 表并对新条目做出响应:

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 表:

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 组件。配置 hostport 字段。当用户填写表单并提交时,新行会自动插入到 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

Last updated on