Vibration

Vibrating the device can be helpful if you need to get the user's attention, especially if their ears and eyes are focused somewhere else. Here we'll discuss how to vibrate your device during a workflow, adding a touch element. This can complement a voice-centric element (say and listen) and a visual element (LEDs).

📘

URN Type for Vibrate

The target URN that is needed to be passed into the vibrate method is an interaction URN.

Using the Vibrate Method

The vibrate() method can be used in a workflow to vibrate the device in a pattern of your choosing. Vibrating the device may be useful if you need to grab the user's attention before speaking a message. For example, the interaction below vibrates the device before saying something to the user:

workflow.on(Event.INTERACTION_STARTED, async({source_uri: interaction_uri}) => {
  // This pattern makes the device vibrate three times. The return value is void.
  await workflow.vibrate(interaction_uri, [100, 500, 500, 500, 500, 500])
  await workflow.sayAndWait(interaction_uri, "I need your attention!")
})
@my_workflow.on_interaction_lifecycle
async def lifecycle_handler(workflow, itype, interaction_uri, reason):
    if itype == relay.workflow.TYPE_STARTED:
        # This pattern makes the device vibrate three times. The return value is void.
        await workflow.vibrate(interaction_uri, [100, 500, 500, 500, 500, 500])
        await workflow.say_and_wait(interaction_uri, 'I need your attention!')
public override async void OnInteractionLifecycle(IDictionary<string, object> dictionary)
        {
            var type = (string) dictionary["type"];
            
            if (type == InteractionLifecycleType.Started)
            {
              var interaction_uri = (string) dictionary["source_uri"];
                            // This pattern makes the device vibrate three times.  The return value is void.
              await Relay.Vibrate(this, interaction_uri, [100, 500, 500, 500, 500, 500]);
              await Relay.SayAndWait(this, interaction_uri, "I need your attention!");

            }
@Override
 public void onInteractionLifecycle(Relay relay, InteractionLifecycleEvent lifecycleEvent) {
   super.onInteractionLifecycle(relay, lifecycleEvent);

   logger.debug("User workflow got interaction lifecycle: " + lifecycleEvent);
   String interactionUri = (String)lifecycleEvent.sourceUri;
   if (lifecycleEvent.isTypeStarted()) {
     // This pattern makes the device vibrate three times.  The return value is void.
     relay.vibrate(interactionUri, new int[] {100, 500, 500, 500, 500, 500});
     relay.sayAndWait(interactionUri, "I need your attention!");
   }

The vibrate() function takes two parameters: the interaction URN and the pattern of the vibration. The pattern of the vibration is represented by an array of numbers. In the example above, the device will vibrate three short times before the workflow terminates. The pattern is described more below.

The Pattern Parameter

The pattern parameter is an array of integers that each represent a duration in milliseconds. The first element in the example array above is how long you would like the device to wait (pause) before it moves to processing the next element in the array. Next, for the 2nd element in the array the device will vibrate for that duration (first vibration). The 3rd element is a pause duration. The 4th element is a vibration duration (second vibration). The 5th element is a pause duration. The 6th element is a vibration duration (third vibration). So in this example there are 3 equal vibrations that are evenly spaced apart.

The array can have as many elements as desired, where the odd elements (start index=1) are delays and the even elements are vibration durations.