Hackerspace Wroclaw Alarm Bot

Warning: this is a proof of concept, don't rely on it

It was very basically tested, and while it seems to work, approach it without any expectations. In other words - treat it as a toy, not as a tool that will save your life or valuables, because it probably won't.

Running

$ TELEGRAM_APITOKEN=YOUR_API_TOKEN ./alarm-bot

Remember that hswro-alarm-bot.yml should be present in the current directory.

Configuration via YAML file

Configuration should be stored in hswro-alarm-bot.yml in current directory.

satel-addr: "192.168.13.37"
tg-chat-ids:
 - 1234
 - 5678
 - 9876
allowed-types:
 - "zone-isolate"
 - "zone-alarm"
allowed-indexes:
 - 5678
 - 1337
pool-interval: 5m
arm-callback-urls:
 - "http://192.168.1.10/hello"
 - "http://example.com/api"
disarm-callback-urls:
 - "http://192.168.1.10/bye"
 - "http://example.com/api2"
alarm-callback-urls:
 - "http://192.168.1.10/ohno"
 - "http://example.com/api3"
matterbridge:
 - uri: "http://localhost:4242/api/message"
   token: "test_token_1"
   gateway: "test_gateway_1"
   username: "test_username_1"

• pool-interval sets how often will the Satel device be asked for changes
• satel-addr sets the IP address of the Satel device
• tg-chat-ids sets which telegram groups will receive notifications about alarm state changes

Matterbridge integration

As Telegram is kinda questionable it's beneficial to get the notifications somewhere else as well. This bot can utilize Matterbridge's API to send notifications to many different chat platforms. Check the Matterbridge API documentation to learn how to configure your existing MAtterbridge installation.

Tip: You can still have independent Telegram and Matterbridge notifications - simply set up an additional gateway in Matterbridge that pushes the messages to your non-telegram chat groups but omits the Telegram group to avoid duplicated messages. Those other chat groups can be the same as those where your regular messages are bridged - Matterbridge will handle that just fine without the need for duplicated bots etc.

To configure that set the matterbridge part of the config file with the following parameters:

• uri - URI to your Matterbridge's API
• token - Token that you've set up for yout Matterbridge API. Situation where this token is not configured is not taken into account.
• gateway - Set it to the same value that is set in the name parameter to your [[gateway]] in matterbridge.toml
• username - The username from which the alarm bot messages will appear to API.

Notification via HTTP callbacks

Set the values in following parts of the config file:

• arm-callback-urls - for an URL that will be POST when partition 0 is armed
• disarm-callback-urls - for an URL that will be POST when partition 0 is unarmed
• alarm-callback-urls - for an URL that will be POST when any partition alarm is activated

Filtering events by change type

It's possible to filter events by change type. Use the allowed-types part of the config file to do that. If that parameter is not provided, then all change types are allowed, otherwise only the provided ones will be used for notifications.

Supported types are:

• zone-violation
• zone-tamper
• zone-alarm
• zone-tamper-alarm
• zone-alarm-memory
• zone-tamper-alarm-memory
• zone-bypass
• zone-no-violation-trouble
• zone-long-violation-trouble
• armed-partition-suppressed
• armed-partition
• partition-armed-mode-2
• partition-armed-mode-3
• partition-with-1st-code-enter
• partition-entry-time
• partition-exit-time-over-10s
• partition-exit-time-under-10s
• partition-temporary-blocked
• partition-blocked-guard-round
• partition-alarm
• partition-fire-alarm
• partition-alarm-memory
• partition-fire-alarm-memory
• output
• doors-opened
• doors-opened-long
• status-bit
• trouble-part-1
• trouble-part-2
• trouble-part-3
• trouble-part-4
• trouble-part-5
• trouble-memory-part-1
• trouble-memory-part-2
• trouble-memory-part-3
• trouble-memory-part-4
• trouble-memory-part-5
• partition-with-violated-zones
• zone-isolate

Filtering events by index (which meaning depends on the change type)

Use the allowed-indexes part of config file to set the list of allowed indexes. If that parameter is not provided, then all indexes are allowed; otherwise the notification is sent only for provided indexes.

example systemd unit

[Unit]
Description=Satel Alarm Telegram Status Notifier
Requires=network.target
After=network.target

[Service]
Type=simple
ExecStart=/path/to/alarm_bot
Environment=TELEGRAM_APITOKEN=YOUR_API_TOKEN
DynamicUser=True
RuntimeDirectory=hswro-alarm-bot
StateDirectory=hswro-alarm-bot
RestartSec=30
Restart=on-failure

CPUAccounting=true
CPUQuota=5%
MemoryAccounting=true
MemoryHigh=25M
MemoryMax=50M

[Install]
WantedBy=multi-user.target

Debugging

Set the OMIT_TG environment variable to, well, omit sending anything over to Telegram and just see the logs instead.