Integrating Alarm Systems with Homekit

This post documents my journey implementing a Homekit integration for my Intelbras AMT8000 alarm system.

This particular alarm system is relatively common here in Brazil, as it can be found in Brazil for a decent price, and is surprisingly easy to install.

The sensors, keyboard, and sirens are all wire-free, which makes it a matter of pairing them with the system and then double-sided taping them wherever you want them.

Configuring it is not too bad either: using an shitty app to add all the sensors, setting up partitions, names, users… The only downside was how badly organized the app is, but once I memorized where the things are, it was easy too.

Then, it came to the worse part of it: the app used to arm/disarm the alarm.

As you can see, it doesn’t look too good. It also doesn’t work very well: it disconnects every now and then, and is usually slow to reconnect.

They made a new app (Intelbras Guardian), which looks like it was made in less than 10 years ago, but requires an account on their cloud, doesn’t allow to share the access with other people, and, to add assault to injury, also logs me off every now and then, but its worse than the previous app, as it also asks me to accept cookies, and fill the username and password manually, because of course password managers don’t work in that particular form.

On top of that, both apps are also impossible to integrate with anything else (e.g. Apple Home scenes), and it was bothering me too.

Intelbras’ support forums are full of people asking for Homekit/Siri integration, and Intelbras has been working on it avidly for the last 5 years, apparently.¹

Taking all that in, I knew, I was going to have to do it myself.

First step was figuring out the API.

API access

To get the API “documentation”, I had to:

• Find out the support number
• Send it a message on WhatsApp
• Navigate an ocean full of chat bot menus until I found the right one
• Give them my CPF (kinda like social security numbers in Brazil)
• Finally, get the URL to a zip file

The zip file contained a bunch of spreadsheets, some text files, and a Java and C# files - no PDFs in sight.²

So, I open the XSLX file that seemed more promising in Apple Numbers, and after what felt like an eternity, it finally opened.

There was indeed a lot of info, but it seemed off, like if things were missing. I assumed it was just bad documentation (expectations were low due to the fact that the documentation was a spreadsheet), but after a couple of days³, I realized that Numbers was indeed not rendering the full spreadsheet.

It was both shitty documentation, and shitty format (xslx) support on Apple Numbers.

I imported it on Google Sheets, and while it is almost unbearably slow, it does render what appears to be the full thing there.

Worth of note that while I was trying to read the documentation, I also found some implementations of this in other languages, which I also use as a reference. I also found a Go implementation of the previous version of the protocol.

The plan

My initial plan was to make some sort of web server that I could later integrate with as a Homebridge plugin.

So, I started with the client to the alarm system. Its API is basically whatever they used 2 decades ago over serial connections, but over TCP.

Yes, it is as horrible as it sounds. Yes, there are lots of bit packing. Yes, Wireshark is now my best friend.

To make a long story short, eventually I got to a working client that could read some statuses correctly, and arm/disarm the alarm.

Man plan, God laughs

After I got something working, I started looking into the Homebridge stuff I would have to write, and wasn’t really looking forward to it, to be honest.

I don’t know why, but I decided to search for “homekit protocol golang”, and found out hap.

To my surprise, it did everything I needed to do. I could now make the entire thing be a single binary, and written in Go!

Soon after that, I had the first working prototype!

Finishing up

From there, I kept adding the features I needed and improving it, and now, about 2 weeks later, I’m pretty happy with it!

It supports all the security system modes Homekit provides, has a panic button, all the sensors work (and report battery and tamper status), I can bypass zones, and, last but not least, I can add it to scenes and automations on Homekit - fucking finally!

Here are some screenshots:

Homekit is a little weird

If dealing with one weird thing weren’t enough, Homekit has its own perks.

It’s a closed protocol, so all the implementations (Homebridge, hap, and others) are products of reverse engineering the protocol - which also means there’s no complete documentation.

For instance, why the security system accessory forces me to have four modes (off, away, night, home)? How can I choose to have just a subset of them, or change the names? Is that even possible? I don’t know, and the only way to know this seems to be by becoming an official Apple Homekit Device whatever Apple calls it. No, thank you.

Also weird is that, while sensors allow to add tamper protection characteristics, it doesn’t send any alert/notification, or show anything, really, when a sensor is tampered with. The only way to know, is by looking into the details of every sensor. Bummer!

Finally, you can totally make combinations of characteristics/accessories that are, apparently, not allowed by the protocol. Hap will run happily, but it won’t work, and will only show you any error if you remove the bridge from your Home app and try to add it again.

Final words

If you’re interested, check out the source code.

If you want to do the same thing at your home with a different alarm system, check out Homebridge first, it might have a plugin ready for you.

You can also make Homekit act as your alarm central, using Homebridge, cheap sensors and a siren connected to a smart plug… not sure how well it works, but there are tutorials out there.

Thanks for reading, until the next time!