Configure a Trigger

Triggers allow you to execute actions when certain types of data are sent from your machine to the cloud, or when the internet connectivity of your machine changes. For example, you can configure a trigger to send you a notification when your robot’s sensor collects a new reading. Viam provides two trigger types depending on the event you want to trigger on:

  • Data has been synced to the cloud: trigger when data from the machine is synced
  • Part is online: trigger continuously at a specified interval while the machine part is online
  • Part is offline: trigger continuously at a specified interval while the machine part is offline

To configure a trigger:

  1. Go to the CONFIGURE tab of your machine on the Viam app. Click the + (Create) button in the left side menu and select Trigger.

    The Create menu with Trigger at the bottom of the list of options.

  2. Name the trigger and click Create.

  3. Select the type of event to trigger on from the Type dropdown.

  4. Follow the instructions depending on the type of trigger you want to implement:

  1. Select the types of data you want to trigger on from the dropdown. Whenever any data of the type you select is synced from any component on your machine, the trigger will trigger.
  1. While your part is online, the trigger action executes at a specified interval. Edit the Time between notifications attribute to set this interval according to your preferences.
  1. While your part is offline, the trigger action executes at a specified interval. Edit the Time between notifications attribute to set this interval according to your preferences.

  1. Replace the URL value with the URL of your cloud/lambda function.

    The trigger configured with an example URL in the Viam app.

If you prefer to configure your trigger with raw JSON instead of the config builder, you can paste one of the following JSON templates into your JSON config. "triggers" is a top-level section like "components" or "services".

  "triggers": [
    {
      "url": "<Insert your own cloud function or lambda URL for sending the event>",
      "event": {
        "type": "part_data_ingested",
        "attributes": {
          "data_types": ["binary", "tabular", "file"]
        }
      }
    }
  ]

  "triggers": [
    {
      "url": "<Insert your own cloud function or lambda URL for sending the event>",
      "event": {
        "type": "part_online",
        "attributes": {
          "seconds_between_notifications": <number of seconds>
        }
      }
    }
  ]

  "triggers": [
    {
      "url": "<Insert your own cloud function or lambda URL for sending the event>",
      "event": {
        "type": "part_offline",
        "attributes": {
          "seconds_between_notifications": <number of seconds>
        }
      }
    }
  ]

{
  "components": [
    {
      "name": "local",
      "model": "pi",
      "type": "board",
      "namespace": "rdk",
      "attributes": {},
      "depends_on": []
    },
    {
      "name": "my_temp_sensor",
      "model": "bme280",
      "type": "sensor",
      "namespace": "rdk",
      "attributes": {},
      "depends_on": [],
      "service_configs": [
        {
          "type": "data_manager",
          "attributes": {
            "capture_methods": [
              {
                "method": "Readings",
                "additional_params": {},
                "capture_frequency_hz": 0.017
              }
            ]
          }
        }
      ]
    }
  ],
  "triggers": [
    {
      "url": "https://1abcde2ab3cd4efg5abcdefgh10zyxwv.lambda-url.us-east-1.on.aws",
      "event": {
        "type": "part_data_ingested",
        "attributes": {
          "data_types": ["binary", "tabular"]
        }
      }
    }
  ]
}

  1. Write your cloud/lambda function to process the request from viam-server. The following example function sends a Slack message with a machine’s details, such as robot and location IDs, when it receives a request:

    import functions_framework
import requests
import time

@functions_framework.http
def hello_http(request):
  payload = {
    "Org-ID": request.headers['org-id'] if 'org-id' in request.headers else 'no value',
    "Location-ID": request.headers['location-id'] if 'location-id' in request.headers else 'no value',
    "Part-ID": request.headers['part-id'] if 'part-id' in request.headers else 'no value',
    "Robot-ID": request.headers['robot-id'] if 'robot-id' in request.headers else 'no value'
  }

  slack_url = "<paste in your own Slack URL>"
  headers = {}

  response = requests.post(slack_url, json=payload, headers=headers)

  request_json = request.get_json(silent=True)
  request_args = request.args

  return 'Sent request to {}'.format(slack_url)

More examples

The Monitor Job Site Helmet Usage with Computer Vision tutorial uses triggers to send email notifications.

Helmet Monitor

Get an email alert if people are not wearing hard hats.

Have questions, or want to meet other people working on robots? Join our Community Discord.

If you notice any issues with the documentation, feel free to file an issue or edit this file.