Defining triggers

The trigger.json 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
activateRegions	Optional. An array of regions that the detected object must overlap in order for the the trigger to fire.	[{"xMinimum": 20, "yMinimum": 30, "xMaximum": 100, "yMaximum": 200}]
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
customEndpoint	Optional. Specifies the custom Deepstack endpoint to call for image analysis. This is an advanced setting that is only useful to call custom models. If specified then watchObjects must be omitted.	/v1/vision/custom/license_plate?image
enabled	Optional. Default true. When set to false the trigger will be ignored.	false
handlers	Required. A list of handlers that get called when the trigger fires. Currently webRequest, mqtt, and Telegram handlers are supported.
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}]
name	Required. A name for the trigger. This is shown in the logs and used to activate the trigger via the REST API.	"Front door"
threshold	Optional. A minimum and maximum threshold that must be satisifed for the trigger to fire. See defining trigger thresholds for more information.
snapshotUri	The web address to call to download a snapshot image for processing when the trigger is activated via the REST API. Either this or watchPattern must be specified.	http://192.168.1.100:5432/ec2/cameraThumbnail?cameraId=00011-1834-2342-2342-23421356
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"]
watchPattern	A wildcard pattern that determines 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. Either this or snapshotUri are required.	"/images/FrontDoorSD*.jpg"

Defining activate regions

Active regions can help manage troublesome detection scenarios by forcing the detected object to only appear in a specific part of the image. If the detected object does not overlap with any of the defined activate regions then the trigger won't fire. If both activate regions and masks are specified then the detected object must overlap at least one active region and must be outside all masked regions.

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

Defining masks

Masks can help block troublesome regions of an image that are prone to repeated false positive predictions. If both active regions and masks are specified then the detected object must overlap at least one activate region and must be outside all masked regions.

Property	Description	Example
xMinimum	Required. The x position of the top left corner of the mask.	20
yMinimum	Required. The y position of the top left corner of the mask.	30
xMaximum	Required. The x position of the bottom right corner of the mask.	100
yMaximum	Required. The y 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. Supports mustache templates.	"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. This handler can be configured in two ways: as a single topic to fire, or an array of topics to send. A single topic should be sufficient for most use cases, with the array option available for more advanced configurations such as specifying an offDelay or custom payload.

Property	Description	Example
messages	An array of message configuration objects. Either this or the topic property must be specified.	[{"topic": "aimotion/trigger/FrontDoor", "offDelay": 0}]
topic	The topics to post when the trigger fires. Either this or the messages property must be specified.	"aimotion/trigger/FrontDoor"

The message configuration object supports the following properties:

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
payload	Optional. The payload to send in the message. Supports mustache templates.	"{{formattedPredictions}}"
topic	Required. The topic to post when the trigger fires.	"aimotion/trigger/FrontDoor"

Here is an example of the default payload sent in a message if no payload configuration is specified:

{
  "fileName":"/images/Dog_20200523-075000.jpg",
  "basename":"Dog_20200523-075000.jpg",
  "name": "Dog detector",
  "analysisDurationMs": 936,
  "predictions":[
    {
      "confidence":0.9681682,
      "label":"dog",
      "y_min":31,
      "x_min":125,
      "y_max":784,
      "x_max":1209
    }
  ],
  "formattedPredictions": "dog (97%)",
  "state": "on"
}

The basename property can be used to retrieve an image with prediction annotations from the system's built-in web server. The server runs by default on port 4242 and the images are available in the annotations directory. For example, from a browser running on the same machine as the Docker containers http://localhost:4242/annotations/Dog_20200523-075000.jpg would return the annotated image for the above MQTT message.

Defining Telegram handlers

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

Property	Description	Example
annotateImage	Optional. If true the image sent in the message is annotated with the identified objects and confidence percentage. Default false.	true
caption	Optional. A caption to send in the message along with the photo that fired the trigger. Supports mustache templates.	"{{name}}: {{formattedPredictions}}"
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

Defining Pushbullet handlers

A Pushbullet handler sends message with the photo that triggered the event.

Property	Description	Example
annotateImage	Optional. If true the image sent in the message is annotated with the identified objects and confidence percentage. Default false.	true
caption	Optional. A caption to send in the message along with the photo that fired the trigger. Supports mustache templates.	"{{formattedPredictions}}"
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 Pushover messages.	60
title	Optional. A title to send in the message along with the photo that fired the trigger. Supports mustache templates.	"{{name}}"

Sample default Pushbullet handler

Since all properties are optional the entry to create a Pushbullet handler that uses all the defaults is simply an empty object:

"pushbullet": {}

Sample Pushbullet handler with optional settings

"pushbullet": {
  "caption": "{{formattedPredictions}}",
  "title": "Motion detected on {{name}}"
}

Defining Pushover handlers

A Pushover handler sends message with the photo that triggered the event.

Property	Description	Example
annotateImage	Optional. If true the image sent in the message is annotated with the identified objects and confidence percentage. Default false.	true
caption	Optional. A caption to send in the message along with the photo that fired the trigger. Supports mustache templates.	"{{name}}: {{formattedPredictions}}"
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 Pushover messages.	60
sound	Optional. The Pushover notification sound to play. If unspecified the Pushover default sound is used.	"magic"
userKeys	Required. An array of userKeys to message when the trigger fires.	["asdflkjasdf34234sdf", "123sdflkj123345sdflkj"]

Mustache templates

The triggerUris, payload, and caption properties support mustache templates to insert data from the trigger. The following variables are supported:

Variable name	Description	Example
analysisDurationMs	The number of milliseconds it took to analyze the image.	936
analyzedFileCount	The number of files analyzed by the trigger.	1042
baseName	The base filename of the image that fired the trigger.	FrontDoorSD_20200523-074700.jpg
fileName	The full filename of the image that fired the trigger.	/aiinput/FrontDoorSD_20200523-074700.jpg
formattedPredictions	A formatted version of the predictions that cuased the trigger to fire, suitable for presentation to a user.	dog (96%), person (88%)
formattedStatistics	A formatted version of the triggeredCount and analyzedFileCount, suitable for presentation to a user.	Triggered count: 50 Analyzed file count: 1042
name	The name of the trigger that fired.	Front door
predictions	An JSON-stringified array of prediction objects that caused the trigger to fire.
state	The state of the trigger. This will always be the value on.	on
triggeredCount	The number of times the trigger matched all the requirements to activate.	50