Thing Model Design Best Practices: How to Divide Properties, Services, and Events
A Thing Model is a standardized, cloud-side description of a physical device. A well-designed Thing Model significantly reduces the complexity of device access and linkage, while a poor one makes later maintenance painful.
Responsibilities of the Three Elements
- Property: A device's state values, readable and writable. Examples: temperature, switch state, working mode. Test: "what is this value right now."
- Service: An action the cloud asks the device to perform, with input and output parameters. Examples: "reboot the device", "set a scheduled task". Test: asking the device to do something.
- Event: A transient message the device proactively reports. Examples: "door sensor triggered", "low battery alarm". Test: something happened on the device.
An Example: Smart Plug
| Element | Identifier | Type | Description |
|---|---|---|---|
| Property | power | bool | Power on/off state |
| Property | voltage | float | Current voltage |
| Service | setTimer | Input: seconds | Set a countdown to power off |
| Event | overload | Output: power | Overload alarm |
Common Pitfalls
- Modeling events as properties: An alarm trigger is instantaneous; storing it as a property makes the semantics of "recovered" ambiguous;
- Overly coarse property granularity: Packing all states into a single JSON string property prevents the Rule Engine from referencing them directly;
- Naming identifiers arbitrarily: Identifiers appear in Topic payloads and Rule Scripts; a consistent lowercase snake_case style is recommended;
- Ignoring data types and units: Numeric properties must be configured with units and value ranges — dashboards and alarms both depend on them.
Summary
Design the Thing Model first, then write the firmware. Treat the Thing Model as the "interface contract" between the device and the platform: the frontend, backend, rules, and dashboards all revolve around it, which keeps rework cost to a minimum.
Related Documentation
- Thing Model: Definition and publishing of properties, services, and events in the open-source edition's Thing Model.
- Thing Model: Introduction to the Thing Model management page in the business edition.
- Product Management: Product creation and Thing Model binding — the prerequisite steps before publishing a Thing Model.