室内资产实时追踪:从 RTLS 标签到平面图上的实时标记

先想清楚问题,再选无线技术。“投影仪在哪个房间?”“叉车在这条通道的具体位置?”“这辆车有没有经过月台门?”是三个不同的问题,每种技术只擅长回答其中一个。Spatial Map 不挑技术:每一行只需要一个 ID 和一个位置(或读取点)。

RFID 和另外三种不一样:你得到的不是一个移动的点,而是固定读写器上的读取记录。我们的 Retail Mart 演示就是这种模式:85 个读写器分布在闸口、电梯和扶梯处,以脉冲区域的形式显示。详见把 RFID 读写器接入室内地图。

Spatial Map 不是定位引擎,也不会直接和标签或基站通信。坐标由你现有的引擎计算;一个小型中转程序(脚本、Serverless 函数或你的集成中间件)把它的数据流转成数据表的行。应用内没有可配置的 webhook、stream 或 WebSocket 接入:数据表写入 API 就是推送通道。

1. 1
   创建数据表

   在 Tables 中创建一张 Asset (mobile) 类型的数据表,包含标记和提示框所需的字段。例如:asset_tag、asset_name、asset_type、status、location、battery_pct、last_seen、lat、lng 和 elevation_m;如果由中转程序决定颜色,再加上 status_color。参见数据表。

2. 2
   创建密钥

   在数据表的 API & access 标签页点击 Create key。密钥以 sgv_tbl_ 开头,只显示一次,且只能写入这一张表;给每个系统单独一把密钥,吊销其中一把不会影响其他系统。准确的基础 URL 和 curl 示例也从这个标签页复制。

3. 3
   换算成经纬度

   大多数引擎输出的是本地坐标系下以米为单位的 x/y。发送前先换算为 WGS84(用两三个实测点做一次仿射变换),并以米为单位发送高度(elevation_m),这样标记在 3D 中会落在正确的楼层高度。

4. 4
   打包发送

   每隔几秒,把位置或状态有变化的标签放进一次 POST /rows/bulk 发送:一个事务最多 1,000 行。无效的行会在 errors[] 中返回,有效的行照常提交;缺少必填字段或唯一值重复的行会被拒绝。

5. 5
   用 PATCH,别整行覆盖

   POST 会替换整行内容。如果表里还有引擎不知道的数据(设备名称、所属部门),就先把每一行创建一次,之后用 PATCH /rows/bulk 发送位置,它只合并你发送的字段。

# 1) Create or replace rows (full payload) — once per asset,
#    or whenever its master data changes
curl -X POST https://app.spatialmap.io/api/v1/public/tables/rows/bulk \
  -H "Authorization: Bearer $SPATIALMAP_TABLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"rows":[
    {"entityKey":"EQ-0103","payload":{"asset_tag":"EQ-0103","asset_name":"Pallet jack 03",
      "asset_type":"Pallet jack","status":"In use","location":"Dock 2","battery_pct":76,
      "lat":42.4637,"lng":-5.8802,"elevation_m":0.9,"status_color":"#2563eb",
      "last_seen":"2026-10-11T16:28:03Z"}},
    {"entityKey":"EQ-0149","payload":{"asset_tag":"EQ-0149","asset_name":"Torque wrench 02",
      "asset_type":"Tool","status":"Available","location":"Tool crib",
      "lat":42.46345,"lng":-5.88047,"elevation_m":0.9,"status_color":"#16a34a",
      "last_seen":"2026-10-11T16:28:01Z"}}
  ]}'

# 2) Every few seconds: patch only the tags that moved or changed
curl -X PATCH https://app.spatialmap.io/api/v1/public/tables/rows/bulk \
  -H "Authorization: Bearer $SPATIALMAP_TABLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"rows":[
    {"entityKey":"EQ-0103","patch":{"lat":42.46336,"lng":-5.88014,"location":"Dock 4",
      "last_seen":"2026-10-11T16:28:09Z"}}
  ]}'

之后会发生什么:每次写入都会被保存、追加到该行的变更记录,并通知所有打开着的地图,地图随即重新拉取该图层;另有每 30 秒一次的刷新作为兜底。端到端来看,标记比真实资产滞后的时间 = 引擎延迟 + 你的发送间隔。几秒钟是现实的预期;亚秒级追踪不是这条链路的用途。

data link 决定数据表的行如何显示在场地上。做追踪用的模式是 Live location marker:每一行变成一个位于其自身经纬度的标记。典型的追踪配置有两个这样的 data link,每张表一个:

• Equipment 读取一张 Asset (mobile) 类型的 Equipment 表:工具、推车、托盘搬运车、测试设备,凡是贴了标签的都行。lng/lat 决定标记位置,elevation_m 决定高度,asset_name 作为标签,图标表明这是设备;颜色可以来自 status_color 这样的字段,也可以来自针对 Available、In use、Maintenance 等状态的样式规则。
• Staff 读取同类型的 Staff 表,以工牌 ID 作为键。同样的模式,人形图标,标签为姓名,按角色或状态着色。

员工标记 data link 的 Connect fields 设置

在 Connect fields 中把 data link 指向你自己的列名,不必非叫 lat 和 lng(字段映射)。颜色可以直接取自 status_color 这样的字段,也可以用样式规则把 In use、Maintenance 等取值映射成颜色。Map tooltip 步骤决定悬停或点击时显示什么;设备图层可以显示资产编号、类型、状态、位置、电量和最后出现时间。

楼层:一个 data link 可以把记录显示在所有楼层、指定楼层,或每条记录自己标明的楼层。如果你的引擎会报告“Level 1”这样的楼层,就把它作为字段发送,并在楼层范围中选择 From record;这样每个标记只会出现在它所在的楼层。

在查看器或分享链接中,两个图层叠在 3D 平面图上,与场地其他内容一起显示。Layers 面板把数据图层和区域、楼梯、货架、平面图列在一起,班组长可以隐藏员工工牌只看设备,也可以整层关闭(图层面板)。

演示工作区里有好几个场地都在运行这样的 BLE 标签图层:Summit Assembly Plant 车间里的工具和班组,Eastport Cross‑Dock Freight Hub 月台上的叉车和班组,Northgate Electronics 按房间定位的工具和设备,以及 Harborview Corporate Campus 按区域定位的员工、访客和设备;在 Harborview,资产台账和设备借还也在同一张三层地图上。

Preview 中的 Harborview Corporate Campus — Building A

点击标记即可打开详情抽屉:显示该行的所有属性(资产编号、状态、位置、电量、最后出现时间、坐标),下方是 History 区,列出这一行自己的变更时间线。

通过 API 的每一次写入都会保存为一个事件,附带该行的完整快照。由此有两种回看方式,详见数据表历史与回放:

• 按资产:抽屉里的 History 按从新到旧列出该行的每次创建、更新和删除,以及变化的字段。它能回答“3 号托盘搬运车什么时候转为 Maintenance,当时在哪?”
• 按整个图层:在同一张表上再加一个 Historical movement 模式的 data link。它可见时,地图底部会出现 History player:选择时间窗(1h、24h、7d 或 30d),点播放或拖动进度条,每个标记就会跳到该资产在那个时刻的位置。速度表示每秒回放多少历史时间,从 15s/s 到 30m/s。

想看这个故事的资产管理一面(资产台账、设备借还和被追踪的设备在同一张地图上),请查看资产管理解决方案和 Harborview Corporate Campus 展示页;车间里的工具和班组见 Summit Assembly Plant,月台上的叉车和班组见 Eastport Cross‑Dock Freight Hub。文档覆盖了每个环节:data link、数据表写入 API,以及教程用实时标记追踪员工和设备,它会从一张空表开始,一步步搭出同样的链路。