nx584mqtt 0.1.13
NX584/NX8E Interface Library and Server with MQTT client

nx584mqtt
NX584/NX8E Interface to MQTT client and HTTP server
===================================================

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 of the control panel. 

This package is designed to be a direct replacement for pynx584.
Connection services allow for MQTT client (paho-mqtt) and/or legacy HTTP server (flask).

MQTT provides considerable improvements in zone change latency. Also, since flask is really designed only for development and is considered unstable, HTTP usage is not suggested, but only is provided for backwards-compability.

Typical use case is for a NX/Caddx alarm connected to MQTT mosquitto broker, possibly then to Home Assistant.
 
# Install
************************************************************
- Package installation allows for optional requirements, based on user needs:
 
 # pip3 install nx584mqtt
 >> default
 # pip3 install nx584mqtt:full
 >> All options
 # pip3 install nx584mqtt:http
 >> Installs flask
 # pip3 install nx584mqtt:client
 >> Installs prettytable
 
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 [...]


# MQTT Usage

 # nx584_server --mqtt 192.168.1.102 [...] 


# Command Line Parameters
************************************************************
-- HTTP (legacy)
'--listen' - 'HTTP Server address (defaults to disabled)'
'--port' - 'HTTP Server port (defaults to 5007)'

-- MQTT
'--mqtt' - 'MQTT Client Host to connect'
'--mqttPort' - 'MQTT client port (defaults to 1883)'
'--username' - 'MQTT Client Username'
'--password' - 'MQTT Client Password')
'--stateTopicRoot' - 'Root topic for MQTT Client publishing (defaults to 'home/alarm')'
'--commandTopic', - 'Command topic for MQTT Client subscription/monitoring (defaults to 'home/alarm/set')'
'--mqttTlsActive' - 'Enable MQTT TLS (default= to false)'
'--mqttTlsInsecure' - 'Ignore MQTT TLS Insecurities (Not Recommended) (defaults to false)'
'--timeout' - 'MQTT Timeout in seconds (default is 10)'
'--debugLevel' - 'Verbosity of logs written to console [WARNING|INFO|DEBUG] (defaults to WARNING)'

- Publish to mqtt <command topic> with value:

'disarm,<part>,<code>' - Disarms partition <part> using code <code>
'arm_home,<part>' - Arms home partition <part>
'arm_away,<part>' - Arms away partition <part>
'bypass_toggle,<zone>' - Toggle bypass of zone (be sure zone is bypassable!!)
'time' - Update alarm time from local time of nx584mqtt server
'status' - Update mqtt status of all fields (dev only)
'nop' - No action, clears command after arm/disarm to reduce code visibility



# Client Usage (if enabled/installed)
************************************************************
Once the server is 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:
   nx584mqtt:
     container_name: nx584mqtt
     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 nx584mqtt 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

 # Set to true if your unit sends DD/MM dates instead of MM/DD
 euro_date_format = False
 
 [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
 
 
 
# Optional Home Assistant MQTT Integration
 ************************************************************
 
>> Binary Sensors
Note: Previous binary sensors were autonamed from zones, and now would require additional effort to reproduce. 
Zone names and details are all published to the mqtt server.
I would suggest using a mqtt explorer to examine your published names and zones numbers to recreate, if desired
```
  - platform: mqtt
    state_topic: "tele/nx584/zones/1/faulted"
    name: "Z1 Front Door"
    device_class: opening
    payload_off: "false"
    payload_on: "true"
    availability:
      - topic: "tele/nx584/system/avail"
        payload_available: "online"
        payload_not_available: "offline"
```
>> Alarm Control Panel
```
alarm_control_panel:
  - platform: mqtt
    state_topic: "tele/nx584/partitions/1/state"
    command_topic: "cmnd/nx584/action"
#    command_template: "{{action}},{partition_int_hardcode_REPLACE_ME},{{code}}"
    command_template: "{{action}},1,{{code}}"
    code_arm_required: false
    code_disarm_required: true
    code_format: "number"
    name: "nx584"
    retain: true
```

NOTE: The below alarm integration allows the user to be displayed a keypad in the Home Assistant web interface.

As of Mar 2021 (HASS core-2021.3.4) to implement the mqtt alarm control panel, a slight adjustment must be performed to the MQTT componenent in HASS. 
I had requested this change, but HASS dev team quickly closed my code change request, stating it was an enhancement. It you would like to see this change too,
urge them to reconsider by creating another issue like https://github.com/home-assistant/core/issues/47234

If you prefer no keypad, then no change is required to HA.