A Guide to Create and Use Triggers

The possibilities are endless with the AutoPi Dongle. This guide will be introducing and explaining one of the recently released features: triggers for your dongle.

This guide will also help you on how to to create and edit triggers on the AutoPi Cloud.

Triggers will allow you to get notifications both based on events from the device, but also all the various data points, including user specified, that are logged from the car.

What are triggers?

Trigger are a way to receive notifications when specific events occur on the device. The AutoPi is able to trigger on actual events from the vehicle (engine started/stopped and so on), and in the future also on a specific data point, like speeding over a certain threshold.

You can set up or edit this triggers on the AutoPi Cloud. As mentioned earlier, these triggers are based on event from the device, and a trigger can have zero or more conditions that needs to be met before it is triggered. Once the condition(s) have been met, the trigger will execute the attached action(s), ie. a notification will be sent to you notifying you of this event, via either an email, a webhook request or similar.

How does it work?

The way these triggers are created and edited is explained in the following guide. The point is for you to create a trigger that will notify you of an event, that you have specified. For example: you’ll be able to create a trigger that will notify you if your vehicle is powered on outside certain hours. For example, you can make conditions that if the car is turned on between the hours of 8 PM - 8 AM , it will be triggered and then send an email notifying you of this event.

Here’s how to start

Once, you have received your AutoPi device, and you have registered it (click HERE to see the getting started guide, if you have not already done so) and you are all set to go and can begin creating your own triggers. Let’s get started with the guide.

Here are the steps:

  1. Once you have logged into your cloud, you’ll see a main menu, which will be on the left side of the screen. Here you will see the option "Triggers" with a lightning symbol next to it. Click on it;

image2

  1. This should take you to your overview of your future triggers.
    image10
    Here, you’ll see a “Create” button with a plus sign. Click on this to display the create trigger form.

  2. Description
    Begin filling out the description box with the type of trigger its, for ex: “trigger on sleep”, “notify on power/on”, and so forth.

  3. Enabled
    You can choose any time to enable or disable this trigger. When disabled, the trigger will not execute any actions.

  4. Type
    Currently on the Cloud, we only have the “event” option, but we are working on expanding it to other types. The ‘event’ type, means that the trigger will be monitoring the events that are sent from your device. In the future an option called ‘Data’ will be added, which will allow you to create triggers that monitors the logged data, like temperatures, speed etc.

  5. Tag
    In the “tag” box, you write what kind of event you want the trigger to monitor. You can use wildcards (*) for ex. to monitor all engine events: “engine/*”. Currently there are only a few options, like: “engine/running”, “engine/stopped” etc. Soon you will be able to define your own events. To see all the events that you can monitor, you can browser the received events on the ‘Events’ page on my.autopi.io

  6. Device
    You can then choose on which device this trigger should be listening for events on.

  7. Conditions
    You can (optionally) add a condition to the trigger. This is done by clicking on the “+ Add condition”, this will then drop down and give you a couple of options to fill out.

  • Field
    In the “Field” box, you can write the full field name. The input box will auto complete the fields when you write, and show the available fields.
    The available fields can also be seen on the events page on my.autopi.io, so use this page to figure out what fields are available on events with the tag you specified.

    • Type
      The type field will be set based on the field you selected.
      But there are situations where you might want to specify the type to something else than the preselected value. One situation is when you want a trigger that will only execute at certain times of the day, like after 8 in the evening. In that case, you would first select a timestamp field (like @ts), and then change the type from datetime, to time. This way the date part of the @ts will be ignored. See example below. (Not that the timestamps are in UTC, so the comparison value should also be UTC)

    • Invert / Not
      Check the “Not” checkbox if you want the condition to be inverted. I.e. you can use that with the ‘field present’ operator, to make a condition that only executes if the field is NOT present.

    • Operator
      Now select the operator, which will decide how the comparison is performed. Not all operators makes sense on all types. Like you would probably not use the relational operators (greater than etc) for a string comparison.

    • Value
      Finally, input whatever value should be used when comparing the field value. I.e.
      some.field should ‘be present’ (in this case no value is needed)
      some.field should ‘equal’ 1234
      some.field should be ‘greater than’ 0

  1. Actions
    Once, you have filled all of that out, you can specify which actions you’d like performed. You need to have at least one action specified, but you can add multiple more if you’d like. The two different types of actions at the moment is “send an email” or “send a webhook request”. The email action requires your to input your email address, and currently it must be the email address you have used to create your user, and validated. The webhook action requires you to input the address and the JSON payload.

  1. Once, you have done all of these steps, you are ready to click the green create button and finish your very first trigger.
    Once created, it will monitor all new events that your device emits.

Examples

Here is a couple of examples

Conditions:

Notify on engine start between 01:00 and 06:00 at night.
(Remember all times are UTC, so keep that in mind when creating the conditions. Ie. So if your timezone is UTC+2, ie. the below conditions will in reality match between 03:00:00 to 08:00:00 local time.

Notify on device update (No conditions)

Notify on all events (will only execute once every minute no matter how many events are received)

Actions:

Send email

)

Send webhook request
You can also send webhook requests to an external API. You can use the Jinja templating within the payload to insert data that’s passed by the trigger’s context.

Trigger context fields:

event #the event that got fired
    @vid: int - Vehicle ID of the vehicle associated with the device
    @uid: UUID - The Unit ID of the device
    @tag: string - Additional event information
    @t:   string - Type of the event
    @ts:  string - Timestamp from the device
    @rec: string - Timestamp of when the event was received

trigger # the trigger
    created:        date - When the trigger was created
    last_modified:  date - When was the trigger last modified
    last_triggered: date - The last time this trigger got executed
    last_error:     date - When was the last error for this trigger
    description:    string - A description of the trigger
    enabled:        boolean - Whether the trigger is enabled or not
    device:         Device - The device model
    interval:       duration - How often is the trigger allowed/going to trigger

# nested models
Device
    id:                 uuid - The device id
    unit_id:            uuid - The device's unit id
    callName:           string - The name of the device (user provided)
    vehicle:            Profile - The profile (vehicle) model
    last_communication: date - The last time this device was connected to the cloud

Profile (the vehicle the device is registered to)
    type:         string - The type of the vehicle
    vin:          string - Serial number of the vehicle
    model:        Model - The model of the vehicle
    year:         integer - The creation year of the vehicle
    callName:     string - The name of the vehicle (user provided)
    licensePlate: string - The license plate of the vehicle

Model
    make: Make - The make of the model
    name: string - The name of the model

Make
    name: string - The name of the make (BMW, Mercedes-Benz, Toyota etc.)

You can use them like so:

{{ trigger['description'] }}

This will insert the description of the trigger (the one that’s been set during the creation of the trigger) inside the payload that you specify. Let’s take a look at an example payload for creating a Slack message via webhook:

Address: Your unique Slack webhook address
Payload:

{"text": "{{ trigger['description'] }} was executed, by device {{ trigger['device']['callName'] }}"}

The payload in this case will end up looking something like this when being sent to Slack:

{
    "text": "your_trigger_description_here was executed by device your_device_callName"
}

This example also shows off how to get nested model data - for each nested level a new set of square brackets needs to be added with a string of the field name that you would like to get. In the above example, we query for the device’s name through the trigger field.

You can check out Slack’s documentation for more information on what fields they accept.

image6

Send MQTT message via webhook (home assistant etc)
Check out this tutorial: https://www.home-assistant.io/blog/2017/03/28/http-to-mqtt-bridge/
Address: heroku app address
Payload: {"topic":"<mqtt_topic>","message":"<mqtt_message>","key":"<AUTH_KEY>"}

Trigger IFTTT applet via webhook
Address: Find on https://ifttt.com/services/maker_webhooks/settings
Payload: optional and custom based on the IFTTT applet.

These triggers, even the future ones, will allow you to be creative with your device and your vehicle.
If you have any suggestions or ideas you would like to discuss or let us know about, feel free to contact us on our social media platforms or right here on the community :slight_smile:
We look forward to hear from you all.

– The AutoPi Team.

2 Likes

Hi,
i’ve configured event to send email when engine turn ON, everything works but the problem is that system send false positive alarm because when car go in Start&Stop function and i’m stopped at traffic light when I’m start to ready the engine turn on again. How I can filter to notify me the first time to power on the car and not when Start&Stop function are active?

Ah, I see.

I think that can be solved a few different ways.

  1. You may want to change the trigger to listen to another event. You can try looking on the event view on my.autopi.io, if you have an event that you can see is only present once on startup, during a time where you have been driving.

  2. The trigger interval can be changed to a higher value, so that you will only get the event once ever hour or so. That would make the trigger only execute the notification once per hour, which effectively would mean that you should only get one notification per trip.
    But if you drive for longer than the interval, you will still get the event, and if you drive twice in an hour, you will only get the first notification.

And to top it off, I don’t think the interval is even possible to change from my.autopi.io yet.
So i’d say the best option is option 1, if possible.

We will look the events.
I think we really need a consistent event that is only ever triggered when the user is physically starting the car.

Best regards
/Malte

Hi,
I have configured the slack webhook. Very fun !
How can I use other fields ? I want send to slack the events type and values… or better, all events data.
{"text": "{{ trigger['description'] }} was executed, by device: {{ trigger['device']['callName'] }} event data=???"}
Thanks in advance,

I have found an interesting webhook message here
{"text": "{{ trigger['description'] }} : {{ trigger['device']['callName'] }} - {{ event['@tag'] }}"}
or more verbose
{"text": "{{ trigger['description'] }} : {{ trigger['device']['callName'] }} - {{ event }}"}

1 Like

Is there an issue with triggers lately? I cannot create or update an existing one.

Hi Mark,

Can you please contact support@autopi.io with the issue you are experiencing? They will help you fix the problem :slight_smile:

Best regard,
/Nadia.