Groovy actions

In Bosch IoT Manager the management action which has to be executed on the connected smart devices is defined by means of a Groovy script and is arranged by the Groovy script engine. As already mentioned in previous sections, the action is one of the main building blocks of both tasks and rules and has to be defined for each of them upon their creation.

You may use the Groovy language in order to define arbitrary programming logic which uses Bosch IoT Manager's Groovy APIs, namely:

  • Groovy Device Inventory API (hereinafter Groovy DI API), which is provided by the system for working with devices. The Groovy DI API allows you to obtain digital twins of the managed devices and thus monitor their state, as well as send commands to them.

  • Groovy HTTP Scripting API, which is provided by the system for HTTP clients. The Groovy HTTP Scripting API allows you to send / receive HTTP requests and responses to / from external HTTP endpoints.

  • Groovy Execution Context API (hereinafter Groovy Exec API) provides execution self-control methods from within the Groovy script source.

These APIs are subject to extension, therefore you may check for newly added functionalities in the future.

The following code snippet provides a schematic example of how you can employ a Groovy-specific programming logic involving the Groovy DI API. Keep in mind that it only illustrates the structure and does not correspond to actual devices

for (/*...*/) { some groovy loop
configState = item.property('configState) // using the Groovy Device Inventory API to get the saved state of a device feature
 
if (configState != desiredState) { // using an if statement to provide reasoning on how to proceed
item.exec('changeState', 'desiredState') // sending a command to the device (via API) to change its state
}
}

The Groovy script defining the management action, called action script or simply action for convenience, has to be written on the basis of:

  • the relevant generic methods and bindings defined in the Groovy DI API for access to devices, features, properties and operations, or

  • the dynamic methods and fields defined as explained later on in this topic.

Practically any type of connected smart device can be managed through Bosch IoT Manager, and each type is represented with its specific features, properties and operations . These properties and operations are the basis for the definition of dynamic methods and fields. As they differ for each device type, it is impossible to define all of them in the Groovy DI API of Bosch IoT Manager. However, there is a convenient logic that you can follow in order to define them ad hoc. Check the Vorto model of the relevant device feature to see what properties and operations have been defined for it. Then use the property name as a dynamic field name, and the operation name as a dynamic method name. Generic methods and fields on the other hand do not depend on a specific device feature and can be applied to any device type.

Let us demonstrate this dynamic method concept through a simple example on the device example.dm:demoDevice:Car:1 where speed is a property of the DeviceInfo feature:

// dynamic field (get speed)
target.feature('DeviceInfo').speed
 
// dynamic method (set speed)
target.feature('DeviceInfo').setSpeed(15)

As a contrast, setting the speed in a non-dynamic manner can be executed by:

currentSpeed = target.feature('DeviceInfo').property('speed')
 
// set speed
target.exec('DeviceInfo', 'setSpeed', 15)
// or
target.feature('DeviceInfo').exec('setSpeed', 15)


Target is an object of Device type.


Each method in the Groovy DI API is defined as synchronous or asynchronous, and is respectively executed as such. By default, dynamic methods which are not defined in the Groovy DI API are asynchronous. Learn more about them and how to apply them properly in the section dedicated to Synchronous and Asynchronous Methods.

The bindings which should be used as entry points in the Groovy script and the differences in the script execution depending on the scope with which the action is executed are presented оn the following page - Action Execution Depending on the Scope.

Groovy binding information for the newly added Groovy HTTP Scripting API and Groovy Execution Context API can be found in their respective pages.

Groovy doc

For more detailed information on the matter visit our Groovy APIs documentation .

The AsyncResult last argument, found in some methods in our groovy doc should be ignored and not included in the actual action script as it merely indicates that this concrete method is asynchronous.