Models and Devices - Cloud of Things Documentation

Model execution for different devices

Models are executed independently for different devices. That is, models for one device can execute in parallel, making use of hardware parallelism where possible, if models are processing data (such as Measurement, Event, or Operation objects) for different devices. When defining a model, you can configure it to use data from only one device, or from a number of devices, with each device being handled independently.

Each model must either:

receive input from a single device, or
receive input for each device within device groups.

A device group is a means of organizing devices. A device group can contain any number of devices or other device groups. When a model uses a device group, the model will act on all devices referred to by the device group, either directly or indirectly through members of the device group that are themselves device groups and have device members (or even “grand-children” device group members). A device can be a member of zero, one or many device groups. See also the information on the Device Management application and grouping devices in the User guide.

Note: A model that acts on a device group only determines the device group membership when the model is activated. If the membership of a device group changes while a model is running, the model will not behave any differently for any new or removed members of the group. If a device group membership is changed, then models that refer to that device group should be de-activated and re-activated.

It is not possible to mix the two types of input blocks above (but see Broadcast devices). However, data from a model processing single devices can be sent to and received from other models, including models for device groups, and vice versa (see Connections between models).

When a model consumes data from groups, the model behaves as if multiple instances of the model are running, as illustrated below, each one processing data from each device independently. Each instance processes data for a different device, but all share the same blocks and block parameters. The values of the wires will be independent for different instances. Any blocks that are stateful, such as the Average (Mean) block, will operate independently of the data from other devices. As with single-device models, if any block causes a runtime error or exception, then the entire model will go into a failed state - it will stop processing data for all devices.

Typically, when using device groups for inputs, all input blocks would use the same group. It is possible to use different device groups. If there are devices in one group but not in another, those blocks will never generate a signal for devices that are not in that group. For some blocks, such as the Expression block, this is not useful - an Expression block will only generate an output if all of the required inputs have received a value, but it may be useful for pulse inputs of a Gate block.

When a model has inputs that are consuming data from a single device, then the output blocks generating synchronous outputs must specify the same device. A model can use any number of output blocks generating asynchronous output, all specifying the same device as input device or different devices. Asynchronous output blocks can also be combined with synchronous output blocks.

When a model has inputs that are consuming data from a device group, all synchronous output blocks must specify the Trigger Device, a special device in the Output category of the palette. The Trigger Device generates data (Measurement, Event or Operation) for whichever device that model instance applies to - or whichever device sent the data to trigger that model instance. Asynchronous output blocks in such models can specify the Trigger Device or any other specific device.

You can use the model editor to change input and output blocks from one device or device group to another. When changing between a device group and a device, output blocks will switch between the Trigger Device and the device specified, so that the model is kept in a usable state. See also Replacing devices, device groups and assets.

The test and simulation modes are only permitted for models using a single device. If you wish to test or simulate a model using a device group, then use the model editor to modify it to apply to a single device within the device group, and then activate the model in test or simulation mode. See Deploying a model for more information on these modes.

Configuring the concurrency level

By default, the Analytics Builder runtime uses 1 CPU core to execute models. If you want to change the number of CPU cores, send a POST request to Cloud of Things that changes the value for the numWorkerThreads key. See Configuration for detailed information.

Typically, this configuration value would be set to the number of CPU cores available for the system, but it may be useful to configure this either higher or lower according to what resources are available. It does not need to scale to the number of devices (that is, it is quite reasonable to have 4 worker threads with hundreds of devices, assuming a moderate event rate per device).

Models consuming data from more than one device

Because each device is processed independently, as noted above, it is only possible to use data from, or generate data for, a single device within each model. However, it is possible to configure the concurrency level to 1, at which point it is possible to activate models which can consume data and generate data across different devices. As the concurrency level (numWorkerThreads) value is a global setting, this means that for a given Analytics Builder environment, it is only possible to achieve either scale up or models that operate across devices.

With the concurrency level set to 1, it is still possible to create models which use device groups as inputs, but these continue to operate independently for each device within the device group, and it is still not possible to mix device group and single device input or output.

Broadcast devices

While Analytics Builder models typically process each device independently, it is sometimes useful to have signals that apply to all devices. These may be signals from devices, or from other systems that are presented as if they were signals from a device. Analytics Builder thus supports devices that are referred to as broadcast devices and signals from these devices are available to all models across all devices.

Broadcast devices can be used as inputs in any model, together with either single device inputs or device group inputs. The diagram below illustrates how a broadcast device applies to all devices within a device group. It is possible to combine signals from devices in a device group with signals from a broadcast device by providing them as different inputs into a processing block such as the Expression block.

Unlike other devices, a broadcast device can only be used for synchronous output of a model that only consumes data from broadcast devices. Broadcast output of the asynchronous type can be generated by a model consuming non-broadcast inputs.

It is also not possible to connect models together using synchronous data from a broadcast device output (that is, no model may use a measurement from a broadcast device that is the output of a different model). Models can be connected together using asynchronous outputs from a broadcast device (that is, models may use an operation from a broadcast device that is the output of a different model).

Identifying broadcast devices

Broadcast devices are identified by the presence of a property on the device object in the inventory for that device; this is the pas_broadcastDevice property. Thus, whether a device is considered a broadcast device or not is global for that device across all models. It is not permitted to use a device group that contains a broadcast device.

Virtual devices

A virtual device is used when a model is deployed in test or simulation mode. See also Deploying a model.

Virtual devices are objects in the Cloud of Things inventory with a c8y_VirtualDevice property. This property refers to the identifier of the real device of which the virtual device is a copy.

Use the creationDate to find out what virtualDevice was created for a model activation and which measurements have that device as their source.

By default, the virtual devices are kept for 30 days. If you want to change this default, you need to change the tenant options. That is, you need to send a POST /tenant/options request. For detailed information, see the information on tenants in the Reference guide. For example, specify the following to set the retention period for the virtual devices to 1 day:

{
    "category": "analytics.builder",
    "key": "retention.virtualDevicesMaxDays",
    "value": "1"
}

Connections between models

You can connect multiple models together using output blocks and input blocks. A model that contains an output block such as Measurement Output (for Measurement objects of Cloud of Things) will generate a series of events, and this can be consumed by a suitable input block (such as Measurement Input) in another model.

Note: The events from one model can only be consumed by another model when all involved models are deployed in production mode. When the models are deployed in test or simulation mode, virtual devices are used and the events from one model can therefore not be consumed by another model.

Input and output blocks identify a series of events by specifying a key for the series of events. This key can be made up of multiple block parameters, and identifies that series of events distinct from other series of events through the same block type. For example:

For Measurement object input and outputs, the key would be the device, the fragment, and the series. The Unit parameter specified in an output block is not considered part of the key (it is for information only) and is not required to match the parameters of the measurement input block.
For Event objects, the key would be the device and the event type.

When one model has a synchronous output block generating a series of events for a given key and a second model has an input block consuming from that same series of events (that is, with the same key parameters), then this forms a connection from the first model to the second. When the first model triggers the output block, this causes the second model to be evaluated with a new input on its input block.

It is also possible to form connections between models using the output from an asynchronous output block. In this case, when the first model triggers the asynchronous output block, the output is generated and sent to the external system (such as Cloud of Things). The data is received back from the external system at some later point in time and causes the evaluation of any other models consuming the data.

Similar to the processing order of wires within a model (see also Processing order of wires), the following applies when an output block in one model generates a series of events that an input block in another model consumes:

A single model can send the same events to more than one other model. This means, it is possible to have a single model perform some common pre-processing, such as unit conversion or calculating an average (with the Average (Mean) block), and that value to be used by multiple other models.
Models are executed in order with respect to the connections between models formed using synchronous output so that the source of a connection is always evaluated before the target of a connection. If a model has connections from multiple blocks all triggered from the same initial event, then they will all evaluate first, and the receiving model will evaluate with all of the inputs once.

Connections formed using asynchronous output do not have a specific execution order. A model consuming the output is executed only when the output is received back from the external system.

Similar to the wire restrictions within a model (see also Wire restrictions), there are restrictions on how output blocks and input blocks can be used to connect models together:

One block across all models is permitted to generate a series of synchronous events for a given key. Multiple output blocks generating asynchronous events can be used within a single model or across multiple models.
No cycles can be created between models using synchronous output. A model that receives events via an input block synchronously generated from another model cannot include an output block that generates synchronous events that the other model would consume. This applies even if one of the models contains two separate parts, such that there is no actual cycle in terms of wires and connections between models. Cycles among models can be created because of asynchronous outputs. Therefore, care must be taken not to introduce indefinite cyclic executions of models.

Any model that does not meet these restrictions when used in combination with the already activated models will cause an error on trying to activate it. This will count for the last element in a cycle of models. For such errors, the problem may be in interactions between models rather than a problem specific to a single model, but existing models that have already been activated will not automatically be deactivated. For example, if multiple models all generate the same series of synchronous events (with the same key), then the first model to be activated can be deployed, but all subsequent models will report an error upon trying to activate them.

For example, there are three models: Model1, Model2, and Model3. A cycle may exist if:

An output block of Model1 produces a series of synchronous events that is consumed by an input block in Model2, and Model2 contains an output block that generates a second series of synchronous events, and
Model3 contains an input block that consumes a series of events from Model2, and Model3 also contains an output block that generates a series of synchronous events used by an input block in Model1.

Note that only activating any two of these models can be done without error. If activated in order, only Model3 would have an error. But if Model1 or Model2 were deactivated, then Model3 could be activated. The error will occur even if one of the models does not contain a link from the input block that is part of the chain to the output block that forms part of the chain, such as the example for Model3 below: the events from Model2 do not form a cycle to the To Model1 Measurement output block, but they count as a cycle as they are both in the same model. (In this case, the issue could be resolved by splitting that model into two models, thus removing the cycle).

Configuring the number of shown devices, device groups and/or assets

By default, a maximum of 10 devices and 10 device groups is shown in the Input and Output categories of the palette (see also Adding a block). When you use the search boxes that are available for these categories, this default also applies to the maximum number of assets that are shown in the search result. When you click Load more, up to 10 more devices, device groups and/or assets are shown.

The same default value is used in the block parameter editor when you select a different device, device group or asset (see Editing the parameters of a block) and when you replace devices, device groups or assets (see Replacing devices, device groups and assets).

If you want to change this default value (to show either more or less items), you need to change the tenant options. That is, you need to send a POST /tenant/options request. For detailed information, see the information on tenants in the Reference guide.

For example, specify the following to set the value to 20:

{
    "category": "analytics.builder",
    "key": "c8yAnalyticsBlocks.queryInventoryPageSize",
    "value": "20"
}

Searching for input and output assets

By default, only devices and device groups are shown in the palette (see also Adding a block). However, when you use the search boxes that are available for the input and output blocks, all assets (not only the devices and device groups) in the Cloud of Things inventory which match the search criteria are shown. You can thus build analytic models by defining any assets in the inventory as input blocks or output blocks.

If you want to restrict the search to show only assets of a specific type (for example, to show only devices), you need to change the tenant options. That is, you need to send a POST /tenant/options request. For detailed information, see the information on tenants in the Reference guide.

For example, specify the following if you only want to show devices:

{
    "category": "analytics.builder",
    "key": "c8yAnalyticsBlocks.queryInventoryNameSearchAdditionalFilter",
    "value": "has(c8y_IsDevice)"
}

The c8y_IsDevice in the value is a so-called fragment. You can specify any fragment that is known to Cloud of Things, including any fragments that you have created yourself.

You can combine several values. For example, specify the following if you only want to show devices and device groups:

{
    "category": "analytics.builder",
    "key": "c8yAnalyticsBlocks.queryInventoryNameSearchAdditionalFilter",
    "value": "has(c8y_IsDevice) or has(c8y_IsDeviceGroup)"
}

The default value of this tenant option is not has(c8y_IsVirtualDevice). As long as you do not change this tenant option, virtual devices are not shown as they would not make sense in an analytic model. If you change the value for this tenant option, make sure to specify all assets that you want to see in the search result.

The tenant options are also used in the block parameter editor when you select a different device (see Editing the parameters of a block) and when you replace devices (see Replacing devices, device groups and assets).