INSTAR Deutschland GmbH

Home Assistant on Debian



INSTAR MQTT Broker

Only for Full HD Camera Models

If you are using an INSTAR Full HD camera also check out our MQTT Broker Integration into Home Assistant. The MQTT Interface enables you to access all camera functions through the native MQTT support from the Home Assistant Lovelace UI!

Installation of Home Assistant on a Debian Stretch Server

Installation of dependencies:

sudo apt update
sudo apt install python3-dev python3-pip python3-venv
sudo pip3 install --upgrade virtualenv

Home Assistant with your INSTAR IP Camera


Create a user and group

Give the user access to serial lines (zwave, insteon, etc):

sudo adduser --system homeassistant
sudo addgroup homeassistant
sudo adduser homeassistant dialout

Home Assistant with your INSTAR IP Camera


  1. Create a directory to install HA in and set its ownership and permissions.
sudo mkdir /opt/homeassistant
sudo chown homeassistant:homeassistant /opt/homeassistant

Home Assistant with your INSTAR IP Camera


  1. Change to the homeassistant user to do the installs.
sudo su -s /bin/bash homeassistant

Install Home Assistant

  1. Install a virtual env to sandbox the Home Assistant software and dependencies and activate it so further installs are done here.
cd /opt/homeassistant
python3 -m venv /opt/homeassistant
source bin/activate

Home Assistant with your INSTAR IP Camera


  1. Install HA from pip. You might get some pip install errors that do not cause an issue later on:
pip3 install --upgrade homeassistant

Home Assistant with your INSTAR IP Camera


  1. Open another terminal and login with your default (sudo enabled) user and open the Home Assistant port 8123 in your Firewall:
sudo firewall-cmd --permanent --zone=public --add-port=8123/tcp
sudo firewall-cmd --reload
sudo firewall-cmd --list-all

Home Assistant with your INSTAR IP Camera


Then switch back to the homeassistant user.

  1. To keep all the config and log files in the same directory (rather than having them in /home/homassistant) we can run Home Assistant with the following command:
mkdir config
./bin/hass -c /opt/homeassistant/config --log-file /opt/homeassistant/hass.log

Home Assistant should install a few things and make a default config file (let it run for a little while - it takes a bit on the first start up). Hit ctrl-c to stop it. The config directory now contains a bunch of sample config files for you to edit.


Home Assistant with your INSTAR IP Camera


  1. You can now access Home Assistants web interface by opening the following URL (exchange the IP address 192.168.2.111 with the IP of your Linux Server) inside your webbrowser http://192.168.2.111:8123/:

Home Assistant with your INSTAR IP Camera


  1. Type in your preferred login credentials and click to create the account:

Home Assistant with your INSTAR IP Camera


  1. And login to the Home Assistant web interface using your credentials:

Home Assistant with your INSTAR IP Camera


  1. Hit ctrl-c to stop Home Assistants. The config directory now contains a bunch of sample config files for you to edit.

Run Home Assistant as a Service

  1. Assuming it works, exit the homeassistant user, change to the /etc/systemd/system/ directory and create a service to start Home Assistant automatically.
exit
cd /etc/systemd/system/
sudo nano homeassistant.service
  1. Create the following systemd init file:

Home Assistant with your INSTAR IP Camera


[Unit]
Description=Home Assistant
After=network.target mosquitto.service

[Service]
Type=simple
User=homeassistant
ExecStart=/opt/homeassistant/bin/hass -c /opt/homeassistant/config --log-file /opt/homeassistant/hass.log

[Install]
WantedBy=multi-user.target



  1. Exit the homeassistant user, copy the service file to the system, and update systemd to run the service.
sudo systemctl --system daemon-reload
sudo systemctl enable homeassistant
sudo systemctl start homeassistant
  1. If something goes wrong with the start command, check the logs:
sudo systemctl status homeassistant

Home Assistant with your INSTAR IP Camera


Finally, to make it easier to edit config files and try out code changes, give your regular user write permissions in the homeassistant directory. For this we need to assign both our regular user - in my case this is the nodeadmin - and the homeassistant user to the homeassistant group.

sudo groupadd homeassistant
sudo usermod -a -G homeassistant nodeadmin
sudo usermod -a -G homeassistant homeassistant

Make sure that both users are inside the created group:


Home Assistant with your INSTAR IP Camera


sudo chgrp -R homeassistant /opt/homeassistant
sudo chmod -R g+w /opt/homeassistant/

Configuring Home Assistant

We set up Home Assistant to be installed in /opt/homeassistant. The configuration file can be found in the config subfolder. Let's open up the file to take a look at it:

sudo nano /opt/homeassistant/config/configuration.yaml

Adding the MQTT Broker

INSTAR MQTT Broker

If you are using an INSTAR Full HD (1080p) camera you don not need to install an separate MQTT broker as your camera already comes with a preinstalled INSTAR MQTT broker.

If you want to use an INSTAR HD (720p) or VGA camera you can use the broker that can be installed with Home Assistant - as described below. To connect your HD or VGA camera to this broker you can use a tool like Node-RED - for which we have a detailed tutorial here.

Once you can access your camera's API through the MQTT Interface you are good to go to connect the MQTT side of it to Home Assistant. How this looks like is described here for the INSTAR MQTT broker and works the same way, when you are using your own MQTT broker + Node-RED.


Home Assistant with your INSTAR IP Camera


The first thing we should do, is adding our Mosquitto server (192.168.2.111) as MQTT broker. We can do this by adding the following lines at the end of the document:

# MQTT Communication

mqtt:
  broker: 192.168.2.111
  port: 1883
  user: debian
  password: mysecretpassword

Note:

Home Assistant comes with an Embedded MQTT broker. Since we already installed the Mosquitto MQTT Broker with Node-RED we deactivated this secondary Broker by adding the configuration above - as well as making sure that the Mosquitto Service is run before Home Assistant.


If you don't plan on using Mosquitto skip this step and Embedded MQTT Broker will be started instead.



To verify that we did not mess up the configuration we can go to the Configuration Tab in Home Assistant:


Home Assistant with your INSTAR IP Camera


Open the General section:


Home Assistant with your INSTAR IP Camera


Click on Check Config and - when it passes - click on Restart Server:


Home Assistant with your INSTAR IP Camera


The Home Assistant Lovelace UI

Now we can start with adding components to the Home Assistant UI - called Lovelace. Adding Buttons and switches to interact with your camera's API through an MQTT interface is described in detail for the INSTAR MQTT Broker here. Note that the INSTAR MQTT Broker is only included in INSTAR Full HD cameras. If you are using a HD (720p) or VGA camera you can still use MQTT to connect your camera. Install the MQTT broker on your Linux system as detailed above and use Node-RED as an Interface between your camera and the MQTT Layer. Once you have this set up you can connect your cameras to Home Assistant using the INSTAR MQTT Broker Tutorial.

The article about the INSTAR MQTT Broker already tells you everything you need to know on how to add your camera's function to the Home Assistant UI. But what is missing is the Live Video.

Adding your camera's Live Video

Home Assistant comes with a Camera Module that we can use to add our camera's Live Video. Lets start by accessing the configuration.yaml. When you followed the steps above you will find this file in /opt/homeassistant/config/configuration.yaml. When you followed the INSTAR MQTT Broker Tutorial and installed Home Assistant on a Raspberry Pi, it will be inside your default user home directory: /home/pi/.homeassistant/configuration.yaml. Open the configuration file and add the line:

camera: !include cameras.yaml

Now create the cameras.yaml file next to the configuration file and add the following lines:

- platform: generic
  name: 'IN-8015FHD'
  still_image_url: http://192.168.2.165/tmpfs/snap.jpg
  stream_source: 'rtsp://192.168.2.165:554/11'
  verify_ssl: false
  authentication: 'basic'
  username: 'admin'
  password: 'instar'

In case you need to restrict the bandwidth this live stream is requiring, use auto.jpg or auto2.jpg instead of snap.jpg in the stillimageurl above. Also the RTSP stream_source can use a smaller live stream by replacing the /11 with a /12 or /13. Alternatively, you can access your camera's MJPEG stream with the following configuration:

- platform: mjpeg
  name: 'IN-9010FHD'
  mjpeg_url: http://192.168.2.117/mjpegstream.cgi?-chn=11
  verify_ssl: false
  authentication: 'basic'
  username: 'admin'
  password: 'instar'

And again, to reduce the bandwidth requirements of this live stream use chn=12 or chn=13 instead of chn=11.

This will add a local INSTAR HD or Full HD camera with the IP address 192.168.2.165 on the default HTTP Port 80 and with the default RTSP Port 554. The camera login is admin/instar in this example - but note: you do not need to use the Administrator account to access the live video.

Now reload Home Assistant to be able to see the changes you just made. Once the UI is back up, click on Configure UI in the top right:


Home Assistant with your INSTAR IP Camera


You might want to add a new Tab for your camera by clicking on the small + icon next to your existing tabs. Then click on the big + Button to add a new card.


Home Assistant with your INSTAR IP Camera


Here we have to add a new Entity and select the camera that we just added - in the case above this was camera.in_8015fhd:


Home Assistant with your INSTAR IP Camera

Home Assistant with your INSTAR IP Camera


Save your setting and quit the UI configuration mode. You should see a small tile with a snapshot from your camera. Click on it to be directed to the live video:


Home Assistant with your INSTAR IP Camera


Using Home Assistant as Alarmserver for your INSTAR Camera

All INSTAR Full HD cameras have a function to send a POST request to a HTTP Webhook when an alarm is triggered (HD cameras currently only support GET requests that are not supported by Home Assistant - though you will be able to use Node-RED to receive a GET request from your HD camera and trigger a POST request to Home Assistant).

When such a post request is received by Home Assistant such an event can be used as a trigger for your automation to control your INSTAR Full HD camera.

For details on how to add camera controls for your INSTAR FUll HD camera please follow our INSTAR MQTT Broker Tutorial

To set up a Webhook that can be used by your camera first open the Lovelace UI and go to Configuration and open the Automation tab:


Home Assistant with your INSTAR IP Camera


Click on the + icon to add a new automation and select Webhook as the automation trigger - the name you choose here for the Webhook will be used to name the resulting URL e.g. mqtt_test (better don't use spaces or special characters):


Home Assistant with your INSTAR IP Camera


Now we need to define an action that we want to trigger. For this we are going to use a MQTT Publish service we created in the INSTAR MQTT Broker. This service requires a MQTT topic (Target) and a MQTT message payload (Message) to be passed down:

{
  "message": "{\"val\":\"1\"}",
  "target": "instar/000389888811/features/ptz/preset"
}

Home Assistant with your INSTAR IP Camera


Here we choose the features/ptz/preset MQTT Topic and send the payload value 1 which will tell the camera with the MAC address 000389888811 to move to Preset Position 2 (numbering of those positions starts at 0).

When you hit Save this automation will be saved inside the automations.yaml file inside the Home Assistant directory:

- id: '1571301476710'
  alias: TEST MQTT Webhook
  trigger:
  - platform: webhook
    webhook_id: mqtt_test
  condition: []
  action:
  - data:
      message: '{"val":"1"}'
      target: instar/000389888811/features/ptz/preset
    service: script.send_mqtt_command

You could test triggering the above automation by sending a POST HTTP Request to

http://your-home-assistant:8123/api/webhook/mqtt_test

Home Assistant with your INSTAR IP Camera


Sending the command curl -d "" http://192.168.2.43:8123/api/webhook/mqtt_test triggers the automation and sends the camera into the second preset position.

Now that we know that our automation is working and the Webhook is set up, we can configure our camera to contact Home Assistant when an Alarm is triggered by the camera internal detection systems. Please open the Alarmserver configuration inside your camera's web user interface and add the Home Assistant Webhook to the following form (don't forget to activate the POST Request):


Home Assistant with your INSTAR IP Camera


Now, every time an alert is triggered our camera will contact it's Alarmserver - the Home Assistant installation - and start the automation.

Please check out our Smarthome Overview for more examples how you can automate your camera using Home Assistant. Simply switch the MQTT topic to automate different functions on your camera.