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 the Groovy Device Inventory API (hereinafter Groovy DI API) provided by the system for working with devices. Bosch IoT Manager’s Groovy DI API allow you to obtain digital twins of the managed devices and thus monitor their state, as well as send commands to them. 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.

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

Groovy doc

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.