mirror of
https://github.com/kerberos-io/documentation.git
synced 2026-08-23 15:18:31 +00:00
256 lines
62 KiB
HTML
256 lines
62 KiB
HTML
<!doctype html><html lang=en-us><head><meta charset=utf-8><meta http-equiv=x-ua-compatible content="ie=edge"><meta name=viewport content="width=device-width,initial-scale=1,shrink-to-fit=no"><link rel=stylesheet href=https://doc.kerberos.io/main.5aa8061fdddcae33bf9aae606a659f783fca649c2a6c915897a14d1088493ae547064045e7ca5a43d69061955d449757d1bcb708760ae71f478384770974e798.css integrity="sha512-WqgGH93crjO/mq5gamWfeD/KZJwqbJFYl6FNEIhJOuVHBkBF58paQ9aQYZVdRJdX0by3CHYK5x9Hg4R3CXTnmA==" crossorigin=anonymous><noscript><style>img.lazyload{display:none}</style></noscript><meta name=robots content="index, follow"><meta name=googlebot content="index, follow, max-snippet:-1, max-image-preview:large, max-video-preview:-1"><meta name=bingbot content="index, follow, max-snippet:-1, max-image-preview:large, max-video-preview:-1"><title>Machinery - Kerberos Docs</title><meta name=description content="The machinery is the engine of the Kerberos Open Source agent, it connects to the camera and makes recordings."><link rel=canonical href=https://doc.kerberos.io/opensource/machinery/><meta name=twitter:card content="summary_large_image"><meta name=twitter:image content="/doks.png"><meta name=twitter:title content="Machinery"><meta name=twitter:description content="The machinery is the engine of the Kerberos Open Source agent, it connects to the camera and makes recordings."><meta name=twitter:site content="@kerberosio"><meta name=twitter:creator content="@kerberosio"><meta property="og:title" content="Machinery"><meta property="og:description" content="The machinery is the engine of the Kerberos Open Source agent, it connects to the camera and makes recordings."><meta property="og:type" content="article"><meta property="og:url" content="/opensource/machinery/"><meta property="og:image" content="/doks.png"><meta property="article:published_time" content="2020-10-06T08:49:31+00:00"><meta property="article:modified_time" content="2020-10-06T08:49:31+00:00"><meta property="og:site_name" content="Kerberos Docs"><meta property="article:publisher" content="https://www.facebook.com/"><meta property="article:author" content="https://www.facebook.com/"><meta property="og:locale" content="en_US"><script type=application/ld+json>{"@context":"http://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https:\/\/doc.kerberos.io\/"},{"@type":"ListItem","position":3,"name":"Opensource","item":"https:\/\/doc.kerberos.io\/\/opensource\/"},{"@type":"ListItem","position":4,"name":"Machinery","item":"https:\/\/doc.kerberos.io\/\/opensource\/machinery\/"}]}</script><meta name=theme-color content="#fff"><link rel=apple-touch-icon sizes=180x180 href=https://doc.kerberos.io/favicons/apple-touch-icon.png><link rel=icon type=image/png sizes=32x32 href=https://doc.kerberos.io/favicons/favicon-32x32.png><link rel=icon type=image/png sizes=16x16 href=https://doc.kerberos.io/favicons/favicon-16x16.png><link rel=manifest href=https://doc.kerberos.io/site.webmanifest><script async defer data-domain=doc.kerberos.io src=https://plausible.kerberos.io/js/plausible.js></script></head><body class="opensource single"><div class="header-bar fixed-top"></div><header class="navbar fixed-top navbar-expand-md navbar-light"><div class=container><input class="menu-btn order-0" type=checkbox id=menu-btn>
|
|
<label class="menu-icon d-md-none" for=menu-btn><span class=navicon></span></label><a class="navbar-brand order-1 order-md-0 me-auto" href=https://doc.kerberos.io/><img src=https://doc.kerberos.io/images/kerberos-logo.svg class=logo>
|
|
Kerberos Docs</a>
|
|
<button id=mode class="btn btn-link order-2 order-md-4" type=button aria-label="Toggle mode">
|
|
<span class=toggle-dark><svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentcolor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-moon"><path d="M21 12.79A9 9 0 1111.21 3 7 7 0 0021 12.79z"/></svg></span><span class=toggle-light><svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentcolor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-sun"><circle cx="12" cy="12" r="5"/><line x1="12" y1="1" x2="12" y2="3"/><line x1="12" y1="21" x2="12" y2="23"/><line x1="4.22" y1="4.22" x2="5.64" y2="5.64"/><line x1="18.36" y1="18.36" x2="19.78" y2="19.78"/><line x1="1" y1="12" x2="3" y2="12"/><line x1="21" y1="12" x2="23" y2="12"/><line x1="4.22" y1="19.78" x2="5.64" y2="18.36"/><line x1="18.36" y1="5.64" x2="19.78" y2="4.22"/></svg></span></button><div class="collapse navbar-collapse order-4 order-md-1"><ul class="navbar-nav main-nav me-auto order-5 order-md-2"><li class=nav-item><a class=nav-link href=https://kerberos.io>Homepage</a></li></ul><div class="break order-6 d-md-none"></div><form class="navbar-form flex-grow-1 order-7 order-md-3"><input id=userinput class="form-control is-search" type=search placeholder="Search docs..." aria-label="Search docs..." autocomplete=off><div id=suggestions class="shadow bg-white rounded"></div></form></div></div></header><div class="wrap container" role=document><div class=content><div class="row flex-xl-nowrap"><div class="col-lg-5 col-xl-4 docs-sidebar"><nav class=docs-links aria-label="Main navigation"><h3>Prologue</h3><ul class=list-unstyled><li><a class=docs-link href=https://doc.kerberos.io/>Introduction</a></li><li><a class=docs-link href=https://doc.kerberos.io/prologue/how/>How it works</a></li><li><a class=docs-link href=https://doc.kerberos.io/prologue/deployments/>Deployments</a></li><li><a class=docs-link href=https://doc.kerberos.io/prologue/glossary/>Glossary</a></li></ul><h3>Opensource v2</h3><ul class=list-unstyled><li><a class=docs-link href=https://doc.kerberos.io/opensource/first-things-first/>First things first</a></li><li><a class=docs-link href=https://doc.kerberos.io/opensource/get-started/>Get started</a></li><li><a class=docs-link href=https://doc.kerberos.io/opensource/installation/>Installation</a></li><li><a class=docs-link href=https://doc.kerberos.io/opensource/installation-advanced/>Advanced Installation</a></li><li><a class=docs-link href=https://doc.kerberos.io/opensource/releases/>Release notes</a></li><li><a class=docs-link href=https://doc.kerberos.io/opensource/license/>License</a></li><li><a class=docs-link href=https://doc.kerberos.io/opensource/upgrade/>Upgrade</a></li><li><a class=docs-link href=https://doc.kerberos.io/opensource/contribute/>Contribute</a></li><li><a class="docs-link active" href=https://doc.kerberos.io/opensource/machinery/>Machinery</a></li><li><a class=docs-link href=https://doc.kerberos.io/opensource/web/>Web</a></li></ul><h3>Opensource v3</h3><ul class=list-unstyled><li><a class=docs-link href=https://doc.kerberos.io/opensourcev3/announcement/>Announcement</a></li></ul><h3>Enterprise</h3><ul class=list-unstyled><li><a class=docs-link href=https://doc.kerberos.io/enterprise/first-things-first/>First things first</a></li><li><a class=docs-link href=https://doc.kerberos.io/enterprise/get-started/>Get Started</a></li><li><a class=docs-link href=https://doc.kerberos.io/enterprise/installation/>Installation</a></li><li><a class=docs-link href=https://doc.kerberos.io/enterprise/installation-cloud/>Cloud Installation</a></li><li><a class=docs-link href=https://doc.kerberos.io/enterprise/installation-edge/>Edge Installation</a></li><li><a class=docs-link href=https://doc.kerberos.io/enterprise/releases/>Releases</a></li></ul><h3>Vault</h3><ul class=list-unstyled><li><a class=docs-link href=https://doc.kerberos.io/vault/first-things-first/>First things first</a></li><li><a class=docs-link href=https://doc.kerberos.io/vault/get-started/>Get Started</a></li><li><a class=docs-link href=https://doc.kerberos.io/vault/installation/>Installation</a></li><li><a class=docs-link href=https://doc.kerberos.io/vault/installation-cloud/>Cloud Installation</a></li><li><a class=docs-link href=https://doc.kerberos.io/vault/installation-edge/>Edge Installation</a></li><li><a class=docs-link href=https://doc.kerberos.io/vault/providers/>Providers</a></li><li><a class=docs-link href=https://doc.kerberos.io/vault/recycle/>Recycle</a></li><li><a class=docs-link href=https://doc.kerberos.io/vault/releases/releases/>Releases</a></li></ul><h3>Hub</h3><ul class=list-unstyled><li><a class=docs-link href=https://doc.kerberos.io/hub/first-things-first/>First things first</a></li></ul></nav></div><nav class="docs-toc d-none d-xl-block col-xl-4" aria-label="Secondary navigation"><div class=page-links><h3>On this page</h3><nav id=TableOfContents><ul><li><a href=#project-structure>Project structure</a></li><li><a href=#capture>Capture</a><ul><li><a href=#usb-camera>USB camera</a></li><li><a href=#raspberry-pi-camera-module>Raspberry Pi Camera Module</a></li><li><a href=#ip-camera>IP camera</a></li></ul></li><li><a href=#condition>Condition</a><ul><li><a href=#enabled>Enabled</a></li><li><a href=#time>Time</a></li></ul></li><li><a href=#algorithm>Algorithm</a><ul><li><a href=#differential-images>Differential images</a></li></ul></li><li><a href=#expositor>Expositor</a><ul><li><a href=#rectangle>Rectangle</a></li><li><a href=#hull>Hull</a></li></ul></li><li><a href=#heuristic>Heuristic</a><ul><li><a href=#sequence>Sequence</a></li></ul></li><li><a href=#output>Output</a><ul><li><a href=#disk>Disk</a></li><li><a href=#video>Video</a></li><li><a href=#tcpip-client>TCP/IP client</a></li><li><a href=#gpio>GPIO</a></li><li><a href=#webhook>Webhook</a></li><li><a href=#script>Script</a></li><li><a href=#mqtt>MQTT</a></li></ul></li><li><a href=#streaming>Streaming</a><ul><li><a href=#parameters-16>Parameters</a></li></ul></li></ul></nav></div></nav><main class="docs-content col-lg-11 col-xl-8"><h1>Machinery</h1><p class=lead>The machinery is the engine of the Kerberos Open Source agent, it connects to the camera and makes recordings.</p><p>The machinery is the processing engine of Kerberos Open Source. It’s an image processing framework, written in C++, who benefits from other third party libraries (OpenCV, etc). It takes images from the type of camera (USB-, IP- or RPi-camera) you’ve configured in the configuration files and executes one ore more algorithms and post-processes (e.g. save a snapshot). The configuration files allow you to define the type of camera, post-processes, conditions and much more; it’s highly configurable. It’s important to note that the machinery, out-of-the-box, can handle only one camera at a time.</p><h2 id=project-structure>Project structure<a href=#project-structure class=anchor aria-hidden=true>#</a></h2><p>The machinery is an image processing framework which is devided into four steps:</p><ul><li>condition</li><li>algorithm</li><li>expositor</li><li>heuristic</li></ul><p>The steps belong to a four passway; illustrated on the image below. In each cycle a sequence of images is processed. Each step will process the sequence, and will return some result to the next step. For example: an algorithm will process the images and returns an array to the Expositor, which contains boolean values. The steps are loosly coupled, so they have simple conventions, just like the example before.</p><p>Thanks to the loosly coupling, each step can be developed indepently. So algorithms, expositors, heuristics and conditions can be switched on the fly. This makes it easier for other developers who want to contribute to the machinery. They can create a new algorithm without knowing how a specific expositor or heuristic works. They just need to be aware of the convention an algorithm should meet.</p><figure class=stretch><img src=project-structure.svg alt="The Kerberos Opensource agent is composed out of different concepts."><figcaption><p>The Kerberos Opensource agent is composed out of different concepts.</p></figcaption></figure><p>These different steps can be configured by editing a couple of configurationn files located at <code>config/</code>. The main configuration file <code>config/config.xml</code> looks like this:</p><pre><code class=language-xml><?xml version="1.0"?>
|
|
<kerberos>
|
|
<instance>
|
|
<name type="text">frontdoor</name>
|
|
<logging type="bool">false</logging>
|
|
<timezone type="timezone">Europe-Brussels</timezone>
|
|
<capture file="capture.xml">RaspiCamera</capture>
|
|
<stream file="stream.xml">Mjpg</stream>
|
|
<condition file="condition.xml" type="multiple">Enabled</condition>
|
|
<algorithm file="algorithm.xml">DifferentialCollins</algorithm>
|
|
<expositor file="expositor.xml">Hull</expositor>
|
|
<heuristic file="heuristic.xml">Sequence</heuristic>
|
|
<io file="io.xml" type="multiple">Video</io>
|
|
<cloud file="cloud.xml">S3</cloud>
|
|
</instance>
|
|
</kerberos>
|
|
</code></pre><h2 id=capture>Capture<a href=#capture class=anchor aria-hidden=true>#</a></h2><p>You can choose which capture device you will be using, you can use your old USB webcam, the popular Raspberry Pi camera or a state-of-the-art IP camera. The capture device will take pictures and deliver them to the algorithm if the conditions (the first step of the four passway) are valid.</p><p>You can change the capture device by changing the <code>config/config.xml</code> file, and choose one of the following:</p><ul><li>USBCamera</li><li>RaspiCamera</li><li>IPCamera</li></ul><pre><code class=language-xml><?xml version="1.0"?>
|
|
<kerberos>
|
|
<instance>
|
|
...
|
|
<capture file="capture.xml">RaspiCamera</capture>
|
|
...
|
|
</instance>
|
|
</kerberos>
|
|
</code></pre><h3 id=usb-camera>USB camera<a href=#usb-camera class=anchor aria-hidden=true>#</a></h3><p>The machinery supports a whole range of USB cameras. You will find a complete list here. Make sure you have updated the web interface, to make the machinery aware you will be using an USB camera.</p><h4 id=parameters>Parameters<a href=#parameters class=anchor aria-hidden=true>#</a></h4><p>The parameters of the USB camera can be found in the <code>config/capture.xml</code> file, but you can also use the web to modify the parameters. Below you see a default configuration file.</p><pre><code class=language-xml><captures>
|
|
<USBCamera>
|
|
<frameWidth type="number">1280</frameWidth>
|
|
<frameHeight type="number">720</frameHeight>
|
|
<deviceNumber type="number">0</deviceNumber>
|
|
<delay type="number">0</delay>
|
|
<angle type="number">0</angle>
|
|
</USBCamera>
|
|
</captures>
|
|
</code></pre><h5 id=framewidth-and--height>Framewidth and -height<a href=#framewidth-and--height class=anchor aria-hidden=true>#</a></h5><p>You can set the resolution of the capture device, make sure the resolution you’ve defined is valid with your camera. Please check the specs of the USB camera you’re using.</p><h5 id=device-number>Device number<a href=#device-number class=anchor aria-hidden=true>#</a></h5><p>If more than one device is connected, you can specify the index of the USB-camera. The index is an integer (1-5).</p><h5 id=delay>Delay<a href=#delay class=anchor aria-hidden=true>#</a></h5><p>You can provide a delay/interval (milliseconds) between two captures.</p><h5 id=angle>Angle<a href=#angle class=anchor aria-hidden=true>#</a></h5><p>By defining an angle (degrees), you can rotate the images taken by the capture device. For example if you would mount the camera upside down, than you could enter the value 180 as the angle; this will flip the images.</p><h3 id=raspberry-pi-camera-module>Raspberry Pi Camera Module<a href=#raspberry-pi-camera-module class=anchor aria-hidden=true>#</a></h3><p>You can use the Raspberry Pi Camera Module with the machinery. You just need to attach the camera module and you’re ready to go. The Raspberry Pi Camera Module is enabled by default in the web.</p><h4 id=parameters-1>Parameters<a href=#parameters-1 class=anchor aria-hidden=true>#</a></h4><p>The parameters of the Raspberry Pi Camera Module can be found in the config/capture.xml file, but you can also use the web to modify the parameters. Below you see a default configuration file.</p><pre><code class=language-xml><captures>
|
|
<RaspiCamera>
|
|
<frameWidth type="number">640</frameWidth>
|
|
<frameHeight type="number">480</frameHeight>
|
|
<delay type="number">1400</delay>
|
|
<angle type="number">0</angle>
|
|
<framerate type="number">30</framerate>
|
|
<sharpness type="number">0</sharpness>
|
|
<saturation type="number">0</saturation>
|
|
<contrast type="number">0</contrast>
|
|
<brightness type="number">50</brightness>
|
|
</RaspiCamera>
|
|
</captures>
|
|
</code></pre><h5 id=framewidth-and--height-1>Framewidth and -height<a href=#framewidth-and--height-1 class=anchor aria-hidden=true>#</a></h5><p>You can set the resolution of the camera module, make sure the resolution you’ve defined is valid.</p><h5 id=delay-1>Delay<a href=#delay-1 class=anchor aria-hidden=true>#</a></h5><p>You can provide a delay/interval (milliseconds) between two captures.</p><h5 id=angle-1>Angle<a href=#angle-1 class=anchor aria-hidden=true>#</a></h5><p>By defining an angle (degrees), you can rotate the images taken by the capture device. For example if you would mount the camera upside down, than you could enter the value 180 as the angle; this will flip the images.</p><h5 id=framerate>Framerate<a href=#framerate class=anchor aria-hidden=true>#</a></h5><p>The number of frames captures per second. Please note that this parameter will also be used if you’re recording video. E.g. if you set this parameter to 20, you’re recorded videos will also be 20 FPS.</p><h5 id=sharpness-saturation-contrast-brightness>Sharpness, saturation, contrast, brightness<a href=#sharpness-saturation-contrast-brightness class=anchor aria-hidden=true>#</a></h5><p>Camera properties which you can specify to tune the settings to your needs.</p><h3 id=ip-camera>IP camera<a href=#ip-camera class=anchor aria-hidden=true>#</a></h3><p>The machinery can be used with any IP camera, that provides a RTSP (or MJPEG) stream. Make sure that you know the correct URL of your IP camera, you can <a href=http://www.ispyconnect.com/sources.aspx>find a list here</a>.</p><h4 id=parameters-2>Parameters<a href=#parameters-2 class=anchor aria-hidden=true>#</a></h4><p>The parameters of the IP capture device can be found in the <code>config/capture.xml</code> file, but you can also use the web to modify the parameters. Below you see a default configuration file.</p><pre><code class=language-xml><captures>
|
|
<IPCamera>
|
|
<url type="text">http://username:password@ipaddress/image.jpg</url>
|
|
<frameWidth type="number">800</frameWidth>
|
|
<frameHeight type="number">640</frameHeight>
|
|
<delay type="number">0</delay>
|
|
<angle type="number">0</angle>
|
|
</IPCamera>
|
|
</captures>
|
|
</code></pre><h5 id=url>URL<a href=#url class=anchor aria-hidden=true>#</a></h5><p>To use your IP camera, you should provide a valid RTSP (or MJPEG) URL. The machinery will take snapshots from this stream.</p><h5 id=framewidth-and--height-2>Framewidth and -height<a href=#framewidth-and--height-2 class=anchor aria-hidden=true>#</a></h5><p>You can set the resolution of the capture device, make sure the resolution you’ve defined is equal to the resolution you’ve defined in your IP-camera software.</p><h5 id=delay-2>Delay<a href=#delay-2 class=anchor aria-hidden=true>#</a></h5><p>You can provide a delay/interval (milliseconds) between two captures.</p><h5 id=angle-2>Angle<a href=#angle-2 class=anchor aria-hidden=true>#</a></h5><p>By defining an angle (degrees), you can rotate the images taken by the capture device. For example if you would mount the camera upside down, than you could enter the value 180 as the angle; this will flip the images.</p><h2 id=condition>Condition<a href=#condition class=anchor aria-hidden=true>#</a></h2><p>The condition is the first step of the four passway. In this step the machinery will determine if it’s allowed to proceed to the next step. For example a condition can be a time constraint, a brightness threshold, etc; multiple conditions can be selected.</p><pre><code class=language-xml><?xml version="1.0"?>
|
|
<kerberos>
|
|
<instance>
|
|
...
|
|
<condition file="condition.xml" type="multiple">Enabled</condition>
|
|
...
|
|
</instance>
|
|
</kerberos>
|
|
</code></pre><h3 id=enabled>Enabled<a href=#enabled class=anchor aria-hidden=true>#</a></h3><p>It can be helpful to enable or disable the machinery at specific times. Therefore the time condition makes it possible to select a time range for each day of the week. When the current time is within the time range, the machinery will be enabled.</p><h4 id=parameters-3>Parameters<a href=#parameters-3 class=anchor aria-hidden=true>#</a></h4><p>The parameters of the Enabled condition can be found in the <code>config/condition.xml</code> file, but you can also use the web to modify the parameters. Below you see a default configuration file.</p><pre><code class=language-xml><conditions>
|
|
<Enabled>
|
|
<active type="bool">true</active>
|
|
<delay type="number">5000</delay>
|
|
</Enabled>
|
|
</conditions>
|
|
</code></pre><h5 id=active>Active<a href=#active class=anchor aria-hidden=true>#</a></h5><p>The active field is boolean value (true/false). When the active field is true, the machinery is enabled, if not it’s disabled.</p><h5 id=delay-3>Delay<a href=#delay-3 class=anchor aria-hidden=true>#</a></h5><p>The delay value is used when the condition failed, so when the current time isn’t in the selected time range for that day. In that case the machinery will idle for the specified delay time. The value of the delay is expressed in miliseconds.</p><h3 id=time>Time<a href=#time class=anchor aria-hidden=true>#</a></h3><p>It can be helpful to enable or disable the machinery at specific times. Therefore the time condition makes it possible to select a time range for each day of the week. When the current time is within the time range, the machinery will be enabled.</p><h4 id=parameters-4>Parameters<a href=#parameters-4 class=anchor aria-hidden=true>#</a></h4><p>The parameters of the Time condition can be found in the <code>config/condition.xml</code> file, but you can also use the web to modify the parameters. Below you see a default configuration file.</p><pre><code class=language-xml><conditions>
|
|
<Time>
|
|
<times type="timeselection">13:00,15:00-0:01,20:58-0:01,20:59-0:01,19:20-0:01,21:59-0,0-0,0</times>
|
|
<delay type="number">10000</delay>
|
|
</Time>
|
|
</conditions>
|
|
</code></pre><h5 id=times>Times<a href=#times class=anchor aria-hidden=true>#</a></h5><p>The times property contains a list of times, delimited by a “-”. The first item in the list will specify the time range for the first day of the week (Monday), the last item for the last day of the week (Sunday). The begin- and end-time, for a specific day, are delimited by a “,” where the first element will specify that start time and the second one specifies the end time.</p><h5 id=delay-4>Delay<a href=#delay-4 class=anchor aria-hidden=true>#</a></h5><p>The delay value is used when the condition failed, so when the current time isn’t in the selected time range for that day. In that case the machinery will idle for the specified delay time. The value of the delay is expressed in miliseconds.</p><h2 id=algorithm>Algorithm<a href=#algorithm class=anchor aria-hidden=true>#</a></h2><p>The algorithm is the second step of the four passway. An algorithm will execute some kind of function on a sequence of images, and end up with a black and white image; just like the image below. An example of an algorithm would be one that does motion detection or one that would detect cats or dogs (using TensorFlow, ar any other Deep Learning framework).</p><figure class=stretch><img src=algorithm.png alt="An algorithm allows us to find the pixels of interests."><figcaption><p>An algorithm allows us to find the pixels of interests.</p></figcaption></figure><p>The white pixels on the image will indicate the object of interest. For example, when looking for motion, the pixels that have been changed; it depends on what the algorithm is looking for. The black pixels are background pixels.</p><p>The only convention that an algorithm should meet is that it should return a black and white image to the next step; the expositor. And of course that it requires a sequence of images as a parameter. Besides those conventions, an algorithm can do everything it wants to do. So you could create your own cat detection algorithm, marker detection, etc.</p><p>You can select the algortihm in the <code>config/config.xml</code>.</p><pre><code class=language-xml><?xml version="1.0"?>
|
|
<kerberos>
|
|
<instance>
|
|
...
|
|
<algorithm file="algorithm.xml">DifferentialCollins</algorithm>
|
|
...
|
|
</instance>
|
|
</kerberos>
|
|
</code></pre><h3 id=differential-images>Differential images<a href=#differential-images class=anchor aria-hidden=true>#</a></h3><p>This algorithm is a very simple method to detect motion; in terms of understanding but also processing. Just like the name says, it’s the result of comparing images. When the images are compared, we know the pixels that have been changed and if the amount of pixels that changed is big enough, one can say that something happened and thus motion was detected.</p><p>To get a more technical explanation: the algoritm will substract 2 or more images, and once that is done it will end up with a black and white image. The white pixels will mark the pixels that where different/changed and the black pixels are the pixels that have not changed; background pixels. Please note that there are several different combinations of substracting images. However for the machinery, we will use the method of Collins et al. as this method erases the phenomenon “ghosting”.</p><figure class=stretch><img src=differential-images.png alt="The differential images algorithm takes a sequence of images to calculate motion."><figcaption><p>The differential images algorithm takes a sequence of images to calculate motion.</p></figcaption></figure><p>In the image above the method of Collins et al. is illustrated. For this method we will process three images. The images are a sequence (from left to right), so the first (A) image was taken before the second (B) one, and the second (B) before the third (C) one. Next we will do a first comparision (C-B) of the third (C) image and the second (B) image, and after that we will do a second comparison (C-A) of the third (C) image and first (A) image.</p><p>After the comparison we will end up with two difference images (C-B) and (C-A); both will mark the white pixels as changed pixels and black as non-changed pixels. To finish the algorithm we will do a logical AND-operation of the two difference images; this will give us the final black and white image ((C-B)&&(C-A)).</p><p>The main idea of the Colins et al. method, is that it will erase “ghosting”. In the last step we are doing a logical AND-operation, by doing this we will only keep the pixels, that changed in the first two images; therefore we can eliminate false positives.</p><h4 id=parameters-5>Parameters<a href=#parameters-5 class=anchor aria-hidden=true>#</a></h4><p>The parameters of the Differential images algorithm can be found in the config/algorithm.xml file, but you can also use the web to modify the parameters. Below you see a default configuration file.</p><pre><code class=language-xml><algorithms>
|
|
<DifferentialCollins>
|
|
<erode type="number">5</erode>
|
|
<threshold type="number">20</threshold>
|
|
</DifferentialCollins>
|
|
</algorithms>
|
|
</code></pre><h5 id=erode>Erode<a href=#erode class=anchor aria-hidden=true>#</a></h5><p>The erode parameter represents a structural element (a morphological operation), which will be used to minimize the changed pixels; more information about eroding can be found here. The idea of the eroding is that pixels which are isolated will be removed; this means that when only one pixel changed, that pixel will reverted to the non-changed state. But for example when a large change happens and a lot of adjacent pixels are changed, the eroding will not be able to revert them.</p><p>The higher the number of the erode parameter, the more aggressive the eroding will be. So high erode values, will make it possible that also large changes will be reverted to the non-changed state.</p><h5 id=threshold>Threshold<a href=#threshold class=anchor aria-hidden=true>#</a></h5><p>When doing the comparison of two images, we won’t end up with a clean black and white image. In most of the cases the values will be between 0 and 255; so gray values. This means that the value 0 will mean that both pixels where the same in both image, and values 255 mean that both pixels where totally different in both images. Of course we will also have values between 0-255, so pixels that are a little bit different in both images. So to make the resulting black and white image, we will need to apply a threshold value.</p><p>The threshold will specify how much a pixel has to be different in the two images. So for example when the threshold is 30, it means that the difference between two pixels has to be equal or more then 30. The higher the threshold the more the pixel needs to be different, to be marked as changed.</p><h2 id=expositor>Expositor<a href=#expositor class=anchor aria-hidden=true>#</a></h2><p>After the algorithm is executed, the expositor will determine, a region, where the changes were detected. An expositor can constrain a region in terms of selecting a hull or defining a rectangle.</p><p>An expositor receives a black and white image as parameter and should modify a JSON object with all the information it processed. The JSON object must include: the bounding rectangle(s) of the positions where the pixels of interest are located and the number of pixels of interest. But can also include other optional parameters.</p><p>You can change the expositor by changing the <code>config/config.xml</code> file, and choose one of the following:</p><ul><li>Hull</li><li>Rectangle</li></ul><pre><code class=language-xml><?xml version="1.0"?>
|
|
<kerberos>
|
|
<instance>
|
|
...
|
|
<expositor file="expositor.xml">Hull</expositor>
|
|
...
|
|
</instance>
|
|
</kerberos>
|
|
</code></pre><h3 id=rectangle>Rectangle<a href=#rectangle class=anchor aria-hidden=true>#</a></h3><p>This is a trivial expositor. A rectangle region can be defined to constrain the locations of pixels of interest. The rectangle repositor will return the region of the pixels of interest.</p><h4 id=parameters-6>Parameters<a href=#parameters-6 class=anchor aria-hidden=true>#</a></h4><p>The parameters of the rectangle expositor can be found in the config/expositor.xml file, but you can also use the web to modify the parameters. Below you see a default configuration file.</p><pre><code class=language-xml><expositors>
|
|
<Rectangle>
|
|
<region>
|
|
<x1 type="number">0</x1>
|
|
<y1 type="number">0</y1>
|
|
<x2 type="number">1280</x2>
|
|
<y2 type="number">720</y2>
|
|
</region>
|
|
</Rectangle>
|
|
</expositors>
|
|
</code></pre><h5 id=region>Region<a href=#region class=anchor aria-hidden=true>#</a></h5><p>The region parameter contains 4 values; x1, y1, x2 and y2 respectively. The values x1 and y1 indicate the x- and y-coordinate of the left upper starting point. The values x2 and y2 are the bottom right coordinates. A virtual rectangle will be drawn from (x1,y1) to (x2,y2). Pixels of interest that lie within this rectangle are valid pixels; if not they are invalid.</p><h3 id=hull>Hull<a href=#hull class=anchor aria-hidden=true>#</a></h3><p>This hull is a more complex expositor than the rectangle. A hull can be selected with the web, you can select one or more coordinates to create a flexible region. The coordinates can be adjusted afterwards and be removed by double clicking on the coordinate. You can expand the hull by removing the start coordinate, which is marked by the white bullet.</p><figure class=stretch><img src=hull.png alt="A hull, or polygon, allows you to specify a region of interest."><figcaption><p>A hull, or polygon, allows you to specify a region of interest.</p></figcaption></figure><h4 id=parameters-7>Parameters<a href=#parameters-7 class=anchor aria-hidden=true>#</a></h4><p>The parameters of the hull expositor can be found in the config/expositor.xml file, but you can also use the web to modify the parameters. Below you see a default configuration file.</p><pre><code class=language-xml><expositors>
|
|
<Hull>
|
|
<region type="hullselection">347,361|627,266|975,328|1091,328|1148,413|1158,516|1121,534|962,567|699,648|531,700|243,613|423,550|665,453|850,470|666,361|467,385|325,460|165,372</region>
|
|
</Hull>
|
|
</expositors>
|
|
</code></pre><h5 id=region-1>Region<a href=#region-1 class=anchor aria-hidden=true>#</a></h5><p>The region parameter contains n values. Each value represents a coordinate (x,y) and are seperated by the “|” delimiter. These coordinates are used to calculate the concave hull. Pixels of interest that lie within the concave hull are valid pixels; if not they are invalid.</p><h2 id=heuristic>Heuristic<a href=#heuristic class=anchor aria-hidden=true>#</a></h2><p>The heuristic is the last step in the four passway which will decide if the detection is valid or not. It will do this by using information from the previous steps (the expositor and the algorithm); e.g. number of changed pixels.</p><p>You can change the heuristic by changing the <code>config/config.xml</code> file, and choose one of the following:</p><ul><li>Sequence</li></ul><pre><code class=language-xml><?xml version="1.0"?>
|
|
<kerberos>
|
|
<instance>
|
|
...
|
|
<heuristic file="heuristic.xml">Sequence</heuristic>
|
|
...
|
|
</instance>
|
|
</kerberos>
|
|
</code></pre><h3 id=sequence>Sequence<a href=#sequence class=anchor aria-hidden=true>#</a></h3><p>This is a trivial heuristic. The sequence heuristic will store a single integer in memory, that will count the numbers of valid detections. When the heuristic will detect a false detection, it will decrease the count. The sequence heuristic will return true, if a threshold is reached; for example when something was detected three times in a row.</p><h4 id=parameters-8>Parameters<a href=#parameters-8 class=anchor aria-hidden=true>#</a></h4><p>The parameters of the Sequence heuristic can be found in the config/heuristic.xml file, but you can also use the web to modify the parameters. Below you see a default configuration file.</p><pre><code class=language-xml><heuristics>
|
|
<Sequence>
|
|
<minimumChanges type="number">1</minimumChanges>
|
|
<minimumDuration type="number">1</minimumDuration>
|
|
<noMotionDelayTime type="number">2000</noMotionDelayTime>
|
|
</Sequence>
|
|
</heuristics>
|
|
</code></pre><h5 id=minimum-changes>Minimum changes<a href=#minimum-changes class=anchor aria-hidden=true>#</a></h5><p>The heuristic will only return true if enough changes have been detected. The minimum of changes indicates the minimum number of pixels that have to been changed, to be a valid detection.</p><h5 id=minimum-durations>Minimum durations<a href=#minimum-durations class=anchor aria-hidden=true>#</a></h5><p>The minimum number of detections in a row to be a valid detection.</p><h5 id=no-motion-delay-time>No motion delay time<a href=#no-motion-delay-time class=anchor aria-hidden=true>#</a></h5><p>When the heuristic failed, due to not enough pixels changed or not x detections in a row, the heuristic will idle for some time.</p><h2 id=output>Output<a href=#output class=anchor aria-hidden=true>#</a></h2><p>If the heuristic determined that the evaluation was valid, one or more output operations can be executed. You configure which ooutput operations that will be executed, by modifying the configuration file or using the web interface.</p><pre><code class=language-xml><?xml version="1.0"?>
|
|
<kerberos>
|
|
<instance>
|
|
...
|
|
<io file="io.xml" type="multiple">Video</io>
|
|
...
|
|
</instance>
|
|
</kerberos>
|
|
</code></pre><p>You can choose which output devices you will be using. If you select multiple outputs, seperate them with an <code>,</code>. You can change the output device by changing the <code>config/config.xml</code> file, and choose one of the following:</p><ul><li>Disk</li><li>Video</li><li>GPIO</li><li>TCPSocket</li><li>Webhook</li><li>MQTT</li><li>Script</li></ul><h3 id=disk>Disk<a href=#disk class=anchor aria-hidden=true>#</a></h3><p>An image can be saved to disk.</p><h4 id=parameters-9>Parameters<a href=#parameters-9 class=anchor aria-hidden=true>#</a></h4><p>The parameters of the Disk output device can be found in the <code>config/io.xml</code> file, but you can also use the web to modify the parameters. Below you see a default configuration file.</p><pre><code class=language-xml><ios>
|
|
<Disk>
|
|
<fileFormat type="text">timestamp_microseconds_instanceName_regionCoordinates_numberOfChanges_token.jpg</fileFormat>
|
|
<directory type="text">/etc/opt/kerberosio/capture/</directory>
|
|
<markWithTimestamp type="bool">false</markWithTimestamp>
|
|
<timestampColor type="text">white</timestampColor>
|
|
<privacy type="bool">false</privacy>
|
|
<throttler type="number">0</throttler>
|
|
</Disk>
|
|
</ios>
|
|
</code></pre><h5 id=file-format>File format<a href=#file-format class=anchor aria-hidden=true>#</a></h5><p>The format that will be used for the name of the image. One or more variables can be defined and will be replaced by the machinery. Note that when you’re using a variables name in the file format, that this name should be defined in the JSON object.</p><h5 id=directory>Directory<a href=#directory class=anchor aria-hidden=true>#</a></h5><p>The directory where the image will be saved to. By default images are saved to the /etc/opt/kerberosio/capture directory.</p><h5 id=mark-with-timestamp>Mark with timestamp<a href=#mark-with-timestamp class=anchor aria-hidden=true>#</a></h5><p>When this settings is set to true, the image is marked with a timestamp.</p><h5 id=timestamp-color>Timestamp color<a href=#timestamp-color class=anchor aria-hidden=true>#</a></h5><p>A color can be defined for timestamp: white, black, red, green and blue.</p><h5 id=privacy>Privacy<a href=#privacy class=anchor aria-hidden=true>#</a></h5><p>The privacy mode can be activated to remove some parts from the image. This especially helpful if you want to filter out public areas. When this option is enabled you will seee that after configuring the Hull expositor, you’ll see that the pixels outside your region of interest (Hull) are made black.</p><h5 id=throttler>Throttler<a href=#throttler class=anchor aria-hidden=true>#</a></h5><p>Control the number of executions by setting a throttling value. E.g. if you set throttling to 5, the Disk will only be triggered once in 5 seconds, nevertheless more detections occurred.</p><h3 id=video>Video<a href=#video class=anchor aria-hidden=true>#</a></h3><p>When a valid event is detected, a video will be recorded for x seconds. When more valid events are detected, while a video is recording, the video file will further record for x seconds; so no new video file be recorded, but the existing one will be expanded.</p><h4 id=parameters-10>Parameters<a href=#parameters-10 class=anchor aria-hidden=true>#</a></h4><p>The parameters of the Video output device can be found in the <code>config/io.xml</code> file, but you can also use the web to modify the parameters. Below you see a default configuration file.</p><pre><code class=language-xml><ios>
|
|
<Video>
|
|
<fps type="number">3</fps>
|
|
<recordAfter type="number">5</recordAfter>
|
|
<maxDuration type="number">120</maxDuration>
|
|
<extension type="number">mp4</extension>
|
|
<codec type="number">h264</codec>
|
|
<fileFormat type="text">timestamp_microseconds_instanceName_regionCoordinates_numberOfChanges_token</fileFormat>
|
|
<directory type="text">/etc/opt/kerberosio/capture/</directory>
|
|
<hardwareDirectory type="text">/etc/opt/kerberosio/h264/</hardwareDirectory>
|
|
<enableHardwareEncoding type="bool">true</enableHardwareEncoding>
|
|
<markWithTimestamp type="bool">false</markWithTimestamp>
|
|
<timestampColor type="text">white</timestampColor>
|
|
<privacy type="bool">false</privacy>
|
|
<throttler type="number">0</throttler>
|
|
</Video>
|
|
</ios>
|
|
</code></pre><h5 id=fps>FPS<a href=#fps class=anchor aria-hidden=true>#</a></h5><p>The frames per second of the video being recorded. Please note that this number is limited and depends heavily on your hardware setup. You’ll be receiving following warning in the systems logs, if the machinery can’t write the desired FPS.</p><pre><code class=language-text>[trivial] IoVideo: framerate is too fast, can't record video at this speed (8/FPS)
|
|
</code></pre><h5 id=record-after>Record after<a href=#record-after class=anchor aria-hidden=true>#</a></h5><p>The number of seconds recorded after the last valid event was detected. This means that when a video is already recording, and a valid event was detected, the video will be expanded with x more seconds.</p><h5 id=extensions>Extensions<a href=#extensions class=anchor aria-hidden=true>#</a></h5><p>The extension or container of the video file. We highly recommend to use the MP4 container if you want cross-browser support. Leave this setting by default, if you don’t know what you’re doing.</p><h5 id=codec>Codec<a href=#codec class=anchor aria-hidden=true>#</a></h5><p>The codec that is used to encode the video file.</p><h5 id=file-format-1>File format<a href=#file-format-1 class=anchor aria-hidden=true>#</a></h5><p>The format that will be used for the name of the image. One or more variables can be defined and will be replaced by the machinery. Note that when you’re using a variables name in the file format, that this name should be defined in the JSON object.</p><h5 id=directory-1>Directory<a href=#directory-1 class=anchor aria-hidden=true>#</a></h5><p>The directory where the videos will be saved. By default videos are saved to the /etc/opt/kerberosio/capture directory.</p><h5 id=hardware-directory>Hardware directory<a href=#hardware-directory class=anchor aria-hidden=true>#</a></h5><p>When using onboard hardware encoding (e.g. with Raspberry Pi camera), h264 video files are generated and stored in this directory. Afterwards these h264 files will be containerized to mp4 files, and stored in the Directory path.</p><h5 id=enable-hardware-encoding>Enable Hardware encoding<a href=#enable-hardware-encoding class=anchor aria-hidden=true>#</a></h5><p>A boolean which can enable or disable hardware encoding. Please note that this option is enabled by default, but does not mean that it will work if you choose to use an USB camera.</p><h5 id=mark-with-timestamp-1>Mark with timestamp<a href=#mark-with-timestamp-1 class=anchor aria-hidden=true>#</a></h5><p>When this settings is set to true, the video is marked with a timestamp (similar to the Disk device).</p><h5 id=timestamp-color-1>Timestamp color<a href=#timestamp-color-1 class=anchor aria-hidden=true>#</a></h5><p>A color can be defined for timestamp: white, black, red, green and blue.</p><h5 id=privacy-1>Privacy<a href=#privacy-1 class=anchor aria-hidden=true>#</a></h5><p>The privacy mode can be activated to remove some parts from the video. This especially helpful if you want to filter out public areas.</p><h5 id=video-privacy>Video privacy<a href=#video-privacy class=anchor aria-hidden=true>#</a></h5><p>After updating the configuration, you’ll see that the pixels outside your region of interest (ROI) are made black; the image below illustrates this.</p><h5 id=throttler-1>Throttler<a href=#throttler-1 class=anchor aria-hidden=true>#</a></h5><p>Control the number of executions by setting a throttling value. E.g. if you set throttling to 5, the Video will only be triggered once in 5 seconds, nevertheless more detections occurred.</p><h3 id=tcpip-client>TCP/IP client<a href=#tcpip-client class=anchor aria-hidden=true>#</a></h3><p>The TCP/IP client will send a TCP packet to a server.</p><h4 id=parameters-11>Parameters<a href=#parameters-11 class=anchor aria-hidden=true>#</a></h4><p>The parameters of the TCP/IP client can be found in the config/io.xml file, but you can also use the web to modify the parameters. Below you see a default configuration file.</p><pre><code class=language-xml><ios>
|
|
<TCPSocket>
|
|
<server type="number">127.0.0.1</server>
|
|
<port type="number">1337</port>
|
|
<message type="text">it's so fluffy</message>
|
|
<throttler type="number">0</throttler>
|
|
</TCPSocket>
|
|
</ios>
|
|
</code></pre><h5 id=server>Server<a href=#server class=anchor aria-hidden=true>#</a></h5><p>The IP of the TCP server.</p><h5 id=port>Port<a href=#port class=anchor aria-hidden=true>#</a></h5><p>This is the port of the TCP server.</p><h5 id=message>Message<a href=#message class=anchor aria-hidden=true>#</a></h5><p>You can send some data to a TCP server.</p><h5 id=throttler-2>Throttler<a href=#throttler-2 class=anchor aria-hidden=true>#</a></h5><p>Control the number of executions by setting a throttling value. E.g. if you set throttling to 5, the TCP will only be triggered once in 5 seconds, nevertheless more detections occurred.</p><h3 id=gpio>GPIO<a href=#gpio class=anchor aria-hidden=true>#</a></h3><p>A GPIO pin can be set as output device.</p><h4 id=parameters-12>Parameters<a href=#parameters-12 class=anchor aria-hidden=true>#</a></h4><p>The parameters of the GPIO pin can be found in the <code>config/io.xml</code> file, but you can also use the web to modify the parameters. Below you see a default configuration file.</p><pre><code class=language-xml><ios>
|
|
<GPIO>
|
|
<pin type="number">17</pin>
|
|
<periods type="number">5</periods>
|
|
<periodTime type="number">100000</periodTime>
|
|
<throttler type="number">0</throttler>
|
|
</GPIO>
|
|
</ios>
|
|
</code></pre><h5 id=pin>Pin<a href=#pin class=anchor aria-hidden=true>#</a></h5><p>The pin that will be triggered.</p><h5 id=periods>Periods<a href=#periods class=anchor aria-hidden=true>#</a></h5><p>The number of times the pin will be triggered.</p><h5 id=period-time>Period time<a href=#period-time class=anchor aria-hidden=true>#</a></h5><p>The time in microseconds that the pin will be set high.</p><h5 id=throttler-3>Throttler<a href=#throttler-3 class=anchor aria-hidden=true>#</a></h5><p>Control the number of executions by setting a throttling value. E.g. if you set throttling to 5, the GPIO will only be triggered once in 5 seconds, nevertheless more detections occurred.</p><h3 id=webhook>Webhook<a href=#webhook class=anchor aria-hidden=true>#</a></h3><p>Detailed information (a JSON object) is send as a POST request to a webhook. The JSON object contains the number of changes, the region, the URL of the image, etc. This is useful if you want to integrate with your own application.</p><p>Make sure that the Webhook comes after the Disk device, otherwise the URL of the image is not included.</p><h4 id=parameters-13>Parameters<a href=#parameters-13 class=anchor aria-hidden=true>#</a></h4><p>The parameters of the webhook can be found in the config/io.xml file, but you can also use the web to modify the parameters. Below you see a default configuration file.</p><pre><code class=language-xml><ios>
|
|
<Webhook>
|
|
<url type="text">http://kerberos.web/api/v1/webhook</url>
|
|
<throttler type="number">0</throttler>
|
|
</Webhook>
|
|
</ios>
|
|
</code></pre><h5 id=url-1>Url<a href=#url-1 class=anchor aria-hidden=true>#</a></h5><p>This is the URL, to which the machinery will send a JSON object (as a POST request).</p><h5 id=throttler-4>Throttler<a href=#throttler-4 class=anchor aria-hidden=true>#</a></h5><p>Control the number of executions by setting a throttling value. E.g. if you set throttling to 5, the Webhook will only be triggered once in 5 seconds, nevertheless more detections occurred.</p><h5 id=output-1>Output<a href=#output-1 class=anchor aria-hidden=true>#</a></h5><p>A JSON object is POSTed to the url you’ve defined.</p><pre><code class=language-json>[
|
|
'regionCoordinates' : [618, 317, 703, 493],
|
|
'numberOfChanges' : 5446,
|
|
'timestamp' : '1465894497',
|
|
'microseconds' : '5-97451',
|
|
'token' : 695,
|
|
'pathToImage' : '1465894497_5-97451_frontdoor_618-317-703-493_5446_695.jpg',
|
|
'instanceName' : 'frontdoor',
|
|
]
|
|
</code></pre><h3 id=script>Script<a href=#script class=anchor aria-hidden=true>#</a></h3><p>A bash script can be executed after a valid event was detected. A JSON object is send in the first parameter to the script you’ve defined.</p><h4 id=parameters-14>Parameters<a href=#parameters-14 class=anchor aria-hidden=true>#</a></h4><p>The parameters of the Script output device can be found in the config/io.xml file, but you can also use the web to modify the parameters. Below you see a default configuration file.</p><pre><code class=language-xml><ios>
|
|
<Script>
|
|
<path type="text">/etc/opt/kerberosio/scripts/run.sh</path>
|
|
<throttler type="number">0</throttler>
|
|
</Script>
|
|
</ios>
|
|
</code></pre><h5 id=path>Path<a href=#path class=anchor aria-hidden=true>#</a></h5><p>The location of the script that will be executed on detection.</p><h5 id=throttler-5>Throttler<a href=#throttler-5 class=anchor aria-hidden=true>#</a></h5><p>Control the number of executions by setting a throttling value. E.g. if you set throttling to 5, the Script will only be triggered once in 5 seconds, nevertheless more detections occurred.</p><h5 id=example>Example<a href=#example class=anchor aria-hidden=true>#</a></h5><p>By default the script will point to /etc/opt/kerberosio/scripts/run.sh, which contains a template how you should start your script. Note that when using KiOS, this script will be read-only, copy it to the /data folder and change the path parameter.</p><pre><code class=language-python>#!/bin/bash
|
|
# -------------------------------------------
|
|
# This is an example script which illustrates
|
|
# how to use the Script IO device.
|
|
#
|
|
# --------------------------------------
|
|
# The first parameter is the JSON object
|
|
#
|
|
# e.g. {"regionCoordinates":[308,250,346,329],"numberOfChanges":194,"timestamp":"1486049622","microseconds":"6-161868","token":344,"pathToImage":"1486049622_6-161868_frontdoor_308-250-346-329_194_344.jpg","instanceName":"frontdoor"}
|
|
JSON=$1
|
|
# -------------------------------------------
|
|
# You can use python to parse the JSON object
|
|
# and get the required fields
|
|
name=$(echo $JSON | python -c "import sys, json; print json.load(sys.stdin)['instanceName']")
|
|
coordinates=$(echo $JSON | python -c "import sys, json; print json.load(sys.stdin)['regionCoordinates']")
|
|
changes=$(echo $JSON | pythfon -c "import sys, json; print json.load(sys.stdin)['numberOfChanges']")
|
|
image=$(echo $JSON | python -c "import sys, json; print json.load(sys.stdin)['pathToImage']")
|
|
The idea is that you can use Python in your bash script, to parse the JSON object send as first parameter. Afterwards you can do with the output what you want.
|
|
</code></pre><h3 id=mqtt>MQTT<a href=#mqtt class=anchor aria-hidden=true>#</a></h3><p>MQTT protocol is a light-weight Machine to Machine (M2M) protocol widely used in Internet of things.
|
|
Detailed information (a JSON object) is published to an MQTT topic. The JSON object contains the number of changes, the region, the URL of the image, etc.</p><h4 id=parameters-15>Parameters<a href=#parameters-15 class=anchor aria-hidden=true>#</a></h4><p>The parameters of the MQTT output can be found in the config/io.xml file, but you can also use the web to modify the parameters. Below you see a default configuration file.</p><pre><code class=language-xml><ios
|
|
<MQTT>
|
|
<secure type="bool">false</secure>
|
|
<verifycn type="bool">false</verifycn>
|
|
<server type="number">127.0.0.1</server>
|
|
<port type="number">1883</port>
|
|
<topic type="text">kios/mqtt</topic>
|
|
<username type="text"></username>
|
|
<password type="text"></password>
|
|
<throttler type="number">0</throttler>
|
|
</MQTT>
|
|
</ios>
|
|
</code></pre><h5 id=secure>Secure<a href=#secure class=anchor aria-hidden=true>#</a></h5><p>If checked, enable SSL/TLS support. Please note that when SSL/TLS support is enabled, the server certificate issuer is verified against the CA (Certification Authority) files available in /etc/ssl/certs.</p><h5 id=verifycn>Verifycn<a href=#verifycn class=anchor aria-hidden=true>#</a></h5><p>If checked, the MQTT server FQDN or ip address must match the CN (Common Name) of the server certificate.</p><h5 id=server-1>Server<a href=#server-1 class=anchor aria-hidden=true>#</a></h5><p>IP address or FQDN of the MQTT broker.</p><h5 id=port-1>Port<a href=#port-1 class=anchor aria-hidden=true>#</a></h5><p>TCP port of the MQTT broker.</p><h5 id=topic>Topic<a href=#topic class=anchor aria-hidden=true>#</a></h5><p>The topic to publish to.</p><h5 id=username>Username<a href=#username class=anchor aria-hidden=true>#</a></h5><p>The username for authenticating to the MQTT broker. This is only supported by brokers that implement the MQTT spec v3.1. If username is not set (empty), the password argument is ignored. This is only needed if the MQTT broker is configured for authentication.</p><h5 id=password>Password<a href=#password class=anchor aria-hidden=true>#</a></h5><p>The password to use, together with the username, for authenticating to the MQTT broker. This is only supported by brokers that implement the MQTT spec v3.1. This is only needed if the MQTT broker is configured for authentication.</p><h5 id=throttler-6>Throttler<a href=#throttler-6 class=anchor aria-hidden=true>#</a></h5><p>Control the number of executions by setting a throttling value. E.g. if you set throttling to 5, the MQTT will only be triggered once in 5 seconds, nevertheless more detections occurred.</p><h5 id=output-2>Output<a href=#output-2 class=anchor aria-hidden=true>#</a></h5><p>A JSON object is published to the topic of the MQTT broker you have configured.</p><pre><code class=language-json>[
|
|
'regionCoordinates' : [618, 317, 703, 493],
|
|
'numberOfChanges' : 5446,
|
|
'timestamp' : '1465894497',
|
|
'microseconds' : '5-97451',
|
|
'token' : 695,
|
|
'pathToImage' : '1465894497_5-97451_frontdoor_618-317-703-493_5446_695.jpg',
|
|
'instanceName' : 'frontdoor',
|
|
]
|
|
</code></pre><h5 id=example-1>Example<a href=#example-1 class=anchor aria-hidden=true>#</a></h5><p>It is possible to subscribe multiple distributed IoT devices to the same MQTT topic and perform specific actions upon the detection of a motion. Devices with more resources could fetch the image to perform further elaboration.</p><h2 id=streaming>Streaming<a href=#streaming class=anchor aria-hidden=true>#</a></h2><p>The machinery has the ability to stream your capture device as a MJPG stream.</p><h3 id=parameters-16>Parameters<a href=#parameters-16 class=anchor aria-hidden=true>#</a></h3><p>The parameters for the supported streaming protocols can be found in the <code>config/stream.xml</code> file, but you can also use the web to modify the parameters. Below you see a default configuration file; at the moment of writing only a MJPG stream is supported.</p><pre><code class=language-xml><streams>
|
|
<Mjpg>
|
|
<enabled type="bool">true</enabled>
|
|
<streamPort type="number">8889</streamPort>
|
|
<quality type="number">75</quality>
|
|
<username type="number"></username>
|
|
<password type="number">75</password>
|
|
</Mjpg>
|
|
</streams>
|
|
</code></pre><h4 id=enabled-1>Enabled<a href=#enabled-1 class=anchor aria-hidden=true>#</a></h4><p>A boolean which turns ON/OFF the stream. This is interesting when working with IP cameras, where you already have an RTSP/MJPG stream from the camera itself.</p><h4 id=stream-port>Stream Port<a href=#stream-port class=anchor aria-hidden=true>#</a></h4><p>The port on which the stream is available.</p><h4 id=quality>Quality<a href=#quality class=anchor aria-hidden=true>#</a></h4><p>The quality is a value between [0-100]. The lower the quality, the more the image will be compressed. If you’re using the RaspberryPi Camera module, this option will be ignored.</p><h4 id=usernamepassword>Username/password<a href=#usernamepassword class=anchor aria-hidden=true>#</a></h4><p>You can secure the MJPEG streaming with a username and password. These credentials will be used to authorize your requests using Basic Authentication. Please note that once enabled, the live stream on the dashboard page can fail; however it will work if you open it directly in your browser or ip camera client. The format of the streaming url, after authentication enabled, will look as following:</p><pre><code class=language-ts>http://username:password@ip-camera:8899
|
|
</code></pre><p class=edit-page><a href=https://github.com/kerberos-io/documentation/blob/master/content/opensource/machinery/index.md><svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentcolor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-edit-2"><path d="M17 3a2.828 2.828.0 114 4L7.5 20.5 2 22l1.5-5.5L17 3z"/></svg>Edit this page on GitHub</a></p><div class="docs-navigation d-flex justify-content-between"><a href=https://doc.kerberos.io/opensource/contribute/><div class="card my-1"><div class="card-body py-2">← Contribute</div></div></a><a class=ms-auto href=https://doc.kerberos.io/opensource/web/><div class="card my-1"><div class="card-body py-2">Web →</div></div></a></div></main></div></div></div><footer class="footer text-muted"><div class=container><div class=row><div class="col-lg-6 order-last order-lg-first"><ul class="navbar-nav social-nav"><li class=copyright>© 2014–2021
|
|
<a href=https://kerberos.io>Kerberos.io</a></li><li class=nav-item><a class=link href=https://twitter.com/kerberosio title=Twitter><svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentcolor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-twitter"><path d="M23 3a10.9 10.9.0 01-3.14 1.53 4.48 4.48.0 00-7.86 3v1A10.66 10.66.0 013 4s-4 9 5 13a11.64 11.64.0 01-7 2c9 5 20 0 20-11.5a4.5 4.5.0 00-.08-.83A7.72 7.72.0 0023 3z"/></svg><span class="ms-2 visually-hidden">Twitter</span></a></li><li class=nav-item><a class=link href=https://github.com/kerberos-io title=GitHub><svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentcolor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-github"><path d="M9 19c-5 1.5-5-2.5-7-3m14 6v-3.87a3.37 3.37.0 00-.94-2.61c3.14-.35 6.44-1.54 6.44-7A5.44 5.44.0 0020 4.77 5.07 5.07.0 0019.91 1S18.73.65 16 2.48a13.38 13.38.0 00-7 0C6.27.65 5.09 1 5.09 1A5.07 5.07.0 005 4.77 5.44 5.44.0 003.5 8.55c0 5.42 3.3 6.61 6.44 7A3.37 3.37.0 009 18.13V22"/></svg><span class="ms-2 visually-hidden">GitHub</span></a></li><li class=nav-item><a class=link href=https://www.reddit.com/r/kerberos_io/ title=Reddit><svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentcolor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-message-circle"><path d="M21 11.5a8.38 8.38.0 01-.9 3.8A8.5 8.5.0 0112.5 20a8.38 8.38.0 01-3.8-.9L3 21l1.9-5.7A8.38 8.38.0 014 11.5a8.5 8.5.0 014.7-7.6 8.38 8.38.0 013.8-.9h.5a8.48 8.48.0 018 8v.5z"/></svg><span class="ms-2 visually-hidden">Reddit</span></a></li></ul></div><div class="col-lg-10 order-first order-lg-last text-lg-end"><ul class=list-inline><li class=list-inline-item>Learn more about</li><li class=list-inline-item><a href=https://kerberos.io/product/enterprise-agent/>Enterprise Agent</a></li><li class=list-inline-item><a href=https://kerberos.io/product/hub/>Hub</a></li><li class=list-inline-item><a href=https://kerberos.io/product/open-source/>Kerberos Opensource</a></li><li class=list-inline-item><a href=https://kerberos.io/product/vault/>Vault</a></li></ul></div></div></div></footer><script src=https://doc.kerberos.io/js/highlight.min.13bf6b39f28cd07b0780c0c154bf050bad1e7b73231c15e43b993504cca3fa814222ded3c525f429528451fe039a5078c71ae4d000486d26f9b920cc7db474da.js integrity="sha512-E79rOfKM0HsHgMDBVL8FC60ee3MjHBXkO5k1BMyj+oFCIt7TxSX0KVKEUf4DmlB4xxrk0ABIbSb5uSDMfbR02g==" crossorigin=anonymous defer></script><script src=https://doc.kerberos.io/main.min.89223fc6eee34e2dc10266cff3c7fc87949c595388f775ec6e93132410cef77e5ff7f24a81db03c9b9eb6d2e6d75ea5a7d22945c574b65dfeb426f65af771230.js integrity="sha512-iSI/xu7jTi3BAmbP88f8h5ScWVOI93XsbpMTJBDO935f9/JKgdsDybnrbS5tdepafSKUXFdLZd/rQm9lr3cSMA==" crossorigin=anonymous defer></script><script src=https://doc.kerberos.io/index.min.71e05784bf5441c378e8824d18e4b5a057f28cde2bd06f927216eb278586f7ea7d96309df4600474b3b928ef2b635a64248e2cf3a7a023136087ed4050162608.js integrity="sha512-ceBXhL9UQcN46IJNGOS1oFfyjN4r0G+SchbrJ4WG9+p9ljCd9GAEdLO5KO8rY1pkJI4s86egIxNgh+1AUBYmCA==" crossorigin=anonymous defer></script></body></html> |