Thing Model Framework
While the Thing Model is optional for compliance with the W3C WoT, it plays a central role in the CityLink framework.
The class diagram above reflects the relationships between the different types of Thing Models in the CityLink framework. The relationships between the different types of Thing Models enforce a modular and extensible architecture while capturing as much information as possible about the devices in the network that can then be used for analytics, code generation, and other purposes in the future.
These relations also serve as a top-level architecture for the expected interactions between the different components of the CityLink framework and as a guide for the development of the Thing Models themselves.
Generally, the developed Thing Models should be as self-contained as possible, linking to other Thing Models via the "extension" and "import" mechanisms provided by the WoT specification. This helps to keep the Thing Models modular and reusable across different implementations and to enforce a single source of truth for the application logic and interaction affordances.
Thing Models should also strive for completeness and detail, limiting possible ambiguity when instantiating Thing Descriptions by replacing fields that require instance-specific metadata with placeholders.
Finally, Thing Models should try to decouple affordance definitions from the communication protocol bindings used to interact with the Thing whenever possible. This helps the development, maintenance, and reusability of Thing Models while creating more possibilities for semantic filtering and grouping of devices in the network.
An AppTM used to instantiate a Thing Description (TD) for an End Node is composed of two submodels: a Platform TM (PlatTM) and a CityLink Embedded Core TM (EmbCTM).
The AppTM may also extend from other Thing Models to inherit common properties or affordances. Additionally, an AppTM can be modeled as a protocol-specific adaptation of a more generic Application TM, designated as "Base Application" in the diagram.
An AppTM models the functionality of an application meant to run on an End Node flashed with a CityLink Embedded Core firmware image. An End Node can be reconfigured by requesting a change of the AppTM that it points to.
- AppTMs must adhere to the General Thing Model Constraints.
- AppTMs must include at least two entries in the
"links"section for the PlatTM and the EmbCTM. - The PlatTM link relation should either be
"tm:submodel"or"tm:extends", and the link instance name should be the term"citylink:platform". - The EmbCTM link relation should either be
"tm:submodel"or"tm:extends", and the link instance name should be the term"citylink:embeddedCore". - AppTMs must use the same type of protocol bindings the EmbCTM utilizes.
A simple TM for a generic temperature sensor application. This TM does not provide protocol-specific bindings or link the required submodels, making it ineligible for direct instantiation. Protocol-specific Application TMs should extend this TM and provide the necessary protocol bindings.
view JSON
{
"@context": [
"https://www.w3.org/2022/wot/td/v1.1"
],
"@type": "tm:ThingModel",
"title": "Generic Temperature Sensor Application",
"description": "A generic temperature sensor",
"version": {
"model": "0.1.0"
},
"properties": {
"temperature": {
"type": "number",
"readOnly": true,
"writeOnly": false,
"description": "Temperature measured by the sensor"
}
}
}This Application TM extends the Generic Temperature Sensor Application TM to provide protocol-specific bindings for MQTT. It also links the submodels for the Platform TM and the Citylink Embedded Core TM, making it eligible for instantiation.
Standard placeholders are used to reference the Thing ID (created upon registration) and the base URL used to reach the Thing which, in this case, will be resolved into an MQTT URL as described in the MQTT binding protocol template.
The "temperature" property is also linked to the corresponding property in the Platform TM to provide a reference to the property's metadata, such as the unit of measure, the measurement range, etc.
view JSON
{
"@context": [
"https://www.w3.org/2022/wot/td/v1.1",
"https://raw.githubusercontent.com/w3c/wot-binding-templates/refs/heads/main/bindings/protocols/mqtt/context.jsonld"
],
"@type": "tm:ThingModel",
"title": "MQTT Temperature Sensor",
"version": {
"model": "0.1.0"
},
"links": [
{
"rel": "tm:submodel",
"href": "https://example.org/wot/thing-models/platforms/temperature-and-humidity-sensor-unit.tm.jsonld",
"type": "application/tm+json",
"instanceName": "citylink:platform"
},
{
"rel": "tm:submodel",
"href": "https://example.org/wot/thing-models/ssa-embedded-core/ssa-core.tm.jsonld",
"type": "application/tm+json",
"instanceName": "citylink:embeddedCore"
},
{
"rel": "tm:extends",
"href": "https://example.org/wot/thing-models/applications/generic-temperature-sensor-application.tm.jsonld",
"type": "application/tm+json"
}
],
"properties": {
"temperature": {
"observable": true,
"tm:ref": "https://example.org/wot/thing-models/platforms/temperature-and-humidity-sensor-unit.tm.jsonld#/properties/temperature",
"forms": [
{
"href": "{{CITYLINK_HREF}}",
"mqv:filter": "{{CITYLINK_PROPERTY}}/temperature",
"mqv:retain": true,
"mqv:qos": 1,
"contentType": "application/json",
"op": [
"readproperty",
"observeproperty",
"unobserveproperty"
]
}
]
}
}
}Referenced by the AppTM, the Platform Thing Model (PlatTM) models the computational platform running the End Node.
For instance, the temperature sensor in the example above may be implemented using a Raspberry Pi Pico W coupled with an analog temperature sensor. Therefore, the Platform Thing Model for this device should be the composition of a TM for the Raspberry Pi Pico W and a TM for the analog temperature sensor being used.
As a general rule of thumb, Platform Thing Models should strive for a high level of detail to provide the network with relevant data about the hardware on the field.
- PlatTMs must adhere to the General Thing Model Constraints.
- PlatTMs should only contain Property Interaction Affordances
- PlatTMs' Property Affordances should have the
"readOnly"field set totrue. - PlatTMs' Property Affordances should have the
"writeOnly"field set tofalse.
This example models a temperature and humidity sensor unit composed of a Raspberry Pi Pico W and a Grove DHT11 sensor. The PlatTM links to the submodels for the Raspberry Pi Pico W and the Grove DHT11 sensor, providing a high-level overview of the hardware used in the Thing.
view JSON
{
"@context": [
"https://www.w3.org/2022/wot/td/v1.1"
],
"@type": "tm:ThingModel",
"title": "Temperature and Humidity Sensor Unit",
"description": "A temperature sensor unit composed of a Raspberry Pi Pico W and a Grove DHT11 sensor",
"version": {
"model": "0.1.0"
},
"links": [
{
"rel": "tm:submodel",
"href": "https://example.org/wot/thing-models/platforms/raspberry-pi-pico-w.tm.jsonld",
"type": "application/tm+json",
"instanceName": "rpi-pico-w"
},
{
"rel": "tm:submodel",
"href": "https://example.org/wot/thing-models/sensors/grove-dht11.tm.jsonld",
"type": "application/tm+json",
"instanceName": "grove-dht11"
}
]
}This example models a Grove DHT11 temperature and humidity sensor. Context extensions include the OM2 namespace for the unit of measure annotations.
view JSON
{
"@context": [
"https://www.w3.org/2022/wot/td/v1.1",
{
"om2": "http://www.ontology-of-units-of-measure.org/resource/om-2/"
}
],
"@type": "tm:ThingModel",
"title": "Grove DHT11 Temperature and Humidity Sensor",
"description": "A Grove DHT11 temperature and humidity sensor",
"version": {
"model": "0.1.0"
},
"properties": {
"temperature": {
"description": "Temperature measured by the sensor in degrees Celsius",
"type": "number",
"readOnly": true,
"minimum": 0,
"maximum": 50,
"unit": "om2:degreeCelsius"
},
"humidity": {
"description": "Relative humidity measured by the sensor in percentage",
"type": "integer",
"readOnly": true,
"minimum": 20,
"maximum": 90,
"unit": "om2:percent"
}
}
}An Embedded Core Thing Model (EmbCTM) models the specific instance of the CityLink Embedded Core firmware image flashed to the End Node. EmbCTMs can be protocol-specific extensions of a more generic EmbCTM as shown in the diagram.
For instance, a CityLink Embedded Core implementation in micropython could support various communication protocols over different interfaces. In this case, the "core" runtime affordances would be modeled in a generic EmbCTM, while the protocol-specific bindings would be modeled in separate EmbCTMs that extend the "core" EmbCTM.
- EmbCTMs must adhere to the General Thing Model Constraints.
- EmbCTMs must provide an
"id"field as a template string, with placeholders for the Thing's id when instantiated. - EmbCTMs may provide the
"id"field indirectly by extending a base EmbCTM that provides the template string. - EmbCTMs that provide protocol-specific bindings may link to a protocol-agnostic EmbCTM used as a reference, using the link relation
"tm:extends". - EmbCTMs that provide protocol-specific bindings must link to their compatible EdgeConTM using the link relation
"controlledBy".
An Edge Connector Thing Model (EdgeConTM) models the CityLink Edge Connector, a software component meant to be deployed at the edge nodes to manage the lifecycle of the End Nodes deployed in the field.
Edge connectors may also operate in "Proxy" mode, acting as intermediaries between End Nodes and consumers.
- EdgeConTMs must adhere to the General Thing Model Constraints.
- EdgeConTMs must include protocol bindings for all supported communication protocols.
- EdgeConTMs must specify the affordance APIs for the lifecycle management of SSA Things.
- EdgeConTMs must specify the affordance APIs for the proxy mode of operation, if applicable.
- EdgeConTMs may include additional affordances for device management, security, and other features.
- Thing Models must conform to the WoT Thing Model specification.
- Thing Models must include a
"title"with a human-readable identifier for the model. - Thing Models must include a
"version"field to track changes to the model. - Thing Models may include a
"links"field to reference other Thing Models or external resources. - Linked Thing Models with the
"tm:submodel"relation should include an"instanceName"field to identify the linked model. - Thing Models may use context extensions and semantic annotations to include additional metadata about the Thing into the model.
- Thing Models must not include any
"id"field unless it is required in the specific model constraints. - Thing Models should follow the Standard SSA Placeholder Recommendations to replace fields that require instance-specific metadata.
When templating the URLs for the interaction affordances in the Thing Models, the following placeholders should be used to replace fields that require instance-specific metadata:
-
{{CITYLINK_ID}}: The unique identifier given to the End Node's Thing Description upon registration. -
{{CITYLINK_HREF}}: The base URL used to reach the End Node. -
{{CITYLINK_TD_HREF}}: The URL used to reach the End Node's Thing Description. -
{{CITYLINK_PROPERTY}}: The base namespace used to reach the End Node's properties. -
{{CITYLINK_ACTION}}: The base namespace used to reach the End Node's actions. -
{{CITYLINK_EVENT}}: The base namespace used to reach the End Node's events.
Note: The concrete values these placeholders resolve to are determined by the Edge Connector implementation and the WoT Protocol Binding used to interact with the End Node.