openGalaxy - a SIA receiver for Galaxy security control panels.
Copyright (C) 2014, Alexander Bruines <alexander.bruines@gmail.com>
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 2 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>.
INDEX:
------
- About openGalaxy
- How it works
- Requirements to install/configure/use this software
- Building/Installing
- Runtime configuration
- Using openGalaxy
- Configuring the Galaxy security control panel
- Still to do
- List of supported commands
- Command examples
About openGalaxy:
----------------------
openGalaxy is a software tool that listens on a serial port for incoming
SIA formatted alarm messages from a Galaxy security control panel. These
messages may then be stored in a MySQL database and/or forwarded by email.
This software is written for use by trained security professionals, but
it could also be used by a layperson who wants to receive the exact same
messages that are normally send to a private emergency response company.
In addition to just listening for messages, openGalaxy can also be used to
arm and disarm areas, omit zones and even to (re)set outputs, a complete
list of commands can be found at the end of this document.
So far, this software has only been tested with a 'Galaxy G3-520' control
panel and some older Galaxy control panels (G18/G60) with varying (Dutch)
firmware versions.
More information about Galaxy control panels can be found on the
manufacturers website for the european market:
http://www.security.honeywell.com/uk/
This software was written using publicly available documentation about the
SIA protocol combined with data analysis of observed rs232 traffic (in
between a Galaxy panel and other software packages) in order to figure out
how to remotely control the panel using the SIA protocol.
openGalaxy is still in a testing (BETA) phase and should not be considered
stable or secure (yet).
openGalaxy is based in part on the work of the libwebsockets project
(http://libwebsockets.org)
openGalaxy makes use of MySQL Connector/C (libmysqlclient) which is
released under the GNU General Public License version 2 and Copyright (c)
2000, 2013, Oracle and/or its affiliates. All rights reserved.
How it works:
-------------
This program listens (on a serial port) for incoming SIA messages and
decodes them. Each message is then send to a websocket and optionaly
to a database (MySQL and/or ODBC).
The messages may also be forwarded to 1 or several email accounts.
In addition to just listening for messages, openGalaxy also provides a
method for sending commands back to the control panel.
By itself openGalaxy is not very usable apart from logging SIA messages
and sending the occasional command to a panel. openGalaxy is meant to be
used by another application that uses the interface openGalaxy provides.
The interface openGalaxy provides consists of a webinterface that uses
a websocket to send SIA messages to, and recieve commands from clients.
Requirements to install/configure/use this software:
----------------------------------------------------
- The user running this software must be a member of group 'dailout'
to be able to use the serial port, and also of group 'mail' if the
email output plugin is used.
- libwebsockets is used to provide the webinterface.
(http://libwebsockets.org)
- The SSMTP package for you distro must be installed in /usr/bin/ssmtp
(Only if you use the email output plugin.)
- libmysqlclient (http://dev.mysql.com/downloads/connector/c/)
is needed for use by the MySQL output plug-in.
- Access to a MySQL server is needed if the MySQL output plug-in is used.
Note:
The code of openGalaxy is multithreaded and uses the POSIX Threads library
(available by default on most modern Linux distributions).
Building/Installing:
--------------------
From this directory, execute:
./configure
followed by:
make && sudo make install
This will install the following file(s):
/usr/local/bin/openGalaxy
Note:
The ./configure script has several options that may assist in compiling
openGalaxy on your target:
--prefix=<DIR>
Installation prefix for installed files
The default is /usr/local
--sysconfdir=<DIR>
Installation prefix for installed configuration files
The default is $(prefix)/etc
--datadir=<DIR>
Installation prefix for installed data files
The default is $(prefix)/share
--without-email-plugin
Disables support for forwarding SIA messages by email
--without-mysql-plugin
Disables support for writing SIA messages to a MySQL database
--with-odbc-plugin
Enables support for writing to a ODBC database (not finished yet)
--with-libwebsockets=<DIR>
Sets the path to the libwebsockets library
The default is /usr/local/lib
--with-libwebsockets-include=<DIR>
Sets the path to the libwebsockets.h header file
The default is /usr/local/include
--with-libmysqlclient=<DIR>
Sets the path to libmysqlclient
The default is /usr/local/mysql
Runtime configuration:
----------------------
To configure openGalaxy, edit the configuration files:
$(sysconfdir)/galaxy/galaxy.conf
$(sysconfdir)/galaxy/ssmtp.conf
$(sysconfdir) is /usr/local/etc, unless changed during the ./configure step
The file(s) in '$(datadir)/galaxy/www' provide the webinterface.
$(datadir) defaults to /usr/local/share
Using openGalaxy:
-----------------
Connect the configured serial port to your control panel and run
'openGalaxy'. To stop the program, press CRTL+C.
While openGalaxy is running the panel may be remotely controlled by
opening a webbrowser* and connecting to the port openGalaxy was
configured to use:
http://localhost:1500
This webinterface also provides a live view of incoming SIA messages
on the websocket.
* The browser must support HTML5
To demonstrate displaying messages written to a MySQL database a small
example webinterface is included in the example directory:
It is written using php5, JQuery and JQuery UI and displays decoded SIA
messages in a web browser as soon as they are written to a MySQL database.
How to set up a web-server is beyond the scope of this documentation, but
the files in the example directory may be copied to the 'docroot' of your
web-server. The web-server will need to support php5 and you'll need to
adjust the settings in 'example/dbconnect.php'
To create the initial database used by the MySQL output plug-in, execute:
mysql -u root -p -h servername <CreateDatabase.sql
mysql -u root -p -h servername <CreateUser.sql
(Edit CreateUser.sql to change the passwords used to connect to the database,
the default is 'topsecret'.)
Configuring the Galaxy security control panel:
----------------------------------------------
- Using the installer code, go to menu 56 and select the RS232 module
- Program the RS232 for SIA level 3 (or 4 if available) and select all
triggers
- Configure the RS232 for 9600 8N1 (Use the same baudrate on the computer!)
- The account ID should not be left empty!
Still to do:
------------
(ordered by priority)
- Output all replies to commands in JSON format (now it's just text)
- Enable SSL on the webinterface/websocket
- Finish the ODBC database output plugin
- Enable support for compiling on windows (cygwin?)
- Deamonize openGalaxy so that it is started as a service
(will be done in a future release when I deem this software package
stable enough).
- See if newer Galaxy panels (Galaxy Dimension series) support more/other
functions to remotely control those panels. *
- Add support for receiving/sending SIA messages over a network using the
Galaxy Ethernet module. *
* I don't own either of these hardware components so support for them is
currently on hold. Donations are welcome ;)
List of supported commands:
---------------------------
The following is a list of commands may be executed by using the
webinterface:
-- AREA -------------------------------------------------------------------
Syntax: AREA <blknum> <action>
Where:
blknum = Area number (0-32), special area 0 operates on all areas.
action = UNSET Disarm an area
SET Arm an area
PARTIAL Partially arm an area
RESET Reset an area
ABORT Abort setting an area
FORCE Force setting an area
STATE Get the status of an area
0=unset, 1=set, 2=partial
READY Area status with more states
3=Ready to arm, 4=Time locked
ALARM Get the alarm status of an area
0=normal, 1=alarm, 2=reset required
-- ZONE -------------------------------------------------------------------
Syntax: ZONE <nr> <action>
Where:
nr = Zone (1001-4158) or zone-type (1-100)
action = OMIT Omit a zone by number or type
UNOMIT Un-omit a zone by number or type
ISOMIT Get omit status of a zone (by number)
STATE Get the status of a zone (by number)
-- ZONES ------------------------------------------------------------------
Syntax: ZONES <action>
Where:
action = READY Get the ready state of all zones
ALARM Get the alarm state of all zones
OPEN Get the open state of all zones
TAMPER Get the tamper state of all zones
RSTATE Get the resistance state of all zones
OMITTED Get the omitted state of all zones
-- OUTPUT -----------------------------------------------------------------
Syntax: OUTPUT <nr> <action> [blknum]
OUTPUT GETALL
Where:
nr = Output (1001-4154) or output type (1-100)
special output type 0 means all outputs
action = ON Turn the output on
OFF Turn the output off
blknum = Area number (0-32), special area 0 operates on all areas.
When not specified, area 0 is implied.
Only has effect for actions on output-types.
Note: GETALL returns an array of 32 bytes with
each bit representing the state of an output.
Note: When setting by output number the panel will ignore
that outputs programming and just performs <action>.
When setting by type, the outputs will follow their
normal programming.
-- HELP -------------------------------------------------------------------
Syntax: HELP <command>
Provides help on a specific command.
Command examples:
-----------------
# Arm area 1
area 1 set
# Omit zone 2145
zone 2145 omit
# Activate output 1002
output 1002 on
Download Latest Version
opengalaxy-0.15.tar.xz (30.8 MB)
