Distributed Motion Surveillance Security System (DMS3): a Go-based distributed video security system
MIT License
Much has changed over the past 4+ years since the 1.3.1 stable release of DMS3, so this release has focused on upgrades and improvements to make the DMS3 surveillance security system that so many people have relied upon even more efficient, stable, and secure.
Ever wonder if your surveillance cameras are operational, in need of updates, or even a reboot? The DMS3Dashboard component can be enabled to run on a DMS3Server and provide regularly-updated information of all DMS3Client components with device metrics that include:
Additionally, DMS3Dashboard provides a quick visual health check of all DMS3Client components, using color-sensitive component icons, where:
The DMS3Dashboard component is written using Go's HTML templating package, making it very easy to integrate new or existing HTML template themes into the component. The template used by DMS3Dashboard is based largely on the following resources:
New for this release are the following additional configuration options for DMS3Dashboard:
cmd
folder, while configuration files are now managed in a config
foldergocode
process to using gopls
If you appreciate isometric drawings, please check out our isometric-icons project, located here.
Distributed Motion Surveillance Security System (DMS3) is a Go-based application that integrates third-party open-source motion detection applications (e.g., the Motion motion detection software package, or OpenCV, the Open Source Computer Vision Library) into a distributed motion surveillance system that:
Support for the DMS3Dashboard component, allowing for the easy, visual monitoring of all DMS3Client devices managed by a DMS3Server component
Automated starting/stopping of any number of motion detection applications installed on smart device clients (e.g., the Motion motion detector software package) based on the presence/absence of user proxy devices
Always On feature starts/stops the motion detection application based on time-of-day (e.g., can enable video surveillance during nighttime or specific holiday hours)
Device clients can be custom-configured to process and respond to surveillance events independently and uniquely (e.g., an outdoor IR camera device only sends email during nighttime hours)
Optionally play separate audio file(s) on surveillance system enable and disable
Configurable event logging
MAC (Layer 2) address sensing
Bluetooth user proxy sensing (using RSSI, L2CAP, or similar) [planned]
Developed for use exclusively with Motion, DMS3Mail is an automated, real-time email notification service triggered by Motion-generated detection events
While DMS3 is primarily responsible for monitoring user proxies and determining when to enable or disable the surveillance system, it alone does not manage the processing of video stream data. That complex real-time task is left to motion detection libraries/applications which can be integrated directly into DMS3.
Support for the Motion motion detector software package
Support for the OpenCV Library [planned]
DMS3 is designed to utilize intelligent IoT devices, called Smart Device Clients (SDCs), while still supporting less intelligent, single-purpose devices, called Less Smart Device Clients (LSDCs).
DMS3 Smart Device Clients (SDCs) are hardware devices capable of processing local video streams for motion detection on-board, with dedicated hardware. Most computers and smaller single board computers (IoT SBCs) would be classed as smart device clients, including:
DMS3 Less Smart Device Clients (LSDCs) are hardware devices--typically purpose-built--unable to process motion detection video streams locally. These devices usually generate raw real-time video data, which is then sent, consumed and processed by an external device(s), oftentimes wirelessly across a network. Some examples of LSDCs include:
At its core, DMS3 sensing relies on the concept of a user proxy. In this context, a user proxy is any device representing a user that can be sensed on a home network. A smartphone is an excellent user proxy, assuming that a user's smartphone is active on the home network when the user is "at home," and drops from the network when the user leaves and is then "not at home."
This concept can extend to multiple user proxies, making it possible for DMS3 to keep a surveillance system disabled until everyone in an entire family has left home: once the last registered user proxy is no longer sensed on the home network, DMS3 automatically enables the surveillance system.
The reverse is true as well: DMS3 will keep the surveillance system enabled only until the first user proxy is seen on the home network (e.g., someone pulling into the driveway), at which time DMS3 will automatically disable the surveillance system.
In addition to sensing user proxies, DMS3 can be configured to keep a surveillance system enabled for a specific periods of time. Called Always On, this DMS3 feature works as an override for sensing user proxies: regardless of whether DMS3 senses a user proxy on the network, as long as the time-of-day policy is met, DMS3 will enable the surveillance system.
This feature is particularly useful for nighttime surveillance, when users may be asleep and/or smartphones may be turned off. For example, DMS3 can be configured to turn a surveillance system on at 2330, and stay on until 0500 the next morning. During this time, DMS3 will remain operational and monitor (and report) surveillance events as they occur.
DMS3 is organized into the following application components:
Optional for smart device clients configured to use the Motion motion detection application:
DMS3 is patterned after a client server model, where the DMS3Server component is centrally responsible for the logic of enabling/disabling the video surveillance system, while each participating smart device client (SDC), through the use of the DMS3Client component, is responsible for starting/stopping the locally-installed motion detection application. For "less smart" device clients (LSDCs), the processing of video stream data is passed over the wire to the server for processing and eventual system response and/or user notification.
In the example presented at the start of this document, one IP camera device, one IoT SBC device (a Raspberry Pi), and one webcam device are managed through the DMS3Server component (using the TCP protocol). The DMS3Server determines when to enable/disable the surveillance system, and notifies each participating device client running their own local instance of the DMS3Client component. Since the Raspberry Pi can be configured to run a local instance of a motion detection application, actual video stream processing, imaging, and eventual reporting is all done locally, greatly limiting network congestion.
The webcam device and the IP camera device--both less smart device clients (LSDCs), incapable of on-board stream processing--must pass raw stream data along to a device proxy running a DMS3Client component, which then applies motion detection processing on the incoming video streams.
The DMS3Server component is responsible for signaling the logic of enabling/disabling the video surveillance system to all device client endpoints. That is, the DMS3Server sends either a Start
or a Stop
message to all DMS3 device clients configured with a DMS3Client component, listening on the network.
DMS3Server does this by periodically scanning the network for the existence of registered user proxies. This device can be anything that exposes its MAC address on the network (e.g., a mobile phone on a home LAN). If that device is found on the network, it's assumed that "someone is home" and so DMS3Server sends out a Stop
message to all participating device clients, and their respective motion detection application is subsequently stopped (if currently running).
If that user proxy then "leaves" and is no longer found on the network, it's assumed that "nobody is home", and the DMS3Server sends out a Start
message to all participating device clients, and the motion detection application on that client is started (if currently stopped). Similar logic is used in the reverse case: when a user proxy is once again "back home," the motion detection application of each device client is signalled to Stop
.
Alternatively, the Always On feature uses time-of-day to enable/disable the surveillance system. The DMS3Server will look at the time range specified, and if the current time falls between the time range, the motion detection application of all client devices will be started. Once the current time falls outside of the specified time range, the motion detection application for each device client is then stopped.
The DMS3Client component runs on each configured smart device client endpoint, and is responsible for starting/stopping its locally installed motion detection application. The DMS3Client does this by periodically listening to the configured DMS3Server at the pre-configured IP address and port (network socket address). When the DMS3Client receives a change in motion detection application state, it either starts or stops its locally-installed motion detection application.
In instances where the device client is "less smart" and unable to process motion detection in local video streams, an LSDC instead passes motion detection processing to a DMS3Client proxy. Multiple LSDCs can be served by a single DMS3Client proxy. This proxy is then responsible for the operations of a typical DMS3Client.
Operationally, the DMS3Server and all DMS3Client device clients work together to establish a synchronized video surveillance state across all endpoints:
The activity diagram below shows the work flow of these two components:
When using Motion, DMS3Mail is a feature written for DMS3 that allows for the creation and sending an email whenever a valid capture event is triggered in Motion. DMS3Mail is very tightly integrated into Motion, where image and video capture events are identified, analyzed, and processed. DMS3Mail is triggered by the on_picture_save
and the on_movie_end
commands in Motion.
Note: the optional DMS3Mail component is called by neither DMS3Client nor DMS3Server. Instead, DMS3Mail is called directly by the Motion motion detection application.
The syntax for these Motion commands are:
<on_picture_save|on_movie_end> <absolute path to dms3mail> -pixels=%D -filename=%f
Once configured, DMS3Mail will respond to these two Motion event hooks, and an email will be generated and sent out with an image file or video clip capturing the surveillance event of interest.
At its core, DMS3 sensing relies on the concept of a user proxy. In this context, a user proxy is any device representing a user that can be sensed on a home network. A smartphone is an excellent user proxy, assuming that a user's smartphone is active on the home network when the user is "at home," and drops from the network when the user leaves and is then "not at home." DMS3 performs this sensing by searching the end user's network for MAC addresses registered during the configuration of the DMS3Server component (in the dms3server.toml
file).
Historically, MAC addresses have always represented, 1-for-1, the underlying hardware. However, more recently, and as a broader privacy policy, some device vendors now provide users the option to have their device generate MAC addresses randomly for over-the-air communications. This feature can disrupt the sensing services used by the DMS3Server component.
As a result, it's important to review your smartphone (or other user proxies) privacy policies and feature options and configure it accordingly.
A separate installation document is available here.
The MIT License (MIT)
Copyright (c) Business Learning Incorporated
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.