As of HSS_v1.2.0 onwards, the format of the config file has been changed slightly to accommodate a “label” feature.

Although the following instructions are still applicable, you should read the FAQ section to understand the “label” feature.

Creating…   hss_config.txt file
If you have got to this section then it is assumed you have HSS up-and-running using the out-of-the-box configuration file. What this section does is explain how to convert the basic configuration file so it matches your system requirements.

If you look in the document-root directory, which on a Raspberry Pi, would be: /var/www/html/hss_media  you should see…

• hss_config_basic.txt
• hss_config_plain.txt
• hss_config_sample.txt

These three files give you a good starting point to create the target file called… ‘hss_config.txt’

You can modify hss_config_basic.txt and insert additional material or you could use hss_config_plain.txt if you wanted to start from scratch with a blank file. Alternatively, you could use hss_config_sample.txt and make adjustments by editing and adding material.

Whatever you decide to do, you need to copy the appropriate source file to: hss_config.txt by performing the following steps.

SSH into the document_root area on your Raspberry Pi and then using the terminal window enter these commands.

   cd  /var/www/html/hss_media

Copy the source file to hss_config.txt

   cp  hss_config_xxxxx.txt  hss_config.txt        // Where xxxxx = basic, plain or sample

If for some reason you can’t find the three config files in your document_root area, you can download a copy from the Downloads area of this website and then modify it as per the instructions below.

For the sake of this example it is assumed you are called Fred Bloggs and your email address is fred.bloggs@gmail.com

It is also assumed you are a Telegram user with a ‘chatId’ of 123456789.

At certain places in this description are values/options you should enter if you are using a Mac to run HSS.

It is also assumed you have installed NGINX (or an alternative web server like Apache2 or lighttpd) and the server is working and able to interpret PHP files, and the document_root is located at…    /var/www/html

Note: If you are using a Mac then the document_root will probably be located at:  /Users/<your_user>/Sites   
e.g.  /Users/Fred/Sites

Please pay particular attention to the layout and formatting of the hss_config.txt file as missing or putting a comma in the wrong place will cause errors during the initialisation process in Node-RED’s flow. Each definition line must end with a comma. If the definition includes a definition of an object, then each line in the object must end with a comma EXCEPT the very last line.

Editing…   hss_config.txt file
The first thing you need to adjust is your email address and your chatId (if you are going to use Telegram).
You can see the above details shown in bold have been entered into this part of hss_config.txt

The next thing you need to define is the platform being used to run HSS. RPI has been entered here as you are running on a Raspberry Pi. Enter ‘macOS’ if you are using a Mac to run HSS.

This section is where you define the document_root for your web server. The most common place that is used is… /var/www/html

Note: If you are using a Mac then enter:  /Users/<your_user_id>/Sites   For example:   /Users/Fred/Sites

Recording. Enter a value for the number of seconds a screen recording should last for and also the type of recording format.

Note: If you are using a Mac then enter:  “mov” as the recording format.

The next, rather long section, deals with the various cameras you want to use with HSS. The key thing you need to know, in order to complete this part of the hss_config.txt file, is the URL for the stream your camera produces.

This first example shows a video stream produced by a Raspberry Pi running MotionEYE-OS. As you can see this particular camera is operating on IP address 192.168.1.182 - yours will most certainly be a different address.

The next example is the stream that is produced by the low-cost ESP32-CAM or the ESP-EYE. As you can see this particular camera is operating on IP address 192.168.1.160 - yours will most certainly be a different address.

Here’s another example using a low-cost IP network camera. In this case it is the D-Link DCS-936L. This particular camera requires a user to login with a user name and password in order to access the stream. These details should be entered in the “url” line.
This particular camera has an option for a user to login without settings any credentials - if you select this option then the “url” could be shortened to…  “url”: “http://192.168.1.167/video/mjpg.cgi”,

Here’s an example of using an Android phone as a camera with HSS.  The DroidCAM app needs to be downloaded to your phone and when it is started the IP address displayed on your phone’s screen needs to be entered in the “url” line. To save having to find the IP address each time you use the phone, the phone could be assigned a fixed IP address by using the Address Reservation facility (keyed to the phone’s MAC address). This facility is available in most modern routers.

The next three sections show examples of handling IP cameras that conform to the HLS.M3U8 protocol. Here’s a link to an article that explains this protocol. HTTP Live Streaming (HLS)

If you inspect the Node-RED flow for HSS you will see some tabs labelled IP CAM9 to IP CAM12 that have been configured to connect to a set of streams published by different streaming companies. The first example, shown on tab IP CAM10, is from the RedBull TV company. The inject node, labelled RedBull, contains all the parameters to connect to this particular stream.

Here’s another example using ‘cam11’ to connect to China CGTN, the China News TV channel.

This example shows ‘cam12’ connected to JSDN.

This example shows ‘cam9’ connected to the video called ‘Tears of Steel’.

This example shows an alternative way of connecting to an IP video stream.

If this is the last camera in the definition sequence, then it should be ended with the following format.

If you look carefully in the above definition you will see the comma after the last curly  } bracket has been omitted and add extra curly bracket and a comma }, have been added on a new line. This is needed to terminate the “cameras”: definition block.

The next section shows examples of linking one or more external video streams to HSS. Here we have linked a YouTube video and the all time classic “Big Buck Bunny” movie.

This section shows how you can define which camera stream will appear on each of the five monitors.

This section enables you to define the camera sequence that will be followed when you click the ‘Tour’ button. You can also specify the delay time that HSS spends on each camera before it moves onto the next one.

Changing this section is optional and depends on whether you want to make use of the User Button. The entries shown below will cause the User Button to automatically be labelled when the HSS Initialization flow is executed.

Please note that you will have to create some code (e.g. JavaScript) to deal with what happens when you click the button. If you want to make use of the values in msg.topic and msg.payload, then you can specify what they should be as shown below.     

Saving…   hss_config.txt file
Once you have made all the adjustments to ‘hss_config.txt’ save it away.

Making adjustments to HSS flow
You then need to do a simple adjustment to the HSS flow so ‘hss_config.txt’ is used in the ‘initialization’ sequence.

As you can see from the screen-shot below, you need to re-route the wire from the ‘inject’ node labelled ‘Load… hss_config.txt’ to the ‘http request’ node, then Deploy the Node-RED flow

Using this method means, if your newly created config file doesn’t work correctly, you can revert back to ‘hss_config_basic.txt’ while you sort out what’s wrong.

Once again - please make sure you pay attention to the format of the hss_config.txt file because if the file is not formatted correctly then it will ‘error’ when it is read by Node-RED during initialisation.

Final adjustments to HSS flow
If you are planning on using Home Surveillance System’s capability to send a snapshot to your email and/or Telegram account, then you need to enter the appropriate credentials in the email and telegram nodes.

Go to the flow-tab labelled HSS Notifications and locate this piece of wiring.

The Telegram node is disabled by default - you need to enable it by double-clicking it and changing the option that reads ‘Disabled’ to ‘Enabled’  then click the [ Done ] button. The view will then change to this.

The first item we are going to set-up is the ‘Telegram sender’ node. Double-click this node to reveal the following.

Enter the Bot-Name and Token for the account where the snapshot should be sent. This information can be obtained by using the ‘BotFather’ administration facility.

When you have completed this task,  click the [ Done ] button to save the details and Deploy the flow.

The next item to set-up is the email facility. Locate this piece of wiring.

The Email node is disabled by default - you need to enable it by double-clicking it and changing the option that reads ‘Disabled’ to ‘Enabled’  then click the [ Done ] button. The view will then change to this.

Double-click the green email node to reveal the following.

What you need to enter here are the credentials needed to send an email. The To entry can be left blank as the flow uses the email address you specified at the start of this section.

The other entries will vary depending on which Internet Service Provider (ISP) you use to send emails.

The example shown here is for Google Mail - gmail.  The name of the out-going server is… smtp.gmail.com

It uses a secure connection on Port 465.

The Userid will probably be the same as your email address. For example fred.bloggs@gmail.com

The Password will obviously be the password you specified when you created your gmail account

When you have completed this task,  click the [ Done ] button to save the details and Deploy the flow.

Congratulations you have come to the end of setting-up the configuration file and adjusting the HSS flow.

If you encounter any problems, when you run the Home Surveillance System, you should re-check the above steps to make sure you haven’t missed a comma or semi-colon. As was mentioned before, you can revert to using ‘hss_config_basic.txt’ to make sure HSS is still working. You could also compare the layout and format of the two files to see if you can spot a mistake.

There is a Frequently Asked Questions (FAQs) section on this website where you will find additional help and guidance.

This is the recommended sequence to get HSS up-and-running quickly and easily.

Please take the time to read the material on these website pages and to perform the steps in the sequence 1 through to 4.

1. Requirements
    This section explains about networks, the extra nodes you need to install for Node-RED and some guidance on
    cameras that work well with HSS.

2. NGINX
    This section explains how to install NGINX, a web server, if you haven’t got one already running on your computer.

3. Install
    This section is a step-by-step guide for the installation sequence of HSS (using the out-of-the box config file)

4. Config file  <<< You are here
    This section is a detailed step-by-step guide, explaining how to customise HSS to accept your cameras, etc..