NetworX NX584/NX8E Interface Library and Server
===============================================

.. image:: https://github.com/kk7ds/pynx584/actions/workflows/test.yaml/badge.svg

This is a tool to let you interact with your NetworX alarm panel via
the NX584 module (which is built into NX8E panels). You must enable it
in the configuration and enable the operations you want to be able to
do before this will work.

This tool supports both the ASCII or Binary home automation
protocol (and works with the binary only NX590E in addition to the
ASCII or binary NX584/NX8E)

Install Locally
***************

::

 # pip install pynx584

The server must be run on a machine with connectivity to the panel,
which can be a local serial port, or a Serial-over-LAN device (i.e. a
TCP socket). For example::

 # nx584_server --serial /dev/ttyS0 --baud 38400

or::

 # nx584_server --connect 192.168.1.101:23

Once that is running, you should be able to do something like this::

 $ nx584_client summary
 +------+-----------------+--------+--------+
 | Zone |       Name      | Bypass | Status |
 +------+-----------------+--------+--------+
 |  1   |    FRONT DOOR   |   -    | False  |
 |  2   |   GARAGE DOOR   |   -    | False  |
 |  3   |     SLIDING     |   -    | False  |
 |  4   | MOTION DETECTOR |   -    | False  |
 +------+-----------------+--------+--------+
 Partition 1 armed

 # Arm for stay with auto-bypass
 $ nx584_client arm-stay

 # Arm for exit (requires tripping an entry zone)
 $ nx584_client arm-exit

 # Auto-arm (no bypass, no entry zone trip required)
 $ nx584_client arm-auto

 # Disarm
 $ nx584_client disarm --master 1234
 
Install via Docker Compose
**************************
Before creating the Docker container, you need to define how you connect to the panel (local serial port, or a Serial-over-LAN device (i.e. a TCP socket)) in the :code:`docker-compose.yml` file. Uncomment and edit the :code:`environment` section to fit your needs::

 version: "3.2"

 services:
   pynx584:
     container_name: pynx584
     image: kk7ds/pynx584
     build:
       context: .docker
       dockerfile: Dockerfile
     restart: unless-stopped
     ports:
       - 5007:5007
     environment:
       # Uncomment these as needed, depending on how you connect to the panel (via Serial or TCP Socket)
       # - SERIAL=/dev/ttyS0
       # - BAUD=38400
       # - CONNECT=192.168.1.101:23

To build the image, create the Docker container and then run it, make sure you're at the root of the checked out repo and run::

 # docker-compose up -d

You should now be able to conect to the pynx584 Docker container via its exposed port (default :code:`5007`).

Config
------

The `config.ini` should be generated once the controller reports the first
zone name. However, here is a full `config.ini` if you want to pre-populate
it with zone names::

 [config]
 # max_zone is the highest numbered zone you have populated
 max_zone = 5

 # Disable zone name updates from NX8 system. If your system doesn't set zone
 # names and you prefer define them through pynx584, set this value to False.
 # Defaults to True
 # zone_name_update = False

 # Set to true if your unit sends DD/MM dates instead of MM/DD
 euro_date_format = False
 
 # Set To true if using binary protocol
 # Defaults to False
 # use_binary_protocol = True

 # Length of idle time before sending heartbeat keep alive
 # (This is useful with the NX590 as it disconnects idle connections in a
 # short period of time)
 # Defaults to 120 seconds
 # idle_time_heartbeat_seconds = 20

 [email]
 fromaddr = security@foo.com
 smtphost = imap.foo.com
 
 [zones]
 # Zone names
 1 = Front Door
 2 = Garage Entry
 3 = Garage Side
 4 = Garage Back
 5 = Kitchen


Panel Configuration
-------------------

Your NX panel must be configured properly to allow this software to
work with it. If it was configured by a monitoring company, there is a
very good chance that it will need quite a bit of tweaking first. Here
is a good start to what needs to be set and how:

- Protocol: ASCII
- Speed: 38400 Baud (OR WHICHEVER YOU CHOOSE)
- Enabled Transition Messages:

 * Interface Configuration Message
 * Zone Status Message
 * Partition Status Message
 * System Status Message
 * Log Event Message
 * Keypad Message Received (OPTIONAL)
 * X-10 Message Received (OPTIONAL)

- Enabled Commands:

 * Interface Configuration Request
 * Zone Name Request
 * Zone Status Request
 * Zones Snapshot Request
 * Partition Status Request
 * Partitions Snapshot Request
 * Send X-10 Message (OPTIONAL)
 * Log Event Request
 * Send Keypad Text Message (OPTIONAL)
 * System Status Request
 * Program Data Request (OPTIONAL)
 * Program Data Command (OPTIONAL)
 * Set Clock / Calendar Command
 * Primary Keypad Function with PIN (OPTIONAL)
 * Secondary Keypad Function (OPTIONAL)
 * Zone Bypass Toggle (OPTIONAL)
