如何使用UltraLight 2.0创建适配FIWARE的IoT设备

以下操作默认你已经完成UltraLight 2.0协议对应的IoT Agent、Orion Context Broker的基础部署，且两个组件之间的对接配置、服务租户/服务路径配置已经调通。

1. 提前梳理设备映射规则 #

UltraLight 2.0本身是为低带宽IoT场景设计的极简报文格式，传感器上报时只会用短字段名传输测量值，因此必须先在IoT Agent侧完成设备预注册，建立短字段和Orion侧NGSI实体属性的映射关系，这也是教程里没覆盖的核心环节：

• 传输层参数：提前规划设备接入用的协议（纯传感器优先选MQTT，低功耗场景适配更好；公网简单部署也可以选HTTP）、租户下唯一的API Key、设备全局唯一的Device ID
• 模型层参数：指定设备在Orion侧对应的实体ID、实体类型，逐个配置传感器测量值的映射：UltraLight报文中的短字段名（object_id）、Orion实体里的正式属性名（name）、属性数据类型。纯上报类传感器不需要配置命令字段，只有需要下发控制指令的执行器才需要加command相关配置。

注意：预注册完成后IoT Agent会自动在Orion侧创建对应实体，不需要手动提前在Orion里插入实体数据。

2. 调用IoT Agent管理接口完成设备注册 #

直接向IoT Agent的设备管理端口（默认4041）发送POST请求提交设备信息即可，示例请求如下：

curl -iX POST \
  'http://<你的IoT Agent服务地址>:4041/iot/devices' \
  -H 'Content-Type: application/json' \
  -H 'fiware-service: openiot' \
  -H 'fiware-servicepath: /' \
  -d '{
  "devices": [
    {
      "device_id": "temp-sensor-001",
      "entity_name": "urn:ngsi-ld:TemperatureSensor:001",
      "entity_type": "TemperatureSensor",
      "protocol": "PDI-IoTA-UltraLight",
      "transport": "MQTT",
      "attributes": [
        { "object_id": "t", "name": "temperature", "type": "Number" },
        { "object_id": "h", "name": "humidity", "type": "Number" },
        { "object_id": "batt", "name": "batteryLevel", "type": "Number" }
      ]
    }
  ]
}'

上面示例里注册了一个温湿度传感器，设备侧上报时用t代指温度、h代指湿度、batt代指电量，同步到Orion后会自动转换为全称属性，方便上层业务调用。

3. 传感器侧按UltraLight 2.0规范上报数据 #

根据你选的传输协议，按对应规则发报文即可：

• MQTT接入：传感器连接MQTT Broker后，向主题 /<你的API Key>/<Device ID>/attrs 发布报文，报文内容为UltraLight格式的键值对，不同字段用|分隔，比如上面注册的传感器上报报文为 t=25.8|h=64.2|batt=98
• HTTP接入：传感器直接向IoT Agent的南向HTTP端口（默认7896）发送POST请求，请求地址为 http://<你的IoT Agent服务地址>:7896/iot/d?k=<你的API Key>&i=temp-sensor-001，请求头Content-Type设为text/plain，请求体和上面MQTT上报的UltraLight报文内容一致。

4. 对接结果验证 #

设备上报数据后，直接调用Orion的查询接口拉取对应实体数据，能看到传感器上报的测量值已经自动同步到实体属性中，就说明设备创建对接成功，示例查询命令：

curl -G 'http://<你的Orion服务地址>:1026/v2/entities/urn:ngsi-ld:TemperatureSensor:001' \
  -H 'fiware-service: openiot' \
  -H 'fiware-servicepath: /' \
  -d 'type=TemperatureSensor'

常见踩坑点：如果数据同步失败，优先检查fiware-service和fiware-servicepath的请求头是否在IoT Agent、Orion两侧完全一致，设备注册时的transport配置和实际接入协议是否匹配，UltraLight报文的短字段名是否和注册时的object_id完全对应。

内容的提问来源于stack exchange，提问作者detonaralph