.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "ZMTRIGGER 1"
.TH ZMTRIGGER 1 "2023-07-27" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
zmtrigger.pl \- ZoneMinder External Trigger Script
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This script is used to trigger and cancel alarms from external connections
using an arbitrary text based format.
.PP
This script offers generic solution to external triggering of alarms. It
can handle external connections via either internet socket, unix socket or
file/device interfaces. You can either use it 'as is' if you can interface
with the existing format, or override connections and channels to customise
it to your needs.
.PP
If enabled by the \s-1OPT_TRIGGERS\s0 option, Zoneminder service start
zmtrigger.pl which listens for control messages on \s-1TCP\s0 port 6802.
.SH "TRIGGER MESSAGE FORMAT"
.IX Header "TRIGGER MESSAGE FORMAT"
\&\fBid\fR|\fBaction\fR|\fBscore\fR|\fBcause\fR|\fBtext\fR|\fBshowtext\fR
.IP "\fBid\fR" 4
.IX Item "id"
.Vb 1
\&  is the id number or name of the ZM monitor.
.Ve
.IP "\fBaction\fR" 4
.IX Item "action"
.Vb 7
\&  Valid actions are \*(Aqon\*(Aq, \*(Aqoff\*(Aq, \*(Aqcancel\*(Aq or \*(Aqshow\*(Aq where
\&  \*(Aqon\*(Aq forces an alarm condition on;
\&  \*(Aqoff\*(Aq forces an alarm condition off;
\&  \*(Aqcancel\*(Aq negates the previous \*(Aqon\*(Aq or \*(Aqoff\*(Aq;
\&  \*(Aqshow\*(Aq updates the auxiliary text represented by the %Q 
\&  placeholder, which can optionally be added to the affected monitor\*(Aqs
\&  timestamp label format.
\&  
\&  Ordinarily you would use \*(Aqon\*(Aq and \*(Aqcancel\*(Aq, \*(Aqoff\*(Aq would tend to be
\&  used to suppress motion based events. Additionally \*(Aqon\*(Aq and \*(Aqoff\*(Aq can
\&  take an additional time offset, e.g. on+20 which automatically
\&  cancel\*(Aqs the previous action after that number of seconds.
.Ve
.IP "\fBscore\fR" 4
.IX Item "score"
.Vb 3
\&  is the score given to the alarm, usually to indicate it\*(Aqs
\&  importance. For \*(Aqon\*(Aq triggers it should be non\-zero, otherwise it should
\&  be zero.
.Ve
.IP "\fBcause\fR" 4
.IX Item "cause"
.Vb 3
\&  is a 32 char max string indicating the reason for, or source of
\&  the alarm e.g. \*(AqRelay 1 open\*(Aq. This is saved in the \*(AqCause\*(Aq field of the
\&  event. Ignored for \*(Aqoff\*(Aq or \*(Aqcancel\*(Aq messages.
.Ve
.IP "\fBtext\fR" 4
.IX Item "text"
.Vb 2
\&  is a 256 char max additional info field, which is saved in the
\&  \*(AqDescription\*(Aq field of an event. Ignored for \*(Aqoff\*(Aq or \*(Aqcancel\*(Aq messages.
.Ve
.IP "\fBshowtext\fR" 4
.IX Item "showtext"
.Vb 6
\&  is up to 32 characters of text that can be displayed in the
\&  timestamp that is added to images. The \*(Aqshow\*(Aq action is designed to
\&  update this text without affecting alarms but the text is updated, if
\&  present, for any of the actions. This is designed to allow external input
\&  to appear on the images captured, for instance temperature or personnel
\&  identity etc.
.Ve
.PP
.Vb 7
\&  Note that multiple messages can be sent at once and should be LF or CRLF
\&  delimited. This script is not necessarily intended to be a solution in
\&  itself, but is intended to be used as \*(Aqglue\*(Aq to help ZoneMinder interface
\&  with other systems. It will almost certainly require some customisation
\&  before you can make any use of it. If all you want to do is generate alarms
\&  from external sources then using the ZoneMinder::SharedMem perl module is
\&  likely to be easier.
.Ve
.SH "EXAMPLES"
.IX Header "EXAMPLES"
.Vb 1
\&  3|on+10|1|motion|text|showtext
.Ve
.PP
Triggers 'alarm' on camera #3 for 10 seconds with score=1, cause='motion'.