Zmxap

zmxap is an integration utility used to connect zoneminder with other (typically home automation) programs via the network protocol, xAP. zmxap is bidirectional--sending alarm event information and accepting control requests to alter zoneminder operation. zmxap is written in Perl and because of its interface with zoneminder must be run on the same system that hosts zoneminder. It is run "stand alone" and is therefore executed separate from zoneminder.

Features

• allows setting runstate; reports current runstate (once set)
• regularly reports each monitor's operating mode
• reports alarm starts
• reports alarm endings--including duration and all event information reportable (e.g., frame count, score)
• reports alarm telemetry (center position) at regular intervals during an alarm
• sends user customizable messages (for display on computers, VCD displays, etc)
• accepts alarm start, stop and suspend requests

Installation and Configuration

Installation/Running

• Download a zmxap "tarball" and untar into an appropriate location. A recommended practice is to place it in /usr/local/zmxap.
• Optionally, install a xAP hub. (IMPORTANT: if you do not want or need a xAP hub, you must declare nohub=1 in the zmxap configuration (zmxap.conf) file). A stand-alone xAP hub can be found at Patrick Lidstone's xAP site.
• zmxap must be started with equivalent access/privs as the user that executes zm. Most installations use apache as this user. Alternatively, zmxap may be run as root.
• zmxap must be executed at the command line or via a startup script. zmxap will continuously monitor for zm execution and begin polling zm when it is running.
• Start zmxap via the command "./zmxap.pl" (w/o the quotes)

IMPORTANT: If you are starting zmxap from a directory other than its installation, you must pass the path to its location. For example:

/usr/local/zmxap/zmxap.pl -path=/usr/local/zmxap &

More precise control over the lib location and config file location exists via the lib and config arguments.

• All logging is sent to /tmp/zmxap.log by default. You can monitor zmxap during execution using the command

tail -f /tmp/zmxap.log

Configuration

Locate zmxap.conf.conf included as a sample in the release and copy to zmxap.conf. Uncomment any properties that you wish to override. Commented properties show the default values. Additional notes are included as comments.

For each monitor that you want to report or control ...

1. Click on the monitor "source" link and leave on Monitor tab
2. Select the Enabled checkbox if you want to be able to start and stop (or cancel) alarms via xAP; otherwise leave as is
3. Alter the function of the monitor to be either: (i) Modect, (ii) Record or (iii) Mocord *if* you want to be able to start and stop the zm motion analysis via xAP messages (Note: each of these modes automatically starts w/ zm analysis or recording enabled)

Consider selecting (iv) Nodect if you don't want zm to perform any motion analysis, but do want to control alarms via xAP.

To be able to report x/y alarm center-position updates via xAP ...

1. Open global options window and leave at System tab
2. Check the ZM_OPT_CONTROL box (regardless of whether your cameras are PTZ)
3. For each monitor to report, click on the monitor "source" link and select the Control tab
4. Check the "Track Motion" check box

To be able to include URLs in the web portion of the message.display xAP message, you must specify the path to zm.

1. Open the global options window and select the Email tab
2. Enter the URL to your zm installation in ZM_URL (e.g., http://192.168.0.2 or http://192.168.0.2/zm. Do not include any trailing slash)

xAP Messages

xAP messages conform to a format specified by the xAP Protocol Definition. The protocol definition describes the overall structure of the message and mandatory elements. All messages contain a xAP header and can look like the following:

xap-header
{
v=12
hop=1
uid=FFEA0901
class=VMI.AlarmEvent
source=zm.zoneminder.myhouse:porch_camera
}

The class declares what "schema" is used. zmxap uses VIM.AlarmEvent schema to convey information about alarms. The source can be thought of as the xAP address. The "subaddress" appears to the right of the colon and is the name of a zoneminder monitor.

Gateway Messages

The run state can be set by passing the runstate via the text property of a xAPBSC.cmd message:

xap-header
{
v=12
hop=1
uid=FFCDEF00
class=xAPBSC.cmd
source=acme.sender.test
target=zm.zoneminder.myhouse
}
output.state.1
{
id=*
state=on
text=MyRunState
} 

Where "MyRunState" is the target zoneminder runstate to be set. zmxap will respond with a xAPBSC.event message reflecting the set runstate.

Alarm Messages

Alarm event start:

xap-header
{
v=12
hop=1
uid=FFEA0901
class=VMI.AlarmEvent
source=zm.zoneminder.myhouse:porch_camera
}
Alarm
{
alarmid=1234
state=on
cause=Motion
} 

The alarmid maps to a zoneminder event id. The cause is what is reported by zoneminder.

Alarm event end:

{
v=12
hop=1
uid=FFEA0901
class=VMI.AlarmEvent
source=zm.zoneminder.myhouse:porch_camera
}
Alarm
{
alarmid=1234    # event ID
state=off
cause=<Motion>|<Forced Web>|<xAP>       # cause
duration=7.2    # event duration in seconds
frames=123      # total frames in event
alarmframes=22  # total alarm frames in event
totalscore=133  # total alarm score
avgscore=34     # averaged score across alarm frames
maxscore=40     # max score of all alarm frames
zonedata=<zonename> # name of the zones causing the alarm if motion
linkeddata=<monitorname> # name of the linked monitor forcing the alarm (if applicable)
}

Note that much of the information about an alarm is not known at the alarm start and therefore is only reportable at completion of the alarm. Zonedata and linkeddata are new attributes that were added since zoneminder 1.22.1--where additional information is now reported from zoneminder.