New integration: INIM alarm system

I managed to integrate my INIM home alarm system in openhab and am providing the steps that I used to achieve this.
This integration is not a full-fledged binding: I’m not a programmer and not able to make this. However it does manage to integrate the alarm system by making use of HTTP POST and JSONPATH.
I’d welcome an Openhab binding for INIM, so in case anyone would be able/willing to write this, I’d be happy to do the testing.

What is INIM?
INIM is an intrusion-detection-and-home-automation system. It’s an Italian brand, see their website for more details:

INIM uses their own software to configure their alarm systems, called Smartleague

Products?
INIM has several different type of control panels. I myself have tested this integration with the Smartliving control panel, more specifically the Smartliving 1050L. This method may potentially also work for other products, although this is not tested

Prerequisites?

  • The installed Smartliving alarm system
  • The Smartlan/G expansion ethernet card, connected to your home network

The smartlan/G is an expansion card which can be attached to the main board of the control panel. There are 2 types: Smartlan/Si and Smartlan/G.
Smartlan/Si is a basic version which provides access to INIM cloud services but which does not have its own webserver
Smartlan/G is more advanced and has its own webserver.

The integration described in this post is only possible through the Smartlan/G, as it requires the webserver for http POST.

Credits
This work has been built on the work which was already available on the internet, notably the integration which was already done for home-assistant.
Please see Inim Alarm - Hardware - Home Assistant Community, for the original source where I got most of my information. The only thing I have added is how to specifically integrate it in Openhab.
I specifically would like to thank Jan Willem Maas and Stewie3112 (Stefano) for their research on this topic and the notes which they shared

Setup and configuration

Step 1: retrieve the secret code and test the HTTP POST commmands

Controling the INIM system is possible through HTTP POST. For this method, you first need to retrieve your secret code, called “tk”
This code can be retrieved by using wireshark.

Start with navigating to the smartlan/g local ip, you should find a login screen like this:
fb1ba78faaaa5cf17b89cc91322111f298f4a5d4_2_547x500

login
open Wireshark
filter per network connection (In my case ethernet), destination device (ip of smartlan) and request method (POST)

91c014ef5b4c5a1941474a8e4af57da7b33debdb_2_690x74

now navigate to the page of interest (in my case “SCENARIOS”)

2ef3f079f83c6102faa953e843e774e76f65ed3c_2_690x345

bfd85b4d45c223bbb3180b0c8ab1cb0fedcda1a6_2_690x357

start wireshark sniffing
click one of the alarm scenarios and look closely at Wireshark. You should notice 2 POST requests different from the others in the “html form url encoded” section. skip the first one and go to the one like the screenshot above (with the form_item “mod”=“do_sce”)

5dc8839bf38d514fbede20dc3fbae079a986787a_2_469x500

you’ll find 4 keys:

  • tk (secret code)
  • qindex (always zero in my case)
  • mod (do_sce is the one to activate the scene)
  • par (is the scene number itself, test with other scenes and it’ll change)

To test if it works:
Install the chrome extension called “talented API tester” and use the values just found:

click send and… voilà, if you receive a 200 reply the scene should have changed.

Step 2: Execute the HTTP POST commands from Openhab
The following methods did not work for me to execute the HTTP POST commands:

  • using the HTTP binding, since the content-type application/x-www-form-urlencoded is not supported
  • using the sendHttpPostRequest which for some reason I could not get working

Instead, I executed the HTTP POST through a bash script using the following command:

val alarmscript = executeCommandLine(Duration.ofSeconds(20),"/etc/openhab/scripts/alarmcontacts.sh")

The alarmcontacts.sh scripts contains the following:

#!/bin/bash
curl -s -X POST -H "Content-Type:application/x-www-form-urlencoded" -d "tk=<your secret code>" -d "mod=zone" -d "par=now" -d "qindex=0" 'http://<your smartlanG IP>/cgi-bin/web.cgi'

The parameters mod and par can be changed and you can use different scripts, depending on what you would like to achieve. A quick quide:

  1. Arming and disarming the alarm:
  • mod = do_sce
  • par = 0 or 1 or 2 > Each number arms a different scene, depending on your configuration
  1. Reading the currentalarm scene:
  • mod = sce
  • par = now
  1. Getting the status of individual zones
  • mod = zone
  • par = now

See attached for an overview of the API parameters (credits to Jan Willem Maas):
API parameters summary.pdf (98.4 KB)

The HTTP POST Request results in a JSON response. The required value can be retrieved using JSONPATH

Step 3: Read the JSON response using JSONPATH

Use the following lines in yout .rules to retrieve the st values:

rule "Retrieve alarm contacts status"
when
		Time cron "0/20 * * ? * * *" // Every 20 seconds (note: it takes about 15 seconds for the bash command to run!)
then
    val alarmscript = executeCommandLine(Duration.ofSeconds(20),"/etc/openhab/scripts/alarmcontacts.sh")

    val Valuedeurinkom = transform("JSONPATH", "$.zone[1].st", alarmscript)
    val Valuedeurberging = transform("JSONPATH", "$.zone[2].st", alarmscript)
	...
    Alarm_zone_Deurinkom.postUpdate(Valuedeurinkom)
    Alarm_zone_Deurberging.postUpdate(Valuedeurberging)
	...
end

Using this methodology you can:

  • Read the status of your contacts and put the results in different items
  • Read the status of your alarm: armed, partially armed, disarmed, …
  • Control your alarm system: arm, disarm, …

I hope this guide is helpful for anyone looking to integrate his/her INIM alarm system into Openhab!