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. 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
topic	The topics to post when the trigger fires. Either this or the messages property must be specified.	"aimotion/trigger/FrontDoor"
messages	An array of message configuration objects. Either this or the topic property must be specified.	[{"topic": "aimotion/trigger/FrontDoor", "offDelay": 0}]

The message configuration object supports the following properties:

Property	Description	Example
topic	Required. The topic to post when the trigger fires.	"aimotion/trigger/FrontDoor"
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}}"

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%)"
}

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 root directory. For example, from a broswer running on the same machine as the Docker containers http://localhost:4242/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 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}}"
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"]
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

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
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%)
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