openGalaxy Files

openGalaxy - a SIA receiver for Galaxy security control panels.
Copyright (C) 2015, 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 version 2 as
published by the Free Software Foundation, with the additional
exemption that compiling, linking, and/or using OpenSSL is allowed.

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
- Acknoledgements
- Note about older Galaxy XL panels
- Configuring the Galaxy security control panel
- Preparing SSL certificates for using openGalaxy
- Runtime configuration
- Running openGalaxy
- Using the MySQL database created by openGalaxy
- Still to do
- Compilation of sourcecode (Linux 32 & 64 bit)
- Compilation of sourcecode (Win32 using MinGW-64/MSYS2)
- Known bugs

(Consult the changelog file for changes between versions of openGalaxy.)



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 are sent to a websocket interface and may optionally 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 (depending on the panels firmware version) arm and disarm areas,
omit zones and even to (re)set outputs.

This requires the 'remote' code to access the panel. A complete list of
commands can be found in the file 'API.TXT'

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.



Acknoledgements:
================

openGalaxy is based in part on the work of the libwebsockets project
(http://libwebsockets.org)

openGalaxy makes use of MySQL Connector/C 6.1 (libmysqlclient) which is
released under the GNU General Public License version 2 and Copyright (c)
2000, 2015, Oracle and/or its affiliates. All rights reserved.

This product includes software developed by the OpenSSL Project for
use in the OpenSSL Toolkit. (http://www.openssl.org/)

openGalaxy is based in part on the work of the CyaSSL project which is
released under the GNU General Public License version 2
(http://www.yassl.com/)

This product makes use of zlib. openGalaxy gratefully acknoledges the
contributions of Jean-loup Gailly and Mark Adler in creating the zlib
general purpose compresssion library.

openGalaxy uses GTK+ 3.0. GTK+ is covered by the GNU Lesser General
Public License (http://www.gtk.org/)

openGalaxy uses jQuery and jQuery-UI witch are provided under the
MIT license (http://jquery.org/license/).

openGalaxy uses the GNOME Adwaita icon theme witch is released under the
the terms of either the GNU LGPL v3 or Creative Commons Attribution-Share
Alike 3.0 United States License.



Note about older Galaxy XL panels:
==================================

Galaxy security panels have always been backwards compatible
(with the exception of G2 panels). The oldest class of panels are now
called XL panels and the new ones G2, G3 and Galaxy Dimension (GD).

The Galaxy XL panels may not support all of the functionality
provided by openGalaxy. Their level of support depends on the firmware
version of each of these panels.

I have only been able to test with the panels at my disposal so I do'nt
know about every quirk and caveat, you will have to test that out
for yourself.

On my Galaxy 18 v1.07 for instance the outputs may only be set by type and 
not by address. Also the area and output status can not be fetched or
seems to work but doesn't.

The newest panel that I can test with is a G3-520 v5.57. All functions in
openGalaxy work on this panel.



Configuring the Galaxy security control panel:
==============================================

- Using the installer code, go to communications menu (56) and select the
  RS232 module.

- Program the RS232 for SIA level 3 (or 4 if available) and select all
  triggers (Realy old panels may name the SIA protocol as 'MultiPro')

- Configure the RS232 for 9600 8N1 (Use the same baudrate on the computer!)

- The account ID should not be left empty!



Preparing SSL certificates for using openGalaxy:
================================================

In order for a webbrowser to connect to the webservice it needs to:

 - Verify the identity of the openGalaxy webservice.

 - Present a client certificate to the webservice in order to authenticate
   itself as a registered/validated user of the webservice.

To achieve this, a number of SSL certificates need to be created and
then imported into the certificate store the browser in question uses.

The openGalaxyCA program is used to create or manage certificates for
use by openGalaxy;

When you start openGalaxyCA you are initialy presented with the page to
create a CA certificate used to sign all other certificates.
To create it select a private key size from the dropdown box and press the
'Generate a new private key' button.

The program will now show you a dialog of the commands (and their output)
it executed. If there was an error there will be an additional messagebox.

Close the dialog and create a new request for a certificate using the
'Make a certificate request' button.

The last step in creating the CA certificate is to sign it (ourselves) by
selecting the number of days the certificate should be made valid and
then using the 'Sign the current certificate request' button to sign it.

With the CA certificate now available we may proceed to create the SSL
certifictes used by the openGalaxy program and the webbrowser used to
access the webinterface.

Go to the 'Server' page of the openGalaxyCA program and follow the same
procedure to create a certificate for use by openGalaxy. The default
values presented on this page can only be used if you run both openGalaxy
and the client browser on the same computer. If you want other computers
on a network (or the internet) to be able to access the webinterface you
will need to at least change the values for the first three items:

'Primary DNS name or IP address' is the url (without http:// in front of
it) or IP address of the computer that runs openGalaxy (ie. the server).
The alternative 'DNS Names' and 'IP addresses' may be used to specify any
additional url's and IP's from witch the server may be reachable.
Multiple addresses/IP's in these fields need to be seperated by a space.

When you have created the server certificate it is time to move on to the
'Clients' page of the openGalaxyCA program where we can create at least one
client SSL certificate.

To do this follow the same procedure we used on the CA and server pages.
All fields must contain a valid inputvalue in order to create the client
certificate.

Now that all certificates have been created, the last thing you need to do
is to import the CA and client certificates into the webbrowser used to
access the openGalaxy webinterface;

The CA certificate is located at:
 "/usr/local/share/galaxy/ssl/certs/openGalaxyCA.crt"  (Linux)
or
 "MyDocuments\openGalaxy\ssl\certs\openGalaxyCA.crt" (Windows)

It should be imported into the browser as 'Certificate Authority' using
it's certificate manager (found somewhere in the settings of the browser)
and be allowed to identify websites.

The client certificate is located at:
 "/usr/local/share/galaxy/sll/certs/users/[username].p12"
or
 "MyDocuments\openGalaxy\ssl\certs\users\[username].p12"

It should be imported into the webbrowser in the same maner as the first
certificate, but this time as 'Personal certificate'. (The password asked
for while importing this certificate is empty,)



Runtime configuration:
======================

- To configure openGalaxy, edit the configuration file(s):

/usr/local/etc/galaxy/galaxy.conf
/usr/local/etc/galaxy/ssmtp.conf

  or on Windows:

"MyDocuments\openGalaxy\galaxy.conf"

  This configuration file is used to store options like the COM port to
  use and at witch baudrate. The other important option in this file is
  the remote code that is used to access the Galaxy panel.


- A set of SSL certificates needs to be present

  See the 'Preparing SSL certificates for using openGalaxy' section
  of this document.


- 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'.)



Running openGalaxy:
===================

Connect the configured serial port to your control panel and run
'openGalaxy'. To stop the program, press CRTL+C.

openGalaxy has several command-line options available.
Use 'openGalaxy --help' to list them, together with an explanation
of what each option does. Links for three operational modes are added
to the start menu during the installation of openGalaxy.

For Windows only; The first time openGalaxy is started, Windows Firewall
will popup a dialog to ask wether or not to block the program's network
access. Choose to allow the program for the appropriate networks.

While openGalaxy is running the panel may be remotely controlled by
opening a webbrowser* and going to the URL***:

https://localhost:1500  (on Linux)
or
https://localhost       (on Windows)

The webbrowser will ask** what client certificate to use in order to
identify itself to the webservice.

This webpage also provides a live view of incoming SIA messages on the
websocket. The webpage is optimized for FullHD format but can be scaled
to your screen resolution by using CTRL-PLUS or CTRL-MINUS.


*   The browser must support HTML5 websockets.

**  Make sure you have read the 'Preparing SSL certificates for using
    openGalaxy' section of this document.

*** On Windows the default port number is set to 443.



Using the MySQL database created by openGalaxy:
===============================================

To demonstrate displaying messages written to the MySQL database that
openGalaxy creates, a small example webinterface for installation on a
webserver (like apache2) 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'




Still to do:
============

- Finish the ODBC database output plugin (or remove it)

- (Linux only) Daemonize openGalaxy so that it is started as a service

- 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 ;)

(Abandoned goals)

- Enable SSL on the MySQL database connection.
  (Why: Users of a remote database server should tunnel with SSH)




Compilation of sourcecode (Linux 32 & 64 bit):
==============================================

If you are interested in building openGalaxy yourself then read the file
 "README-BUILDING" included with the source distribution.



Compilation of sourcecode (Win32 using MinGW-64/MSYS2):
=======================================================

If you are interested in building openGalaxy yourself then read the file
 "README-MSYS2.TXT" included with the source distribution.


Known bugs:
===========

Currently openGalaxy needs to be compiled with CyaSSL in order to
use client SSL certificates. When building openGalaxy with OpenSSL
the server application 'openGalaxy' needs to be started with the
--no-client-certs option.

Linux with CyaSSL:
  Only 1024 and 2048 bit private key sizes may be used for
  client certificates. If you try to connect with a 4096 bit
  client certificate the authentication wil fail.