Zmxap - Revision history

QuQ: /* xAP Messages */

2008-02-25T23:33:53Z

xAP Messages

← Older revision		Revision as of 19:33, 25 February 2008
Line 55:		Line 55:

	==xAP Messages==		==xAP Messages==
	xAP messages conform to a format specified by the [http://www.xapautomation.org/wiki/index.php/Protocol_definition xAP Protocol Definition]. The protocol definition describes ~~mandatory~~ the overall structure of the message and mandatory elements. All messages contain a xAP header and can look like the following:		xAP messages conform to a format specified by the [http://www.xapautomation.org/wiki/index.php/Protocol_definition 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		xap-header

Gliming: Describe ability to set runstate

2007-04-05T15:06:46Z

Describe ability to set runstate

@@ Line 5: / Line 5: @@
 ===Features===
 * regularly reports each monitor's operating mode
 * reports alarm starts
@@ Line 67: / Line 68: @@
 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.
 ===Alarm Messages===
 '''Alarm event start:'''

Gliming: Added info on xAP messages

2006-06-14T22:04:16Z

Added info on xAP messages

← Older revision		Revision as of 18:04, 14 June 2006
Line 51:		Line 51:
	# Open the global options window and select the Email tab		# Open the global options window and select the Email tab
	# 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)		# 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 [http://www.xapautomation.org/wiki/index.php/Protocol_definition xAP Protocol Definition]. The protocol definition describes mandatory 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.

			===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.

Gliming at 21:46, 14 June 2006

2006-06-14T21:46:09Z

New page

zmxap is an integration utility used to connect zoneminder with other (typically home automation) programs via the network protocol, [http://www.xapautomation.org 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===

* 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===
* [http://www.limings.net/xap/zmxap 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 [http://patrick.lidstone.net/haweb/html/infrastructure.html 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 ...''
# Click on the monitor "source" link and leave on Monitor tab
# Select the Enabled checkbox if you want to be able to start and stop (or cancel) alarms via xAP; otherwise leave as is
# 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 ...''
# Open global options window and leave at System tab
# Check the ZM_OPT_CONTROL box (regardless of whether your cameras are PTZ)
# For each monitor to report, click on the monitor "source" link and select the Control tab
# 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.''
# Open the global options window and select the Email tab
# 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)