1 背景

1.1 物模型简介

物模型是设备在物联平台的标准模型，通过标准模型表征该设备的参数指标、控制能力、数据采集能力。平台基于物模型进行设备的标准化管理，并提供标准化的北向接口以及南向标准设备接入报文协议，物模型在物联平台包括品类和产品两种表征方式，品类即安心加标准物模型，产品则是根据厂商设备特性在品类的基础上进行裁剪或者扩展得到的物模型

1.2 物模型应用流程

2 物模型实现方案

2.1 物模型定义过程

2.1.1 明确设备功能

为了方便开发者快速定义产品的功能，开发者在定义产品功能前，首先需要明确产品的功能。

设备	新风面板	环境质量探测器	智能灯	净水器
功能 1	可开关	可查询湿度	可开关	可开关
功能 2	可查询湿度	可查询温度	可调节亮度	可调节模式
功能 3	可查询温度	可查询光照度	可调节颜色	可查询滤芯生命值
功能 4	可调节模式	可查询电量	可度调节色温	可冲洗
功能 5	可调节风速	-	可查询电量	-

2.1.2 功能组（服务）

将待接入设备性质相同的功能分为一组，功能分组后，每个设备可能会有多个功能组

不同的设备的某些功能可能是⼀样的，⽐如：

• 电池类的功能：如查询电量等
• 环境质量传感器类的功能：如查询温度、查询湿度等

设备	新风面板	环境质量探测器	智能灯	净水器
功能组 1	新风	环境质量探测	灯泡	净水
功能组 2	环境质量探测	电池	电池	-

2.1.3 功能组中的功能

将功能组细化：

功能组	新风	环境质量探测	电池	净水	灯泡
功能 1	可开关	可查询湿度	可查询电量	可开关	可开关
功能 2	可调节/查询风速	可查询温度	可查询电压	可调节模式	可调节亮度
功能 3	可调节/查询模式	-	-	可查询滤芯生命值	可调节颜色
功能 4	-	-	-	可冲洗	可度调节色温

2.1.4 物模型定义结果

新风面板

• 新风(服务)

  • 开关
  • 调节/查询风速
  • 调节/查询模式
  • 滤网运行时长

• 环境质量探测（服务）

  • 查询湿度
  • 查询温度

2.2 物模型基本定义

定义	说明	指引
设备	设备是描述一类功能差异不大的设备类型，由服务组成。	是什么设备？ 有哪些服务可⽤？
服务	服务是一个功能组，需要通过抽象定义，由方法、事件、属性组成。	是什么服务？ 有什么⽅法可以操作？ 有什么事件可能会发⽣？ 有哪些属性？
方法	方法可以同时对多个属性进⾏读写，通过一条指令实现更复杂的业务逻辑，由入参属性、出参属性组成。	是什么⽅法？ 输⼊参数是什么？ ⽅法执⾏完有没有输出值，如果有，输出值什么？
事件	事件是描述属性变化上报，由属性组成。	发⽣了什么事情? 哪些属性发⽣了变化？
属性	属性是描述设备运行时的状态、配置参数，由数据格式、参数定义组成。	语义是什么？ 数据格式是什么？ 是否可读？是否可写？数据变化了是否有通知？ 值是否有约束？如果有，取值范围是离散值还是连续值？ 单位是否定义？如果有定义，单位是什么？

2.3 物模型名词解释

Specification

aciga-spec

规范定义

实例定义

type

category

service

property

action

event

instance

iid

2.4 物模型规范定义

2.4.1 规范内容

• SpecificationType 规范
• 设备规范定义
• 服务规范定义
• ⽅法规范定义
• 事件规范定义
• 属性规范定义

2.4.2 SpecificationType 规范

需要有⼀个字段来表达不同的定义，这个字段称之为 SpecificationType

#小米
<URN> ::= "urn:"<namespace>":"<type>":"<name>":"<value>[":"<vendor-product>":"<version>]

#如影
<URN> ::= "urn:"<namespace>":"<type>":"<name>":"<value>[":"<vendor>:"<model>":"<version>]

#安心加（对于产品的定位有差异）
<URN> ::= "urn:"<namespace>":"<type>":"<code>":"<uuid>[":"<vendor>:"<product>":"<version>]

规范定义类型，简写为 type，必须是 URN 格式：

urn:aciga-spec:service:category-information:00007801:aciga:c200:1

字段	描述
urn	第⼀个字段必须为 urn，否则视为⾮法 urn。
namespace	名字空间，如果是安心加定义的规范为 aciga-spec。
type	SpecificationType (类型，简写为: type)，只能是如下几个： - category - service- property - action - event
code	有意义的单词或单词组合(⼩写字⺟)，多个单词⽤"-"间隔，⽐如： temperature、current-temperature、category-name、battery-level
uuid	16 进制字符串，使⽤ UUID 前 8 个字符，如： 00002A06 00002A00
vendor	入网渠道（非供应商，表示该设备通过哪个入网渠道进来的），有意义的单词或单词组合(⼩写字⺟)，⽐如： philips aciga 注：这个字段只有在设备实例定义⾥出现。
product	平台产品型号，有意义的单词或单词组合(⼩写字⺟)，⽐如： c200 a6 mx-5 注：这个字段只有在设备实例定义⾥出现。
version	版本号，只能是数字，如: 1、2、3 注：这个字段只有在设备实例定义⾥出现

2.4.3 属性规范内容

属性描述需要表达这⼏个意思:

• 语义是什么？
• 数据格式是什么？
• 是否可读？是否可写？数据变化了是否有通知？
• 值是否有约束？如果有，取值范围是离散值还是连续值？
• 单位是否定义？如果有定义，单位是什么？

字段	中文名称	描述	设计阶段	模板化阶段	实例化阶段	限制
code	代号	属性的代号	可自定义不可修改	不可编辑	不可编辑	仅支持英文小写字母及中横线，限长 30 字符
type	—	SpecificationType, 简写为 type 事件类型，必须是 URN 表达式，如："type": "urn:aciga-spec:property:color-temperature:0000000F"	后台根据 code 自动生成	不可编辑	不可编辑
description zh-CN	中文名称	纯⽂本字段，对此 property 做⼀个简单的描述	可自定义可修改	可编辑	可编辑	限长 30 字符
description en-US	英文名称	纯⽂本字段，对此 property 做⼀个简单的描述	可自定义可修改	可编辑	可编辑	限长 30 字符
unit	单位	单位	可自定义可修改	可编辑	可编辑
format	格式	数据格式	可自定义可修改	可编辑	可编辑
access	权限	访问⽅式，可多选	可自定义可修改	可编辑	可编辑
value-range	数值范围	对取值范围进⾏约束，可选字段	可自定义可修改	可编辑	可编辑
value-list	数值列表	对取值范围进⾏约束，可选字段	可自定义可修改	可编辑	可编辑
edit-flag	编辑标志位	属性实例化后，能否再编辑的标志位	可自定义可修改	不可编辑	不可见

2.4.3.1 format

数据格式	描述	备注
bool	布尔值: true/false 或 1/0
uint8	⽆符号 8 位整型	建议约束取值范围
uint16	⽆符号 16 位整型	同上
uint32	⽆符号 32 位整型	同上
int8	有符号 8 位整型	同上
int16	有符号 16 位整型	同上
int32	有符号 32 位整型	同上
int64	有符号 64 位整型	同上
float	浮点数	同上
string	字符串	建议约束最⼤⻓度
hex	16 进制	建议约束取值范围

2.4.3.2 access

值	描述
read	读
write	写
notify	通知

2.4.3.3 value-range

最小值	最大值	步长
16	32	0.5

⽤JSON数组表示：
[16, 32, 0.5]

2.4.3.4 **value-list **

当format为整型，可定义"value-list"，每个元素都包含： 
value 
description
[ 
 {"value": 1, "description": "Monday"}, 
 {"value": 2, "description": "Tuesday"}, 
 {"value": 3, "description": "Wednesday"}, 
 {"value": 4, "description": "Thursday"}, 
 {"value": 5, "description": "Friday"}, 
 {"value": 6, "description": "Saturday"}, 
 {"value": 7, "description": "Sunday"} 
]

2.4.3.5 unit

zh-CN	en-US	zh-TW
无	null	无
百分比	percentage	百分比
秒	seconds	秒
分	minutes	分
小时	hours	小時
勒克斯	lux	勒克斯
摄氏度	celsius	攝氏度
华氏度	fahrenheit	華氏度
弧度	arc-degree	弧度
开氏文	kelvin	開氏文
升	litre	升
毫克每立方米	mg/m3	毫克每立方米
帕斯卡	pascal	帕斯卡
ppm 浓度	ppm	ppm 濃度
颜色	rgb	顏色
瓦特	watt	瓦特
安培	ampere	安培
伏特	volt	伏特
千瓦时	kW.h	千瓦時

2.4.3.6 edit-flag

选项
属性可在实例化阶段中编辑
属性不可在实例化阶段中编辑

2.4.3.7 属性 Example

{
        "unit": "percentage",
        "access": ["read", "write", "notify"],
        "iid": 2,
        "format": "uint8",
        "description": {
                "en-US": "Brightness",
                "zh-CN": "亮度"
        },
        "value-range": [1, 100, 1],
        "type": "urn:aciga-spec:property:brightness:00000015:aciga:hy_dim_swi:1"
}

2.4.4 方法规范内容

⼀个有意义的操作需要对多个属性进⾏读写，可以⽤⽅法来实现，描述⼀个⽅法，需要说清楚：

• 是什么⽅法？
• 输⼊参数是什么？
• ⽅法执⾏完有没有输出值，如果有，输出值什么？

字段	中文名称	描述	设计阶段	模板化阶段	实例化阶段	限制
iid	实例 ID	多个方法定义的唯一标识	可自定义不可修改	不可编辑	不可编辑	仅支持英文小写字母及中横线，限长 30 字符
type		SpecificationType, 简写为 type 方法类型，必须是 URN 表达式，如： "type": "urn:aciga-spec:action:play:0000280B"	后台根据 code 自动生成	不可编辑	不可编辑
description zh-CN	中文名称	纯⽂本字段，对此 Action 做⼀个简单的描述	可自定义可修改	可编辑	可编辑	限长 30 字符
description en-US	英文名称	纯⽂本字段，对此 Action 做⼀个简单的描述	可自定义可修改	可编辑	可编辑	限长 30 字符
in	输入参数	输⼊参数列表，可以是 0 到 N 个，每个参数都由属性组成，参数为可变参数，可以重复多次，也可以不出现。	不在此阶段编辑	可编辑	可编辑
out	输出参数	输出参数列表，可以是 0 到 N 个，每个参数都由属性组成，参数为可变参数，可以重复多次，也可以不出现。	不在此阶段编辑	可编辑	可编辑
piid	属性实例 ID	属性实例 ID，在同一个服务中属性定义唯一标识	不在此阶段编辑	可编辑	可编辑
repeat	参数出现次数	[0,1]表示可以为空，[1,1]表示有且只有一个，[1,n]表示可以一个以上。	不在此阶段编辑	可编辑	可编辑

{
        "iid": 1,
        "type": "urn:aciga-spec:action:add-infrared-device:00000c1d:aciga:p1_controller:1",
        "description": {
                "en-US": "Add Infrared Device",
                "zh-CN": "添加红外设备"
        },
        "in": [{
                "piid": 1,
                "repeat": [1, 1]
        }, {
                "piid": 2,
                "repeat": [1, 1]
        }, {
                "piid": 3,
                "repeat": [1, 1]
        }, {
                "piid": 4,
                "repeat": [1, 1]
        }],
        "out": [{
                "piid": 5,
                "repeat": [1, 1]
        }, {
                "piid": 9,
                "repeat": [1, 1]
        }]
}

⽅法在两种情况下引⽤到了属性定义，⼀种是参数列表中的数据，另⼀种是是返回结果列表的数据。在⽬前的设计⾥，⽅法只能引⽤同服务内部的其他属性

2.4.5 事件规范内容

简单的事件，⽤属性的变化来通知⽤户。复杂的事件，需要⽤ Event 来表达:

• 发⽣了什么事情?
• 哪些属性发⽣了变化？

字段	中文名称	描述	设计阶段	模板化阶段	实例化阶段	限制
iid	实例 ID	在多个事件定义中的唯一标识	可自定义不可修改	不可编辑	不可编辑	仅支持英文小写字母及中横线，限长 30 字符
type		SpecificationType, 简写为 type 方法类型，必须是 URN 表达式，如： "type": "urn:aciga-spec:action:play:0000280B"	后台根据 code 自动生成	不可编辑	不可编辑
description zh-CN	中文名称	纯⽂本字段，对此 event 做⼀个简单的描述	可自定义可修改	可编辑	可编辑	限长 30 字符
description en-US	英文名称	纯⽂本字段，对此 event 做⼀个简单的描述	可自定义可修改	可编辑	可编辑	限长 30 字符
arguments	输出参数	可以是 0 到 N 个，每个参数都由属性组成，参数为可变参数，可以重复多次，也可以不出现。	不在此阶段编辑	可编辑	可编辑
piid	属性实例 ID	属性实例 ID，在同一个服务中属性定义唯一标识	不在此阶段编辑	可编辑	可编辑
repeat	参数出现次数	[0,1]表示可以为空，[1,1]表示有且只有一个，[1,n]表示可以一个以上。	不在此阶段编辑	可编辑	可编辑

{
      "iid": 1,
      "description": {
        "en-US": "heartbeat-timeouted",
        "zh-TW": "",
        "zh-CN": "心跳超时事件"
      },
      "arguments": [{
        "piid": 3,
        "repeat": [1, 1]
      }],
      "type": "urn:aciga-spec:event:heartbeat-timeouted:0000533c:aciga:test-switch-008:1"
    }

2.4..6 服务规范内容

服务是⼀个独⽴的有意义的功能组，描述⼀个服务，需要说清楚：

• 是什么服务？
• 有什么⽅法可以操作？
• 有什么事件可能会发⽣？
• 有哪些属性

字段	中文名称	描述	设计阶段	模板化阶段	实例化阶段	限制
iid	服务序号	在多个服务中唯一标识	可自定义不可修改	不可编辑	不可编辑	仅支持英文小写字母及中横线，限长 30 字符
type		SpecificationType, 简写为 type 服务类型，必须是 URN 表达式，如： "type": "urn:aciga-spec:service:fan:00007808"	后台根据 code 自动生成	不可编辑	不可编辑
description zh-CN	中文名称	纯⽂本字段，对此 event 做⼀个简单的描述	可自定义可修改	可编辑	可编辑	限长 30 字符
description en-US	英文名称	纯⽂本字段，对此 event 做⼀个简单的描述	可自定义可修改	可编辑	可编辑	限长 30 字符
properties	属性列表	服务包含了哪些属性列表	可自定义可修改	不可编辑	可编辑
events	事件列表	服务包含了哪些事件列表	可自定义可修改	不可编辑	可编辑
actions	方法列表	服务包含了哪些方法列表	可自定义可修改	不可编辑	可编辑

{
    "iid": 2,
    "description": {
      "en-US": "Heartbeat",
      "zh-CN": "心跳"
    },
    "type": "urn:aciga-spec:service:heartbeat:000007d1:aciga:test-switch-008:1",
    "properties": [{
      "unit": "seconds",
      "access": ["read", "notify"],
      "iid": 1,
      "format": "uint16",
      "description": {
        "en-US": "Heartbeat Intertval",
        "zh-CN": "心跳间隔"
      },
      "value-range": [1, 86400, 1],
      "type": "urn:aciga-spec:property:heartbeat-intertval:00000fca:aciga:test-switch-008:1"
    }, {
      "access": ["read", "notify"],
      "iid": 2,
      "format": "uint16",
      "description": {
        "en-US": "Heartbeat Timeout",
        "zh-CN": "心跳超时次数"
      },
      "value-range": [1, 1000, 1],
      "type": "urn:aciga-spec:property:heartbeat-timeout:00000fcb:aciga:test-switch-008:1"
    }, {
      "unit": "",
      "access": ["notify"],
      "iid": 3,
      "format": "int32",
      "description": {
        "en-US": "heart-time",
        "zh-TW": "",
        "zh-CN": "心跳最后上报时间"
      },
      "type": "urn:aciga-spec:property:heart-time:0000c3b0:aciga:test-switch-008:1"
    }],
    "events": [{
      "iid": 1,
      "description": {
        "en-US": "heartbeat-timeouted",
        "zh-TW": "",
        "zh-CN": "心跳超时事件"
      },
      "arguments": [{
        "piid": 3,
        "repeat": [1, 1]
      }],
      "type": "urn:aciga-spec:event:heartbeat-timeouted:0000533c:aciga:test-switch-008:1"
    }]
  }

2.4.7 产品品类规范内容

产品品类是⼀个独⽴的有意义的品类，⽐如：灯泡、插座、⻛扇。描述⼀个设备，需要说清楚：

• 因此，产品品类规范定义需要包含如下字段：是什么产品品类？

因此，设备规范定义需要包含如下字段：

字段	中文名称	描述	模板化阶段	限制
type		SpecificationType, 简写为 type 设备类型，必须是 URN 表达式，如： "type": "urn:aciga-spec:device:switch:0000000a"	后台根据 code 自动生成
description zh-CN	中文名称	纯⽂本字段，对此 category 做⼀个简单的描述，⽀持多语⾔："description": { "en_US": "Switch", "zh_CN": "开关", "zh_TW": "開關" }	可编辑	限长 30 字符
description en-US	英文名称		可编辑	限长 30 字符

{
	"description": {
		"zh-TW": "开关",
		"zh-CN": "开关",
		"en-US": "switch"
	},
	"type": "urn:aciga-spec:device:switch:0000000a"
}

2.4.8 自定义产品内容

字段	描述	实例化阶段	限制
PID	实例代号，实例唯一识别号	后端生成，不可编辑
category	从后端 api 拉取设备列表
产品型号		新建时自定义不可修改	仅支持英文小写字母及中横线，限长 30 字符
description zh-CN	纯⽂本字段，对此 category 做⼀个简单的描述，⽀持多语⾔："description": { "en_US": "Switch", "zh_CN": "开关", "zh_TW": "開關" }	可自定义可修改	限长 30 字符
description en-US		可自定义可修改	限长 30 字符
连接方式	设备和 IOT 云平台的连接方式	可自定义可修改
设备类型		可自定义可修改
备注		可自定义可修改
开发方式	例如基于 aciga-SDK 接入、MCU+aciga 标准模组	可自定义可修改
选择模组	模组型号	可自定义可修改
配网方式		可自定义可修改
是否支持 OTA	是否支持在线升级	可自定义可修改
系统	设备操作系统，例如 Linux、Free RTOS 等	可自定义可修改

2.4.8.1 连接方式

现阶段暂时支持 4 种

Wi-Fi
ZigBee
BLE Mesh
Wi-Fi+ 网线

2.4.8.2 设备类型

普通设备
网关
网关子设备

2.4.8.3 开发方式

MCU+aciga 标准模组
基于 aciga-SDK 接入

2.4.8.4 选择模组

ESP32-C3 标准模组

2.4.8.5 配网方式

AP 配网
Combo 配网
ZigBee 配网
网线
BLE 配网
BLE Mesh 配网

2.4.8.6 是否支持 OTA

是
否

2.4.8.7 系统

Linux
Free RTOS
无

2.5 物模型规范 DEMO

2.5.1 双键开关

{
  "description": {
    "en-US": "Two-Key Switch",
    "zh-CN": "二键开关"
  },
  "services": [{
    "iid": 1,
    "description": {
      "en-US": "Device Information",
      "zh-CN": "设备信息"
    },
    "type": "urn:aciga-spec:service:device-information:00000001:aciga:test-switch-008:1",
    "properties": [{
      "access": ["read", "notify"],
      "iid": 1,
      "format": "string",
      "description": {
        "en-US": "Firmware Revision",
        "zh-CN": "固件版本"
      },
      "type": "urn:aciga-spec:property:firmware-revision:00000006:aciga:test-switch-008:1"
    }, {
      "access": ["read", "notify"],
      "iid": 2,
      "format": "string",
      "description": {
        "en-US": "Manufacturer",
        "zh-CN": "厂商"
      },
      "type": "urn:aciga-spec:property:manufacturer:00000fa3:aciga:test-switch-008:1"
    }, {
      "access": ["read", "notify"],
      "iid": 3,
      "format": "string",
      "description": {
        "en-US": "Hardware Revision",
        "zh-CN": "硬件版本"
      },
      "type": "urn:aciga-spec:property:hardware-revision:00000fa2:aciga:test-switch-008:1"
    }]
  }, {
    "iid": 2,
    "description": {
      "en-US": "Heartbeat",
      "zh-CN": "心跳"
    },
    "type": "urn:aciga-spec:service:heartbeat:000007d1:aciga:test-switch-008:1",
    "properties": [{
      "unit": "seconds",
      "access": ["read", "notify"],
      "iid": 1,
      "format": "uint16",
      "description": {
        "en-US": "Heartbeat Intertval",
        "zh-CN": "心跳间隔"
      },
      "value-range": [1, 86400, 1],
      "type": "urn:aciga-spec:property:heartbeat-intertval:00000fca:aciga:test-switch-008:1"
    }, {
      "access": ["read", "notify"],
      "iid": 2,
      "format": "uint16",
      "description": {
        "en-US": "Heartbeat Timeout",
        "zh-CN": "心跳超时次数"
      },
      "value-range": [1, 1000, 1],
      "type": "urn:aciga-spec:property:heartbeat-timeout:00000fcb:aciga:test-switch-008:1"
    }, {
      "unit": "",
      "access": ["notify"],
      "iid": 3,
      "format": "int32",
      "description": {
        "en-US": "heart-time",
        "zh-TW": "",
        "zh-CN": "心跳最后上报时间"
      },
      "type": "urn:aciga-spec:property:heart-time:0000c3b0:aciga:test-switch-008:1"
    }],
    "events": [{
      "iid": 1,
      "description": {
        "en-US": "heartbeat-timeouted",
        "zh-TW": "",
        "zh-CN": "心跳超时事件"
      },
      "arguments": [{
        "piid": 3,
        "repeat": [1, 1]
      }],
      "type": "urn:aciga-spec:event:heartbeat-timeouted:0000533c:aciga:test-switch-008:1"
    }]
  }, {
    "iid": 7,
    "description": {
      "en-US": "Switch Status",
      "zh-CN": "开关状态"
    },
    "type": "urn:aciga-spec:service:switch:00000002:aciga:test-switch-008:1",
    "actions": [{
      "iid": 1,
      "description": {
        "en-US": "Toggle",
        "zh-CN": "状态切换"
      },
      "type": "urn:aciga-spec:action:toggle:000007d2:aciga:test-switch-008:1"
    }],
    "properties": [{
      "access": ["read", "write", "notify"],
      "iid": 1,
      "format": "bool",
      "description": {
        "en-US": "on",
        "zh-CN": "开关"
      },
      "type": "urn:aciga-spec:property:on:00000014:aciga:test-switch-008:1"
    }]
  }, {
    "iid": 8,
    "description": {
      "en-US": "Switch Status",
      "zh-CN": "开关状态"
    },
    "type": "urn:aciga-spec:service:switch:00000002:aciga:test-switch-008:1",
    "actions": [{
      "iid": 1,
      "description": {
        "en-US": "Toggle",
        "zh-CN": "状态切换"
      },
      "type": "urn:aciga-spec:action:toggle:000007d2:aciga:test-switch-008:1"
    }],
    "properties": [{
      "access": ["read", "write", "notify"],
      "iid": 1,
      "format": "bool",
      "description": {
        "en-US": "on",
        "zh-CN": "开关"
      },
      "type": "urn:aciga-spec:property:on:00000014:aciga:test-switch-008:1"
    }]
  }],
  "type": "urn:aciga-spec:device:switch:0000000a:aciga:test-switch-008:1"
}