Defining triggers

The trigger.conf file defines a list of triggers that fire when certain AI detection parameters are met. Triggers can call a web request url, send an MQTT event, and send an Telegram message when activated.

In the case of using this to make BlueIris start recording the web request URL is the way to go. MQTT is useful if you want to do fancier automation based on the detected objects. Telegram is nice if you want a quick photo notification of the event.

A sample file to start from is included in the sampleConfiguration/triggers.json folder. You'll have a happier time editing the trigger configuration if you use a text editor that supports real-time schema validation (such as Visual Studio Code).

Property	Description	Example
name	Required. A name for the trigger. This is shown in the logs.	"Front door"
watchPattern	Required. A wildcard pattern that determins which images are processed by this trigger. For Blue Iris use this will be something like "/images/FrontDoorSD*.jpg". By default the image folder is mounted to /images so unless you mounted the image folder elsewhere for some reason all watchPatterns should start with /images.	"/images/FrontDoorSD*.jpg"
watchObjects	Required. An array of object types that the trigger watches for. The list of supported objects is available in the DeepStack AI documentation however the most useful are: "person", "car", "truck", "dog", "bear"	["car", "truck", "person"]
masks	Optional. An array of masks that block the trigger from firing if a prediction overlaps any of the masked areas.	[{"xMinimum": 20, "yMinimum": 30, "xMaximum": 100, "yMaximum": 200}]
handlers	Required. A list of handlers that get called when the trigger fires. Currently webRequest, mqtt, and Telegram handlers are supported.
enabled	Optional. Default true. When set to false the trigger will be ignored.	false
threshold	Optional. A minimum and maximum threshold that must be satisifed for the trigger to fire. See defining trigger thresholds for more information.
cooldownTime	Optional. Default 0. Specifies the length of time in seconds that have to pass between detected images for the trigger to fire again.	60

Defining masks

Masks can help block troublesome regions of an image that are prone to repeated false positive predictions. If any part of a predicted object overlaps any of the masks on a trigger then the trigger won't fire.

Property	Description	Example
xMinimum	Required. The left position of the top left corner of the mask.	20
yMinimum	Required. The top position of the top left corner of the mask.	30
xMaximum	Required. The right position of the bottom right corner of the mask.	100
yMaximum	Required. The bottom position of the bottom right corner of the mask.	200

Defining trigger thresholds

The trigger threshold can help fine tune how sensitive the trigger is to detected objects. It is optional and suggested to omit until you've looked at some of the output logs to see which triggers need adjusting.

Property	Description	Example
minimum	Optional. Default 0. A value between 0 and 100 that determines the minimum label confidence level required to activate the trigger.	50
maximum	Optional. Default 100. A value between 0 and 100 that determines the maximum confidence level allowed to activate the trigger.	90

Defining webRequest handlers

A webRequest handler calls a web URI any time the trigger is fired. In the BlueIris use case this is how to define the URI that tells Blue Iris to start recording the HD camera. Note that you will likely have to specify the host as an IP address rather than as a hostname if you want to use a host on your internal network.

Property	Description	Example
triggerUris	Required. An array of URIs to call when the trigger fires.	"http://192.168.1.100:81/admin?trigger&camera=FrontDoorHD&user=username&pw=password"

Defining mqtt handlers

An mqtt handler sends an MQTT event any time the trigger is fired. The event includes an array of all the predictions that matched the trigger configuration, making it easy to do advanced automation based on the specific detected objects.

Property	Description	Example
offDelay	Optional. The number of seconds to wait before sending a state: off event. Default 30. Set to 0 to disable sending the message.	300
topic	Required. The topics to post when the trigger fires.	"aimotion/trigger/FrontDoor"

Here is an example of the data sent in the message:

{
  "fileName":"/images/Dog_20200523-075000.jpg",
  "basename":"Dog_20200523-075000.jpg",
  "predictions":[
    {"confidence":0.9681682,
    "label":"dog",
    "y_min":31,
    "x_min":125,
    "y_max":784,
    "x_max":1209}
  ]
}

Defining Telegram handlers

A Telegram handler sends message with the photo that triggered the event. See Configuring Telegram below for details on how to obtain chatIds.

Property	Description	Example
chatIds	Required. An array of chatIds to message when the trigger fires.	[123123, 227352]
cooldownTime	Optional. Default 0. Specifies the length of time in seconds that have to pass between detected images for the chat messages to get sent again. This is independent from the cooldownTime specified for the overall trigger, and allows the trigger to fire more often overall than the Telegram messages.	60