deiger/pima repository overview

⁠PIMA Alarms

This program implements an interface for negotiation with PIMA Hunter Pro alarms⁠.
It was built based on PIMA™'s General Specification for Home Automation & Building Management protocol Ver. 1.15.
PIMA™ is a trademark of PIMA Electronic Systems Ltd, http://www.pima-alarms.com⁠.
This program was built with no affiliation of PIMA Electronic Systems Ltd.

⁠Prerequisites

1. PIMA Hunter Pro alarm™, with 32, 96 or 144 zones.
2. PIMA Home Automation kit™ (SA-232, LCL-11A and Serial-to-USB cable), or net4pro ethernet connection. Diagram by PIMA™ ©:
   • According to various users, the alarm can be alternatively connected using a PL2303TA USB-to-TTL cable, like this one⁠.
   • Yet another option is to connect directly to Raspberry pi, as specified here:
3. Raspberry Pi or similar, connected to the alarm through the Home Automation kit.
   • Tested on Raspbian⁠. Other operating systems may use different path structure for the serial ports.
4. Alarm technician login code. Unfortunately, it is not possible to connect to the alarm using a user login code.

⁠Enabling the alarm serial port or network connection

1. Enable extended menus:
   • Primary login code
   • NEXT
   • Technician login code
   • 5 (General parameters)
   • ENTR
   • NEXT till you get to the right P (extended menus)
   • Toggle by #
   • ENTR
   • END to exit
2. Enable the serial port:
   • Primary login code
   • NEXT
   • Technician login code
   • 3 (Communication)
   • ENTR
   • 8 x NEXT (Serial port)
   • ENTR
   • Toggle the first L (for serial connection) or first N (for net4pro) by #
   • ENTR
   • END to exit

⁠Setup

1. Create an SSL certificate, if you wish to access the server through HTTPS:

   openssl req -x509 -newkey rsa:2048 -nodes -keyout key.pem -out cert.pem -days 365
   

   Copy
2. Install additional Python libraries:

   pip3 install crcmod paho-mqtt pyserial
   

   Copy
3. Download pima.py⁠ and pima_server.py⁠, and put them in the same directory.
4. Set run permissions to pima_server.py⁠:

   chmod a+x pima_server.py
   

   Copy

⁠Run for testing

1. Test out that you can run the server, e.g.:

   ./pima_server.py --ssl_cert cert.pem --ssl_key key.pem --port 7777 --key my_random_key --login 000000 --mqtt_host localhost
   

   Copy
   Parameters:
   • --ssl_cert - Path to the SSL certificate file. If not set, will run a non-encrypted web server.
   • --ssl_key - Path to the SSL private key file. If not set, will get the key from the certificate file.
   • --port or -p - Port for the web server.
   • --key or -k - An arbitrary string key to authenticate the server calls.
     Consider generating a random key using uuid -v4.
   • --login or -l - The technician login code to the alarm.
   • --zones or -z - Number of zones supported by the alarm, one of 32, 96 or 144. Default is 32.
   • --serialport - Serial port, e.g. /dev/serial0. Needed if connected directly through GPIO serial.
   • --pima_host - Pima alarm hostname or IP address. Must be set if connected by ethernet.
   • --pima_port - Pima alarm port. Must be set if connected by ethernet.
   • --mqtt_host - The MQTT broker hostname or IP address. Must be set to enable MQTT.
   • --mqtt_port - The MQTT broker port. Default is 1883.
   • --mqtt_client_id - The MQTT client ID. If not set, a random client ID will be generated.
   • --mqtt_user - <user:password> for the MQTT channel. If not set, no authentication is used.
   • --mqtt_topic - The MQTT root topic. Default is "pima_alarm". The server will listen on topic <{mqtt_topic}/command> and publish to <{mqtt_topic}/status>.
   • --log_level - The minimal log level to send to syslog. Default is WARNING.
2. Access e.g. using curl:

   curl -ik 'http://localhost:7777/pima?key=my_random_key&command=status'
   curl -ik 'http://localhost:7777/pima?key=my_random_key&command=arm&mode=home1&partitions=1'
   

   Copy
   CGI Arguments:
   • key - The key specified on the web server startup.
   • command - Either status or arm.
     When arm is specified:
     • mode - Either full_arm, home1, home2 or disarm.
     • partitions Comma separated list of partitions. Default is 1.

⁠Run as a service

1. Create a dedicated directory for the script files, and move the files to it. Pass the ownership to root. e.g.:

   sudo mkdir /usr/lib/pima
   sudo mv pima_server.py pima.py key.pem cert.pem /usr/lib/pima
   sudo chown root:root /usr/lib/pima/*
   sudo pip3 install crcmod paho-mqtt pyserial
   

   Copy
2. Create a service configuration file (as root), e.g. /lib/systemd/system/pima.service:

   [Unit]
   Description=PIMA alarm server
   After=network.target
   
   [Service]
   ExecStart=/usr/bin/python3 -u pima_server.py --ssl_cert cert.pem --ssl_key key.pem --port 7777 --key my_random_key --login 000000 --mqtt_host localhost
   WorkingDirectory=/usr/lib/pima
   StandardOutput=inherit
   StandardError=inherit
   Restart=always
   
   [Install]
   WantedBy=multi-user.target
   

   Copy
3. Link to it from /etc/systemd/system/:

   sudo ln -s /lib/systemd/system/pima.service /etc/systemd/system/multi-user.target.wants/pima.service
   

   Copy
4. Enable and start the new service:

   sudo systemctl enable pima.service
   sudo systemctl start pima.service
   

   Copy
5. If you use MQTT⁠ for HomeAssistant⁠ or openHAB⁠, the broker should now provide the updated status of the alarm, and accepts commands. Basic yaml config files for HomeAssistant are available under the hass⁠ directory.

⁠Next steps

1. Groovy⁠ Device Type Handlers⁠ for SmartThings⁠ integration.
2. Support further functionality, e.g. change user codes.