Additional pynx584 Documentation

[Pre10der]

Here is some additional documentation that I have put together that may be useful to users of the pynx584 library. It has some Raspberry Pi and Home Assistant specific components as they are fairly common use case for this library. It also contains some information on the NX-584E and its compatibility with related panels (namely the Networx NX and Hills Reliance series panels). This is a collection of information I have obtained that has not been easy to find else where, so hopefully it will help some others.

@kk7ds - I am not overly familiar with how to add this to the repo, so adding it here for you to merge into the README.rst as you see fit. I also feel some other nx584_client examples may be warranted. Once @lumavp has provided his info on the SMTP integration nx584_client panic functions, these can also be added into the mix. Hope you find it useful.

Merry Christmas!

Documentation Contributor: Pre10der
Date: 19th December 2017
Documentation Version: 1.0

Configuring the NX-584E Module for use with pynx584 The NX-584E module is an additional serial (RS232) module for the Networx NX (NX-4,NX-6,NX-8) series alarm panels and is designed for home automation tasks. This is built into the NX-8E boards by default. These alarm panels are also known as the Hills Reliance panels (R8/R12/R128) in some countries (e.g. Australia). Nb. The base models of these alarm panels only allows a single additional module to be installed. If you are using the NX-4/R8 panel and have another module already installed (such as an NX-595E/ComNav board), you will run into trouble with having both the NX-584E and the NX-595E/ComNav modules co-exist (the NX-595E/ComNav will appear to go offline). In this case, consider upgrading your alarm panel to a higher model such as the NX-8/R128. If the NX-584E is the only additional module installed on the base model panel, then you are good to go and the NX-584E should work as per the below.

The NX-584E module should be installed as per the installation instructions of the module and configured to allow only the required features. This is more of a security best practice than it is a compatibility issue. Best practice is to enable the baseline set of features, and then enable additional items on an as needs basis.

Depending on your deployment model, it would also be wise to ensure that the host running the pynx584 library and in turn the serial connection is secured so that other hosts on the network are unable to impact the security system. Remember, communications to pynx584 by default are unencrypted, and the NX-584E should be considered as a trusted and privileged device as it has direct access to the security systems data bus.

The below features can be used as a baseline set to allow interfacing with the pynx584 library.

   - Protocol: ASCII
    Feature: 0
    Segment: 1
    Option: 1 
   - Speed: 9600 Baud (OR WHICHEVER YOU CHOOSE). 
        Nb. People have reported that anything above 9600bps can have adverse affects on some system integrations including Home Assistant. This is likely dependent on the serial hardware that is used, however 9600bps is typically a safe option.
    Feature: 1
    Segment: 1
    Option: 4 
   - Enabled Transition Messages:
    Feature: 2
    Segment: 1
        Options: 
            2 - Interface Configuration Message
                    5 - Zone Status Message
                    7 - Partition Status Message
         Segment: 2
        Options: 
                1 - System Status Message
                2 - X-10 Message Received (OPTIONAL)
                    3 - Log Event Message
                    4 - Keypad Message Received (OPTIONAL)

   - Enabled Commands:
    Feature: 3
        Segment: 1
        Options: 
            2 - Interface Configuration Request
                    4 - Zone Name Request
                    5 - Zone Status Request
                    6 - Zones Snapshot Request
                    7 - Partition Status Request
                    8 - Partitions Snapshot Request
    Segment: 2
        Options: 
            1 - System Status Request
            2 - Send X-10 Message (OPTIONAL)
                    3 - Log Event Request
                    4 - Send Keypad Text Message (OPTIONAL)
    Segment: 3
        Options:            
                    1 - Program Data Request (OPTIONAL)
                    2 - Program Data Command (OPTIONAL)
    Segment: 4
        Options: 
                    4 - Set Clock / Calendar Command
                    5 - Primary Keypad Function with PIN (OPTIONAL)
                    7 - Secondary Keypad Function (OPTIONAL)
                    8 - Zone Bypass Toggle (OPTIONAL)

Installing pynx584 on a Raspberry Pi w/USB to Serial Adapter

1. Install latest version of Minibian (or your favourite flavour of Raspbian)

2. Change locale, timezone etc: sudo raspi-config

3. Undertake some mandatory configuration changes including password resets: Change root PW passwd root Add new user account (not root). Nb. Minibian does not have 'pi' user by default. This is not necessary for Raspbian distro's. adduser pi Add user to sudo file adduser pi sudo Change hostname: nano /etc/hostname

4. Reset passwords for pi and root:

   passwd pi
   passwd root

5. Install pynx584 for interfacing with alarm: sudo pip3 install pynx584 Nb. You can upgrade pynx584 by running: sudo pip3 install pynx584 --upgrade

6. Insert your USB to serial device and give permission to the USB device for the pi user account: sudo usermod -a -G dialout pi Nb. If the usb-to-serial device is not detected, you may need to run: apt-get install firmware-linux-free

7. Run pynx584_server at startup by modifying /etc/rc.local sudo /etc/rc.local Add the following line (or similar): sudo su - pi -c '/usr/local/bin/nx584_server --config /home/pi/config.ini --serial /dev/ttyUSB0 --baudrate 9600 --listen 192.168.1.100 --port 5007 --log /home/pi/nx584.log' Nb. This will log output to /home/pi/nx584.log. Make sure log file exists, and that pi user has access to it (sudo chown pi /home/pi/nx584.log).

8. By default, pynx584 should create a config.ini file. Some users have reported that this does not happen. You can work around this by creating the file manually in /home/pi/config.ini and adding/modifying the following config.ini contents:

   
   [config]
   max_zones = 8
   euro_date_format = False

[email] fromaddr = security@foo.com smtphost = imap.foo.com

[zones] 1 = Study 2 = Kitchen 3 = Hallway 1 4 = Hallway 2 5 = Pool Room 6 = Front Door 7 = Rear Door 8 = Garage Door

8. Reboot and check that the server is running by running top. Look for nx584_server in the process list.
`sudo reboot`

**Using pynx584_client to execute common commands (CLI):**
The first point to note is that if any zone is tripped\faulted during the testing of nx584_client, you may notice that the commands will not execute and the alarm panel will not respond to nx584_client commands as you would expect. This is especially notable when issuing 'arm' commands. 

Also note, if nx584_server is running on a specific host (as per the above example), then you must use the --host argument as is articulated throughout these examples.

**_List command help text:_**

nx584_client -h nx584_server -h

**_Display a summary summary of partitions and zone status:_**
`nx584_client summary --host 192.168.1.100:5007`

**_Output version of panel:_**
`nx584_client version --host 192.168.1.100:5007`

**_Tail (follow) realtime logs of nx584_server:_**
`tail -f /home/pi/nx584.log`

**_Show individual zone information:_**
`nx584_client show --host 192.168.1.100:5007 --zone 1`

**_Show individual partition information:_**
`nx584_client show --host 192.168.1.100:5007 --partition 1`

**_Arm alarm_**
`nx584_client arm --partition 1 --host 192.168.1.100:5007`

**_Arm in stay mode_**
`nx584_client arm-stay --host 192.168.1.100:5007`

**_Arm in away mode_**
`nx584_client arm-stay --host 192.168.1.100:5007`

**_Disarm alarm_**
`nx584_client --host 192.168.1.100:5007 --master <USER PIN> disarm`
**Nb. The --master argument does not imply the use of the alarm panels master/installer/program code/pin. Instead, it implies the use of a 'user' code/pin. It is best practice not to use the master code/pin where at all possible. Applying the 'master' role to a user account is likely a better option.**

**_Get user info from panel - Requires user pin that has 'Master' access rights on the panel_**
`nx584_client --host 192.168.1.100:5007 --user 1 --master <USER PIN> getuser`

**_Show events_**
`nx584_client --host 192.168.1.100:5007 --master <USER PIN> events`

**_List all partitions_**
`nx584_client --host 192.168.1.100:5007 --master <USER PIN> partitions`

**_Bypass an individual zone._** Nb. User must have access to bypass zones on the panel.
`nx584_client --host 192.168.1.100:5007 --master <USER PIN> --zone 2 bypass`

**_Unbypass an individual zone. Nb. User must have access to unbypass zones on the panel._**
`nx584_client --host 192.168.1.100:5007 --master <USER PIN> --zone 2 unbypass`

**Using pynx584 with Home Assistant:**
Pynx584 can be integrated with Home Assistant (or HASSIO) as follows. Nb. If using HASS.IO, you will need to run nx584_server on a seperate device (like a RaspberryPi - illustrated above). You can consider a RaspberryPi Zero, or even an older model 1 of the RapsberryPi with a minimal install and SD card as it's all very light weight.

Once you have the nx584_server set up, it is now time to configure Home Assistant. There are three parts to this:
1. NX584 Alarm Control Panel - This is used to display the current status of the panel (armed/disarmed) as well as arming and disarming the panel.
For information on how to enable this in Home Assistant, go here: https://home-assistant.io/components/alarm_control_panel.nx584/
TL;DR: Add this to your configuration.yaml:

alarm_control_panel:

• platform: nx584 host: 192.168.1.100 port: 5007

  2. Binary Sensor Status - This is used to present the status of each zone, sensor to Home Assistant for the purposes of automating certain events such as turning a light on when motion is detected for example.
  For information on how to enable this in Home Assistant, go here: https://home-assistant.io/components/binary_sensor.nx584/
  TL;DR: Add this to your configuration.yaml (adapt to your specific needs):

  binary_sensor:

• platform: nx584 host: 192.168.1.100 port: 5007 exclude_zones:
  • 9
  • 10
  • 11
  • 12 zone_types: 1: motion 2: motion 3: motion 4: motion 5: motion 6: opening 7: motion 8: opening

    3. Automating based on binary_sensor status - Adding an automation that uses the binary_sensors. This example turns on a light when motion is detected after sunset. You can add this as an automation.yaml entry for HASS.IO:

    • id: ACTION-001 alias: Action - Turn off lamp in bedroom after 10min of no movement detected trigger:
• entity_id: binary_sensor.bedroom platform: state to: 'off' for: minutes: 10 condition:
• condition: sun after: sunset action:
• alias: Turn off the Bedroom Lamp data: entity_id: light.bedroom_lamp service: light.turn_off

[kk7ds]

This is great, thanks! I wonder if it might be best integrated under the wiki tab? That way you (and others) can easily add and update it. Also, it will allow it to be split up a bit, as I think the HA-specific bits should probably be somewhat separate from the regular setup and use.

What do you think? I think by default anyone should be able to use the wiki, if you want to give it a try. I think you can probably just copy/paste what you have into a new wiki page. If that works, then I can commit a change to the main readme file with a link directing people there for more info.

[Pre10der]

Yep, I'm good with that approach. I'll put it in as is, and when time allows, break it up a bit.

[Pre10der]

I'm a bit new to GitHub, but I'll figure it out. Is the wiki disabled on this repo? When I hit wiki, it just takes me back to the main repo page....

[kk7ds]

I might've had to create a page first before it would advertise it or something. I just did that and put your stuff, with a few tweaks, into a few different pages. See if this works and verify that you can edit it:

https://github.com/kk7ds/pynx584/wiki

[Pre10der]

Just tried updating the RPi Example page via github desktop and received this:

[Pre10der]

Got the invite. All fixed, and updates working correctly now.

Thanks!

[Pre10der]

Documentation content now moved to Wiki. Closing this issue.

[kk7ds]

Apparently I can't control it any more granularly than granting you full push access to the entire repository. So, please use care and probably limit any sort of push activity to the wiki :)

Thanks!

[Pre10der]

Understood and no problem at all. I'll stick to the wiki and use the issues section for any items relating to code changes.