Using MQTT to receive and trigger events

OUTDATED!

New Method : https://hub.shinobi.video/articles/view/LXw2fdkTPIU8BlP

Why integrate with MQTT?

By integrating Shinobi with MQTT you can both receive events generated by Shinobi and trigger events in Shinobi from outside sources. Using this integration camera detections can trigger external actions. For instance in home assistant.  Also it is possible to use external sensors connected to MQTT to trigger an event in Shinobi and start recording.

How to configure Shinobi with MQTT

Shinobi can be configured to integrate with MQTT using a customAutoLoad MQTT module. In addition you need to configure the main configuration file (conf.json) and load the mqtt library with npm. Before configuring Shinobi make sure you have a working MQTT server and created a userid and password for Shinobi to use.

Step by step instruction:

1. Go to your Shinobi install directory

Login to you system with a terminal and go to the Shinobi home directory. In most cases at /home/Shinobi:

cd /home/Shinobi

2. Modify conf.json to include a mqtt section

Open your main conf.json.

sudo nano /home/Shinobi/conf.json

3. Add a mqtt section with the url of your mqtt server and the created userid and password

{
 ...
 "mqtt": {
    "verbose": false,
    "url": "mqtt://localhost:1883",
    "mqtt_options": {
      "username": "xxxxx",
      "password": "xxxxx" 
    },
    "topic": "shinobi",
    "filterplugs": ["pir1", "pir2", ...],
    "toMqttMessage": {
      "key": "key",
      "name": "name",
      "details": "details",
      "currentTimestamp": "currentTimestamp",
      "plug": "plug",
      "name": "mon.name"
    },
    "triggerTopics": {
      "motionsensor/pir1/out": {
        "monitorid": "monitorid",
        "groupkey": "groupkey"
      }, 
      {...}
    }
 },
 ...
}

Explanation of above config items:

• verbose - enables a lot more log output, used mainly for debugging
• url - a URL to your MQTT broker which will receive Shinobi events (see also https://github.com/mqtt/mqtt.github.io/wiki/URI-Scheme)
• topic - root MQTT topic where all events will go
• username - the username to authenticate with the mqtt server
• password - the password to authenticate with the mqtt server
• filterplugs filter out events with plugs defined in this array, usefull to prevent triggers originating from mqtt itself
• toMqttMessage - object to define message structure
• triggerTopics - to define the topics to subscribe to and receive triggers from mqtt which are stored in Shinobi. This can be usefull to use external sensors (e.g. pir sensors).

You can also specify other mqtt_options used to connect to the mqtt server. For a complete list of options see: mqttsjs.

4. Download the MQTT module into the customAutoLoad directory.

sudo curl -o ./libs/customAutoLoad/mqtt.js https://gitlab.com/geerd/shinobi-mqtt/raw/master/mqtt.js

5. Install the mqtt dependencies:

sudo npm install mqtt

6. Shinobi will need to be restarted after configuring and installing the mqtt module.

sudo HOME=/root pm2 restart camera

After these steps Shinobi should successfully log in to your MQTT server and when the triggerTopics are configured also subscribe to the configured triggerTopics. To troubleshoot set verbose to true in conf.json and view the log using:

sudo HOME=/root pm2 log camera --lines=100

Messages details of messages originating from Shinobi

The messages originating from Shinobi can be formatted as desired using the toMqttMessage config item. The default will use the following formatting.

{
  "name": "livingroom",
  "details": {
    "plug": "Yolo",
    "name": "yolo",
    "reason": "object",
    "matrices": [
      {
        "x": 521.9678344726562,
        "y": 182.34503173828125,
        "width": 253.935302734375,
        "height": 777.6563720703125,
        "tag": "person",
        "confidence": 62.821685791015625
      }
    ],
    "imgHeight": 480,
    "imgWidth": 640
  },
  "currentTimestamp": "2019-11-23T22:16:02+01:00",
  "plug": "Yolo"
}

The message will always be formatted as a json message.

Triggering events in Shinobi using MQTT

Events can be triggered in Shinobi via MQTT by specifying the triggerTopics to which Shinobi should subscribe to. The monitorid and groupkey needs to be provided when specifying this triggerTopic. The messages published on this topic should be valid json and have a plug field and reason field specified. Example trigger event message:

{ 
  "plug": “pir1”, 
  "reason": "motion", 
  "name": “livingroom” 
 }

The message will be added to the details field of the trigger event. To prevent that the same messages are exported again from Shinobi to the mqtt broker use filterplugs. All messages with a certain plug field will be filtered out and not be published from Shinobi to the mqtt server.

Example config in home assistant

Using the detections in Shinobi you can trigger events in home assistant. For instance a detected person can be used to trigger a motion event for a binary sensor in home assistant. Below an example how to setup home assistant for this:

binary_sensor:
  - platform: mqtt
    name: cam2
    state_topic: shinobi/<groupkey>/<monitorid>/trigger
    payload_on: motion
    payload_off: no motion
    value_template: >-
      {% set shinobi = namespace(person_detected=false) %}
      {% for matrix in value_json.details.matrices %}
        {% if value_json.details.matrices[loop.index0].tag == 'person'  %}
          {% set shinobi.person_detected = true %}
        {% endif %}
      {% endfor %}
      {% if shinobi.person_detected %}
         motion
      {% else %}
         no motion
      {% endif %}
    off_delay: 5
    device_class: motion