search

scarpazza / home-assistant-konnected-tutorial

A minimalistic tutorial on Home Assistant - Konnected Alarm board integration
55 stars 4 forks source link

readme

Creating a smart alarm system in Home Assistant with Konnected Alarm Pro boards

This is a minimalistic, step-by-step tutorial on how to bring up a full-featured alarm system based on the Konnected Alarm Pro board in Home Assistant.

Motivation

I wrote this tutorial because I found existing documentation lacking in their coverage of the distinction between the functions built into Home Assistant's manual alarm panel and those you must add yourself to bring up a functional system. New users of Konnected.io with no prior Home Assistant experience seem especially puzzled by manual's documentation.

Audience

My ideal reader is someone who just unboxed their Konnected boards and wants to integrate them into an existing Home Assistant setup, but has no prior experience with HA's alarm panels. This tutorial has many limitations and teaches by example rather than covering concepts in depth. That's by design: it's intended for audiences who prefer understanding a design as they bring it up, as opposed to mastering all concepts before writing any configuration code.

I learn with my hands. If you are like me, this tutorial might be a more useful initial starting point than HA documentation.

My design decisions are somewhat arbitrary, and tuned to my very personal needs. Change them according to your needs.

All feedback is welcome, but I'll make corrections only workload and family permitting. I have a full time job, two kids and other hobbies.

Acknowledgments

Many thanks to @johnny-co for his help in testing and fixing my typos.

Mistakes and improvements

I no longer maintain this project regularly, and therefore I encourage correctionst and updates from the community. Feel free to open issues and send pull requests.

Step 1 - configure the boards

Start configuring the Konnected boards from the Konnected mobile phone app including inclusion into your home wi-fi network. While this step is pretty straightforward and already documented plenty elsewhere, there is one important caveat that has to do with your phone's OS.

At one point during the setup of a new board, the Konnected app will require you to join the konnected- wi-fi, and will open up your phone's wi-fi settings page for you to do so.

On Android phones, pay special attention to your phone's notifications, including one saying

Wi-fi has no internet access
Touch for options

Do touch that notification, which leads to a dialog box informing you that

This network has no internet access. 
Stay connected? [No] [Yes]

You must select the checkbox "Don't ask again for this network" and tap "Yes". Failing to do so might well cause your Android phone to revert automatically to your home network (without warning), thus preventing communication with the Konnected board.

You now have the options to configure Zones and Sensors in the Konnected app. You only need to do so if you plan to register your board with the Konnected Cloud, which is only necessary if you plan to integrate it into Samsung's SmartThings.

The decision is up to you: the device can be operated in the SmartThings and Home Assistant ecosystems concurrently. If you choose to do so, consider taking a screenshot of your configuration page, in order to ensure it is consistent with the Home Assistant configuration you will specify in the next step.

Step 2 - integration

A. Configure the Konnected integration.

Start this process in the Home Assistant UI by selecting "Configuration", then "Integrations", then "Konnected.io". After you provide your Konnected username and password, HomeAssistant must create one device for each board you have.

At this point you need to configure once again your zones inside Home Assistant, replicating the same options you selected in the app in the previous step. (For the avoidance of doubt, I use the word zone as a synonym for sensor, as Konnected.io documentation does. This is a disjoint concept from Home Assistant's Zones, that are basically geofencing areas designed to track people's presence.)

Do it by clicking "Options" on the card associated with each board. This is a rather laborious process: you'll be presented with two pages to configure zones 1-6 and 7-12 (plus outputs), followed by as many additional pages as the zones you enabled. It is at this moment that the screenshot you took in the previous step comes in handy.

Even if it takes extra time, choose good, descriptive names for the zones now, as opposed to choosing poor names that you'll come back to revise later. Home Assistant will create entity names based on your descriptive names. Doing things right the first time will save you time in the end.

Good examples of descriptive names are "Bedroom window sensor", "Living room motion sensor" and "Boiler room CO detector".

B. Configure additional (optional) support systems Studio Code Server - Tool to easily modify configuration.yaml, scripts.yaml, groups.yaml, automations.yaml, etc.

Sonos - Use Sonos TTS to give verbal warnings, eg. 'Disarm before alarm sounds', 'House Armed', etc.

Step 3 - create the alarm automaton

In this step you create what Home Assistant calls a "manual alarm control panel".

Contrary to reasonable expectations, this panel only performs a fraction of an alarm panel's typical functions. You should think of it not as a complete control panel, but rather as a finite state machine or automaton. (Do not confuse automaton with automation - we will have instances of both.)

Specifically, the manual control panel automaton has:

  1. a defined collection of states: disarmed, arming, armed_home, armed_away, pending, triggered;
  2. customizable delays between one state and the other, and
  3. user interface code that displays the panel in the dashboard and takes your input.

It is important to realize what the control panel does not: it does not include triggers and responses. You'll need to write those yourself:

  1. you will define what triggers will cause a transition from a state to another, except for the arm/disarm UI inputs. The most important among them will be what triggers the alarm;
  2. you will define the responses you want when the alarm enters or leaves certain states. They determines how Home Assistant reacts when the alarm triggers, is armed, is disarmed, become pending, etc.

This tutorial covers triggers and responses in the next steps. In this step, you merely create the automaton. You do so by editing your configuration.yaml file.

You might be surprised by my example creating not one but two panels: one for intrusion and for fire/CO (CO: carbon monoxide detection).

I recommend two distinct panels because you want them to behave differently. Specifically, you may want to arm/disarm the home intrusion alarm automatically according to presence in the house, whereas fire/CO detection should always active (except for exceptional circumstances like maintenance or incident investigation).

Here are the lines I added in my configuration.yaml:

alarm_control_panel:
  - platform: manual
    name: Home Alarm
    arming_time: 15
    delay_time: 30
    trigger_time: 180
  - platform: manual
    name: Fire and CO Alarm
    arming_time: 0
    delay_time: 0
    trigger_time: 180

Relevant configuration options are as follows:

Contrary to most examples you find on the internet, I chose not to set up an arming/disarming code. Consider requiring a code if you have wall-mounted tablets in the house, to prevent burglars from disarming the system with a simple tap. Otherwise, rather focus on fortifying security at the app/website login point, e.g., enabling encryption (https).

You can always come back and tweak these setting later, including setting a code. At that point, you'll know the process enough to naviage options yourself from the HA manual documentation.

If you choose to set up a code, the alarm card in the UI will present you with a numeric keyboard to type that code. If you do not, the UI will hide that keyboard.

Step 4 - define sensor groups

In this step you aggregate your sensors in meaningful groups, creating as many as necessary, with special attention to groups that you don't want to trigger the alarm when you are home at night, and sensors you always want to trigger a response if the alarm is armed.

In my example, I group motion sensors together, door sensors together, and window sensors together.

The main purpose of this step is to simplify trigger rules and sensor testing. This is especially useful when you have many sensors and zones.

Even if you don't care about grouping sensors by type, it's still useful to create at least one group where they all belong: this makes it easier for you write trigger automations.

You do this by adding to your groups.yaml file the contents in sensor-groups.yaml. (Remove the original [] contents, if that's all you have in that file.)

Step 5 - user interface

In this step you add the alarm user interface cards to HA's Lovelace dashboards.

Create and use a new view named 'Security' and matching url 'security'. This becomes important in scripts below.

Then create at least the control panel card. In the example figure below, it's the one called "Home Alarm" in the left column.

In addition to that, I recommend you create a history card that tracks the alarm state in the last 24 hours, displaying it against your presence at home. In the example below, I chart alarm status against me and my wife's presence at home. Presence here is detected via Zone and mobile phone sensors.

If you don't have your Home Assistant phone app configured yet, I recommend you go configure it now, and definitely before you get to Step 8, during which you will create "smart" automations.

You should also create entity cards depicting the state of the individual sensors, and sensor groups. You'll be using them at least once during the walkaround, but I find it useful to see what's going on in the house.

For illustration purposes, here is my security dashboard at the end of this step: Sample security dashboard

Step 6 - walkaround

Do a walkaround of the house, with your phone in your hand, explicitly triggering all sensors one by one and verifying that each of them behaves as desired.

Finally, trigger the buzzers manually and trigger the siren manually, verifying they behave as desired.

Step 7 - System health sensors and groups

This is a more recent addition to my set up, intended to prevent silent failures. I'm especially interested in monitoring the reachability of the Konnected boards from Home Assistant. In one instance I found that both my Konnected boards "fell off" my home network (either hung or stopped being reachable), and the system failed silently. The HA alarm panel would arm and disarm according to the automations, but would be really blind to any intrusion, because door sensor events or motion sensor events could not reach the HA server... because the Konnected boards were not on the network.

To counter that, I define as many ping sensors as Konnected boards I have: (do this in your configuration.yaml

binary_sensor:

  - platform: ping
    host: 192.168.x.y1
    name: Konnected Board 1
    count: 2
    scan_interval: 10

  - platform: ping
    host: 192.168.x.y2
    name: Konnected Board 2                                                            
    count: 2
    scan_interval: 10

Correct both host: entries, placing there the static IP addresses of your Konnected boards. Each of these sensors will ping the corresponding board every ten seconds, return a false truth value when the board misses two pings in a sequence.

If you have multiple boards, you also want to create a corresponding group in your groups.yaml:

konnected_boards:
    name: Konnected Boards
    icon: mdi:lan-connect
    all: true
    entities:
    - binary_sensor.konnected_board_1
    - binary_sensor.konnected_board_2

Pay attention to configuration variable all being set to true. By default, sensor groups are "on" when any of the sensors in the group is "on". This behavior is not the desired one - you rather want HA to declare your system healthy when all boards are connected. Variable all: true achieves that goal.

In your lovelace dashboard, add appropriate cards to track system health, e.g.:

Step 8 - core automations

In this step you will create automations (alarm triggers and responses) that perform those functions you would expect a traditional, keypad based, 1990s, "dumb" intrusion alarm system to perform: arm, disarm, trigger, sound the siren, send you notifications.

I recommend the automations described below. They are quite a few. Of course my setup is arbitrary and could be done in a gazillion alternate, but this is a relatively comprehensive example and it works well with my mental representation of the alarm state machine. Modify it as you please.

Consider that the when your triggers fire, the alarm does NOT transition to state triggered. It goes instead into the pending state. This is a the 30 seconds grace period in which you go "oh, f'ck the alarm is on! let me disarm it!" and scramble to reach for your Home Assistant app as you drop your groceries. I sound the buzzer during that period.

Similarly, when press the "arm home" or "arm away" buttons, the alarm transitions into the arming state before it transitions into the respective armed status. That's designed to give you time to exit the house. I also sound the buzzer during that period.

To support automations that rely on time and date, add the following entry under your sensor: section in your configuration.yaml file:

sensor:
  # ...
  - platform: time_date                
    display_options:
      - 'time'
      - 'date'     
      - 'date_time'    
      - 'date_time_utc'
      - 'date_time_iso'
      - 'time_date'
      - 'time_utc'
      - 'beat'

I list the automations in order of importance, with the names that I suggest:

Text to speech

In the previous sections I mentioned text-to-speech announcements associated with alarm status transitions. At home I have Sonos smart speakers, and I use those for the announcements. I play those announcements via actions relying on a Sonos TTS script that is designed to pause the music being currently played on the speaker, get the announcement wavefile as rendered by a Google TTS call, play the announcement, and restore the smart speaker state (which will resume playing any music it was playing before the announcement, if any).

You will need the following entries in your configuration.yaml file to use Google's TTS interface:

tts:
  - platform: google_translate               
    cache: true
    cache_dir: /tmp/tts-cache    
    time_memory: 36000
    base_url: https://your_domain_name.duckdns.org:8123

Caveats:

  1. While the rest of the intrusion alarm is entirely self sufficient and able to work locally (including during network loss intentionally cause by burglars), this TTS function relies on access to Google. There are alternative TTS engines you can configure locally, but I haven't explored them yet.
  2. I manually created /tmp/tts-cache on my linux box where I run Home Assistant Core. If you run on a different platform, adapt the cache directory accordingly.
  3. Provide your external URL as a parameter to base_url. You can set up external HTTPS access following this tutorial.

Step 9 - geofencing automations

You should now consider smarter automations, primarily alarm geofencing, that Home Assistant can perform thanks to its app running on a GPS-enabled mobile phone. Geofencing is the most prominent feature that the traditional 1990s systems would not offer.

My philosophy is that I prefer to keep humans in the loop, so my automations do not always arm or disarm the system when your presence in proximity of the house changes. It rather prompts you with suggestions to arm or disarm. Of course, the automations I present are just examples, and you should configure yours to suit your unique needs.

Set up people and mobile apps

Configuring your people:

Note that device tracker entities become available in Home Assistant only after you have configured each mobile app.

Define a family group

You now want to define a family group for presence-tracking purposes, by adding the following to your groups.yaml file.

family:
  name: Family
  entities:
  - device_tracker.person1
  - device_tracker.person2
  - device_tracker.person3

This will act as your family group for the purpose of determining if someone is at home. Ideally, the system should prompt you to arm as soon as nobody is home, and remind you to unarm as soon as someone is coming home. The family group works well for that purpose:

Write your geo-fenced automations

Once your family group is established, I recommend the following automations:

Step 10 - repeat for the fire/CO alarm

Repeat Steps 4...8 for the fire and carbon monoxide alarm system.

You may want a separate dashboard, depending on the complexity of your system.

You need a few automations. I recommend the following:

Ensure that all these rules operate on alarm_control_panel.fire_and_co_alarm rather than the home alarm panel we used so far.

I won't describe them in detail because they are a simplified version of those I already described for the intrusion alarm.

Fire/CO automations are fewer and simpler than those of the intrusion alarm because you basically want fire/CO protection to be always armed, regardless of where you are.