Block list

General usage

The following common options are available for (most) blocks:

genericmodal

This modal contains the following parts:

  • Title (containing the name of the block or setting)

  • md check icon (to apply the changes)

  • Main screen (with the available options or settings)

  • Sub-screen (for additional options)

  • Cancel-button (to cancel the changes)

  • Accept-button (to apply the changes)

Restrictions

Some blocks will not be shown when connected to a robot incompatible with the blocks. For example, the 'Head motion' block will not be shown for robots where the head cannot move.

Categories

The composer blocks have been sorted into various categories:

Some blocks are only available in the advanced composer.

Simple blocks

The following blocks are available for both the simple and advanced composer.

poiblock Go to POI block

Function

This block will move the robot to a specified POI on the currently selected map.

Settings

poisettings
  1. The current map is shown in the title of the modal

  2. Tap the POI for the robot to move to from the list of available POIs

  3. Slide the bar to the left or right to set the speed for the robot to move to the POI

  4. Enter a text for the robot to say if the POI can’t be reached after 5 tries

  5. Set the language for the robot to state the 'retry text' in.

  • The POI block will be skipped if the map and/or POI is no longer available or if the route has been blocked off (by virtual/real obstacles)

  • The retry text will only be spoken if the POI itself cannot be reached (e.g. someone is actually standing on the POI). Otherwise, the robot will re-calculate a router to the POI.

headblock Head-motion block

Function

This block is used to move the head of the robot to a custom position.

Settings

headsettings
  1. Move the head in the allowed direction(s) to the new position (1)

  2. Tap the button 'Test' to test the new position and allow for corrections if needed

(1): Robot-specific property. For example, James and Cruzr can only move the head up or down, while a Zora/Nao can move the head in all directions.

gymblock Gym block

Function

This block will make the robot perform an exercise.

Settings

gymsettings
  1. Tap the exercise to display a list of exercises available on the robot. Select an exercise in the list for the robot to execute.

  2. Enter the additional parameters for the exercise (e.g. slow the exercise down, set the distance to walk, …​).

  3. Select the sub-exercise to execute (e.g. 'move the left arm only')

  4. Tap the option 'Robot will count cycles' to have the robot count the number of times the exercise has been completed.

  5. A figure is shown with information on the parameters of the exercise.

  • Every exercise has different options. For example: 'Moving with the arms' will show options for which arm to move, while the exercise 'To step' will have options for the direction to move in.

  • The explanatory figure isn’t shown for all exercises. For dance-exercises for instance, this option will not be shown.

speechblock Speech block

Function

This block will make the robot say something (with some customizable properties). For example, the volume and language to be used by the robot can be changed.

The available options for the speech are determined by the connected device.

Settings

speechsettings
  1. Enter a text in the main text box.
    Tap the button 'Add (x)' to insert a variable in the message at the location of the cursor.

  2. Toggle the options 'animated speech' and/or 'blocking' as needed.

  3. Tap the icon md volume low to view or hide advanced speech options. (1)
    Change the 'speech speed', 'voice pitch' and/or the 'volume' for the speech.

  4. Tap the icon md mic to use voice input to enter the message. (2)

  5. Set the language (3) and voice (4) for the speech.

(1): Changing the volume in a speech-block will change the general volume on the device.
(2): Requires the app 'Google assistant' on Android tablet (which in turn requires internet connection).
(3): The current language and the default voice will be selected by default.
(4): This option is only available if multiple voices for the selected language are installed.

waitforvoiceblock Wait for voice command block

Function

This block will pause the composition until the robot understands (one of) the entered command(s).

To avoid false positives, use normal sentences and avoid using short statements or single words.

Settings

waitforvoicesettings
  1. Enter the command for the robot to listen to.
    Tap the button 'Add (x)' to enter a variable at the location of the cursor.
    Tap the icon md mic to use voice input to enter the command.
    Tap the button '+ Add new command' to create a new entry to the list.

  2. If necessary, enter a timeout after which the composition will continue.

  3. Set the options for how the device will start to listen to the voice commands.
    Check the option 'Require hotword' if the user needs to state the wakeword (e.g. 'OK James') before stating the voice-command.
    Check the option 'Show microphone' to display the microphone on the kiosk screen.

  4. Toggle the option 'Show multiple output connectors' to show an additional output connector for each entry in the voice command list. (advanced composer only)

The device will listen for the term in the currently set (speech-)language of the robot.

danceblock Dance block

Function

This block will make the robot perform a dance routine.

Settings

dancesettings
  1. The currently selected dance is shown at the top of the modal

  2. Enter a search-term or apply a filter to narrow the list of dances down

  3. Select the dance routine to be executed from the list

Make sure the robot has plenty of room before starting this composer-block.

animationblock Animation block

Function

This block will make the robot perform an animation (e.g. 'Wave hello').

On Zora, the 'Postures' are included in this category.

Settings

animationsettings
  1. The currently selected animation is shown at the top of the modal

  2. Enter a search-term or apply a filter to narrow the list of animations down

  3. Select the animation for the robot to execute

  • Not all animations can be performed all the time. For example, no animations can be performed while Zora is sitting on the bench.

  • The robot will assume the correct posture before executing the animation. For example, the robot will stand up before starting the animation 'BowShort1'.

emotionblock Emotion block

Function

This block will make the robot perform an emotional animation (e.g. 'Angry' or 'Determined').

Settings

emotionsettings
  1. The currently selected emotion is shown at the top of the modal

  2. Enter a search-term or apply a filter to narrow the list of emotions down

  3. Select the emotion for the robot to emulate

The robot will assume the correct posture before executing the animation. For example, the robot will stand up before starting the animation 'Confused 1'.

waitblock Wait block

Function

This block will pause the composition for the specified time. For example, the robot will wait for 2 seconds while an image is being shown.

Settings

waitsettings
  1. Enter the amount of time to wait (e.g. '5' out of '5 minutes')

  2. Select the unit of time (i.e. Seconds, Minutes or Hours) for the composition to wait before continuing

sensorblock Wait on sensor

Function

This block will pause the composition until a specific (collection of) sensor(s) is triggered. For example, a James can be configured to continue if 'any bumper' or if 'only the front bumper' is triggered.

Settings

sensorsettings
  1. Enter a timeout for the block.
    Enter a number and select a unit (e.g. '5' 'seconds' or '2' 'minutes').

  2. Toggle whether the block should have multiple output connectors.

  3. Enter a search term in the field to narrow down the list.

  4. Tap any input (or collection of input devices) in the list to enable them to continue the composition.
    The value for the wait_sensor is shown below the name of the input device (e.g. 'wait_sensor' will contain the value 'BASE_LEFT' if the left bumper was triggered).
    The path number will be shown next to the bumper (1).

(1): This option is only available when used in the advanced composer.

The list of available sensors will only be shown if ZBOS Control is connected to a robot.

publishblock Publish to MQTT block

DEPRECATED This block has been replaced by the mqtt block on robots with software version 2.2.0+.

Function

This block will send a message on the specified MQTT topic to the MQTT server installed on the robot.

Settings

publishsettings
  1. Enter the topic for the message

  2. Enter the payload for the message

subscribeblock Subscribe to MQTT block

DEPRECATED This block has been replaced by the mqtt block on robots with software version 2.2.0+.

Function

This block pauses the composition until a message is received on the specified topic on the MQTT server installed on the robot.

Settings

subscribesettings
  1. Enter the topic for the block to listen to

mqttblock Mqtt block

Function

This block allows publishing and subscribing to MQTT topics, either on the internal robot broker or external MQTT brokers (see: mqtt connection block) Any data received is stored in a variable named mqtt. To use the variable in subsequent blocks (e.g. speech), the content can be accessed by using the term {mqtt.payload}.

Settings

mqttsettings
  1. Toggle whether the composition should wait for a message from the broker before continuing with the composition

  2. Enter the topic for the message for the composition to listen to (e.g. zbos/audio/volume/event)

  3. Enter the name of the mqtt connection to use (leave blank to use the broker on the robot)

  4. Toggle whether some conditions should be met before continuing with the composition after the event has been received

  5. Set the conditional setting (e.g. "mqtt.payload" > 40)

  6. Tap the button 'And/or' to expand the conditional filtering (e.g. "mqtt.payload" < 90 ). Tap the new option 'X' to remove the additional condition if required.

  7. Toggle whether a message should be sent to the broker

  8. Enter the topic for the message to be sent to the broker (e.g. zbos/audio/volume/set)

  9. Enter the name of the mqtt connection to use (leave blank to use the broker on the robot)

  10. Enter the payload for the message (e.g. 60)

  11. Tap the button 'Add (X)' to add a variable to the payload

Tap the icon md list to view the currently available events for the ZBOS platform.

Usage

The composition will listen for a message before sending the message.
  • Listening to a topic

  1. Tap the icon md list to view a list of all available topics for the ZBOS platform.

mqtttopiclist
Take care not to confuse the PUB/SUB tags of the message list. For example, the robot will publish a message on topic zbos/audio/volume/event (PUB) where the block will SUBscribe to the topic.
  1. Enter a search term (1) and select the topic (2) for the composition to subscribe to.

  2. Set the payload for the message (See MQTT API Reference for more information and examples of existing topics and payloads)

  3. (Optional) Set the conditional requirements for the response

  • Sending a message on a topic

  1. Tap the icon md list to view a list of all available topics for the ZBOS platform.

mqtttopiclist
  1. Enter a search term (1) and select the topic (2) for the composition to publish on.

  2. Set the payload for the message (See MQTT API Reference for more information and examples of existing topics and payloads)

Example

The following configuration could be used to set the volume to 60 using the mqtt block:

mqttexampleconfig

waitqrblock Wait for QR code block

Function

This block will make the robot wait for a QR code before continuing with the composition. The scanned code can be used in the subsequent block using the "wait_qr_code" variable

Settings

waitqrsettings
  1. Check whether the shown qr code must match specific entries (see (7))

  2. Enter how many times the robot should try to scan the code

  3. Enter how long the scan should wait for a code to continue if no qr code is shown (at least 10 seconds)

  4. Check whether the block should use the built-in speech options (i.e. 'I will now start a qr scan')

  5. Check whether the robot should play a 'beep' when a valid QR code has been detected

  6. Check whether the display should show what the robot’s camera is showing

  7. Enter the terms that must be matched for a 'valid' qr code

Not all options may be available on robots. For example, the option 'Show camera' will not be available robots without an external display.

Usage

  • Using the block

Simply drag the block into the timeline and enter the proper configuration:

waitqrexample1
  • Retrieving the data

Enter the variable "wait_qr_block" to retrieve the information. For example, using the variable in a speech-block:

waitqrexample2

waitmonitoringblock Wait for monitoring event

Function

This block will make the robot wait for a monitoring event to occur before continuing with the composition.

The options for the specific sensor must be enabled in the Apps and config page. Only the option 'Enabled' needs to be checked, the setting cloud-sync is optional.

Settings

The following options are available for the block:

waitmonitoringsettings
  1. Enter the source of the monitoring event (i.e. the sensor/button pushed)

  2. Enter the type of event

  3. Enter the type of alarm for the event (optional)

The Monitoring page can be used to review the available options for a sensor or button.

waitmonitoringcheatsheet
  1. The type of the event

  2. The source of the event

Usage

  • Using the block

Simply drag the block into the timeline and enter the configuration for a monitoring event. For example:

waitmonitoringexample1
  • Retrieving the data

Enter the variable "wait_monitoring" to retrieve the information. For example, retrieving the source of a monitoring event:

waitmonitoringexample2

The Monitoring page can be used to view the content of the event. Tap the 'i' button to view the details for an event. For example:

waitmonitoringexample3

mqttconnectionblock Mqtt connection block

Function

This block allows for the configuration of an external mqtt broker.

Settings

mqttconnectionsettings
  1. The name of the connection to be used in the mqtt block (1)

  2. Enter the required connection information for the external mqtt broker

  3. Enter the rest of the optional information for the external mqtt broker

(1): The name of the connection is auto-generated and cannot be changed manually.

Usage

  1. Enter the information for the external mqtt broker

  2. Enter the name of the broker in the field 'broker connection' in the mqtt block.

settingsblock Settings block

Function

This block allows getting, updating or resetting settings of the device.

Settings

settingssettings1
  1. Toggle whether to get the current settings from the device.

  2. Toggle whether the settings of the device should be updated.

  3. Toggle whether settings should be reset.

The response from this block will be stored in the 'settings' variable.

Get device settings

The following settings are available for the settings:

settings get
  1. Select the app category and the app name(1) to get the current settings of the ZBOS device (see the Apps & Config page for more information).

  2. Select which settings from the category should be included in the response.

  3. Optionally, select which settings of the subcategories should be included in the response.

(1): Alternatively, the settings category can be entered manually.

Update device settings

settings update
  1. Select the app category and the app name(1)(2) to get the current settings of the ZBOS device (see the Apps & Config page for more information).

  2. Enter the new settings to be used by the robot.

settings update example1

(1): Alternatively, the settings category can be entered manually.
(2): The settings will be opened as soon as the app name has been selected.

Reset device settings

settings reset
  1. Select the app category and the app name(1)(2) to get the current settings of the ZBOS device (see the Apps & Config page for more information).

webpageblock Open web page block

Function: Display a web page on the tablet of the robot

Available settings:

webpagesettings
  1. Enter the URL for the website to be shown on the robot

This block is set to be non-blocking, meaning the composition will continue while the website is being shown. The duration of the time the website will be displayed must be set in the next block (e.g. Wait for sensor-input).

facerecognitionblock Wait for face block

This block requires the app ZoraBots Face Recognition to be installed on the robot with at least one person added to the list for James and/or Cruzr.

Function

This block will pause the composition until a human face is detected (by the main camera).

Settings

facerecognitionsettings
  1. Tap the option 'Only allow a known face' to continue the composition only after a registered face has been detected.

  2. Select how many faces should be detected before the composition should continue (e.g. 'equal to one' or 'at least two'). (1)

  3. Set the timeout for the composition to continue if no face has been detected (value '0' equals no timeout).

  4. Toggle the option 'Show multiple output connectors' to show an additional output connector for the timeout if it is set. (2)

(1): The option 'Amount of faces' will only be available if the option 'Only allow a known face' is unchecked. (2): Advanced composer only.

Output

The data retrieved from the block can be used in the rest of the composition using the following variables:

{face_detect} has the following properties:

{
"uuid":"uniqueidentifier",
"name":"<name of the known user>",
"role":"<description of the user>"
}

{face_detect_length} is a different variable containing the number of recognized faces.

For example, the following input can be used to state the response: "Hello, {face_detect.name}. You are registered as {face_detect.role} in the system.".

  • The name will be "unknown" if the face isn’t registered in the system.

  • Only one event will be sent even if multiple people were recognized.

  • The variables will have their default value if the timeout expires.

motiondetectionblock Motion detection block

Function

This block will make the robot take images and warn the user if changes have been detected since the previously taken image.

Settings

motiondetectionsettings
  1. Tap the option 'Upload photo to cloud' to toggle whether the registered image(s) should be stored (on the cloud platform)

  2. Tap the option 'Continue on detection' to toggle whether the composition should continue once any motion has been detected

  3. Tap the option 'Stop after time' to toggle whether the robot should stop recording after the set period of time (see (4))

  4. Set the maximum duration for the robot to take image(s)

  5. Toggle the option 'Show multiple output connectors' to show an additional output connector for the timeout if it is set. (2)

The option 'Upload photo to cloud' must be checked to view the security images in the Surveillance page in ZBOS Control.

Examples

  • Security-camera

motiondetectionsecurity
  • Doorman

motiondetectiondoorman

textinputblock Text input block

Function

This block will ask the user to enter some input on the kiosk-screen.

Settings

textinputsettings
  1. Enter the title that will be shown on the kiosk (e.g. 'What is your e-mail address')

  2. Select the type of entry the user needs to enter (e.g. 'E-mail')

  3. Enter the text to be shown in the 'confirmation' button (e.g. 'Continue')

The type of entry needs to be entered correctly before the composition will continue.

variableblock Variables

Function

This block is used to declare and define variables to be used in the composition.

Settings

variablessettings
  1. Enter the name of the variable to use (will change to a green background)

  2. Enter the (new) value for the variable

Once a valid variable/value pair has been entered, a new blank field will be shown below the currently existing list.

Tap the button {x} next to a field to display a list of known variables. Select a variable to enter it in the adjacent field.

Usage

The defined variable can be used in other blocks (speech-block for example):

variablesusage
  1. Add the earlier defined variable by tapping the 'Add {x}' button and selecting the variable in the list to insert it at the location of the cursor in the text field.

  2. Enter the name of the variable between brackets to enter the variable in the text-field.

The variable will only be styled once the text-field has been un-selected.

textoverlayblock Text overlay block

Function

This block has been designed to display some text on the tablet of the robot. The text will be shown on top of the background image, video or default background of the running composition.

Settings

textoverlaysettings
  1. Enter the text to be shown (in multiple lines if necessary).

  2. Set the font color (transparent by default).

  3. Set the background color (transparent by default).

Usage

  • Show text only

The example below can be used to show the sample text on top of the background:

textoverlayexample1
  • Show text with background

The example below can be used to show the sample text with a semi-transparent background:

textoverlayexample1

stringoperationsblock String operations

Function

This block is used to perform operations on variables.

Settings

stringoperationssettings general

Tap the '+' button to view the available operations:

stringoperationssettings options

Select an operation from the list and tap the option 'OK' to add the operation to the block. Additional options will be shown in the list based on the available operation. For example, the following options will be shown for a 'replace' operation:

stringoperationssettings example

The variable 'input' will have every character 't' replaced by 'T' and the result of the operation will be stored in the variable input_replaced.

Operation Arguments Result

Uppercase

  • Input variable

  • Output variable

String

Lowercase

  • Input variable

  • Output variable

String

Capitalize

  • Input variable

  • Output variable

String

Title

  • Input variable

  • Output variable

String

Remove

  • Input variable

  • Target (can be a regex)

  • Output variable

String

Replace

  • Input variable

  • Replacement

  • Target (can be a regex)

  • Output variable

String

Length

  • Input variable

  • Output variable

Number

Count

  • Input variable

  • Target (can be a regex)

  • Output variable

Number

Slice

  • Input variable

  • End position

  • Start position

  • Output variable

Number

Starts with

  • Input variable

  • Target

  • Output variable

Boolean

Ends with

  • Input variable

  • Target

  • Output variable

Boolean

Contains

  • Input variable

  • Target (can be regex)

  • Output variable

Boolean

mediablock Multimedia block

Function

This block will display a media file on the robot. The settings vary based on the media type of the selected file (e.g. audio, video or image)

General settings

The following options will always be shown:

multimediageneralsettings
  1. Tap an item in the list of media stored on the robot to make the robot play the selected file.

  2. Tap the button 'Manage' to display the multimedia-page in ZBOS Control to upload or remove files from the robot.

A preview of the selected media-file will be shown if ZBOS control is connected locally to the robot.

Settings for images

multimediaimagesettings
  1. Select the color for the background of the selected image (transparency) using a color wheel

  2. Select the scaling for the image (i.e. ('Center crop', 'Center inside' or 'Fit center'))

Settings for audio-files

multimediaaudiosettings
  1. Tap the option 'Blocking' toggle if the composition should continue after the audio file has finished. If this option is unchecked, the composition will continue while the audio file is playing.

  2. Tap the option 'Loop' to repeat the audio file until the end of the composition or until a 'Stop audio' block is started.

If the option 'Blocking' is checked, the option 'Loop' will be disabled.

Settings for video-files

multimediaaudiosettings
  1. Tap the option 'Blocking' toggle if the composition should continue after the video file has finished. If this option is unchecked, the composition will continue while the video file is playing.

  2. Tap the option 'Loop' to repeat the video file until the end of the composition or until a 'Stop video' block is started.

If the option 'Blocking' is checked, the option 'Loop' will be disabled.

startappblock Start app block

Function

This block will start an app installed on the robot

Settings

startappsettings
  1. The currently selected app to start is shown at the top of the modal

  2. Enter a search term to narrow the list of available apps

  3. Tap the app to start from the (searched) list

  4. Tap the option 'Blocking' to toggle whether the composition should continue playing while the app is being shown

  5. Tap the button to add a key/value pair to send to the app (e.g. 'data_source':'example')

  6. Tap the md trash to remove the added data from the block

changekioskblock Change kiosk block

Function

This block will change the current dataset used by the kiosk.

Settings

It is highly recommended to add a 'wait' block after the 'Change Kiosk' block to allow the robot to apply the new dataset before the composition ends.
changekiosksettings
  1. The currently selected dataset to apply is shown at the top of the list

  2. Enter a search term to narrow the list of available datasets on the connected robot

  3. Tap a dataset in the (searched) list to select it

stopmediablock Stop media block

Function

This block stops the currently playing media-type

Settings

stopmediasettings
  1. Tap the type of media to stop to display a modal with the following options:

    • Audio

    • Video

    • Image

    • Text overlay

domoticsactionblock Domotics action block

Function

This block allows the ZBOS device to send a command to the devices registered on a home automation system.

See the chapter Home Automation for more information on configuring domotics.

Settings

domoticsactionsettings general

Tap the '+' button to view the list of registered home automation systems:

domoticsactionsettings systemselect

Select the home automation system to use and tap the button 'OK' to select the device to configure.

If only one home automation system is active, the devices will be shown immediately.
domoticsactionsettings deviceselect

Tap a device to control and tap the button 'OK' to see the available actions in the list:

domoticsactionsettings deviceactions

Tap the option 'Action' to see the available actions for the selected device. For example, the available options are available for a light bulb:

domoticsactionsettings deviceoptions

domoticswaitblock Domotics wait block

Function

This block allows the ZBOS device to wait for a change in a device registered on a home automation system before continuing with the composition.

See the chapter Home Automation for more information on configuring domotics.

Settings

domoticswaitsettings general

Tap the '+' button to view the list of registered home automation systems:

domoticsactionsettings systemselect

Select the home automation system to use and tap the button 'OK' to select the device to configure.

If only one home automation system is active, the devices will be shown immediately.

Select the type of action to wait for and tap the 'OK' button to add it to the list:

domoticswaitsettings typeselect

Select the device or event from the list and tap the button 'OK' to continue:

domoticsactionsettings deviceselect

This will add the device to the list of conditions for the composer to wait for change. By default, the option 'On Change' is selected and the composition will continue if there is any action changed.

domoticswaitsettings waitconfiguration

Tap the option 'On Change' and select the option 'On Condition' to configure more detailed conditions if necessary:

domoticswaitsettings changeconditions

The advanced conditions can be configured using the new options:

domoticswaitsettings conditionaloptions

domoticsstateblock Domotics state block

Function

This block allows the ZBOS device to retrieve the state of a current device registered on a home automation system. This information can be retrieved in a new variable in the rest of the composition.

See the chapter Home Automation for more information on configuring domotics.

Settings

domoticsstatesettings general

Tap the '+' button to view the list of registered home automation systems:

domoticsactionsettings systemselect

Select the home automation system to use and tap the button 'OK' to select the device to configure.

If only one home automation system is active, the devices will be shown immediately.

Select the device or event from the list and tap the button 'OK' to continue:

domoticsactionsettings deviceselect

The device is now shown in the list along with the name of the variable containing the information:

domoticsstatesettings result

Advanced blocks

ifelseblock If Else

Function

This block will create multiple outcomes of the composition, based on an if/else equation.

For more information, see wikipedia

Settings

ifelsesettings
  1. Enter the first boolean equation for the if/else equation (e.g. if 'loop_count' < '5')

  2. Tap the button '+ And/Or' to add another condition to the if/else equation (e.g. if 'loop_count' < '5' or if 'stop' == '1')

  3. Enter the second part of the equation

  4. Tap the button times to remove any additional parts of the equation

  5. Tap the button '+ Else if' to add a second if-statement (e.g. if 'loop_count' > '3')

  6. Tap the button md trash to remove the equation

  7. The default return-statement is shown below.

Samples

High-low game

The following instance shows a case of how to program a basic game of high-low:

highlowscreen

The composition can also be viewed here

The setting for the if/else block in this case is the following:

highlowifelsesetting
  1. The first equation translates to: 'If the generated number is higher than the input from the user, use path 1'

  2. The second equation translates to: 'If the generated number is lower than the input from the user, use path 2'

If none of the equations above are matched, Path 3 will be taken (and the composition will end).

loopblock Advanced Loop

Function

This block will use loop 'path 1' while the condition is met.

looppath

The blocks linked to 'Path 1' will repeat while the conditions of the loop are met. Afterward, the blocks linked to path 2 will be played.

Settings

  • For-loop (default)

forloopblocksettings
  1. Select the option 'For loop' at the top of the modal

  2. Enter the name and initial value for the variable (e.g. i = 0)

  3. Enter the condition for the loop (e.g. i < 5)

  4. Enter the operator to apply at the end of the loop (e.g. i+1 )

    • While-loop

whileloopblocksettings
  1. Select the option 'While loop' at the top of the modal

  2. Enter the condition for the while-loop (e.g. 'while loop == '1')

Tap the button {x} next to a field to display a list of known variables. Select a variable to enter it in the adjacent field.

Usage

  • Link up all earlier blocks containing variables to be used in the loop (e.g. a variable set to '0' for the while loop)

  • Set the loop-conditions

  • Link the blocks to be looped to path 1 and place a Stop-block at the end

  • Link path 2 for the rest of the composition

The name of the variable used for the loop condition must be unique and can only be used by the blocks in path 1.

Loop block samples

For loop

This sample will play the looped block four times:

forloopsample

The composition can be also be seen here

The settings for the loop block are:

forloopsettings

The equivalent of the code for(i=1;i⇐5;i++) has been entered in the block.

While loop

This example will play the loop while the user hasn’t entered the 'lucky number':

whileloopsample

The composition can be also be seen here

whileloopsettings

The equivalent of 'while (loop==true)' is shown in this example.

The variable 'loop' has been defined in the variable-block as a '1' (or the equivalent 'true') in the variable-block at the start of the composition.

healthblock Health Certificate

Function

This block is used to scan health certificate QR codes, such as the EU Digital COVID Certificate.

The aim of the EU Digital COVID Certificate is to facilitate travel, helping to exempt holders from restrictions such as quarantine and to provide safe access to areas like concerts, festivals, theaters and restaurants.

The EU Digital COVID Certificate serves as proof that a person has been vaccinated against COVID-19, has recently received a negative COVID-19 test, or is protected against the disease after being infected (recovery valid for up to 6 months).

Settings

healthcertificateblocksettings

The settings for the health certificate block can be tweaked to conform with local requirements, as these tend to vary depending on the country or region of use.

  1. Minimum number of days since the last vaccination

  2. Maximum hours since last PCR test

  3. Maximum hours since the last antigen test

  4. Maximum days since recovery from infection

  5. Allowed vaccine types
    (this list will be need to be updated via a software update in case new vaccines become available)

  6. Allowed test types
    (this list will be need to be updated via a software update in case new tests become available)

  7. Signature validation: verify the validity of a QR code by checking if it is officially signed (requires internet connection).

  8. Timeout: how many seconds to wait until reading of the QR code is cancelled when not QR code is presented.

  9. Info section, describes the different outputs of this block:

    • First output is the flow for when the contents of the QR code is considered safe;

    • Second output is the flow for unsafe QR code;

    • Third output is the flow when a timeout occurs (when no QR code was presented).

Usage

A demo composition is available on ZBOS powered devices (with RAIL 2.5.0+ installed), displaying the default options for vaccination records as used in Belgium:

healthcertificateblockexample

The health certificate has 3 output connectors:

healthcertificateblockexample detailed
  1. If the certificate is safe, the output md checkmark green will be used.

  2. If the certificate is unsafe, the output md close red will be used.

  3. If no certificate is shown within the set time range, the output md stopwatch will be used.

Information in the certificate

Global information

This information is contained in every certificate:

  • Name

  • Date of birth

  • EU Member State that is issuing the certificate

  • Unique identifier or code of the document

Vaccination certificate
  • Type of vaccine

  • Vaccine’s manufacturer

  • Number of doses

  • Date of vaccination

Test certificate
  • Type of test taken

  • Date and time of the test

  • Test center

  • Result

Recovery certificate
  • Date of positive test result

  • The issuer of the certificate

  • Date of issuance

  • Validity date

Information in the payload

When the QR is read out by ZBOS Composer, the information is placed in a {health_certificate} variable which can be used for further processing or user feedback.

The data structure goes like this:

{
	"health_certificate": {
		"raw_content": {

		},
		"formatted_content": {
			"person": {
				"given_name": "The person's given name",
				"family_name": "The person's family name",
				"given_name_transliterated": "A transliterated version of the person's given name",
				"family_name_transliterated": "A transiterated version of the persons family name",
				"name_mrz_type1": "MRZ Type 1 version of the name",
				"name_mrz_type2": "MRZ Type 2 version of the name",
				"name_mrz_type3": "MRZ Type 3 version of the name",
				"name_mrz_be": "MRZ version of the name as used on Belgian ID",
				"name_mrz_sk": "MRZ version of the name as used on Slovakian ID",
				"name_mrz_fr": "MRZ version of the name as used on a French ID",
				"date_of_birth": "The person's date of birth"
			},
			"vaccination": {
				"target_disease": "Which disease this certificate is about",
				"vaccine": "The name of the vaccine",
				"medicinal_product": "The contents of the vaccine",
				"manufacturer": "The manufacturer of the vaccine",
				"dose_number": "Dose number",
				"dose_total": "Dose total",
				"date": "Date of the vaccine",
				"country_code": "Issueing country code",
				"country": "Issueing country"
			},
			"test": {
				"target_disease": "Which disease this certificate is about",
				"test_type": "The type of test taken",
				"test_name": "The name of the test",
				"manufacturer": "The manufacturer of the test",
				"sample_date": "The date of the test",
				"test_result": "The result of the test",
				"testing_centre": "The testing centre where the test was taken",
				"country_code": "Issueing country code",
				"country": "Issueing country"
			},
			"recovery": {
				"target_disease": "Which disease this certificate is about",
				"first_result": "Date of the first negative test result",
				"valid_from": "Start date of recovery certificate",
				"valid_until": "End date of recovery certificate",
				"country_code": "Issueing country code",
				"country": "Issueing country"
			}
		}
	}
}

The formatted content can be used in Composer to perform further actions, for example display the name of the person, or compare to identity information.

For compatibility with a broad variety of international travel documents, different types of MRZ name formats are provided:

Key Type Location (0 based, not incl. last) Max. length Example

name_mrz_type1

Type 1

Row 2, column 0-30

30

SOME<SURNAME<<FIRSTNAME<SECOND

name_mrz_type2

Type 2

Row 0, column 5-36

31

SOME<SURNAME<<FIRSTNAME<SECONDN

name_mrz_type3

Type 3 (eg.: internation passport)

Row 0, column 5-44

39

SOME<SURNAME<<FIRSTNAME<SECONDNAME<THIR

name_mrz_type_be

Belgian (similar to Type 1, but always truncates the third name regardless of available space)

Row 2, column 0-30

30

SOME<SURNAME<<FIRSTNAME<SECOND

name_mrz_type_sk

Slovak

Row 0, column 5-34

29

SOME<SURNAME<<FIRSTNAME<SECON

name_mrz_type_fr

French

Surname: row 0, column 5-30
Given name: row 1, column 13-27

25
14
(= 39 + 2 = 41)

SOME<SURNAME
FIRSTNAME<SECO
⇒ SOME<SURNAME<<FIRSTNAME<SECO

For using these values in a composition, use variable names like this: {health_certificate.formatted_content.person.name_mrz_type1}.

startblock Start

Function

This block is used to indicate the start of the composition.

This block is required for each advanced composition, and has no settings.

A warning will be shown if no start-block is present when starting an advanced composition.

startwarning

stopblock Stop

Function

This block is used to indicate the stop of (a branch of) the composition.

This block can be linked to multiple times.

apiblock API Call

Function

This block will retrieve information using an API Call. (See here for more information on API)

Settings

apisettings
  1. Enter the name of the variable containing the reply of the API request (e.g. api-response
    Tap the button {x} to insert a variable at the cursor location.

  2. Enter the API to call.
    Tap the button 'Add {x}' to insert a variable at the cursor location.

  3. Enter optional parameters for the API request (optional).

  4. Enter optional header information for the API request (optional).

  5. Enter a message for the API request (optional).

The list of parameters will expand or shrink once a parameter has been entered or removed.

Usage

  • Enter a variable name

  • Enter the endpoint and other required information (i.e. parameters and header)

  • If the response is JSON-formatted, the information retrieved can be used in other blocks (see further).

The website http://www.mocky.io can be used to send/receive API calls for testing/evaluation purposes.

A possible example of a JSON-file the API will return:

{
   "location": "Oostende",
   "company":
   {
	"name": "ZoraBots",
	"address": "Archimedesstraat 17",
       "field":"Robotics",
       "hours":
       {
           "mondays":"08:00 - 18:00",
           "tuesdays":"08:00 - 18:00",
           "wednesdays":"08:00 - 18:00",
           "thursdays":"08:00 - 18:00",
           "fridays":"08:00 - 18:00",
           "saturdays":"closed",
           "sundays":"closed"
       }
   }
}

Data retrieval

The following variables can be used in the following blocks of the composition to retrieve specific JSON-related data:

Variables Output

{test.location}

Oostende

{test.company.name}

ZoraBots

{test.company.hours.mondays}

08:00 - 18:00

{test.company.hours[0]}

08:00 - 18:00

mathformulablock Math Formula

Function

This block will calculate a variable based on the math formula entered.

If the math formula isn’t valid, the composition will skip this block altogether.

Settings

mathformulasettings
  1. Enter the name of the variable to use the result of the formula (e.g. 'Diameter') or tap the button '{x}' to enter an earlier defined variable.

  2. Enter the equation for the variable in the formula field. Tap the button 'Add {x}' to enter a variable in the location of the cursor.

Only use the operators and/or functions listed below. Other operators are not supported and may cause the composition to misbehave.

Allowed operators

Some operators can be used directly (e.g. {variable} * {variable}). The following list details all operators that can be used directly.

Operator Function

+

addition

-

subtraction

*

multiplication

/

division

-

sign operator (e.g. -4)

%

modulo

Built-in functions

Other than using mathematical operators, the following functions can also be used to calculate a result. These functions must be used as follows: <function>(<argument>). E.g. sqrt(4) will result in a variable with the value 2.

Function Calculates

abs

absolute value

acos

arc cosine

asin

arc sine

atan

arc tangent

cbrt

cubic root

ceil

nearest upper integer

cos

cosine

cosh

hyperbolic cosine

exp

Euler’s number raised to the power (e^x)

floor

nearest lower integer

log

logarithmus naturalis (base e)

log10

logarithm (base 10)

log2

logarithm (base 2)

sin

sine

sinh

hyperbolic sine

sqrt

square root

tan

tangent

tanh

hyperbolic tangent

signum

signum function

To use already existing variables, enter them between curly brackets (e.g. \{variable 1\}) to use them in the equation.
Leave spaces between the operators to calculate the correct values.

Samples

Calculate the diameter of a circle

In the following example, the robot will calculate the diameter of a circle up to two decimal points.

mathformulabasic

In the sample shown, the variable-block contains the radius of the circle, whereas the formula-block is used to calculate the radius.

mathformulabasicsettings

To trim the result down to two decimal points, the function ceil() is used on the result * 100 to round it up and then divided by 100 to return the digits after the decimal point.

mathoperationsblock Math Operations

Function

This block will perform basic calculations on 2 variables. For example: <Var3> = <Var2> + <Var1>.

Settings

mathoperationssettings
  1. Enter the equation for the operation (see details further down)

  2. Tap the button plus to add another equation to the list

Detailed settings

mathoperationsdetailedsettings
  1. Enter the name for the variable containing the result of the equation

  2. Enter a number or variable for the first operand

  3. Enter the operator (+,-,*,/,mod or ^)

  4. Enter a number or variable for the second operand

Tap the button *{x}* next to a field to display a list of known variables. Select a known variable from the list to add the variable to the field.

Samples

Even/Odd

The following example calculates whether a number entered by the user is odd or even:

mathoperationsoddevenscreen

The composition can be also be seen here

The current operation is shown as:

mathoperationsoddeven
  1. The result of the equation is stored in the variable 'result'

  2. The input from the user is used as the first operand from the equation

  3. The 'mod' operator is used to calculate the result

  4. The second operand is '2' to determine if a variable can be divided by 2

randomnumberblock Random number

Function

This block will generate a number between a minimum and maximum value.

Settings

randomnumbersettings
  1. Enter the numbers or variables to be used for the generator

  2. Tap the to add another number to be generated

randomnumberdetailedsettings
  1. Enter the name of the variable containing the randomly generated result

  2. Enter a number or variable for the minimum value to be used by the generator

  3. Enter a number or variable for the maximum value to be used by the generator

  • Tap the button *{x}* next to a field to display a list of known variables. Select a known variable from the list to add the variable to the field.

  • The minimum and maximum value are included as possible results of the generator.

Random number samples

Number between 1 and 10

The following setting will generate a number between 1 and 10:

randomnumbersettings
  1. The result of the equation will be stored in the variable 'result'

  2. The minimum value is set to 1

  3. The maximum value is set to 10