Overview of IoT Things Data Model - Imou Open Platform
Overview of IoT things data model
1. What is a things data model
Things data model refers to digitizing entities in physical space and constructing a data model of that entity in the cloud. In the Internet of Things platform, defining the Things model means defining product functions. After completing the function definition, the system will automatically generate a physical model of the product. The things model describes what a product is, what it can do, and what services it can provide to the outside world.
The things data model uses JSON format file descriptions. It is a digital representation of entities in physical space, such as sensors, vehicle mounted devices, buildings, factories, etc., in the cloud. It describes what the entity is, what it can do, and what information it can provide from three dimensions: property, services, and events. Defining these three dimensions completes the definition of product functionality.
2. Function definition of things data model
Property: Generally used to describe the status of a device during operation, such as the volume switch status of the device, the current ambient temperature read by the environmental monitoring device, etc. Properties can be queried and modified for device functional parameters through read and write operations;
Service: The ability or method of a device to be called externally, with the ability to set input and output parameters. Compared to property, services can implement more complex business logic through a single instruction, such as performing a specific task such as device firmware upgrade;
Event: An event that occurs during the operation of a device. Events generally contain notification information that needs to be perceived and processed externally, and can include multiple output parameters. For example, information on the completion of a task, or the temperature when a device malfunctions or alarms, events can be subscribed and pushed. For details, please refer to "4. Imou Cloud Things Data Model Format".
3. Protocol related to things data model
| Serial Number | Interface functions | description |
|---|---|---|
| 1 | getProductModel: Obtain things data model of product | Obtain the things model of the product based on productId |
| 2 | iotDeviceControl: Call the Service method in the things data model | Using the things model to operate the specified Service method on the device |
| 3 | getIotDeviceProperties: Obtain the property value specified in the things data model | Obtain the property value of the product based on productId |
| 4 | setIotDeviceProperties：Set the property value specified in the things data model | Set the property value of the product based on productId |
4. Imou Cloud Things Data Model Format
{
"schema": "1.0. The version of the things model format template is currently 1.0",
"profile": {
"identifier": "Product model unique identifier (identifying a unique product model, different from SN, SN is identifying a unique device)"
},
"//": "Things Model Properties",
"Properties": [
{
"identifier": "Property unique identifier (unique under the product)",
"ref": "0. property reference number (unique under the product, must be a numeric value string, used in protocol communication)",
"name": "Property name, such as: battery level",
"description": "The annotation of this property",
"accessMode": "rw, property read/write type: read (r) write (w), read-only as r, read and written as rw",
"defaultData": "$value. It can be a single value or an array, check before accessing",
"//": "Basic data types include: int, text, bool, date, enum; complex data types include: struct, array. Taking bool as an example",
"dataType": {
"//": "Use 0 and 1 to refer to, 0 is false, 1 is true",
"type": "bool"
},
"desc": "0 is off, 1 is on",
"DataType": {
"Type": "int (native integer, excluding float type, converted to int type for processing)",
"Specs": {
"Unit": "property unit, property supplementary description class definition, all types can carry",
"//": "Unique to int type, range of values, minimum to maximum",
"Range": [
0,
9
],
"//": "Step size",
"Step": 1
}
},
"//": "The following shows other types of dataType data values.",
"//": "text example",
"DataType": {
"//": "text (the longest native string is 255)",
"Type": "text"
},
"//": "date example",
"DataType": {
"//": "date (text type in YYYY-MM-DD hh: mm: ss format)",
"Type": "date"
},
"//": "enum example",
"DataType": {
"Type": "enum (enumeration type, enumeration items are of type int)",
"Specs": {
"//": "enumeration value, unique to enum type",
"List": [{
"Value": 0,
"Desc": "value description"
},
{
"Value": 1,
"Desc": "value description"
}
]
}
},
"//": "struct example",
"DataType": {
"Type": "struct (structural object type, which can include the basic types mentioned above)",
"//": "specs is an array because it contains multiple basic types",
"Specs": [{
"Identifier": "identifier",
"Ref": "1001",
"Name": "Name",
"Desc": "Description",
"DefaultData": "$value",
"DataType": {
"Type": "int"
}
},
{
"Identifier": "identifier",
"Ref": "1002",
"Name": "Name",
"Desc": "Description",
"DefaultData": "$value",
"DataType": {
"Type": "text"
}
}
]
},
"//": "array example",
"DataType": {
"Type": "array (an array type that can contain the basic types and struct types mentioned above)",
"Specs": {
"//": "Array size, default maximum 128 (unique to the array).",
"Size": 8,
"Item": {
"//": "The type of array element",
"Type": "int"
}
}
},
"//": "Array&struct example",
"DataType": {
"Type": "array (an array type that can contain the basic types and struct types mentioned above)",
"Specs": {
"//": "Array size, default maximum 128 (array specific)",
"Size": 4,
"Item": {
"//": "The type of array element",
"Type": "struct",
"Specs": [{
"Ref": "1001",
"Name": "Name",
"Desc": "Description",
"DefaultData": "$value",
"DataType": {
"Type": "int"
}
},
{
"Ref": "1002",
"Name": "Name",
"Desc": "Description",
"DefaultData": "$value",
"DataType": {
"Type": "text"
}
}
]
}
}
},
"//": "Error code definition, optional",
"ErrorCodes": [{
"//": "Error code enumeration definition",
"Code": 40000,
"Msg": "Error code description"
}]
}
],
"//": "Things Model Services",
"Services": [
{
"Identifier": "Service unique identifier (unique under the product)",
"Ref": "30. Service reference number (unique under the product, must be a numeric value string, used in protocol communication)",
"Name": "Service name",
"Description": "Explanation of service comments",
"InputData": [{
"Identifier": "unique identifier for input parameters",
"Ref": "40. Reference number (unique under the product, must be a numeric value string, used in protocol communication)",
"Name": "Input parameter name",
"Desc": "Input parameter description",
"DataType": {
"//": "Same as the definition in the property"
}
}],
"OutputData": [{
"Identifier": "Parameter unique identifier",
"Ref": "50. Reference number (unique under the product, must be a numeric value string, used in protocol communication)",
"Name": "Parameter name",
"Desc": "Parameter description",
"DataType": {
"//": "Same as the definition in the property"
}
}],
"//": "Error code definition, optional",
"ErrorCodes": [{
"//": "Error code enumeration definition",
"Code": 40000,
"Msg": "Error code description"
}],
"Method": "The name of the method corresponding to the service (generated based on the identifier)"
}
],
"//": "Things Model Events",
"Events": [
{
"Identifier": "Event unique identifier (unique under the product)",
"//": "Event reference number (unique under the product, must be a numeric value string, used in protocol communication)",
"Ref": "10",
"Name": "Event name",
"Description": "Explanation of the event's comments",
"//": "Event type (info, alert, error)",
"Type": "error",
"OutputData": [{
"Identifier": "Parameter unique identifier",
"//": "Parameter reference number (unique under the product, must be a numeric value string, used in protocol communication)",
"Ref": "20",
"Name": "Parameter name",
"Desc": "Parameter Description",
"DataType": {
"//": "Same as the definition in the property"
}
}],
"Method": "The name of the method corresponding to the event (generated based on the identifier)"
}
]
}