Things¶

Things represent real-world devices, parts of devices, actuators, sensors or other entities. They are fine-grained digital twins which are typically contained inside Instances. They have a strict type and there may be many things of the same type running inside SMIP Agents.

Thing facts:

has a globally unique id which consists of two parts:
- the namespace UUID like: TI-f6ab19b0-20ed-41ef-99cc-40bf287f25b7
- the local thing id like: rgb_light_01
- there may be more things grouped together under the same namespace
has a strict type
may have various custom (searchable) attributes
- may be searched or filtered by using Thing Selectors
has access to real-time data from its entity
- declares real-time data variables whose values are obtained from various data sources
- things that directly connect to an entity trough a communication protocol (e.g., modbus, s7, CyBro SCGI etc.) are also called bridges.
may affect its entity (e.g., switch light on/off, change temperature setpoint, open door etc.)
declares its own alarms (e.g., high temperature, low battery etc.)
declares its own events (e.g., motion detected, security key used etc.)
uses scripted rules that listen to data changes and produce various consequences by possibly calling other things or cloud modules.
may send/push real-time data points, alarms and events to various (cloud) targets including Cloud Data Push targets
may be visualized, scripted, affected by instances in SMIP
may expose its data and functionality trough SMIP IoT Data APIs
may be managed and upgraded from SMIP

For more details about things please see chapter 6. IoT Content: cloud and edge in SMIP Architecture and Functionality Overview .

Things exposed in Data API¶

Data API clients may obtain a list of all available thing types by calling READ all thing types info API.

Thing type info API returns:

type namespace like: com.company.smarthome.things
type id like: temperature_sensor-1_0
list of readable attributes: only available trough polling APIs
list of readable/writable/pushable real-time variables
list of pushable alarms
list of pushable events

Thing’s attributes¶

Thing’s attributes are mostly constant values which usually describe a thing. The table below contains attributes and attribute types that may be exposed in IoT APIs.

Prefix	Searchable	Description	Examples
`a:`	true	Basic thing attributes	`a:title` - a label that describes the thing which may be visible to end users `a:enabled` - is thing enabled or disabled (disabled things are usually not present in APIs) `a:root` - is this a root thing / bridge (this relates to thing’s hard-wired hierarchy) `a:bridge` - is this thing a bridge
`x:`	false	Extra thing attributes	`x:type` - the full thing’s type id like: `com.company.smarthome.things.temperature_sensor-1_0` `x:type_namespace` - the type’s namespace like: `com.company.smarthome.things` `x:type_name` - the type without the trailing version: `com.company.smarthome.things.temperature_sensor`
`p:`	true	Thing initialization parameters	These depend on each thing’s type. Parameters are something like: `p:index`, `p:operation_mode`, `p:debug_mode` etc.
`m:`	true	Thing metadata attributes. They may be used by IoT Agents or by SMIP cloud to group things or to affect thing representation and behavior.	These depend on each thing’s type. Attributes are something like: `m:visible_to_users`, `m:is_important`, `m:is_searchable` etc.

API clients may read things’ attributes and real-time data by calling IoT Data APIs, which directly return the requested values (polling-based APIs). For Push-based APIs see next chapter.

Things as data push sources¶

When third-party partners need to access things, they may use polling-based REST IoT Data APIs. However, things are also the primary data push source in SMIP.

When real-time push notification are needed, API clients may subscribe to things’ real-time data changes, alarms and events. One may use Push Data APIs described also in Cloud Data Push. Calls to READ all thing types info API will return the information about what is available to polling APIs and what to push ones.

Using push APIs and protocols is the preferred way of obtaining IoT Data from SMIP.

Thing Selectors¶

Searching for things and grouping things is a common requirement. Many operations may be performed on a thing group not just on a per thing basis.

A thing selector is a query expression that searches for things by using various thing properties like: thing id, thing type, thing parameters, thing metadata attributes etc. The name selector is used on purpose here, since it mimics HTML DOM and CSS selectors.

All selectors are executed on a specific instance.

A simple selector example:

#consumer_1_1 - find the thing with local id consumer_1_1.

Basic selectors¶

Operator	Description	Examples
`*`	Any thing	`*` - find all things
`type`	Thing by exact type (with possible version at the end) Thing by exact type without namespace (with possible version at the end)	`com.company.smart_home.consumer-1_0` - find all v1.0 consumers `consumer-1_0` - find all v1.0 consumers (regardless of their type namespace)
`?type`	Thing by type ignoring possible version at the end Thing by type without namespace ignoring possible version at the end	`?com.company.smart_home.consumer` - find all consumers (regardless of their type version) `?consumer` - find all consumers (regardless of their type version and namespace)
`#`	Thing by local id	`#consumer_1_1` - find the thing with local id consumer_1_1
`:`	TODO - Thing by class	TODO - future development
`,`	Grouping (UNION - multiple selector results in one selector)	`#my_first_consumer,?producer` - find consumer my_first_consumer and all producers

Relational selectors¶

Operator	Description	Examples
`white space`	Descendant thing	`#iot_linker ` - find all things that are descendants of thing iot_linker* `#my_controller ?consumer` - find all consumers that are descendants of thing my_controller
`>`	Direct child thing	`#my_controller > ?consumer` - find all consumers that are direct children of thing my_controller
`~`	General sibling thing	`#my_first_consumer ~ ?producer` - find all producers that are siblings of consumer my_first_consumer

Attribute selectors¶

Operator	Description	Examples
`[a:]` must be one of: STRING: `[a:title='title']` BOOLEAN: `[a:enabled=true\|false]` BOOLEAN: `[a:root=true\|false]` BOOLEAN: `[a:bridge=true\|false]`	Thing with (hardcoded) attribute	`[a:bridge=true]` - find all bridges `[a:bridge=true][a:root=true]` - find all root bridges
`[p:]`	Thing with parameter	`[p:index]` - find all things that have a parameter named index* `?consumer[p:index]` - find all consumers that have a parameter named index `?consumer[p:index=42]` - find all consumers that have a parameter named index that equals 42
`[m:]`	Thing with metadata attribute	`[m:icon]` - find all things that have a metadata attribute named icon* `?consumer[m:icon=31]` - find all consumers that have a metadata attribute icon that equals 31

Attribute types¶

Type	Description	Examples
STRING	A single quoted string (sequence of characters).	`?consumer[a:title='Power Socket']` - find consumers whose title equals Power Socket
NUMERIC	A number with or without a decimal point.	`?consumer[m:thing_display=1]` - find consumers that have a metadata attribute named thing_display with value 1 `?consumer[m:test_attribute=3.14]` - find consumers that have a metadata attribute named test_attribute with value 3.14
BOOLEAN	true or false	`?consumer[a:enabled=true]` - find enabled consumers

Attribute operators¶

Operator	Description	Examples
	Parameter exists	`[p:index]` - find all things that have a parameter named index* (whichever value it has)
`=`	NUMERIC, STRING or BOOLEAN parameter equals	`?consumer[m:thing_display=1][a:title='Power Socket']` - find consumers that have a metadata attribute named thing_display with value 1 and title that equals Power Socket `?consumer[m:icon=4]` - find thing with metadata attribute icon that equals 4 `*[a:root=true]` - find root things
`~=`	Parameter has a STRING value in a whitespace separated list	`?consumer[a:title~='Power']` - find consumers that have a title that contains a separate word ‘Power’ in strings like ‘Power Socket’, ‘… Power …’
`\|=`	Parameter has a hyphen-separated list of STRING values beginning (from the left) with value	`?consumer[a:title\|='test']` - find consumers that have a title that starts with the word test in strings like ‘test-XXXX’
`^=`	Parameter has a STRING value that starts with the given value	`?consumer[a:title^='test']` - find consumers that have a title that contains the word test in strings like ‘testtesttest …’, ‘test …’, ‘test…’
`$=`	Parameter has a STRING value that ends with the given value	`?consumer[a:title$='test']` - find consumers that have a title that contains the word test in strings like ‘…testtesttest’, ‘… test’, ‘…test’
`*=`	Parameter has a STRING value that contains at least one instance of the given value	`?consumer[a:title='test']` - find consumers that have a title* that contains the word test in strings like ‘…testtesttest…’, ‘…test’, ‘test…’
`>=`	Parameter has a NUMERIC value that is greater or equal to the given NUMERIC value	`?consumer[m:icon>=5]` - find consumers that have an icon greater than or equal to 5
`>`	Parameter has a NUMERIC value that is greater the given NUMERIC value	`?consumer[m:icon>5]` - find consumers that have an icon greater than 5
`<=`	Parameter has a NUMERIC value that is lower that or equal to the given NUMERIC value	`?consumer[m:icon<=5]` - find consumers that have an icon lower than or equal to 5
`<`	Parameter has a NUMERIC value that is lower that the given NUMERIC value	`?consumer[m:icon<5]` - find consumers that have an icon lower than 5
`!`	Negation of the first parameter expression that follows	`?consumer[m:thing_display=1]![m:consumer_type='other'][m:flow_display=0]` - find consumers with thing_display that equals 1, consumer type that is NOT ‘other’ and flow_display that equals 0

Selector Combinations¶

All specific selectors described in previous chapters may be combined into one selector as follows:

Simple Combined Selector¶

Selector: BASIC_SELECTOR[ATTRIBUTE_SELECTOR_1]...[ATTRIBUTE_SELECTOR_N]

Meaning: find things such as each thing obeys BASIC_SELECTOR AND [ATTRIBUTE_SELECTOR_1] AND … AND [ATTRIBUTE_SELECTOR_N].

Example: ?consumer[p:index=1][m:icon>0][m:thing_display=1]

Hierarchical combined Selector¶

Selector: SEL_1[ATT_SEL_11]...[ATT_SEL_1N] > SEL_2[ATT_SEL_21]...[ATT_SEL_2N]

Meaning: find things such as each thing obeys ALL given constraints (AND operation).

Example: #my_controller > ?consumer[p:index=1][m:icon>0][m:thing_display=1]

Grouping selectors¶

Selector: SELECTOR_1, ..., SELECTOR_N

Meaning: find things such as each thing obeys SELECTOR_1 OR … OR SELECTOR_N : the result is a UNION of N selectors.

Examples:

#xems_bridge,#consumer_1_1,#consumer_2_1

#xems_bridge>?consumer[p:index>0],#consumer_1_1~?consumer