Cynical SecuritySpy

Cynical Weather #

BenSoftware makes a Macintosh application called SecuritySpy, useful to manage local and network cameras. It can record them, play them back, trigger recording based on visual motion detection or various schedules, and do pretty much whatever you’d like your typical surveillance camera application to do. I’ve been using it in my house for many years, and am a fairly satisfied customer.

Indigo and SecuritySpy have obvious shared interests. They both are often used to track movement through space and time, and they both have a concept of events and how to respond to them. Cynical SecuritySpy brings them together.

You will need SecuritySpy version 2.1.1 or later for this plugin to work. The plugin will work with versions 3 and later as well. Of course, if you use an older version of SecuritySpy, you’ll only get the capabilities of that version. Be sure to use the latest released update for whatever version you paid for; earlier versions may have bugs that interfere with Cynical SecuritySpy.

Overview #

Install and configure SecuritySpy normally. Then create a Server device to represent each SecuritySpy installation, and one Camera device for each camera of interest. Use Indigo plugin actions to manipulate those cameras, and use Events to respond to changes.

Cynical SecuritySpy tracks changes in SecuritySpy’s state and reflects them in the state of the server and camera devices, as well as through Camera Motion events. When your Indigo scripts cause changes in SecuritySpy, they will be reflected as Indigo device changes only when SecuritySpy reports them. This means that Cynical SecuritySpy provides you with closed-loop supervision over SecuritySpy servers - what you see in Indigo state and events is what actually happened on the server, not just what you said you wanted to happen.

To supplement SecuritySpy’s motion sensing, use Indigo Trigger Recording actions, for example in response to an Indigo motion sensor. To respond to motion detected by SecuritySpy, write triggers for Camera Motion events.

To arrange for Indigo to directly control recording in SecuritySpy, configure the camera in SecuritySpy for continuous recording, and then use the Arm Camera action in Indigo to enable and disable continuous recording as desired. This requires SecuritySpy 4 or later.

Devices #

Server Device #

To work with a SecuritySpy server, you must first tell Indigo about it by creating a Server device. This tells Indigo where the server is and how to talk to it. The server must have its web server component enabled, and the port number you enter is that of the web server. The web server must allow http connections, not just https (secure) ones, though it’s okay to allow both.

Cynical SecuritySpy talks to SecuritySpy exclusively through its web interface. There is no need for Indigo and SecuritySpy to run on the same computer, though they certainly can.

Yes, you can talk to multiple SecuritySpy servers on different computers if you like; just make a different Server device for each one. The right things will happen.

Access Control #

I highly recommend creating a new user account in SecuritySpy and using that to authorize access for Indigo. Use a good, random password for it; you’ll never type it in again.

Different versions of SecuritySpy handle access control in varying ways. Allowing full access to the account always works, but is of course the least secure solution. Recent versions require (just) view access to all the cameras you want Indigo to see. If your (older) version has an “Allow access to general settings” checkbox, use that. If you want Indigo to make changes to SecuritySpy, add the appropriate options.

Note that if you’ve migrated repeatedly to newer versions of SecuritySpy, your configuration may be in a state you can’t actually achieve from scratch with the current version. Don’t sweat that. When in doubt, delete and recreate the SecuritySpy account and follow the new rules.

Configuration Settings #

Setting Value Description
SecuritySpy Host Address ip name or address Name or address of the host running SecuritySpy. If it’s the same computer as Indigo, leave it blank.
Port number or name Port number of SecuritySpy’s web server.
Username string Username for SecuritySpy web access. Leave blank if not needed.
Password string Password for SecuritySpy web access. Leave blank if not needed.
Report SecuritySpy Errors bool If checked, any error reported by SecuritySpy is written to the Indigo log as an error message.

Camera Device #

This is one camera configured on a SecuritySpy server. Pick from the popup list that shows all cameras on all SecuritySpy servers for which you have created devices in Indigo (and which are responding at the moment).

You can name your Indigo Camera device anything you like, quite independent from the name SecuritySpy uses for it. Cynical SecuritySpy remembers SecuritySpy cameras by their camera number, which is meant to be stable and will survive renaming. In practice, it is probably a good idea to keep those names similar to avoid confusing you.

Device States #

Camera devices have a state state that reflects the current status of the camera:

State Meaning
active The camera is available and active. It can record video and report motion.
passive The camera is available but is passive. It will not record or report motion.
disconnected SecuritySpy cannot connect to this network camera.
preparing The device is trying to initialize.
unavailable Something has gone wrong and the camera cannot be used right now. Check the Indigo log for error messages.

In addition, a camera device has these additional states:

State Type Meaning
sensitivity number The sensitivity of the camera’s motion detection function.
motion bool whether motion detection is enabled.
continuous bool [v4+] whether continuous recording is enabled.
actions bool [v4+] whether SecuritySpy actions are enabled

The sensitivity state is a value between 0 and 100 indicating how little the picture needs to change to trigger motion detection (when enabled). This is the same value you can set in SecuritySpy’s camera configuration window. You can script changes using the Set Motion Sensitivity action.

The motion, continuous, and actions states represent the arming states of the camera. They directly correspond to the SecuritySpy settings for this camera. You can use the Arm Camera action to set them from Indigo, and you can set triggers on these states to detect changes, regardless of source.

If motion is on, the camera detects motion and starts recording according to its configuration; in earlier versions of SecuritySpy this was called the “active” state. If motion is off, the camera will not detect motion.

The continuous switch, when on, enables any continuous recording configured for the camera. If it is off, continuous recording is disabled. This lets you directly control recording activity from Indigo.

The actions switch determines whether SecuritySpy’s configured actions for the camera are executed when their conditions apply. If actions is off, then SecuritySpy actions for this camera are ignored. This has no effect on any actions you may have programmed into Indigo; motion triggers will still fire in Indigo as long as the motion state for the camera is on.

If you are using SecuritySpy version 3 or earlier, the only arming state in effect is motion, formerly called “active”. The continuous and actions switches require version 4 or later.

Actions #

Arm Camera Action #

This action can change any of a camera’s arming states. From the pop-up menus, choose the camera, which arming state to change, and whether you want to turn it on, off, or toggle it.

For SecuritySpy versions 3 or earlier, the only arming state you can set is the motion state.

Make Active Action #

This is an old way to set the motion state of a camera to true.

Make Passive Action #

This is an old way to set the motion state of a camera to false.

Toggle Active Action #

This is an old way to toggle the motion state of a camera - make it true if it was false, or vice versa.

Trigger Recording Action #

This action tells SecuritySpy to act as if it had seen motion on the designated camera. If you have a motion sensor in the general area covered by a camera, that’s what you want to do. All the usual consequences follow; in particular, any motion-triggered recording commences. SecuritySpy’s usual rules apply; the camera must be active (have motion recording enabled) and must be configured appropriately.

This action is the complement to the Camera Motion event. Together, they link Indigo’s and SecuritySpy’s event systems together. In fact, if everything is hooked up right, this action will cause Camera Motion triggers to fire, as SecuritySpy faithfully reports the (simulated) motion back to Indigo. (As of SecuritySpy 5, you can recognize this situation in the event filter.)

Set Overlay Action #

This changes the text overlay that SecuritySpy can place onto a video camera’s image. This text becomes part of the video stream, so that it is displayed and recorded along with it. Note that it also irreversibly obscures what’s behind it.

Configuration Settings #

Setting Value Description
Message string The text to display. Consult the SecuritySpy manual for escape codes you can use in it.
Font Size number The size of the text, in video pixels.
Screen Position enum What corner of the display to use.

Note: This action neither sets nor clears the Camera Setup checkbox that enables overlays. If that checkbox is off, no overlays will ever be placed on the camera image. If you want to dynamically turn overlays off for a camera, leave that checkbox on and simply set the message text to empty.

Set Motion Sensitivity Action #

This action lets you change the sensitivity of a camera’s motion detection. It controls the same SecuritySpy parameter as the sensitivity slider in the Camera Setup window. The higher the number, the smaller the amount of motion needed to trigger an event. This is an integer value between 0 and 100.

The current sensitivity setting of a camera can be read as a camera state value. Any state change trigger set on this will fire when the camera’s sensitivity is changed, whether that is done through SecuritySpy’s user interface, its web interface, or through an Indigo action.

Move Camera Action #

This action allows you to control a PTZ (Point-Tilt-Zoom) capable camera - the kind that can be told to move around. Only cameras recognized by SecuritySpy as able to move will be shown in the camera selection menu. Modern SecuritySpy versions also have checkboxes to control this. But if you ask Indigo to move a camera that is in fact securely bolted to the ground, nothing bad will happen.

Position Preset Action #

This action tells a PTZ-capable camera to move to one of its preset positions. Even fewer types of cameras support presets, and only those cameras will be shown in the camera selection menu.

Run Script Action #

Ask SecuritySpy to execute one of the scripts in its Scripts folder. Pick the desired script from the popup list.

Play Sound Action #

Ask SecuritySpy to play one of the sounds available on the server. Loud siren sounds are particularly amusing. Pick the desired sound from the popup list.

Events #

Camera Motion Event #

This event triggers when SecuritySpy reports motion on a particular camera. This is based on SecuritySpy’s motion detection logic as set in the camera’s Camera Setup panel. It requires the camera to be active (its motion state to be on) and have motion detection enabled.

SecuritySpy 5 (and later) has a two-stage detection logic. As long as motion detection is active for a camera, SecuritySpy continuously monitors the camera image for change, subject to the camera settings in SecuritySpy about masks and detection delays. Once it detects such a change, it attempts image recognition on the picture. SecuritySpy’s “AI” settings for subject types then determine whether it triggers motion recording or SecuritySpy actions. SecuritySpy 4 (and earlier) does not have the image recognition part and simply reports the result of the first (and only) stage.

Camera Motion can trigger on SecuritySpy’s configured notions of either Motion Capture or SecuritySpy Actions. These use the thresholds and settings of SecuritySpy’s camera configuration; they work simultaneous with SecuritySpy’s triggers for motion recording and actions, respectively. You may optionally specify a particular detection cause to further limit when the trigger fires.

Alternatively, you may ask for specified (custom) detection and give your freely chosen type of object (human, vehicle, etc.) and a detection threshold. A trigger using specified detection works independently from SecuritySpy’s image recognition settings. (It is still subject to the first-stage settings like detection delays.)

The Maximum Rate configuration parameter determines how often continuing motion is reported - it is never triggered more often than every so many seconds. Under no circumstances will motion be reported more than once per second.

This is the complement to the Trigger Recording action, which tells SecuritySpy to take action as if it had detected motion on a camera.

Configuration Settings #

Setting Value Description
Camera device An already defined Camera device to watch for motion.
Maximum Rate number The minimum number of seconds between consecutive event triggers. This limits how often continuing motion is reported.
Detection enum Whether to detect SecuritySpy Motion, SecuritySpy actions, or explicitly Specified motion.
Reason enum For SecuritySpy configured events, what specific type of event to require. Use Anything to trigger on all event sources.
Detect enum For Specified detection, what to look for.
Threshold number For Specified detection, what detection threshold to use.

If your SecuritySpy server is version 4 or earlier, image detection is not available. Only Detection: Motion Capture should be used (it’s the default), and you cannot use a Reason other than Anything.

Notes #

Release Notes #

Notable releases:

Release Notes
2.4.2 More detailed event filtering for SecuritySpy 5.
2.4.0 Support for SecuritySpy 5.
2.3.0 Released under Apache 2.0 license.
2.2.2 Support for Indigo 7.
2.0.0 Support for SecuritySpy 4.
1.6.3 Fix a nasty resource leak that led to hangs in some situations.
1.4.1 Support for SecuritySpy 3. Better support for Indigo 6.
1.1.1 Add Toggle Active action.
1.1.0 Support field formulas.
1.0.1 Work with Indigo 5.1.1.
1.0.0 Initial release.