xAP Zoneminder Integration

• • Note**: it you are new to xPL, please first read xAP and xPL - Getting Started.

Introduction

Zoneminder is a unix-based application that monitors analog and/or network-enabled video cameras. It uses motion analysis to determine whether an area (definable by the user) is considered in alarm or not. Information about the image analysis, alarm status etc. is available as well as the ability to capture images and/or video from the cameras.

Zmxap is a "conduit" that allows home automation programs like misterhouse to receive information about ZoneMinder's monitored cameras as well as the ability to control ZoneMinder operation. The ZoneMinder wiki contains information specific to zmxap setup and operation.

Misterhouse/Zoneminder Concepts

There are two basic misterhouse items that map directly to ZoneMinder concepts: (1) ZM_Monitor_Item and (2) ZM_Zone_Item. The ZM_Monitor_Item mirrors ZoneMinder's concept of a monitor. Usually, there is a single monitor for each camera; although more advanced configurations have more than one monitor for a camera (usually, toggled based upon ZoneMinder "run state"). If ZoneMinder's image analysis is utilized, there will be one or more "zones" that the user defines (which are polygons within the camera's viewing area). The ZM_Zone_Item maps to each zone. This means that it is possible to know which zone is in alert and to differentiate actions that misterhouse might perform based upon logic specific to each zone. The ability to monitor individual zones within a monitor provides very fine-grained monitoring capability within misterhouse. If a monitor is configured to support positional tracking, then zmxap and, in turn, a ZM_Monitor_Item will be able to track x and y-positional movements as a target moves within an alarming zone. Currently, there is no support within misterhouse to extrapolate apparent direction of motion for use in occupancy tracking schemes; but, that may be an option for future development.

The state of ZM_Monitor_Items and ZM_Zone_Items change as updates are received via zmxap. ZM_Monitor_Item states have the possible value: idle and alarm (note: only ZoneMinder reported "Motion"-caused alerts are tracked; web-caused alarms are not). ZM_Zone_Item states are motion and still (to correspond with Motion_Item states).

Configuration within Misterhouse

ZM_Monitor_Items and ZM_Zone_Items are declared using an mht syntax:

ZM_MONITOR, <zoneminder_monitor_name></zoneminder_monitor_name>, <monitor_item_name></monitor_item_name>, <group_list></group_list> ZM_ZONE, <zoneminder_zone_name></zoneminder_zone_name>, <zone_item_name></zone_item_name>, <monitor_item_name></monitor_item_name>

Unlike some xAP (or xPL) item declarations, the full xAP address is never used since it defaults to zmxap. Note that it is possible (and, perhaps desirable) to have the <monitor_item_name></monitor_item_name> be the same as the <zoneminder_monitor_name></zoneminder_monitor_name> (or <zone_item_name></zone_item_name> be the same as <zoneminder_zone_name></zoneminder_zone_name>); however, the option exists to keep them separate (in case name collisions were to occur). One exception to the above is the use of a (xAP) BSC_Item to control ZoneMinder run state.

Example Usage

in items.mht:

ZM_MONITOR, front-porch, front_porch_monitor, Outside ZM_ZONE, front-porch, front_porch_zone, front_porch_monitor ZM_MONITOR, driveway, driveway_monitor, Outside ZM_ZONE, drive, drive_zone, driveway_monitor ZM_ZONE, side, side_zone, driveway_monitor ZM_ZONE, rear, rear_zone, driveway_monitor

BSC, zm.zoneminder.house, zone_minder_manager

Note that the above declaration of multiple zones for the driveway monitor allows an ability to segment up different parts of the field of view to correspond to different locations--each treated as distinct "motion detectors".

code format="perl"

1. manage the automatic image analysis on a per-monitor basis

$motion_analysis_vc = new Voice_Cmd '[suspend,resume,stop,start] motion analysis'; if (defined($state = said $motion_analysis_vc)) {

   $driveway_monitor->start_motion_analysis() if $state eq 'start';
   $driveway_monitor->stop_motion_analysis() if $state eq 'stop';
   $driveway_monitor->suspend_motion_analysis() if $state eq 'suspend';
   $driveway_monitor->resume_motion_analysis() if $state eq 'resume';

}

1. directly control whether an alarm occurs (perhaps triggered by a non-zoneminder alert
2. this is very useful if wanting to automatically trigger a zoneminder alarm if a security sensor
3. detects intrusion, etc.

$driveway_vc = new Voice_Cmd '[stop,start,block] driveway alarm'; if (defined($state = said $driveway_vc)) {

   $driveway_monitor->start_alarm('mh alarm test') if $state eq 'start';
   $driveway_monitor->stop_alarm() if $state eq 'stop';
   $driveway_monitor->block_alarm() if $state eq 'block';

}

1. 1. report on state changes to the driveway zones

$drive_zone->tie_event('zone_hook($drive_zone)'); $side_zone->tie_event('zone_hook($side_zone)'); $rear_zone->tie_event('zone_hook($rear_zone)');

sub zone_hook {

   my ($zone) = @_;
   if ($zone->state eq 'motion') {
      print "detected motion from zone: " . $zone->name . "\n";
   } else {
      print "zone: " . $zone->name . " is now still\n";
   }

} code