diff --git a/1_getting_started.md b/1_getting_started.md deleted file mode 100644 index 9305aeb..0000000 --- a/1_getting_started.md +++ /dev/null @@ -1,64 +0,0 @@ -# Getting started - -* [Why Kerberos.io](#why-kerberos-io) -* [What is Kerberos.io](#what-is-kerberos-io) -* [How does it work](#how-does-it-work) -* [Features](#features) -* [Installation](#installation) - - - -## Why Kerberos.io? - -As burglary is very common, we believe that video surveillance is a **trivial tool** in our daily lifes which helps us to **feel** a little bit more **secure**. Responding to this need, a lot of companies have started developing their own video surveillance software in the past few years. - -Nowadays we have a myriad of **expensive** cameras, recorders, and software solutions which are mainly **outdated** and **difficult** to install and use. Kerberos.io's goal is to solve these problems and to provide every human being in this world to have their own **ecological**, **affordable**, **easy-to-use** and **innovative** surveillance solution. Read more about [**our strategy here**](/strategy). - - -## What's Kerberos.io? - -Kerberos.io is a **low-budget** video surveillance solution, that uses computer vision algorithms to detect changes, and that can trigger other devices. Kerberos.io is open source so everyone can customize the source code to its needs and share it with the community under the [**CC-NC-ND license model**](/license). When deployed on the Raspberry Pi or any other board, it has a **green footprint** and it's **easy to install**; you only need to transfer the [**Kerberos.io OS (KIOS)**](/installation/KiOS) to your SD card and that's it. - - - - -## How does it work? - -When installed Kerberos.io on a Raspberry Pi or any other Linux device, two applications are available: the [**machinery**](https://github.com/kerberos-io/machinery) and the [**web**](https://github.com/kerberos-io/web). - -The machinery is responsible for the processing. It's **an image processing framework** which takes images from the type of camera (USB-, IP- or RPi-camera) you've configured in the configuration files and executes one or 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. - -The web is responsible for the visualization. It's a **GUI** which helps the user to find activity at a specific period, configure the machinery, view a live stream, see system information and much more. It's important to note that the machinery can work without the web, however we don't recommend this. - -The cloud is an extra service, which is available by default but is not required. The main goal of this service is **to view your activity from everywhere** in the world. By [**subscribing to a plan**](https://cloud.kerberos.io), you can sync your images to the cloud application. To have a more detailed explanation go to the [**machinery**](/machinery/introduction) and [**web**](/web/introduction) pages. - -![How does it work](1_how_does_it_work.png) - - -## Features - -Kerberos.io comes with **a bunch of features**, below you can find a short list of the most important ones. - - * Full range camera support (**USB**, **Raspberry Pi** v1.3 and v2.1, and **IP cameras** which support a RTSP or MJPEG stream). - * **Hardware encoding** when using the Raspberry Pi Camera. - * Constraints to make detection more intelligent (time interval, regions, etc). - * Ability to save snapshots and **video recording** and execute/trigger a bash script, webhooks or GPIO pin. - * **Live streaming** (MJPEG) on the web or with another program like VLC or IP camera viewer; ability to secure with Basic Authentication. - * **Heatmap** and latest sequence of activity. - * Fluent and **responsive overview** (Smartphone, Tablet and PC) of snapshots by day and hour. - * System information (CPU, disk, network, etc). - * Use [**Kerberos.cloud**](https://cloud.kerberos.io) to view your activity from anywhere in the world. - * **Multiple cameras** with Docker or Raspbian; read more about the [**best practices**](/best_practices). - * **REST API** to control Kerberos.io from your custom solution/program. - * **Cross-browser support**: IE, Chrome, Safari, Firefox. - - -## Installation - -Installing Kerberos.io to your IoT device, has never been so easy. By using our cross-platform installer, you can run a fully configured video surveillance system within 3 minutes. Indeed, we also think that's awesome! - - - - - -By using the KiOS installer, you'll get an easy to use GUI which allows you to configure and **flash KiOS to your SD card**. Just download the installer, select a version, specify your network configurations, select your SD card and press the flash button; **it can't be easier**. If you **don't want to reflash you SD card**, you can run Kerberos.io on your existing [**Raspbian**](/installation/Raspbian) or [**Armbian**](/installation/armbian) installation, or if you like containers you can use [**Docker**](/installation/Docker). diff --git a/1_how_does_it_work.png b/1_how_does_it_work.png deleted file mode 100644 index 9cb8321..0000000 Binary files a/1_how_does_it_work.png and /dev/null differ diff --git a/2_strategy.md b/2_strategy.md deleted file mode 100644 index 80f82bc..0000000 --- a/2_strategy.md +++ /dev/null @@ -1,42 +0,0 @@ -# Strategy - -In this section we'll explain the strategy of Kerberos.io in terms of goals, design/architecture and user experience. - -## Mission - -As you may have read on the [**Getting started**](/getting_started) page, Kerbers.io's goal is to be an easy to use video surveillance system which works on almost **every system/device**, with almost **every camera**, and that in just a few minutes. - -Before Kerberos.io was designed or we even thought about it, we've found a lot of different surveillance solutions available in the market, of which **most of them are commercialized**. The free surveillance solutions, were mostly outdated and weren't synced with the bleeding edge technologies that we see nowadays. - -We at Kerberos.io want to do something about it. Creating a video surveillance solution with bleeding edge technologies, available for everyone in this world, is our mission. With Kerberos.io we even want to **challenge commercial surveillance solutions**, by showing them how powerful an open source community is. - -You only live once (YOLO), and therefore we want to give this world, with all the people living on it, something to **protect itself against all the bad things** strolling in our streets. We want to protect your families, properties and the things you care for. We **are a team** of hobbiest, professionals and people that want to move forward. - -## Architecture - -Here you'll find the thoughts we had, and still have, while developing and architecturing Kerberos.io. These are the results of what Kerberos.io nowadays is. - - -### The one vs multi camera support discussion - -The most common question we get is the following: - -*I want to connect multiple cameras to Kerberos.io is it possible?* - -The answer that we give is: - -*Yes, it's possible because a lot of people asked for it, but we don't recommend it at all.* - -So this might be a strange answer, but why don't we recommend it? The core idea of Kerberos.io is that it's easy to use, isolated and developed with clean code. We at Kerberos.io don't believe that a surveillance system which can configure **N** cameras is or can be intuitive for an end user, in terms of visualization and configuration. Besides user experience this will also **face its technical limitations when scaling** the solution with a lot of cameras; this can cause weird, unexpected and hard to debug deviations. - -Kerberos.io **embraces the concept of isolation**. Every camera should have its own isolated environment, so a processing unit (server, Raspberry Pi, Docker container, etc) per camera. By using this concept you have **the benefit of spreading risk**: if one processing unit goes down, the other ones stay operational. We think the best way to manage your cameras is to have **the ability to pin point** them, and **replace** them **without affecting any other** cameras. - -On the other hand we **don't see a lot of benefits** (others than saving some money) **in practice** for connecting multiple cameras to a single processing unit. For example if you would be using USB cameras, it would be **rare to use them at exactly the same place**. When you're in this situation you probably need to pick a better place or position to install the camera and its processing unit. When running a lot of IP cameras, **running a Raspberry Pi** or other board, **for every single IP camera is overkill**, in this situation we strongly recommend to deploy Docker containers, so they are still virtually seperated processing units. Using **a single machine**, Raspberry Pi or other board **to manage all your IP cameras** without seperate virtual processing units (Docker) **is against the concept of isolation**. - -This is **our vision about one vs multi camera support**, however we are aware that situations might exist where multi camera support is the best option, and that's also the reason why we've made it possible. You can use the Armbian, Raspbian or Docker installation to make this possible. For more information when to use which scenario, read the [**best practices**](/best_practices) page. - -### Security - -Security is Kerberos.io's number 1. When installing Kerberos.io, we **don't force** the system or user **to expose ports**. The idea is that Kerberos.io is used and **managed within a local network**, and **doesn't need internet access** to work properly. However a user can, at own risk, decide to make Kerberos.io public by enabling port forwarding on the router, so he or she is able to view the media remotely; a better option would be to setup a VPN tunnel, so the information is encrypted. - -When you want to access your media online, we strongly [**recommend to use Kerberos.cloud**](https://cloud.kerberos.io) for making it public. With Kerberos.cloud we encrypt all your data and only make it available for a short period (minutes). Read more [**about Kerberos.cloud here**](/addons/Cloud). \ No newline at end of file diff --git a/3_cameras.png b/3_cameras.png deleted file mode 100644 index 2921da7..0000000 Binary files a/3_cameras.png and /dev/null differ diff --git a/3_machines.png b/3_machines.png deleted file mode 100644 index b2fec3e..0000000 Binary files a/3_machines.png and /dev/null differ diff --git a/3_requirements.md b/3_requirements.md deleted file mode 100644 index c6bf894..0000000 --- a/3_requirements.md +++ /dev/null @@ -1,24 +0,0 @@ -# Requirements - -## Which type of machines can you use? - -Kerberos.io runs on every Linux based machine but its main goal is to run on a Raspberry Pi or other boards due to its low energy consumption. We provide multiple ways (KIOS, Raspbian, Armbian, Docker, etc) to install Kerberos.io on the device your prefer. If you will install Kerberos.io with Docker, or on your local Linux machine, nothing special should be purchased except a video camera. - -![Machines](3_machines.png) - -### Raspberry Pi - -We recommend to run Kerberos.io on a **Raspberry Pi**, as it is a very popluar microcontroller which can you buy in almost every (online) electronic shop. To simplify the lives of our Raspberry Pi users, Kerberos.io comes with a custom ARM OS called [**KIOS**](installation/KiOS) (Kerberos.io Operating System), which you can deploy to your Raspberry Pi in just a few minutes. Kerberos.io supports **all Raspberry Pi versions**: 1, 2, 3 and Zero (W). - -### What about other boards? - -Kerberos.io can also be installed on other boards by following the [**Armbian**](/installation/armbian) installation. At the moment of writing we don't have support for KiOS, so the installation is a little bit harder. This is a short list of microcontrollers on which we have tested Kerberos.io using the Armbian OS: - - * PCDuino3 Nano (Allwinner A20) - * Orange Pi + (Allwinner H3) - -## Which type of camera can you use? - -Kerberos.io works with the full range of camera's. You can use an **USB-**, **IP-** or the **Raspberry Pi camera (v1.3 and v2.1)**. When using the Raspberry Pi camera, you'll benefit from its **hardware encoding** which makes it possible to record video at 30 FPS on a Raspbery Pi Zero. If you want to use an IP camera, we recommend to use the RTSP connection if available; note that it's possible that cheap IP cameras will not work properly. USB camera's that need special drivers will probably **NOT work**. - -![Cameras](3_cameras.png) diff --git a/4_best_practices.md b/4_best_practices.md deleted file mode 100644 index b1dada5..0000000 --- a/4_best_practices.md +++ /dev/null @@ -1,52 +0,0 @@ -# Best practices - -Kerberos.io can be **used for many different purposes**: nanny cam, baby monitor, site monitor, parking monitor, pet monitor, vacation monitor, people counting, real-time monitoring, recording, and the list goes on. Kerberos.io also gives you **a lot of possible ways to install it** on the devices your prefer. You can install it on your local Linux system e.g. Ubuntu, Raspbian, Armbian, Docker and by using our own OS, named KiOS. - -Having all these different scenarios, ways to install and possible combinations, **it might be hard to find the best setup** for your specific situation. On this page we will discuss a couple of scenarios, and which solution/setup is the best pratice/match for each one of them. - -One of the strategies Kerberos.io follows is **the concept of isolation**. Read more about it on the [**strategy page**](/strategy) and the [**one vs multi camera support**](/strategy#one-vs-multi) discussion for a complete understanding of the best practices. - -## IP cameras - -This is the most common scenario. Nowadays if you want to buy a camera, there is a 90% chance that it will be an IP camera. - -IP cameras have outnumbered the video camera industry, they come with many different flavours and technologies (e.g. ONVIF). Typically a user will **buy one or more IP cameras**, **position them** at various places at home or work, and **install a video surveillance system** to manage them; e.g. Kerberos.io. - -### Desire - -What we often see is that users ask for, or desire to have, one single application where they can access and manage all their different IP cameras. This desire may look obvious at first sight, but has **limitations on the long run**. - -Many video surveillance solutions, other than Kerberos.io, uses the approach previously described. However this approach is against the Kerberos.io strategy/philosophy, read more about it on the [**strategy page**](/strategy) and the [**one vs multi camera support**](/strategy#one-vs-multi) discussion. - -### Best practice - -When you have an enterprise environment, or just have a lot of IP cameras (>2), you [**should consider to use Docker**](/installation/Multi-camera/Docker). When using **Kerberos.io with Docker**, you create an individual virtual processing units, **a Docker container**, for each camera. - -By using this approach the management of your cameras is transparant and you have the ability to pin point them by an IP address (or port). Next to that you will have **a highly scalable solution**, when new cameras are installed you create new containers for each camera. When processing a lot of cameras you can eventually use **Docker swarm** to load balance containers over multiple systems. - -### Dont's - -What we often see is that users want to use a single Raspberry Pi or other board, to manage multiple IP cameras. Though this is possible with the Raspbian or Armbian installation, we don't recommend this when processing a lot of IP cameras (>2), due to: - -* limited resources (CPU and RAM), -* visualization and configuration in the web interface is not intuitive, -* and unreliably for network drops. - -When using only one or two IP cameras you can consider to use a multi camera approach with Raspbian or Armbian. In this case a Docker setup can be overkill. - -## Local cameras (e.g. USB camera) - -One of the goals of Kerberos.io is to be a cheap and ecologic video surveillance solution. With Kerberos.io you can **reuse your old USB cameras**, and combine them with a board (Raspberry Pi or other) to use them as a professional surveillance system. - -### Desire - -Just the like the IP camera scenario, users want to have a single application where they can manage all their cameras. The same philosophy applies here, Kerberos.io recommends the concept of **isolation**. Though with USB cameras it might be more useful to connect multiple cameras as they require a machine or board to process them; the processing unit needs to be at the same place of the camera. You **don't have the possibility to use Docker** when using USB cameras. - -### Best practice - -If you consider to connect multiple local cameras to a processing unit (server, Raspberry Pi or other board), you should take into account following points: - -* Did you positioned your cameras properly? -* Has the second (or other) camera a lot of value? Maybe can you give it a better position somewhere else. - -In some cases a second or third camera can be of a lot of value e.g. a 360° view, but most of the time this is totally overkill and you should better use it elsewhere. diff --git a/5_release_notes.md b/5_release_notes.md deleted file mode 100644 index fcd8905..0000000 --- a/5_release_notes.md +++ /dev/null @@ -1,355 +0,0 @@ -# Release notes - -* [2.7.2](#2-7-2) -* [2.7.1](#2-7-1) -* [2.7.0](#2-7-0) -* [2.6.1](#2-6-1) -* [2.6.0](#2-6-0) -* [2.5.0](#2-5-0) -* [2.4.2](#2-4-2) -* [2.4.1](#2-4-1) -* [2.4.0](#2-4-0) -* [2.3.1](#2-3-1) -* [2.3.0](#2-3-0) -* [2.2.1](#2-2-1) -* [2.2.0](#2-2-0) -* [2.1.0](#2-1-0) -* [2.0.0](#2-0-0) -* [1.1.0](#1-1-0) -* [1.0.3](#1-0-3) -* [1.0.2](#1-0-2) -* [1.0.1](#1-0-1) -* [1.0.0](#1-0-0) - - -## 2.7.2 - -#### Machinery - -* To optimise the cloud experience we've added a proxy.kerberos.io machine in between. -* We've changed the S3 storage scheme (class:ONEZONE_IA). - - -## 2.7.1 - -#### Machinery - -* Resolved deadlock with livestreaming while restarting machinery. -* Revert logging library; enabled log rotating. - -#### KiOS - -* Updated firmware to latest Raspbian (raspberrypi-kernel_1.20180417-1). -* Resolved issue with WIFI on Raspberry Pi 3B+ - - -## 2.7.0 - -#### Web - -* Unique session cookie, which allows to open multiple web interfaces (e.g. when using docker). - -#### Machinery - -* Added live streaming feature for app.kerberos.io -* Upgraded logging library: log file can be max 5MB, and will rotate. -* Better logging for cloud uploads (failed information). - -#### Docker - -* No longer need docker-compose, we merged the web and machinery containers to [a single container](http://hub.docker.com/r/kerberos/kerberos). - -#### KiOS - -* Updated firmware to latest Raspbian. -* Support for the Raspberry Pi 3B+. - - -## 2.6.1 - -#### Web - -* Solved issue with persisting login configuration. [#111](https://github.com/kerberos-io/web/issues/111) - -#### Machinery - -* Added Pushbullet. [#139](https://github.com/kerberos-io/machinery/pull/139) -* Cloud upload was not longer working (hotfix also in 2.6.0). - - -## 2.6.0 - -#### Web - -* Add a cloud connection verification method. [#112](https://github.com/kerberos-io/web/issues/112) - -#### Machinery - -* Add background color timestamp. [#128](https://github.com/kerberos-io/machinery/issues/128) -* Send instanceId in AWS header when uploading to cloud (necessary for new cloud app). -* Better support for Chinese IP cameras. - -#### Docker - -* Bug: Autoremove old images/video within Docker Containers. [#104](https://github.com/kerberos-io/web/issues/104) - - -## 2.5.0 - -#### Web - -* Added Chinese and Italian language. -* Resolved issue with INSTALLED=true. -* Make latest_sequence available with basic auth. [#99](https://github.com/kerberos-io/web/issues/99) - -#### Machinery - -* Provide an IO service for publishing events to MQTT. [#89](https://github.com/kerberos-io/machinery/issues/89) -* Optimize recording with H264_OMX. [#83](https://github.com/kerberos-io/machinery/issues/83) -* Implement throttler for Io detections. [#96](https://github.com/kerberos-io/machinery/issues/96) -* SSL version 1.0.0 is no longer accessible in Raspbian. [#109](https://github.com/kerberos-io/machinery/issues/109) - - -## 2.4.2 - -#### Web - -* Typo in french translation, causes the web interface crash. - -#### Machinery - -* Resolved major bug in livestream: memory leak in stream class. [#94](https://github.com/kerberos-io/machinery/issues/94) -* Capture health verification: check if the chosen capture device is still grabbing (and didn't stalled). -* Extra logging when recording with raspberry pi camera. -* Make sure the cloud upload is functioning properly, after an upload it's verified if the files really exist in the cloud. - - -## 2.4.1 - -#### Web - -* Show warning when system is disabled. [#88](https://github.com/kerberos-io/web/issues/88). -* Hull selector in basic view not always working. - - -## 2.4.0 - -#### Ecosystem - -* Enable/Disable force network mode. -* Enable/Disable auto removal media. - -#### Web - -* Upgrade from Laravel 4.2 to Laravel 5.4 [#70](https://github.com/kerberos-io/web/issues/70). -* Fix bug with heatmap radius slider [#84](https://github.com/kerberos-io/web/issues/84). -* Design tweaks toggle button (remove outline). -* Disabled possibility to timestamp video when using hardware acceleration. - -#### Docker - -* Fix SSL support [#4](https://github.com/kerberos-io/docker/issues/4). -* Auto removal if disk is full. - -#### Machinery - -* OpenMAX IL hardware encoding for Raspberry Pi camera. [#83](https://github.com/kerberos-io/machinery/issues/83) - * Optimized live streaming. - * Optimized h264 recording. -* Basic authentication for live streaming (username and password). [#80](https://github.com/kerberos-io/machinery/issues/80) - - -## 2.3.1 - -#### Machinery - -* Update for kerberos.cloud: pushing content-type. -* Change default configurations. - - -## 2.3.0 - -#### Ecosystem - -* Support for Raspberry Pi Zero W. [#8](https://github.com/kerberos-io/kios/issues/8) - - -## 2.2.1 - -#### Ecosystem - -* Upgraded FFmpeg and libx264 on KiOS. - -#### Web - -* Add Bulgarian translation. [#81](https://github.com/kerberos-io/web/pull/81) - -#### Machinery - -* Bug: IoVideo crashes due to a memory leak. [#70](https://github.com/kerberos-io/machinery/issues/70) - - -## 2.2.0 - -#### Ecosystem - -* Added support for Armbian. -* Raspbian: Async requests causes session corruption. [#78](https://github.com/kerberos-io/web/issues/78) - -#### Web - -* Bug: Issue format instance name. [#57](https://github.com/kerberos-io/web/issues/57) -* Redesign settings page (better UX). [#39](https://github.com/kerberos-io/web/issues/39) -* Possibility to edit password through web interface. [#63](https://github.com/kerberos-io/web/issues/63) -* Support for viewing videos. -* Update radius of heatmap. -* PHP7 support. [#60](https://github.com/kerberos-io/web/issues/60) -* Welcome/installation page. [#60](https://github.com/kerberos-io/web/issues/60) -* Translation updated. [#74](https://github.com/kerberos-io/web/issues/74) -* Privacy mode. [#54](https://github.com/kerberos-io/web/issues/54) - -#### Machinery - -* Output as video file. [#60](https://github.com/kerberos-io/machinery/issues/60) -* Bug: System hangs when a wrong IP camera url was defined. [#48](https://github.com/kerberos-io/machinery/issues/48) -* Run arbitrary script/program. [#31](https://github.com/kerberos-io/machinery/issues/31) -* Bug: Weird colors from RPi Camera. [#64](https://github.com/kerberos-io/machinery/issues/64) -* Upgrade to OpenCV 3.2.0. - - -## 2.1.0 - -#### Web - -* Added PhotoSwipe for image overview (easier to browse through images). [#45](https://github.com/kerberos-io/web/issues/45) -* Added reboot and shutdown commands. [#46](https://github.com/kerberos-io/web/issues/46) -* Added logging view to system page. [#33](https://github.com/kerberos-io/web/issues/33) -* Added labels to check if machinery is running. -* Added error handling if web interface isn’t working properly. -* Fixed Heatmap.js fail to load by ad-blocker. [#42](https://github.com/kerberos-io/web/issues/42) -* Show additional information on the dashboard (streaming is opening or not) there is no data available. -* Settings page is now visible on mobile (+ changed icon). -* Fixed sorting of news articles. -* Removed links to assets in the cloud (.css files). -* Design: improved layout of login page, async loading of image view. - -#### Machinery - -* Added configurable streaming port and quality. [#41](https://github.com/kerberos-io/machinery/issues/41) -* Added new algorithm: Background subtraction. -* Added new heuristic: Counter (for object/people counting). [#42](https://github.com/kerberos-io/machinery/issues/42) -* Added video capture, which can be used for debugging purposes (replay a video fragment). -* It’s now possible to mark the images with a timestamp. [#36](https://github.com/kerberos-io/machinery/issues/36) -* Fixed blocking streaming socket. [#39](https://github.com/kerberos-io/machinery/issues/39) - -#### Ecosystem - -* Fix removal images if disk is almost full (wrong path was defined). -* Support for the Raspberry Pi Camera module v2.1. [#3](https://github.com/kerberos-io/kios/issues/3) -* Support for the Raspberry Pi Zero; updated kernel to latest Raspbian. [#3](https://github.com/kerberos-io/kios/issues/3) -* KiOS GUI installer. - - -## 2.0.0 - -#### Web - -* Add simple ON/OFF toggle. [#24](https://github.com/kerberos-io/web/issues/24) -* Added update strategy when using KiOS. [#23](https://github.com/kerberos-io/web/issues/23) -* A system page which shows system information. [#20](https://github.com/kerberos-io/web/issues/20) -* Heatmap on dashboard page [#19](https://github.com/kerberos-io/web/issues/19) -* Added live stream view on the dashboard page [#2](https://github.com/kerberos-io/web/issues/2) -* Fixed bug cloud syncing [#16](https://github.com/kerberos-io/web/issues/16) -* Fixed broken settings page when space in instane name [#16](https://github.com/kerberos-io/web/issues/16) - -#### Machinery - -* RTSP support for IP-camera's. [#21](https://github.com/kerberos-io/machinery/issues/21) -* Verbose logging. [#35](https://github.com/kerberos-io/machinery/issues/35) -* IO-devices are executed in a seperate thread. [#28](https://github.com/kerberos-io/machinery/issues/28) -* Live streaming (MJPEG). [#26](https://github.com/kerberos-io/machinery/issues/26) -* Execute multiple instances on a machine. [#24](https://github.com/kerberos-io/machinery/issues/24) -* Override config by arguments. [#22](https://github.com/kerberos-io/machinery/issues/22) -* Move S3 upload to machinery and remove sync-s3 repository. [#16](https://github.com/kerberos-io/machinery/issues/16) - -#### Docker - -* Added Docker image (x86_x64) to Docker Hub. - -#### Ecosystem - -* Add support for Raspberry Pi 1, 2 and 3. [#1](https://github.com/kerberos-io/kios/issues/1) - - -## 1.1.0 - -#### Web - -* Support IP camera's with MJPEG stream. [#3](https://github.com/kerberos-io/web/issues/3) -* Introduce new API methods to configure the machinery, using basic auth. [#4](https://github.com/kerberos-io/web/issues/4) -* Optimization of loading image and dashboard page, completely redesigned the retrieval of images. [#5](https://github.com/kerberos-io/web/issues/5) -* Optimization of settings page. [#5](https://github.com/kerberos-io/web/issues/5) -* Timebar gradient only works in Chrome. [#6](https://github.com/kerberos-io/web/issues/6) -* Minor CSS fixes for responsive layout. - -#### Machinery - -* Flip/rotate option for capture devices. [#5](https://github.com/kerberos-io/machinery/issues/1) -* Support IP camera's with MJPEG stream. [#4](https://github.com/kerberos-io/machinery/issues/4) -* Introduced webhook io device. [#5](https://github.com/kerberos-io/machinery/issues/5) - -#### Cloud - -* Fixed problem when syncing a huge amount of images. [#1](https://github.com/kerberos-io/sync-s3/issues/1) - - -## 1.0.3 - -#### Web - -* Optimize performance, new datastructure has been implemented. - -#### Machinery - -* Memory optimization. -* Removal of images older than 3 days have been removed. -* Start machinery automatically (delay has been removed). - -#### Cloud - -* Resolved file exist problem. - - -## 1.0.2 - -#### Web - -* Timezone on settings page is also used for the webinterface. - -#### Machinery - -* Added extra timezones to timezone.xml. - - -## 1.0.1 - -#### Web - -* Improved error handling (date search). - -#### Machinery - -* Improved memory cleanup. - - -## 1.0.0 - -#### First commit of Kerberos.io - -* Camera support: **USBCamera** (V4L), **Raspberry Pi camera module** (MMAL). -* Conditions: **Enabled** (turn on/off Kerberos) and active **Time** per day. -* Algorithms: **Differential Images**. -* Heuristics: **Sequence**. -* Expositors: Select a **Hull** or **Rectangle**. -* Outputs: Write image to **Disk**, trigger an **GPIO** output pin and send a **TCP/IP packet**. -* Cloud: send your images to the **Kerberos.io cloud aplication**. diff --git a/6_license.md b/6_license.md deleted file mode 100644 index f45f91a..0000000 --- a/6_license.md +++ /dev/null @@ -1,75 +0,0 @@ -# CC-NC-ND - -THE WORK (AS DEFINED BELOW) IS PROVIDED UNDER THE TERMS OF THIS CREATIVE COMMONS PUBLIC LICENSE ("CCPL" OR "LICENSE"). THE WORK IS PROTECTED BY COPYRIGHT AND/OR OTHER APPLICABLE LAW. ANY USE OF THE WORK OTHER THAN AS AUTHORIZED UNDER THIS LICENSE OR COPYRIGHT LAW IS PROHIBITED. - -BY EXERCISING ANY RIGHTS TO THE WORK PROVIDED HERE, YOU ACCEPT AND AGREE TO BE BOUND BY THE TERMS OF THIS LICENSE. TO THE EXTENT THIS LICENSE MAY BE CONSIDERED TO BE A CONTRACT, THE LICENSOR GRANTS YOU THE RIGHTS CONTAINED HERE IN CONSIDERATION OF YOUR ACCEPTANCE OF SUCH TERMS AND CONDITIONS. - -## Exceptions / Commercial use - -Any exceptions regarding this license, and/or business opportunities should be discussed with **cedric@verstraeten.io**. - -## Definitions - -"Adaptation" means a work based upon the Work, or upon the Work and other pre-existing works, such as a translation, adaptation, derivative work, arrangement of music or other alterations of a literary or artistic work, or phonogram or performance and includes cinematographic adaptations or any other form in which the Work may be recast, transformed, or adapted including in any form recognizably derived from the original, except that a work that constitutes a Collection will not be considered an Adaptation for the purpose of this License. For the avoidance of doubt, where the Work is a musical work, performance or phonogram, the synchronization of the Work in timed-relation with a moving image ("synching") will be considered an Adaptation for the purpose of this License. -"Collection" means a collection of literary or artistic works, such as encyclopedias and anthologies, or performances, phonograms or broadcasts, or other works or subject matter other than works listed in Section 1(f) below, which, by reason of the selection and arrangement of their contents, constitute intellectual creations, in which the Work is included in its entirety in unmodified form along with one or more other contributions, each constituting separate and independent works in themselves, which together are assembled into a collective whole. A work that constitutes a Collection will not be considered an Adaptation (as defined above) for the purposes of this License. -"Distribute" means to make available to the public the original and copies of the Work through sale or other transfer of ownership. -"Licensor" means the individual, individuals, entity or entities that offer(s) the Work under the terms of this License. -"Original Author" means, in the case of a literary or artistic work, the individual, individuals, entity or entities who created the Work or if no individual or entity can be identified, the publisher; and in addition (i) in the case of a performance the actors, singers, musicians, dancers, and other persons who act, sing, deliver, declaim, play in, interpret or otherwise perform literary or artistic works or expressions of folklore; (ii) in the case of a phonogram the producer being the person or legal entity who first fixes the sounds of a performance or other sounds; and, (iii) in the case of broadcasts, the organization that transmits the broadcast. -"Work" means the literary and/or artistic work offered under the terms of this License including without limitation any production in the literary, scientific and artistic domain, whatever may be the mode or form of its expression including digital form, such as a book, pamphlet and other writing; a lecture, address, sermon or other work of the same nature; a dramatic or dramatico-musical work; a choreographic work or entertainment in dumb show; a musical composition with or without words; a cinematographic work to which are assimilated works expressed by a process analogous to cinematography; a work of drawing, painting, architecture, sculpture, engraving or lithography; a photographic work to which are assimilated works expressed by a process analogous to photography; a work of applied art; an illustration, map, plan, sketch or three-dimensional work relative to geography, topography, architecture or science; a performance; a broadcast; a phonogram; a compilation of data to the extent it is protected as a copyrightable work; or a work performed by a variety or circus performer to the extent it is not otherwise considered a literary or artistic work. -"You" means an individual or entity exercising rights under this License who has not previously violated the terms of this License with respect to the Work, or who has received express permission from the Licensor to exercise rights under this License despite a previous violation. -"Publicly Perform" means to perform public recitations of the Work and to communicate to the public those public recitations, by any means or process, including by wire or wireless means or public digital performances; to make available to the public Works in such a way that members of the public may access these Works from a place and at a place individually chosen by them; to perform the Work to the public by any means or process and the communication to the public of the performances of the Work, including by public digital performance; to broadcast and rebroadcast the Work by any means including signs, sounds or images. -"Reproduce" means to make copies of the Work by any means including without limitation by sound or visual recordings and the right of fixation and reproducing fixations of the Work, including storage of a protected performance or phonogram in digital form or other electronic medium. - -## Fair Dealing Rights - -Nothing in this License is intended to reduce, limit, or restrict any uses free from copyright or rights arising from limitations or exceptions that are provided for in connection with the copyright protection under copyright law or other applicable laws. - -## License Grant - -Subject to the terms and conditions of this License, Licensor hereby grants You a worldwide, royalty-free, non-exclusive, perpetual (for the duration of the applicable copyright) license to exercise the rights in the Work as stated below: - -to Reproduce the Work, to incorporate the Work into one or more Collections, and to Reproduce the Work as incorporated in the Collections; and, -to Distribute and Publicly Perform the Work including as incorporated in Collections. -The above rights may be exercised in all media and formats whether now known or hereafter devised. The above rights include the right to make such modifications as are technically necessary to exercise the rights in other media and formats, but otherwise you have no rights to make Adaptations. Subject to 8(f), all rights not expressly granted by Licensor are hereby reserved, including but not limited to the rights set forth in Section 4(d). - -## Restrictions. - -The license granted in Section 3 above is expressly made subject to and limited by the following restrictions: - -You may Distribute or Publicly Perform the Work only under the terms of this License. You must include a copy of, or the Uniform Resource Identifier (URI) for, this License with every copy of the Work You Distribute or Publicly Perform. You may not offer or impose any terms on the Work that restrict the terms of this License or the ability of the recipient of the Work to exercise the rights granted to that recipient under the terms of the License. You may not sublicense the Work. You must keep intact all notices that refer to this License and to the disclaimer of warranties with every copy of the Work You Distribute or Publicly Perform. When You Distribute or Publicly Perform the Work, You may not impose any effective technological measures on the Work that restrict the ability of a recipient of the Work from You to exercise the rights granted to that recipient under the terms of the License. This Section 4(a) applies to the Work as incorporated in a Collection, but this does not require the Collection apart from the Work itself to be made subject to the terms of this License. If You create a Collection, upon notice from any Licensor You must, to the extent practicable, remove from the Collection any credit as required by Section 4(c), as requested. - -You may not exercise any of the rights granted to You in Section 3 above in any manner that is primarily intended for or directed toward commercial advantage or private monetary compensation. The exchange of the Work for other copyrighted works by means of digital file-sharing or otherwise shall not be considered to be intended for or directed toward commercial advantage or private monetary compensation, provided there is no payment of any monetary compensation in connection with the exchange of copyrighted works. - - -If You Distribute, or Publicly Perform the Work or Collections, You must, unless a request has been made pursuant to Section 4(a), keep intact all copyright notices for the Work and provide, reasonable to the medium or means You are utilizing: (i) the name of the Original Author (or pseudonym, if applicable) if supplied, and/or if the Original Author and/or Licensor designate another party or parties (e.g., a sponsor institute, publishing entity, journal) for attribution ("Attribution Parties") in Licensor's copyright notice, terms of service or by other reasonable means, the name of such party or parties; (ii) the title of the Work if supplied; (iii) to the extent reasonably practicable, the URI, if any, that Licensor specifies to be associated with the Work, unless such URI does not refer to the copyright notice or licensing information for the Work. The credit required by this Section 4(c) may be implemented in any reasonable manner; provided, however, that in the case of a Collection, at a minimum such credit will appear, if a credit for all contributing authors of Collection appears, then as part of these credits and in a manner at least as prominent as the credits for the other contributing authors. For the avoidance of doubt, You may only use the credit required by this Section for the purpose of attribution in the manner set out above and, by exercising Your rights under this License, You may not implicitly or explicitly assert or imply any connection with, sponsorship or endorsement by the Original Author, Licensor and/or Attribution Parties, as appropriate, of You or Your use of the Work, without the separate, express prior written permission of the Original Author, Licensor and/or Attribution Parties. -For the avoidance of doubt: - -Non-waivable Compulsory License Schemes. In those jurisdictions in which the right to collect royalties through any statutory or compulsory licensing scheme cannot be waived, the Licensor reserves the exclusive right to collect such royalties for any exercise by You of the rights granted under this License -Waivable Compulsory License Schemes. In those jurisdictions in which the right to collect royalties through any statutory or compulsory licensing scheme can be waived, the Licensor reserves the exclusive right to collect such royalties for any exercise by You of the rights granted under this License if Your exercise of such rights is for a purpose or use which is otherwise than noncommercial as permitted under Section 4(b) and otherwise waives the right to collect royalties through any statutory or compulsory licensing scheme; and, -Voluntary License Schemes. The Licensor reserves the right to collect royalties, whether individually or, in the event that the Licensor is a member of a collecting society that administers voluntary licensing schemes, via that society, from any exercise by You of the rights granted under this License that is for a purpose or use which is otherwise than noncommercial as permitted under Section 4(b). -Except as otherwise agreed in writing by the Licensor or as may be otherwise permitted by applicable law, if You Reproduce, Distribute or Publicly Perform the Work either by itself or as part of any Collections, You must not distort, mutilate, modify or take other derogatory action in relation to the Work which would be prejudicial to the Original Author's honor or reputation. - -## Representations, Warranties and Disclaimer - -UNLESS OTHERWISE MUTUALLY AGREED BY THE PARTIES IN WRITING, LICENSOR OFFERS THE WORK AS-IS AND MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND CONCERNING THE WORK, EXPRESS, IMPLIED, STATUTORY OR OTHERWISE, INCLUDING, WITHOUT LIMITATION, WARRANTIES OF TITLE, MERCHANTIBILITY, FITNESS FOR A PARTICULAR PURPOSE, NONINFRINGEMENT, OR THE ABSENCE OF LATENT OR OTHER DEFECTS, ACCURACY, OR THE PRESENCE OF ABSENCE OF ERRORS, WHETHER OR NOT DISCOVERABLE. SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION OF IMPLIED WARRANTIES, SO SUCH EXCLUSION MAY NOT APPLY TO YOU. - -## Limitation on Liability - -EXCEPT TO THE EXTENT REQUIRED BY APPLICABLE LAW, IN NO EVENT WILL LICENSOR BE LIABLE TO YOU ON ANY LEGAL THEORY FOR ANY SPECIAL, INCIDENTAL, CONSEQUENTIAL, PUNITIVE OR EXEMPLARY DAMAGES ARISING OUT OF THIS LICENSE OR THE USE OF THE WORK, EVEN IF LICENSOR HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. - -## Termination - -This License and the rights granted hereunder will terminate automatically upon any breach by You of the terms of this License. Individuals or entities who have received Collections from You under this License, however, will not have their licenses terminated provided such individuals or entities remain in full compliance with those licenses. Sections 1, 2, 5, 6, 7, and 8 will survive any termination of this License. - -Subject to the above terms and conditions, the license granted here is perpetual (for the duration of the applicable copyright in the Work). Notwithstanding the above, Licensor reserves the right to release the Work under different license terms or to stop distributing the Work at any time; provided, however that any such election will not serve to withdraw this License (or any other license that has been, or is required to be, granted under the terms of this License), and this License will continue in full force and effect unless terminated as stated above. - -## Miscellaneous - -Each time You Distribute or Publicly Perform the Work or a Collection, the Licensor offers to the recipient a license to the Work on the same terms and conditions as the license granted to You under this License. - -If any provision of this License is invalid or unenforceable under applicable law, it shall not affect the validity or enforceability of the remainder of the terms of this License, and without further action by the parties to this agreement, such provision shall be reformed to the minimum extent necessary to make such provision valid and enforceable. - -No term or provision of this License shall be deemed waived and no breach consented to unless such waiver or consent shall be in writing and signed by the party to be charged with such waiver or consent. - -This License constitutes the entire agreement between the parties with respect to the Work licensed here. There are no understandings, agreements or representations with respect to the Work not specified here. Licensor shall not be bound by any additional provisions that may appear in any communication from You. This License may not be modified without the mutual written agreement of the Licensor and You. -The rights granted under, and the subject matter referenced, in this License were drafted utilizing the terminology of the Berne Convention for the Protection of Literary and Artistic Works (as amended on September 28, 1979), the Rome Convention of 1961, the WIPO Copyright Treaty of 1996, the WIPO Performances and Phonograms Treaty of 1996 and the Universal Copyright Convention (as revised on July 24, 1971). These rights and subject matter take effect in the relevant jurisdiction in which the License terms are sought to be enforced according to the corresponding provisions of the implementation of those treaty provisions in the applicable national law. If the standard suite of rights granted under applicable copyright law includes additional rights not granted under this License, such additional rights are deemed to be included in the License; this License is not intended to restrict the license of any rights under applicable law. diff --git a/70_installation/1_first_things_first.md b/70_installation/1_first_things_first.md deleted file mode 100644 index 599f72e..0000000 --- a/70_installation/1_first_things_first.md +++ /dev/null @@ -1,39 +0,0 @@ -# First things first - -The reason why you're on this page is because you want to know **how to install Kerberos.io** on your microcontroller, Docker, local working station, server or whatever Linux environment you prefer. The good news is that we have **different approaches** from basic to advanced; it depends on how you want to install it. - -Before you decide which installation method you will use, it might be interesting to read about our [**best practices**](/best_practices) and the [**one vs multi camera support**](/strategy#one-vs-multi) discussion. - -## Raspberry Pi - -When deploying on the Raspberry Pi there are two possible solutions. You can use our custom OS, [**KiOS**](installation/KiOS) (Kerberos.io Operating System), which is production-ready or install it on an existing OS, [**Raspbian**](installation/Raspbian). - -### KiOS - -[KiOS](https://github.com/kerberos-io/kios) is a custom linux OS (created by Buildroot) which runs Kerberos.io out-of-the-box. This is the **most simple** and **basic** installation procedure. Note that with KiOS you don't have multiple camera support. - -
Install KiOS
- -### Raspbian - -If you already have a Raspberry Pi running with Raspbian, you probably **don't want to reflash your SD card**. Therefore you can install and download the different parts of Kerberos.io (the machinery and the web) without the need for complex and time consuming compiling. - -
Install on Raspbian
- -## Armbian supported boards - -If you have *an Armbian supported board**, you can follow the Armbian installation to transform it into a surveillance system. - -
Install on Armbian
- -## Docker - -A Docker image is available on the Docker Hub for **x86 machines**. By using docker-compose you can run Kerberos.io with a one-liner. - -
Run on Docker
- -## Generic - -You can install Kerberos.io on any Linux based OS like Ubuntu, Debian, Raspbian, OSX, etc. The only thing you need to do is to compile the machinery and install the web interface. Kerberos.io can't be compiled on a native Windows machine, if you want to use Kerberos.io on windows you should Docker. - -
Compile yourself
diff --git a/70_installation/1_how-to-access.png b/70_installation/1_how-to-access.png deleted file mode 100644 index 4caacee..0000000 Binary files a/70_installation/1_how-to-access.png and /dev/null differ diff --git a/70_installation/1_upgrade-install.png b/70_installation/1_upgrade-install.png deleted file mode 100644 index 5dc453b..0000000 Binary files a/70_installation/1_upgrade-install.png and /dev/null differ diff --git a/70_installation/1_upgrade-newrelease.png b/70_installation/1_upgrade-newrelease.png deleted file mode 100644 index 169e965..0000000 Binary files a/70_installation/1_upgrade-newrelease.png and /dev/null differ diff --git a/70_installation/1_upgrade.md b/70_installation/1_upgrade.md deleted file mode 100644 index a936e61..0000000 --- a/70_installation/1_upgrade.md +++ /dev/null @@ -1,86 +0,0 @@ -# Upgrade - -To upgrade Kerberos.io to a new version you should **follow the approach which fits your initial installation** method. If you installed KiOS follow the KiOS upgrade procedure, if installed on Raspbian follow the Raspbian upgrade procedure, etc. - -Please note that it might be possible that some new files are added or existing files were updated. To make sure everything works as expected, you should **clear your browser cache**. - -## KiOS - -If you installed KiOS, you can **use the built-in versioning** method. You can find the versioning at the bottom of the system page. If a new version of Kerberos.io is released, you'll see a new version available. Note that you'll also receive **a notification on top of the Kerberos.io web interface**, when a new release is available. - -![New release available](1_upgrade-newrelease.png) - -### Start an upgrade - -When a new release is available, you have the possibilty to **install** it **by clicking on** the name of **the release**. A popup will open giving you some more information about the release. Press the install button to start the upgrade. Make sure that you **don't close the upgrade screen** while upgrading. - -![Install release](1_upgrade-install.png) - -This is what will happen: - -* New KiOS image is downloaded. -* Release is unpacked and transferred to /root partition. -* Systems is rebooted. -* Post-upgrade scripts are applied. - -## Raspbian / Armbian - -If you want to install a new version of Kerberos.io on Raspbian or Armbian, there is **no automated versioning** process available like KiOS. To perform an upgrade you'll need to follow the traditional installation procedure for [Raspbian**](/installation/Raspbian) or for [**Armbian**](/installation/Armbian). - -Please read the notes below that matches your current and desired version to upgrade to. If no notes are available, you'll only need to follow the installation guide. - -### Upgrade from 2.3.x to 2.4.0 - -At 2.4.0 we are now using Laravel 5.4.0, which requires >= PHP 5.6. We recommend you to install PHP 7.0. - -Install PHP7 packages. - - sudo apt-get install php7.0 php7.0-curl php7.0-gd php7.0-fpm php7.0-cli php7.0-opcache php7.0-mbstring php7.0-xml php7.0-zip php7.0-mcrypt - -Modify the fastcgi_pass parameter in your nginx config. - - sudo nano /etc/nginx/sites-enabled/default - -Replace following line. - - - fastcgi_pass unix:/var/run/php5-fpm.sock; - + fastcgi_pass unix:/var/run/php/php7.0-fpm.sock; - -Reboot the system (or only Nginx). - - sudo reboot - -## Docker - -When a new release is available, new docker images are available [**on the docker hub**](https://hub.docker.com/u/kerberos/). There are two possible ways to upgrade your docker containers. - -### Append or change version number - -The easiest way is to update your **docker-compose.yml** file by changing or adding the version number. - - machinery: - image: kerberos/machinery:v2.2.0 - ports: - - "8889" - web: - image: kerberos/web:v2.2.0 - ports: - - "80" - volumes_from: - - machinery - links: - - machinery - -### Remove containers and images - -Another solution is to start completely over again (clean state). You can do this by removing all your containers and images from your docker environment. - - #!/bin/bash - # Delete all containers - docker rm $(docker ps -a -q) - # Delete all images - docker rmi $(docker images -q) - -After you've deleted all your containers and images, you can start the containers again with **docker-compose**. You'll see that the new Kerberos.io images will be downloaded. - - docker-compose up diff --git a/70_installation/2_KiOS.md b/70_installation/2_KiOS.md deleted file mode 100644 index 2dd4026..0000000 --- a/70_installation/2_KiOS.md +++ /dev/null @@ -1,120 +0,0 @@ -# KiOS - -* [Easy Installation](#installer) -* [Advanced Installation](#advanced) - * [Download the .img](#download) - * [Flash the .img to a SD card with Etcher.io](#flash) - * [Network configuration](#network) -* [Power on the Raspberry Pi](#poweron) -* [Access the Raspberry Pi with SSH](#access) - - -## Introduction - -[KiOS](https://github.com/kerberos-io/kios) (Kerberos.io Operating System) is our own **custom linux OS**, which runs Kerberos.io out-of-the-box. KiOS is **installed like every other OS** for the Raspberry Pi, you need to flash the OS (.img) to a SD card. If you want to get Kerberos.io up and running at a short time frame, this is the **most simple** and **basic** installation procedure. - -You can install KiOS by using our **own installer**, which gives you a nice GUI that will handle the flashing and network configuration for you, or you can do the flashing **yourself** by using Etcher. - - - - -
-

Easy Installation

- -

ATTENTION!
-We've experiencing issues with the easy installation if you are running Windows 10. When you're also experiencing issues, please follow the advanced installation using the Etcher installer. Meanwhile we'll try to resolve those issues. -

- -

-Installing Kerberos.io to your IoT device, has never been so easy. By using our cross-platform installer, you can run a fully configured video surveillance system within 3 minutes. Indeed, we also think that's awesome! -

- - - -
- - - -
- -

By using the KiOS installer, you'll get an easy to use GUI which allows you to configure and flash KiOS to your SD card. Just download the installer, select a version, specify your network configurations, select your SD card and press the flash button; it can't be easier.

- -
- - - -

Power on the Raspberry Pi

- -

When the installation is completed, you can plug the SD card into your Raspberry Pi. From this point KiOS will boot the kernel and re-partition your SD-card; Please note that the first time you boot KiOS it can take about 2 mins before the system is operational. When KiOS is ready you can open your favorite browser and type in the IP address of your Raspberry Pi. This will open the Kerberos.io login page, which you can access with the username: root and password: root.

- -![Login page kerberos.io webinterface](1_how-to-access.png) - - -

Access the Raspberry Pi with SSH

- -

To use Kerberos.io you only need access to the webinterface, however you can also access the system with SSH.

- -
Cedrics-Mac-mini:build cedricverst$ ssh root@192.168.0.12
-Welcome to kios-79e30bbb!
-[root@kios-79e30bbb ~]#
- -

Note that by default no root password is set, you can define a password in the /data/etc/kios.conf file.

- -
[root@kios-79e30bbb ~]# nano /data/etc/kios.conf
-[root@kios-79e30bbb ~]# reboot
- -

Add your password, save the file and reboot the system.

diff --git a/70_installation/2_etcher.png b/70_installation/2_etcher.png deleted file mode 100644 index e8491f6..0000000 Binary files a/70_installation/2_etcher.png and /dev/null differ diff --git a/70_installation/2_kerberos-image.png b/70_installation/2_kerberos-image.png deleted file mode 100644 index 850e429..0000000 Binary files a/70_installation/2_kerberos-image.png and /dev/null differ diff --git a/70_installation/2_rpi-logo-cloner.png b/70_installation/2_rpi-logo-cloner.png deleted file mode 100644 index 047e80c..0000000 Binary files a/70_installation/2_rpi-logo-cloner.png and /dev/null differ diff --git a/70_installation/3_Raspbian.md b/70_installation/3_Raspbian.md deleted file mode 100644 index 2bcdea5..0000000 --- a/70_installation/3_Raspbian.md +++ /dev/null @@ -1,235 +0,0 @@ -# Raspbian - -* [How to install](#how-to-install) -* [Machinery](#machinery) - * [Install package](#machinery-install-package) - * [Configure](#machinery-configure) - * [Run](#machinery-run) -* [Web](#web) - * [Install webserver + PHP (optional)](#web-installation-webserver) - * [Install source](#web-installation-source) -* [Auto removal](#auto-removal) - - - -## How to install -A short video explaining how to install Kerberos.io on Raspbian. - - - - -## Machinery - - -### Install package - -Update system and install libav-tools. - - sudo apt-get update && sudo apt-get install libav-tools libssl-dev - -Download the debian file from [**the machinery repository**](https://github.com/kerberos-io/machinery/releases/v%machineryversion%/); Please download the correct version for your Raspberry Pi. - -Raspberry Pi Zero/Zero W - - wget https://github.com/kerberos-io/machinery/releases/download/v%machineryversion%/rpi0-machinery-kerberosio-armhf-%machineryversion%.deb - sudo dpkg -i rpi0-machinery-kerberosio-armhf-%machineryversion%.deb - -Raspberry Pi A/B/B+ - - wget https://github.com/kerberos-io/machinery/releases/download/v%machineryversion%/rpi1-machinery-kerberosio-armhf-%machineryversion%.deb - sudo dpkg -i rpi1-machinery-kerberosio-armhf-%machineryversion%.deb - -Raspberry Pi 2 - - wget https://github.com/kerberos-io/machinery/releases/download/v%machineryversion%/rpi2-machinery-kerberosio-armhf-%machineryversion%.deb - sudo dpkg -i rpi2-machinery-kerberosio-armhf-%machineryversion%.deb - -Raspberry Pi 3 - - wget https://github.com/kerberos-io/machinery/releases/download/v%machineryversion%/rpi3-machinery-kerberosio-armhf-%machineryversion%.deb - sudo dpkg -i rpi3-machinery-kerberosio-armhf-%machineryversion%.deb - -Enable Raspberry Pi camera (if needed). - - sudo raspi-config - -Set machinery to start on boot, and start it now. A reboot is required if you have changed the options in raspi-config in the previous step. - - sudo systemctl enable kerberosio - sudo service kerberosio start - - -### Configure - -The configuration files can be found at **/etc/opt/kerberosio/config**. By default the Raspberry Pi Camera module is set as capture device. You can update the **config.xml** file to change it to **USBCamera** or **IPCamera**. Images are stored in the **/etc/opt/kerberosio/capture** directory by default; this location can be changed by editing the **io.xml** file. - - -### Run - -After kerberos is installed a binary is available at **/usr/bin/kerberosio**. Just run following command in your terminal to start kerberosio - - kerberosio - - -## Web - - -### Install Nginx + PHP - -Before you can run the web interface, you'll need to download and configure a webserver. Kerberos.io recommends to use Nginx, as it is a light-weight and fast webserver. The web interface is written in PHP, so we also need to download PHP and some packages. - -Update the packages and kernel. - - echo "deb http://mirrordirector.raspbian.org/raspbian/ stretch main contrib non-free rpi" | sudo tee --append /etc/apt/sources.list - sudo apt-get update && sudo apt-get upgrade - -Install Nginx and PHP (+extension). - - sudo apt-get install -t stretch nginx php7.0 php7.0-curl php7.0-gd php7.0-fpm php7.0-cli php7.0-opcache php7.0-mbstring php7.0-xml php7.0-zip php7.0-mcrypt - -Creating a Nginx config. - - sudo rm -f /etc/nginx/sites-enabled/default - sudo nano /etc/nginx/sites-enabled/kerberosio.conf - -Copy and paste following config file; this file tells nginx where the web will be installed and that it requires PHP. - - server - { - listen 80 default_server; - listen [::]:80 default_server; - root /var/www/web/public; - server_name kerberos.rpi; - index index.php index.html index.htm; - location / - { - autoindex on; - try_files $uri $uri/ /index.php?$query_string; - } - location ~ \.php$ - { - fastcgi_pass unix:/var/run/php/php7.0-fpm.sock; - fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; - include fastcgi_params; - } - } - -Restart nginx - - sudo service nginx restart - - -### Install source - -Create a www location. - - sudo mkdir -p /var/www/web && sudo chown www-data:www-data /var/www/web - cd /var/www/web - -Get the source code from Github. - - sudo -u www-data wget https://github.com/kerberos-io/web/releases/download/v%webversion%/web.tar.gz - -Unpack - - sudo -u www-data tar xvf web.tar.gz . - -Change write permission on the storage directory. - - sudo chown www-data -R storage bootstrap/cache config/kerberos.php - sudo chmod -R 775 storage bootstrap/cache - sudo chmod 0600 config/kerberos.php - - -## Auto removal - -By default images or videos **aren't removed automatically**. This means that Kerberos.io will keep writing to disk, even if there is no more space available on your SD card. When your **SD card is full** you'll be **experiencing strange errors**: a corrupt web interface, blank images or corrupt videos. - -To resolve this your should install a simple **bash script** and initiate **a cronjob** which continuously poll your filesystem, and start removing media when your disk is getting full. - -Create a bash script and copy following script. - - nano /home/pi/autoremoval.sh - -Copy following script (make sure the partition is correct, this is the default one for a Raspberry Pi). - - partition=/dev/root - imagedir=/etc/opt/kerberosio/capture/ - if [[ $(df -h | grep $partition | head -1 | awk -F' ' '{ print $5/1 }' | tr ['%'] ["0"]) -gt 90 ]]; - then - echo "Cleaning disk" - find $imagedir -type f | sort | head -n 100 | xargs -r rm -rf; - fi; - -Make the script executable. - - chmod +x /home/pi/autoremoval.sh - -Initiate a cronjob, and select the **nano** editor. - - crontab -e - -Append following line, to execute the **autoremoval.sh** script every 5min. - - */5 * * * * /bin/bash /home/pi/autoremoval.sh - - -# Multi-camera on Raspbian - -When you've installed Kerberos.io on your **Raspbian** installation, then you have the possibility **to connect one or more cameras** to the Raspberry Pi. Please note that this functionality **isn't available out-of-the-box**, and therefore requires some technical skills to configure. - -## Install Raspbian - -First things first. Install Kerberos.io on Raspbian by following **the Raspbian installation** mentioned before, and make sure you've installed Kerberos.io properly. - -By default Kerberos.io **only support a single type of camera**, you can navigate to the settings page and change the capture device. If you want to connect more cameras, it **isn't possible** to configure it **through the web interface**. - -## This is how it works - -When installed properly, the kerberos.io binary will start at boot, and read the configuration files located at **/etc/opt/kerberosio/config**. Next to that Kerberos.io will start the correct capture device, and configure the complete system according the settings you've defined in those configuration files. This is what happens: - - $ kerberosio --config /etc/opt/kerberosio/config/config.xml - - -To start multiple devices we can simple run the binary a second time, and **overwrite the settings** by commandline parameters. Suppose that we want to connect two more USB cameras, next to our Raspberry Pi camera, then we can do this as following: - - $ kerberosio --name usbcamera1 --capture USBCamera --captures.USBCamera.deviceNumber 0 --streams.Mjpg.enabled false & - $ kerberosio --name usbcamera2 --capture USBCamera --captures.USBCamera.deviceNumber 1 --streams.Mjpg.enabled false & - -What this will do is start two new kerberosio processes, and **connect each USB camera to a kerberosio process**. By overwriting the devicenumber we're able to select a specific USB camera. Next to that we also disabled the stream, because by default kerberosio will bind to the port 8889, and that will not work if we have multiple processes running (additionally you can change the port for each process). - -## Where can I find those variables? - -When Kerberos.io is started it will write to a log file located at **/etc/opt/kerberosio/logs/log.stash**, which you can see on the system page of the web interface. In the log file you'll see the startup configuration with all the different settings. You can overwrite every setting which is listed in this overview, just keep in mind that you have to prefix every option with **a double dash --**. - - 26/10/2016 08:11:36.135 INFO [trivial] Reading configuration - 26/10/2016 08:11:36.141 INFO [trivial] Final configuration: - - algorithm = DifferentialCollins - - algorithms.BackgroundSubtraction.dilate = 7 - - algorithms.BackgroundSubtraction.erode = 5 - - algorithms.BackgroundSubtraction.history = 50 - ... - - algorithms.DifferentialCollins.threshold = 15 - - capture = USBCamera - - captures.IPCamera.angle = 0 - - captures.IPCamera.delay = 1000 - - captures.IPCamera.frameHeight = 360 - - captures.IPCamera.frameWidth = 640 - - captures.IPCamera.url = rtsp://admin:888888@192 - - captures.RaspiCamera.angle = 0 - - captures.RaspiCamera.delay = 500 - - captures.RaspiCamera.frameHeight = 720 - - captures.RaspiCamera.frameWidth = 1280 - - captures.USBCamera.angle = 0 - - captures.USBCamera.delay = 500 - - captures.USBCamera.deviceNumber = 0 - - captures.USBCamera.frameHeight = 640 - ... - - streams.Mjpg.enabled = false - - streams.Mjpg.quality = 75 - - streams.Mjpg.streamPort = 8889 - - timezone = Europe-Brussels - -## Where can I find my images? - -All images will be stored at the same location, so they will be mixed in the webinterface. We don't provide a way to see the images independent (on a camera basis), if you would like to have this then you should check out our [**cloud application**](https://cloud.kerberos.io) which has some additional features. diff --git a/70_installation/4_Armbian.md b/70_installation/4_Armbian.md deleted file mode 100644 index f0e67bc..0000000 --- a/70_installation/4_Armbian.md +++ /dev/null @@ -1,151 +0,0 @@ -# Armbian - -* [How to install](#how-to-install) -* [Machinery](#machinery) - * [Install package](#machinery-install-package) - * [Configure](#machinery-configure) - * [Run](#machinery-run) -* [Web](#web) - * [Install webserver + PHP (optional)](#web-installation-webserver) - * [Install source](#web-installation-source) -* [Auto removal](#auto-removal) - - - -## Machinery - - -### Install package - -Update system and install dependency avcodec. These installation instructions assume that a fresh Armbian 5.24 or 5.25 installed. - - sudo apt-get update && sudo apt-get install libav-tools - -Download the debian file from [**the machinery repository**](https://github.com/kerberos-io/machinery/releases/v%machineryversion%/); This should work on all Armbian supported boards. If not: inform us!. - - wget https://github.com/kerberos-io/machinery/releases/download/v%machineryversion%/armbian-machinery-kerberosio-armhf-%machineryversion%.deb - -Unpackage the file - - sudo dpkg -i armbian-machinery-kerberosio-armhf-%machineryversion%.deb - -Start the machinery on start-up, and reboot the system. - - sudo systemctl enable kerberosio && sudo reboot - - -### Configure - -The configuration files can be found at **/etc/opt/kerberosio/config**. By default the Raspberry Pi Camera module is set as capture device. This must be changed in the **config.xml** to **USBCamera** or **IPCamera** depending on your camera. Images / videos are stored in the **/etc/opt/kerberosio/capture** directory by default; this location can be changed by editing the **io.xml** file. - - -### Run - -After kerberos is installed a binary is available at **/usr/bin/kerberosio**. Just run following command in your terminal to start kerberosio - - kerberosio - -In case kerberosio does not start and complains about missing libraries, install the following libraries. - - sudo apt-get install pkg-config libavcodec-dev libavformat-dev libswscale-dev - - -## Web - - -### Install webserver + PHP (optional) - -Add Raspbian package repo and update the packages and kernel. - - echo "deb http://mirrordirector.raspbian.org/raspbian/ stretch main contrib non-free rpi" | sudo tee --append /etc/apt/sources.list - sudo apt-get update && sudo apt-get upgrade - -Install Nginx and PHP (+extension). - - sudo apt-get install nginx php7.0 php7.0-curl php7.0-gd php7.0-fpm php7.0-cli php7.0-opcache php7.0-mbstring php7.0-xml php7.0-zip php7.0-mcrypt nodejs npm - -Creating a Nginx config. - - sudo rm -f /etc/nginx/sites-enabled/default - sudo nano /etc/nginx/sites-enabled/default - -Copy and paste following config file; this file tells nginx where the web will be installed and that it requires PHP. - - server - { - listen 80 default_server; - listen [::]:80 default_server; - root /var/www/web/public; - server_name kerberos.rpi; - index index.php index.html index.htm; - location / - { - autoindex on; - try_files $uri $uri/ /index.php?$query_string; - } - location ~ \.php$ - { - fastcgi_pass unix:/var/run/php/php7.0-fpm.sock; - fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; - include fastcgi_params; - } - } - -Restart nginx and reboot system - - sudo service nginx restart && sudo reboot - - -### Install source - -Create a www location. - - sudo mkdir -p /var/www/web && sudo chown www-data:www-data /var/www/web - cd /var/www/web - -Get the source code from Github. - - sudo -u www-data wget https://github.com/kerberos-io/web/releases/download/v%webversion%/web.tar.gz - -Unpack - - sudo -u www-data tar xvf web.tar.gz . - -Change write permission on the storage directory. - - sudo chown www-data -R storage bootstrap/cache config/kerberos.php - sudo chmod -R 775 storage bootstrap/cache - sudo chmod 0600 config/kerberos.php - - -## Auto removal - -By default images or videos **aren't removed automatically**. This means that Kerberos.io will keep writing to disk, even if there is no more space available on your SD card. When your **SD card is full** you'll be **experiencing strange errors**: a corrupt web interface, blank images or corrupt videos. - -To resolve this your should install a simple **bash script** and initiate **a cronjob** which continuously poll your filesystem, and start removing media when your disk is getting full. - -Create a bash script and copy following script. - - nano /home/pi/autoremoval.sh - -Copy following script (make sure the partition is correct, this is the default one for a Raspberry Pi). - - partition=/dev/root - imagedir=/etc/opt/kerberosio/capture/ - if [[ $(df -h | grep $partition | head -1 | awk -F' ' '{ print $5/1 }' | tr ['%'] ["0"]) -gt 90 ]]; - then - echo "Cleaning disk" - find $imagedir -type f | sort | head -n 100 | xargs -r rm -rf; - fi; - -Make the script executable. - - chmod +x /home/pi/autoremoval.sh - -Initiate a cronjob, and select the **nano** editor. - - crontab -e - -Append following line, to execute the **autoremoval.sh** script every 5min. - - */5 * * * * /bin/bash /home/pi/autoremoval.sh diff --git a/70_installation/4_Docker.md b/70_installation/4_Docker.md deleted file mode 100644 index e37e615..0000000 --- a/70_installation/4_Docker.md +++ /dev/null @@ -1,63 +0,0 @@ -# Docker - -**!!! For the moment this approach only works for IP cameras, we don't have a cross-platform method to inject a USB camera or Raspberry Pi camera !!!** - -A Docker image (x86, ARMv7, ARMv8) is available on [**the Docker Hub**](https://hub.docker.com/u/kerberos/kerberos), which contains all the necessary software to setup your security infrastructure in a matter of seconds. Before you can run this image you will have to get [**Docker**](https://docker.com) installed. After the installation you can use **docker run** to get Kerberos.io up and running, or you can opt for **dockeros** to create and scale your security infrastructure. - -## Use docker run - -After you've installed docker, you can open a command prompt and type in following command. This will pull the kerberos image and make the web interface available on port 80 and the livestream on port 8889. You can give the container a custom name using the **--name** property. - - $ docker run --name camera1 -p 80:80 -p 8889:8889 -d kerberos/kerberos - $ docker run --name camera2 -p 81:80 -p 8890:8889 -d kerberos/kerberos - $ docker run --name camera3 -p 82:80 -p 8891:8889 -d kerberos/kerberos - -## Mixed Content - -If you're using HTTPS and have mixed content errors or have no login page set **KERBEROSIO_SECURE_SSL** environment flag to 'true', **--env KERBEROSIO_SECURE_SSL=true** - - $ docker run --name camera1 -p 80:80 -p 8889:8889 -env KERBEROSIO_SECURE_SSL=true -d kerberos/kerberos - -For docker-compose add flag to environment section like below: - - environment: - - KERBEROSIO_SECURE_SSL=true - -## Or use dockeros (our docker creation tool) - -We've created a simple and small tool to auto provision and auto configure Kerberos.io containers. The idea is that you define the different configurations for every camera upfront (/environments directory), and map them to into your Docker container (using volumes). The ultimate goal is to have a fully automated and lightning fast way for provisioning your video surveillance environments in just a matter of seconds. It's also a great way to backup your security configuration. - - CAMERA 1 <<== CONTAINER1 <<== environment/cameraconfig1 - CAMERA 2 <<== CONTAINER2 <<== environment/cameraconfig2 - CAMERA 3 <<== CONTAINER2 <<== environment/cameraconfig3 - -### How to use it? - -The tool we've created is a simple bash script which we called **dockeros**, and exposes a couple of methods; discussed below. By specifying a number of parameters, **dockeros** will do all the magic dockering for you. This tool is still work in progress, so PR's and new features are welcome! - - git clone https://github.com/kerberos-io/docker - cd docker/bin - ./dockeros.sh {command} - -### Commands - -List all kerberos.io containers which are created. - - ./dockeros.sh showall - - -Remove all kerberos.io containers which were created before. - - ./dockeros.sh cleanup - -Create a kerberos.io container with a name and predefined configuration. - - ./dockeros.sh create {name} {config} {webport} {streamport} - -* **name**: This is the name of the container which will be created. - -* **config**: The configuration which needs to be injected in the container. The configuration directories can be found in the **/environments** folder. - -* **webport**: The port on which the webinterface will be served. - -* **streamport**: The port on which the livestream will be served. diff --git a/70_installation/5_Generic.md b/70_installation/5_Generic.md deleted file mode 100644 index ec2a862..0000000 --- a/70_installation/5_Generic.md +++ /dev/null @@ -1,192 +0,0 @@ -# Generic - -* [Machinery](#machinery) - * [Compile](#machinery-compile) - * [Configure](#machinery-configure) - * [Run](#machinery-run) -* [Web](#web) - * [Install webserver + PHP (optional)](#web-installation-webserver) - * [Install source](#web-installation-source) -* [Auto removal](#auto-removal) - - - -## Machinery - - -### Compile - -Update the packages and kernel. - - sudo apt-get update && sudo apt-get upgrade - -Install development tools (c++, cmake). - - sudo apt-get install git cmake subversion libav-tools dh-autoreconf libcurl4-openssl-dev yasm libx264-dev pkg-config libssl-dev - -If you want to use IP cameras, make sure to compile FFMPEG with x264 support. - - git clone https://github.com/FFmpeg/FFmpeg ffmpeg - cd ffmpeg && git checkout remotes/origin/release/2.8 - ./configure --enable-gpl --enable-libx264 --enable-shared --prefix=/usr/local - make && sudo make install - -Go to home directory and pull the machinery from github. - - cd && git clone https://github.com/kerberos-io/machinery - -Compile the machinery; this can take some time. - - cd machinery && mkdir build && cd build - cmake .. && make && make check && sudo make install - -Start the machinery on start-up. - - sudo systemctl enable kerberosio - - -### Configure - -The configuration files can be found at **/etc/opt/kerberosio/config**. By default the Raspberry Pi Camera module is set as capture device. You can update the **config.xml** file to change it to **USBCamera** or **IPCamera**. Images are stored in the **/etc/opt/kerberosio/capture** directory by default; this location can be changed by editing the **io.xml** file. - - -### Run - -After kerberos is installed a binary is available at **/usr/bin/kerberosio**. Just run following command in your terminal to start kerberosio. - - kerberosio - - -## Web - - -### Install web - -If you want to install **the web**, you'll need to have **a webserver** (e.g. Nginx) and **PHP** running with some extensions. You also need **NodeJS** and **npm** installed to install **Bower**. Below you can find the installation procedure to install the web on your preferred environment. - -**Install Dependencies** - -Install Git, PHP7 (+extensions) and NodeJS. - -A) Ubuntu - - sudo apt-get update && sudo apt-get upgrade - curl -sL https://deb.nodesource.com/setup | sudo bash - - sudo apt-get install git php7.0-cli php7.0-gd php7.0-mcrypt php7.0-curl php7.0-mbstring php7.0-dom php7.0-zip php7.0-fpm nodejs npm - sudo ln -s /usr/bin/nodejs /usr/bin/node - -B) Raspbian - - echo "deb http://mirrordirector.raspbian.org/raspbian/ stretch main contrib non-free rpi" | sudo tee --append /etc/apt/sources.list - sudo apt-get update - sudo apt-get install -t stretch php7.0 php7.0-curl php7.0-gd php7.0-fpm php7.0-cli php7.0-opcache php7.0-mbstring php7.0-xml php7.0-zip php7.0-mcrypt nodejs npm - sudo ln -s /usr/bin/nodejs /usr/bin/node - -C) OSX - - brew install php7.0 php7.0-curl php7.0-gd php7.0-fpm php7.0-cli php7.0-opcache php7.0-mbstring php7.0-xml php7.0-zip php7.0-mcrypt nodejs npm - -**Configure webserver** - -Install Nginx, - - sudo apt-get install nginx - -or if you're running OSX use brew. - - sudo brew install nginx - -Creating a Nginx config. - - sudo rm -f /etc/nginx/sites-enabled/default - sudo nano /etc/nginx/sites-enabled/default - -Copy and paste following config file; this file tells nginx where the web will be installed and that it requires PHP. - - server - { - listen 80 default_server; - listen [::]:80 default_server; - root /var/www/web/public; - server_name kerberos.rpi; - index index.php index.html index.htm; - location / - { - autoindex on; - try_files $uri $uri/ /index.php?$query_string; - } - location ~ \.php$ - { - fastcgi_pass unix:/var/run/php/php7.0-fpm.sock; - fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; - include fastcgi_params; - } - } - -**Clone source** - -Create a www location. - - mkdir -p /var/www - -Get the source code from Github. - - cd /var/www && sudo git clone https://github.com/kerberos-io/web && cd web - -Install PHP packages by using composer. - - curl -sS https://getcomposer.org/installer | sudo php - sudo mv composer.phar /usr/bin/composer - sudo composer install - -Add write permission for the storage directory, and the kerberos config file. - - sudo chmod -R 777 storage - sudo chmod -R 777 bootstrap/cache - sudo chmod 777 config/kerberos.php - -Install bower globally by using npm. - - sudo npm -g install bower - -Install Front-end dependencies with bower - - cd public - sudo bower --allow-root install - -Reboot - - sudo reboot - - -## Auto removal - -By default images or videos **aren't removed automatically**. This means that Kerberos.io will keep writing to disk, even if there is no more space available on your disk. When your **disk is full** you'll be **experiencing strange errors**: a corrupt web interface, blank images or corrupt videos. - -To resolve this your should install a simple **bash script** and initiate **a cronjob** which continuously poll your filesystem, and start removing media when your disk is getting full. - -Create a bash script and copy following script. - - nano /home/[your user]/autoremoval.sh - -Copy following script (make sure the partition is correct, this is the default one for a Raspberry Pi). - - partition=/dev/root - imagedir=/etc/opt/kerberosio/capture/ - if [[ $(df -h | grep $partition | head -1 | awk -F' ' '{ print $5/1 }' | tr ['%'] ["0"]) -gt 90 ]]; - then - echo "Cleaning disk" - find $imagedir -type f | sort | head -n 100 | xargs -r rm -rf; - fi; - -Make the script executable. - - chmod +x /home/[your user]/autoremoval.sh - -Initiate a cronjob, and select the **nano** editor. - - crontab -e - -Append following line, to execute the **autoremoval.sh** script every 5min. - - */5 * * * * /bin/bash /home/[your user]/autoremoval.sh diff --git a/71_web/1_dashboard.png b/71_web/1_dashboard.png deleted file mode 100644 index 73c4692..0000000 Binary files a/71_web/1_dashboard.png and /dev/null differ diff --git a/71_web/1_how-to-access.png b/71_web/1_how-to-access.png deleted file mode 100644 index 4caacee..0000000 Binary files a/71_web/1_how-to-access.png and /dev/null differ diff --git a/71_web/1_introduction.md b/71_web/1_introduction.md deleted file mode 100644 index cf0859c..0000000 --- a/71_web/1_introduction.md +++ /dev/null @@ -1,31 +0,0 @@ -# Introduction - -The web is responsible for the visualization. It's a **GUI** which helps the user to find activity at a specific period, configure the machinery, view a live stream, see system information and much more. - -## How does it work? - -The web is written in PHP using the extremely popular PHP Framework **Laravel**, and Javascript using the client-side framework **BackboneJS**; to create the dynamic behaviour. We will discuss the different pages and functionality briefly. Please check out the [**demo environment**](https://demo.kerberos.io) if you want to see a real life example. - -### Dashboard - -The landing page of the web is the dashboard. On the dashboard a user will see some statistics: activity per hour, activity per day, a live stream, the latest activity and a heatmap. - -![Dashboard](1_dashboard.png) - -### Overview - -When selecting a specific day, you'll will get a timeline and overview. By using the timeline you can navigate through a day; the timeline highlights the amount of activity, from gray to red. - -![Overview](1_overview.png) - -### Settings - -The settings page allows you to configure the machinery. You can define the type of camera, post-processes, conditions and much more; it's **highly configurable**. - -![Settings](1_settings.png) - -### System - -The system page allows you to **monitor** the system. On this page you'll get an overview of the **system specifications** (CPU, Memory, Network, etc). When installed KiOS, you'll also get the possibility to **update Kerberos.io** to a newer release. Several actions are available: you can **download system information** (for debugging purposes) and **download or remove** your images. - -![System](1_system.png) \ No newline at end of file diff --git a/71_web/1_overview.png b/71_web/1_overview.png deleted file mode 100644 index 7920b50..0000000 Binary files a/71_web/1_overview.png and /dev/null differ diff --git a/71_web/1_settings.png b/71_web/1_settings.png deleted file mode 100644 index 52412cd..0000000 Binary files a/71_web/1_settings.png and /dev/null differ diff --git a/71_web/1_system.png b/71_web/1_system.png deleted file mode 100644 index 0b595c3..0000000 Binary files a/71_web/1_system.png and /dev/null differ diff --git a/71_web/2_contribute.md b/71_web/2_contribute.md deleted file mode 100644 index 6cdd044..0000000 --- a/71_web/2_contribute.md +++ /dev/null @@ -1,75 +0,0 @@ -# Contribute - -* [Installation](#installation) -* [Versioning](#versioning) -* [Dependency management](#dependency-management) - * [Composer](#composer) - * [Bower](#bower) -* [Frameworks](#frameworks) - * [Laravel](#laravel) - * [BackboneJS](#backbonejs) - -Contributing to the **web** repository requires both front- and back-end sklls. This document describes how to contribute to Kerberos.io and describes all the technical stuff you will need to know. If you want to contribute, the first thing you will need to do is installing the source code on your local environment. - - -## Installation - -The installation can be found on [**the generic installation page**](/installation/generic), describing the complete set of instructions. - - -## Versioning - -As you've probably seen in the **installation summary** we are hosting our repositories on [**github**](https://github.com/kerberos-io). As any larger project we are also using a versioning strategy; an easy one :) we don't want to get the things complicated. The version strategy is based on this [**branching model**](http://nvie.com/posts/a-successful-git-branching-model/). - -The model includes: - -* master branch, -* develop branch and -* hotfixes - -The idea is that the **master** branch always contains a stable release and development happens on the **develop** branch. When we plan to create a new release we merge the develop branch to the master branch and create a new release. If **bugs are introduced** in the master branch (stable release), **hotfixes** are pushed to the master branch and merged back to the develop branch. Believe me, it's very straight-forward if you are into it. - - -## Dependency management - -The web is created with PHP and JS. It's obvious that we don't have developed all the functionality ourself, a lot of other open-source third-party libraries are used. To install these libraries (dependencies) a dependency manager is used. For the PHP side we have **composer** and for the JS side there is **bower**. - - -### Composer (PHP) - -[**Composer**](https://getcomposer.org/) is a dependency manager for PHP, which is very easy to install and use. To install composer execute following commands: - - php -r "readfile('https://getcomposer.org/installer');" > composer-setup.php - php -r "if (hash('SHA384', file_get_contents('composer-setup.php')) === '41e71d86b40f28e771d4bb662b997f79625196afcca95a5abf44391188c695c6c1456e16154c75a211d238cc3bc5cb47') { echo 'Installer verified'; } else { echo 'Installer corrupt'; unlink('composer-setup.php'); } echo PHP_EOL;" - php composer-setup.php - php -r "unlink('composer-setup.php');" - -After composer is installed properly you can just do **composer install** or **composer update** within the root directory of the **web** repository; this will update all the dependencies if a newer version is available. - - composer update - - -### Bower (JS) - -[**Bower**](http://bower.io/) is a dependency manager for JS, it's very similar to composer. To install bower you'll need to download **nodejs** and execute following command: - - npm -g install bower - -After bower is installed you can install or update dependencies within the **/public** directory. - - bower update - - -## Frameworks - -The web is created with two frameworks and a lot of third-party libraries. - - -### Laravel 5.4 - -[**Laravel**](http://laravel.com) is a very **powerful** and **popular** PHP framework. This is also the main reason why the web is created with Laravel, the community is huge. A lot of people are writing tutorials and recording webcasts. This makes **getting started** with contributing to the web repository so **easy**. You will find all the information you need on the Laravel [**documentation site**](http://laravel.com/docs/5.4). - - -### BackboneJS - -[**BackboneJS**](http://backbonejs.org/) is a **lightweight** framework. It's used in the web to create the **dynamic behaviour** and **structure** the source code. You will find all the information you need on the BackeboneJS [**documentation site**](http://backbonejs.org/). diff --git a/71_web/3_project_structure.md b/71_web/3_project_structure.md deleted file mode 100644 index bfb98f3..0000000 --- a/71_web/3_project_structure.md +++ /dev/null @@ -1,39 +0,0 @@ -# Project structure - -* [File structure](#file-structure) - * [Server](#server) - * [Client](#client) -* [Settings page](#settings-page) - - -The web contains several important concepts and this is the right place where we will explain them briefly. - - -## File structure - -The web repository is not that big, however we give you a brief overview of the most important files/directories. - -### Server -* **config/app.php** - general application settings. -* **config/kerberos.php** - this file contains Kerberos.io specific parameters; the user credentials to sign in, etc. -* **app/Http/Controllers** - MVC controllers -* **app/Http/Repositories** -repositories are injected into the controller. -* **app/Providers/AppServiceProvider.php** - bind repositories to a specific interface - dependency injection. -* **routes/api.php** - contains all the URI endpoints for Ajax calls. -* **routes/web.php** - url routing for pages. - - -### Client - -* **public/css/less** - LESS is used for the CSS. -* **public/js/app** - BackboneJS and RequireJS is used for building modular JS classes. -* **public/js/mustache** - Mustache is used for the client-side view rendering. -* **public/js/vendor** - This is where the bower extensions are installed. -* **public/capture** - A directory where images are written to by default. -* **public/bower.json** - The bower extensions used in the kerberos project. -* **public/Gruntfile.js** - We are using Grunt for our task manager. - - -## Settings page - -One of the most important reasons why the web exists is because it's a **GUI** to configure the machinery. The web contains a *settings* page where algorithms, expositors and much more can be configured. There is a basic setting view and an advanced settings view. The advanced view will convert the configuration files (from the machinery) into **HTML elements**, so e.g. when adding new algorithms or heuristics, the parameters will be shown on the settings page automatically. The only thing you need to do is to specify a type to each parameter. You will find an equivalent *view* with the same name in the **resources/views/controls** directory. diff --git a/71_web/4_aPI.md b/71_web/4_aPI.md deleted file mode 100644 index cf3647c..0000000 --- a/71_web/4_aPI.md +++ /dev/null @@ -1,184 +0,0 @@ -# API - -If you want to integrate Kerberos.io into your own application, you're at the right place! The Kerberos.io web interface comes with a **REST**full **API**, that allows you to get and modify data delivered by the Kerberos.io framework. - - * Reboot the system - * Disable Kerberos.io - * Health check - * Enable or disable output devices - * .. - - -## Authentication - -To use the RESTfull API of your Kerberos.io instance you need to define an **Authorization header** with each request. We use **Basic Authentication** to secure the different **endpoints**. - - "Authorization": "Basic root:root" - -An example with Python looks like this. - - import requests - import json - import base64 - - url = "http://ip-of-pi/api/v1/condition/enabled" - username = "user" - password = "passw" - basicAuth = base64.b64encode('%s:%s' % (username, password)) - headers = {"Authorization": "Basic " + basicAuth, "Content-Type": "application/json"} - - data = '{"active": "true"}' - - #Call REST API - response = requests.put(url, data=data, headers=headers) - - print(response.text) - -If you're using the wrong credentials, Kerberos.io will return following error message. - - Invalid credentials. - -## Endpoints - -All endpoints are prefixed with **api/v[version #]/**, in which the last part defines the API version number. Below you will find all the available endpoints with there signature and response. Note that when you call an endpoint which doesn't exists, Kerberos.io will throw an 404. - - { - "error": "API method does not exists" - } - -## API version 1 - -A list of all API methods available for version 1. - -
- GET api/v1/name -
-
- -**Description** - -Retrieve the name of your instance. - -**Response** - - { - "name": "frontdoor" - } - - -
- PUT api/v1/name -
-
- -**Description** - -Change the name of your instance. - -**Data** - - { - "name": "frontdoor-changed" - } - -
- GET api/v1/images/latest_sequence -
-
- -**Description** - -Retrieve the latest sequence detected. - -**Response** - - [ - { - time: "10:59:57", - src: "https://demo.kerberos.io/capture/1501491597_6-310145_frontdoor_722-691-873-926_703_511.mp4", - local_src: "/var/www/web/public/capture/1501491597_6-310145_frontdoor_722-691-873-926_703_511.mp4", - metadata: { - key: "1501491597_6-310145_frontdoor_722-691-873-926_703_511.mp4", - user: "1501491597_6-310145_frontdoor_722-691-873-926_703_511.mp4", - timestamp: 1501491597, - microseconds: "6-310145", - instanceName: "frontdoor", - regionCoordinates: "722-691-873-926", - numberOfChanges: "703", - token: "511" - }, - type: "video" - } - ] - -**Response** - -Similar to **GET api/v1/name**. - -
- GET api/v1/condition/enabled -
-
- -**Description** - -Check if enabled or disabled. - -**Response** - - { - "active": "true", - "delay": "5000" - } - -
- PUT api/v1/condition/enabled -
-
- -**Description** - -Activate or disable the system - -**Data** - - { - "active": "false" - } - -**Response** - -Similar to **GET api/v1/condition/enabled**. - -
- GET api/v1/system/health -
-
- -**Description** - -Check if the machinery is running (the stream is connected). - -**Response** - - { - "status": "false" - } - -
- POST api/v1/system/reboot -
-
- -**Description** - -Restart the system. - -
- POST api/v1/system/shutdown -
-
- -**Description** - -Shutdown the system. diff --git a/72_machinery/1_introduction.md b/72_machinery/1_introduction.md deleted file mode 100644 index c8fabe1..0000000 --- a/72_machinery/1_introduction.md +++ /dev/null @@ -1,48 +0,0 @@ -# Introduction - -The machinery is responsible for the processing. It's **an image processing framework** which 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. - -## How does it work? - -The machinery is an **image processing framework** which is devided into four steps: - -* condition -* algorithm -* expositor -* heuristic - -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. - -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 Kerberos.io. 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. - -![Lifecycle](1_project_structure.png) - - -### Capture/Camera - -You can choose which capture device you will be using, you can use your old USB-webcam, the **hi-tech** and **cheap** Raspberry Pi camera or a **fancy** 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. - - -### Condition - -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. - - -### Algorithm - -The algorithm is the second step of the four passway. An algorithm will execute some kind of function on a sequence of images. An example of an algorithm would be one that does motion detection or one that would detect cats or dogs. - - -### Expositor - -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. - - -### Heuristic - -When the expositor detected a region where activity was detection, a **heuristic** will evaluate, the current and previous detections. The heuristic is basically some kind of memory which makes a decision and tells the machinery if the detection was true or false. - - -### IO - -The IO is a post-process which takes action when the heuristic is valid. Examples of an IO device are: saving a snapshot, triggering a GPIO pin, sending an e-mail, etc. \ No newline at end of file diff --git a/72_machinery/1_project_structure.png b/72_machinery/1_project_structure.png deleted file mode 100644 index 8b54153..0000000 Binary files a/72_machinery/1_project_structure.png and /dev/null differ diff --git a/72_machinery/3_contribute.md b/72_machinery/3_contribute.md deleted file mode 100644 index b8fa40e..0000000 --- a/72_machinery/3_contribute.md +++ /dev/null @@ -1,289 +0,0 @@ -# Contribute - -* [Installation](#installation) -* [Versioning](#versioning) -* [IDE](#ide) - * [CLion](#clion) -* [Testing](#testing) - * [Continous integration](#continous-integration) - * [Unit testing / Mocking](#unit-testing-mocking) -* [Adding a new class](#adding-a-new-class) - * [Create the header file](#create-the-header-file) - * [Create the source file](#create-the-source-file) - * [Modify the CMakeLists.txt file](#modifile-the-cmakelists-file) - * [Create a new entry in the config file](#create-a-new-entry-in-the-config-file) - * [Compile](#compile) -* [Adding a test](#adding-a-test) - * [Create the test file](#create-the-test-file) - -Contributing to the **machinery** repository requires C++ sklls. This document describes how to contribute to Kerberos.io and describes all the technical stuff you will need to know. If you want to contribute, the first thing you will need to do is installing the source code on your local environment. - - -## Installation - -The complete installation can be found on [**the advanced installation page**](/installation/advanced), describing the complete set of instructions. However for simplicity we will give a summarized version, as probably you will already have a development environment set up. - -Install development tools (c++, cmake) and V4L utils. - - sudo apt-get install git libav-tools cmake subversion dh-autoreconf libcurl4-openssl-dev - -Go to home directory and pull the machinery from github. - - cd && sudo git clone https://github.com/kerberos-io/machinery - -Compile the machinery; this can take some time. - - cd machinery && mkdir build && cd build - cmake .. && make && make check && sudo make install - -That's it.. - - -## Versioning - -As you've probably seen in the **installation summary** we are hosting our repositories on [**github**](https://github.com/kerberos-io). As any larger project we are also using a versioning strategy; an easy one :) we don't want to get the things complicated. The version strategy is based on this [**branching model**](http://nvie.com/posts/a-successful-git-branching-model/). - -The model includes: - -* master branch, -* develop branch and -* hotfixes - -The idea is that the **master** branch always contains a stable release and development happens on the **develop** branch. When we plan to create a new release we merge the develop branch to the master branch and create a new release. If **bugs are introduced** in the master branch (stable release), **hotfixes** are pushed to the master branch and merged back to the develop branch. Believe me, it's very straight-forward if you are into it. - - -## IDE - - -### CLion - -Contributing to the machinery by using CLion is **very easy**. You just need to **open the root folder** of the machinery and run the project. CLion will compile the source code by using cmake. You don't have to do anything. - - -## Testing - - -### Continous integration - -The machinery is build automatically on **Travis-CI**, when a new commit/release is pushed. - - -### Unit testing / Mocking - -We strongly recommend testing as a best practice in complex projects. Therefore the machinery uses the popular C++ test library: Google Test and Google Mock. The tests can be found in the **test** directory. You can run the test by executing following command: - - make check - - -## Adding a new class - -This paragraph will tell you how to create a new condition, algorithm, expositor, io or capture device. For simplicity we will show how to create a new algorithm; the steps are identical if you want to create for example a new capture device; only the directory will differ. - - -### Create the header file - -First we will need to create a new header file in the **include/kerberos/machinery/algorithm** directory. You can copy an existing algorithm header file, and start from there. You will end up with the following header file: - - // - // Class: AnotherAlgorithm - // Description: Another algorithm - // Created: ... - // Author: ... - // Mail: ... - // Website: ... - // - // The copyright to the computer program(s) herein - // is the property of kerberos.io, Belgium. - // The program(s) may be used and/or copied . - // - ///////////////////////////////////////////////////// - #ifndef __AnotherAlgorithm_H_INCLUDED__ // if AnotherAlgorithm.h hasn't been included yet... - #define __AnotherAlgorithm_H_INCLUDED__ // #define this so the compiler knows it has been included - #include "machinery/algorithm/Algorithm.h" - namespace kerberos - { - char AnotherAlgorithmName[] = "AnotherAlgorithm"; - class AnotherAlgorithm : public AlgorithmCreator - { - private: - Image m_result; - int m_parameter; - public: - AnotherAlgorithm(){} - void setup(const StringMap & settings); - void initialize(ImageVector & images); - Image evaluate(ImageVector & images, JSON & data); - void setParameter(int parameter); - }; - } - #endif - -When creating a new class you will need to inherit from it corresponding creator, for the algorithm example: AlgorithmCreator. The creator class **requires two template parameters**. The first one is a unique name for the class, this name will be used to make some kind of dependency injection possible; and **is used in the configurations files**. The second parameter is the class itself. - -The inheritance of the creator class can be a little bit strange, but it is required and needed **to register the class automatically** with the factory. When the code gets compiled, the classes will be automatically registered with the factory, and you can create instances of those classes by using the name we've defined in the first template parameter. For example we could create a new instance of our previously created class with the following command. - - Algorithm * anotherAlgorithm = Factory::getInstance()->create("AnotherAlgorithm"); - - -### Create the source file - -Ofcourse we also need to have an implementation file, therefore we need to create a new source file in the **src/kerberos/machinery/algorithm** directory. Just like the previous example, you can copy an existing class and implement the member functions you've declared in the header file. An example would be: - - #include "machinery/algorithm/AnotherAlgorithm.h" - namespace kerberos - { - void AnotherAlgorithm::setup(const StringMap & settings) - { - Algorithm::setup(settings); - int parameter = std::atoi(settings.at("algorithms.AnotherAlgorithm.parameter").c_str()); - setParameter(parameter); - } - void AnotherAlgorithm::initialize(ImageVector & images) - { - .... - } - Image AnotherAlgorithm::evaluate(ImageVector & images, JSON & data) - { - Image evaluation; - ... do something .. - return evaluation; - } - void AnotherAlgorithm::setParameter(int parameter) - { - m_parameter = parameter; - } - } - - -### Modify the CMakeLists.txt file - -Open the CMakeLists.txt in the **src/kerberos** directory file and append the name of the algorithm class to the **KERBEROS_FACTORY_ENTITIES** variable; for example **machinery/algorithm/AnotherAlgorithm.cpp**. - - # ------------------------------------------------------- - # Entities that have to be registered with the factory - # - classes are registered on compile time, so they - # don't belong to a library. New algorithms, expositors - # or Io classes belong here. - set(KERBEROS_FACTORY_ENTITIES - capture/USBCamera.cpp - machinery/condition/Time.cpp - machinery/condition/Enabled.cpp - machinery/algorithm/DifferentialCollins.cpp - machinery/algorithm/DifferentialCollinsWithColor.cpp - machinery/algorithm/AnotherAlgorithm.cpp - machinery/expositor/RectangleExpositor.cpp - machinery/expositor/HullExpositor.cpp - machinery/heuristic/Sequence.cpp - machinery/io/IoDisk.cpp - machinery/io/IoTCP.cpp - machinery/io/IoMongoDB.cpp - ) - - -### Create a new entry in the config file - -Open the algorithm.xml file in the **config** directory, and add a new tag with exactly the same name you've used in the header file; so in our example "AnotherAlgorithm". Within the new tag we can add properties that we will be use to configure our algorithm, in our example we defined a field **parameter** so we can add this field in the config file. - -One thing you will need to do is to attach a **type** to a property. The type will be used by the web to **automatically render** the properties. For simplicity we can use the type number, this will show an input box on the settings page of the web where we are able to add numbers. - - - - 5 - - - -You can retrieve the parameter in the **setup** function with the settings parameter. - - settings.at("algorithms.AnotherAlgorithm.parameter") - - -### Compile - -Hurray, we've made it! So now you can compile the code again, and if you're using an IDE don't forget to include the new source file! If you are compiling from the command-line you just have to go to the build folder and write **make**. - - -## Adding a new test - -When someone adds a class for a new io device, algorithm or expositor, he/she will need to write some documentation about the class but also need to provide some unit tests. This paragraph will provide you all the information about writing a simple test. - - -### Create the test file - -Add a new file to the **test/** directory, prefix the file with **test_** e.g. test_condition_enabled.cpp. Include the **gtest** and **gmock** headers; and also the Factory and Type headers. Write a new test condition, this is where the assert will be executed. - - #include "gtest/gtest.h" - #include "gmock/gmock.h" - #include "Factory.h" - #include "Types.h" - using ::testing::AtLeast; - using ::testing::Return; - using namespace kerberos; - // ---------------------------------------- - // Enabled condition: allowed function - TEST(ENABLED_CONDITION, ALLOWED) - { - Condition * condition = Factory::getInstance()->create("Enabled"); - // This is only for mocking - ImageVector images; - StringMap settings; - settings["conditions.Enabled.delay"] = "2000"; - // Enable condition - settings["conditions.Enabled.active"] = "true"; - condition->setup(settings); - bool canExecute = condition->allowed(images); - EXPECT_EQ(true, canExecute); - // Disable condition - settings["conditions.Enabled.active"] = "false"; - condition->setup(settings); - canExecute = condition->allowed(images); - EXPECT_EQ(false, canExecute); - } - -### Run tests - -To execute the test you can run the **make check** in the **build/** directory. When you've added a new test file, you will need to execute the **cmake** command again. - - cd build/ - cmake .. - make check - -You will get following output - - macbook:build cedricverstraeten$ make check - [ 1%] Built target EXECUTOR_LIBRARY - [ 8%] Built target TINYXML_LIBRARY - [ 16%] Built target FILEWATCHER_LIBRARY - [ 29%] Built target opencv - [ 49%] Built target KERBEROS_CORE - [ 62%] Built target googletest - [ 75%] Built target googlemock - [100%] Built target kerberos-test - [==========] Running 6 tests from 5 test cases. - [----------] Global test environment set-up. - [----------] 1 test from ENABLED_CONDITION - [ RUN ] ENABLED_CONDITION.ALLOWED - [ OK ] ENABLED_CONDITION.ALLOWED (2002 ms) - [----------] 1 test from ENABLED_CONDITION (2002 ms total) - [----------] 2 tests from HELPER - [ RUN ] HELPER.T_TO_STRING - [ OK ] HELPER.T_TO_STRING (0 ms) - [ RUN ] HELPER.NORMALIZE_PATH - [ OK ] HELPER.NORMALIZE_PATH (0 ms) - [----------] 2 tests from HELPER (0 ms total) - [----------] 1 test from HULL_EXPOSITOR - [ RUN ] HULL_EXPOSITOR.CALCULATE - [ OK ] HULL_EXPOSITOR.CALCULATE (1 ms) - [----------] 1 test from HULL_EXPOSITOR (1 ms total) - [----------] 1 test from RECTANGLE_EXPOSITOR - [ RUN ] RECTANGLE_EXPOSITOR.CALCULATE - [ OK ] RECTANGLE_EXPOSITOR.CALCULATE (0 ms) - [----------] 1 test from RECTANGLE_EXPOSITOR (0 ms total) - [----------] 1 test from SEQUENCE_HEURISTIC - [ RUN ] SEQUENCE_HEURISTIC.IS_VALID - [ OK ] SEQUENCE_HEURISTIC.IS_VALID (1005 ms) - [----------] 1 test from SEQUENCE_HEURISTIC (1005 ms total) - [----------] Global test environment tear-down - [==========] 6 tests from 5 test cases ran. (3008 ms total) - [ PASSED ] 6 tests. - [100%] Built target check - macbook:build cedricverstraeten$ diff --git a/72_machinery/3_header-paths.png b/72_machinery/3_header-paths.png deleted file mode 100644 index a7c534c..0000000 Binary files a/72_machinery/3_header-paths.png and /dev/null differ diff --git a/72_machinery/3_library-paths.png b/72_machinery/3_library-paths.png deleted file mode 100644 index 7f0c104..0000000 Binary files a/72_machinery/3_library-paths.png and /dev/null differ diff --git a/72_machinery/3_select-search-criteria.png b/72_machinery/3_select-search-criteria.png deleted file mode 100644 index a305b2c..0000000 Binary files a/72_machinery/3_select-search-criteria.png and /dev/null differ diff --git a/72_machinery/4_project_structure.md b/72_machinery/4_project_structure.md deleted file mode 100644 index 9e9b665..0000000 --- a/72_machinery/4_project_structure.md +++ /dev/null @@ -1,89 +0,0 @@ -# Project structure - -* [File structure](#file-structure) -* [CMake](#cmake) - * [CMake setup](#cmake-setup) - * [Src folder](#src-folder) - * [CMake folder](#cmake-folder) -* [Technical design](#techinal-design) - * [Configuration](#configuration) - * [Filewatcher](#filewatcher) - * [Factory](#factory) -* [Dependencies](#dependencies) - * [Image Processing](#image-processing) - * [RapidJSON](#rapidjson) - * [Easylogging](#easylogging) - - -## File structure - -* **bin** - contains the compiled and linked executable. -* **build** - contains all the compiled dependencies and source code. -* **cmake** - external dependencies. -* **config** - configuration files that are used to configure Kerberos.io. -* **exceptions** - custom exceptions. -* **include** - header files. -* **logs** - logging. -* **src** - source files. -* **test** - google tests - - -## CMake - -As mentioned before the machinery is using CMake. Therefore if you want to compile the source code, you will need to have CMake installed first. When executing the **CMake** command, CMake will create the appropriate makefiles to compile the machinery. - - -### CMake setup - -At the root of the project you will find **the main CMakeList.txt** file, and this is where everything starts. The root CMake file will include all the other CMake files; which are located in the **src** and **cmake** folder. - - -#### Src folder - -The **src** folder includes the machinery. You will find a CMakeLists.txt file in the folder and every subfolder. The CMakeLists.txt is reponsible for the directory it belongs to and will contain all the necesarry commands. - - -#### CMake folder - -The **CMake** directory in the root folder, contains the cmakefiles that will download all the dependencies. The CMake files describe where the dependencies are located (Github, SVN, etc.) but also how they need to be build, configured and/or installed. - - -## Technical design - -The machinery has some technical design concepts, the most important parts are described below. - - -### Configuration - -When the machinery is started, the first thing it will do is read the configuration files; XML files. The configuration file contains which algorithm, expositor, or capture device are selected, and the parameters they require. When the configuration is done, the machinery will enter the four passway and start the recognition. The configuration file can be modified on the settings page from the web, but could also be modified manually; in the config directory of the machinery. - - -### Filewatcher - -When the configuration file is modified, we don't need to restart the machinery ourself. The machinery uses a filewatcher, named **Guard**, that will reconfigure the machinery on the fly without restarting the machinery itself. For example, if a user want to change the time constraints, or wants to enlarge the resolution of the captured images. - - -### Factory - -The machinery uses the **factory class registration pattern**. Algorithms, expositors, heurstics and conditions are registered to the factory on compilation. Thanks to this mechanism, developers don't have to modify other classes than those they've created. So for example if a developer would add a new algorithm he will just need to create a new header and implementation file, and map a unique name to the class in the implementation file; this behaviour is similar to dependency injection without using reflection; reflection is not available in C++. - - -## Dependencies - -The machinery has some dependencies, which are installed on the fly, when compiling machinery. We are using the externalproject feature of the cmake autotool to get the different depedencies from their source control (Github, SVN, ..). - - -### Image Processing - -Kerberos.io is a video recognition framework and is therefore using a image processing library: [**OpenCV (Open Source Computer Vision)**](https://github.com/Itseez/opencv). Thanks to this very powerful computer vision framework, developers can re-use complex algorithms. - - -### Rapidjson - -The machinery is using [**the rapidjson library**](https://github.com/miloyip/rapidjson) to provide a flexible datastructure: JSON. The library is **used within the core of the machinery**, and is concerned within every step of the four pass way; except in the first step the condition, to be 100% correct. - - - -### Easylogging - -The [**easylogging library**](https://github.com/easylogging/easyloggingpp)is used to support the logging in the machinery. Trivials logging is enabled by default, and will be written to the **logs/log.stash** file. When enabled verbose logging (it's an option in the configuration files), extensive logging is added. \ No newline at end of file diff --git a/72_machinery/5_capture.md b/72_machinery/5_capture.md deleted file mode 100644 index d08d704..0000000 --- a/72_machinery/5_capture.md +++ /dev/null @@ -1,24 +0,0 @@ -# Capture - -* [USB camera](#usb-camera) -* [IP camera](#ip-camera) -* [Raspberry Pi camera](#raspberry-pi-camera) - -The capture device is responsible to take images. The images are used in the four pass way. - - -## USB camera - -Kerberos supports a whole range of USB cameras. You will find a complete list [here](https://web.archive.org/web/20120815172655/http://opencv.willowgarage.com/wiki/Welcome/OS/). Make sure that you've updated the settings page on the web interface, that you will be using an USB camera. - - -## IP camera - -Kerberos can be used with any IP camera, that provides a streaming URL. Make sure that you know the correct URL of your IP camera, you can find [a list here](http://www.ispyconnect.com/sources.aspx). Make sure you have updated the web interface, to make Kerberos aware you will be using an IP camera. - - -## Raspberry Pi camera - -You can use the Raspberry Pi camera (v1.3 and v2.1) with Kerberos.io, you just need to attach the camera and you are ready to go. The Raspberry Pi Camera Module is enabled by default in the web interface. Please note that if you are running Raspbian, you'll **need to enable the camera module** yourself. - -Using the Raspberry Pi camera will give **the best performance**, because Kerberos.io uses hardware acceleration for both the live streaming and the video recording. On a Raspberry Pi Zero W, **HD/30 FPS** can be achieved **with ease**. diff --git a/72_machinery/6_condition.md b/72_machinery/6_condition.md deleted file mode 100644 index 4d2c1eb..0000000 --- a/72_machinery/6_condition.md +++ /dev/null @@ -1,16 +0,0 @@ -# Condition - -* [Time](#time) -* [Enabled](#enabled) - -The condition is the first step of Kerberos. A condition is, like the word states, a conditional statement. One or more conditions can be selected (a sequence of conditions), that have to be valid. When the sequence of conditions is valid, Kerberos will go to the next step of the four passway, the algorithm. When one of the conditions in the sequence fail, Kerberos will idle for a specific time according the condition that failed. - - -## Time - -A user can set a time range for each day of the week. The condition is valid if the current time is within the time range, for that specific day. - - -## Enabled - -A user can select a checkbox to enable Kerberos. \ No newline at end of file diff --git a/72_machinery/70_captures/1_USB-camera.md b/72_machinery/70_captures/1_USB-camera.md deleted file mode 100644 index 67f3595..0000000 --- a/72_machinery/70_captures/1_USB-camera.md +++ /dev/null @@ -1,33 +0,0 @@ -# USB-Camera - -Kerberos.io supports a whole range of USB-cameras. You will find a complete list [**here**](https://web.archive.org/web/20120815172655/http://opencv.willowgarage.com/wiki/Welcome/OS/). Make sure you have updated the web interface, to make Kerberos.io aware you will be using an USB camera. [**Be careful**](http://raspberrypi.stackexchange.com/questions/340/how-much-power-can-be-provided-through-usb) that you don't attach USB-devices that require more than 100mA. - -## Parameters - -The parameters of the USB-camera 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. - - - - 1280 - 720 - 0 - 0 - 0 - - - -### Framewidth and -height - -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. - -### Device number - -If more than one device is connected, you can specify the index of the USB-camera. The index is an integer (1-5). - -### Delay - -You can provide a delay/interval (milliseconds) between two captures. - -### Angle - -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. diff --git a/72_machinery/70_captures/1_usb-camera.png b/72_machinery/70_captures/1_usb-camera.png deleted file mode 100644 index a2f629e..0000000 Binary files a/72_machinery/70_captures/1_usb-camera.png and /dev/null differ diff --git a/72_machinery/70_captures/2_IP-camera.md b/72_machinery/70_captures/2_IP-camera.md deleted file mode 100644 index dbc2edc..0000000 --- a/72_machinery/70_captures/2_IP-camera.md +++ /dev/null @@ -1,33 +0,0 @@ -# IP-camera - -Kerberos.io 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 find [a list here](http://www.ispyconnect.com/sources.aspx). Make sure you have updated the web, to make Kerberos.io aware you will be using an IP-camera. - -## Parameters - -The parameters of the IP capture device 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. - - - - http://username:password@ipaddress/image.jpg - 800 - 640 - 0 - 0 - - - -### URL - -To use your IP-camera, you should provide a valid RTSP (or MJPEG) URL. Kerberos.io will take snapshots from this stream. - -### Framewidth and -height - -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. - -### Delay - -You can provide a delay/interval (milliseconds) between two captures. - -### Angle - -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. diff --git a/72_machinery/70_captures/2_ip-camera.png b/72_machinery/70_captures/2_ip-camera.png deleted file mode 100644 index 2d9a1c9..0000000 Binary files a/72_machinery/70_captures/2_ip-camera.png and /dev/null differ diff --git a/72_machinery/70_captures/3_RPi-camera.md b/72_machinery/70_captures/3_RPi-camera.md deleted file mode 100644 index 6d4579c..0000000 --- a/72_machinery/70_captures/3_RPi-camera.md +++ /dev/null @@ -1,41 +0,0 @@ -# RPi-camera - -You can use the Raspberry Pi Camera Module with Kerberos.io. You just need [**to attach the camera module**](https://www.raspberrypi.org/help/camera-module-setup/) and you're ready to go. The Raspberry Pi Camera Module is enabled by default in the web. - -## Parameters - -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. - - - - 640 - 480 - 1400 - 0 - 30 - 0 - 0 - 0 - 50 - - - -### Framewidth and -height - -You can set the resolution of the camera module, make sure the resolution you've defined is valid. - -### Delay - -You can provide a delay/interval (milliseconds) between two captures. - -### Angle - -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. - -### Framerate - -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. - -### Sharpness, saturation, contrast, brightness - -Camera properties which you can specify to tune the settings to your needs. diff --git a/72_machinery/70_captures/3_raspi-camera.png b/72_machinery/70_captures/3_raspi-camera.png deleted file mode 100644 index 13a8397..0000000 Binary files a/72_machinery/70_captures/3_raspi-camera.png and /dev/null differ diff --git a/72_machinery/7_algorithm.md b/72_machinery/7_algorithm.md deleted file mode 100644 index 9aefbce..0000000 --- a/72_machinery/7_algorithm.md +++ /dev/null @@ -1,16 +0,0 @@ -# Algorithm - -* [Differential Images](#differential-images) - -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. - -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. - -![Black and white image](7_black-and-white-image.png) - -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. - - -## Differential Images - -This is a trivial **motion detection algorithm**. Three images are compared, and the pixels that have been changed are marked as white pixels, pixels that are black are background images. \ No newline at end of file diff --git a/72_machinery/7_black-and-white-image.png b/72_machinery/7_black-and-white-image.png deleted file mode 100644 index 03aa907..0000000 Binary files a/72_machinery/7_black-and-white-image.png and /dev/null differ diff --git a/72_machinery/80_conditions/1_time-condition.png b/72_machinery/80_conditions/1_time-condition.png deleted file mode 100644 index dbe651f..0000000 Binary files a/72_machinery/80_conditions/1_time-condition.png and /dev/null differ diff --git a/72_machinery/80_conditions/1_time.md b/72_machinery/80_conditions/1_time.md deleted file mode 100644 index 89e7891..0000000 --- a/72_machinery/80_conditions/1_time.md +++ /dev/null @@ -1,23 +0,0 @@ -# Time - -It can be helpful to **enable or disable Kerberos.io 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, Kerberos.io will be enabled. - -## Parameters - -The parameters of the Time condition can be found in the **config/condition.xml** file, but you can also use the web to modify the parameters. Below you see a default configuration file. - - - - - - -### Times - -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. - -### Delay - -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 Kerberos.io will idle for the specified delay time. The value of the delay is expressed in miliseconds. diff --git a/72_machinery/80_conditions/2_enabled-condition.png b/72_machinery/80_conditions/2_enabled-condition.png deleted file mode 100644 index 6c25ae0..0000000 Binary files a/72_machinery/80_conditions/2_enabled-condition.png and /dev/null differ diff --git a/72_machinery/80_conditions/2_enabled.md b/72_machinery/80_conditions/2_enabled.md deleted file mode 100644 index 37325b3..0000000 --- a/72_machinery/80_conditions/2_enabled.md +++ /dev/null @@ -1,22 +0,0 @@ -# Enabled - -This condition makes it possible to **disable/enable Kerberos.io**, with a simple true/false parameter. This is helpful when you're expecting a lot of activity, and you don't want Kerberos.io to trigger all those events. - -## Parameters - -The parameters of the Time condition can be found in the **config/condition.xml** file, but you can also use the web to modify the parameters. Below you see a default configuration file. - - - - true - 5000 - - - -### Active - -The active field is boolean value (true/false). When the active field is true, Kerberos.io is enabled, if not it's disabled. - -### Delay - -The delay value is used when the condition failed, so when enabled is set to false. In that case Kerberos.io will idle for the specfied delay time. The value of the delay is expressed in miliseconds. diff --git a/72_machinery/81_algorithms/1_differential-images.png b/72_machinery/81_algorithms/1_differential-images.png deleted file mode 100644 index 0ff1946..0000000 Binary files a/72_machinery/81_algorithms/1_differential-images.png and /dev/null differ diff --git a/72_machinery/81_algorithms/1_differential_images.md b/72_machinery/81_algorithms/1_differential_images.md deleted file mode 100644 index 18aa8a2..0000000 --- a/72_machinery/81_algorithms/1_differential_images.md +++ /dev/null @@ -1,38 +0,0 @@ -# Differential images - -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. - -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 Kerberos.io project, we will use the method of *Collins et al.* as this method erases the phenomenon "ghosting". - -![Differential images](1_differential_images.png) - -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. - -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)). - -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 elimante false positives. - -A more detailed explanation can be found [here](http://blog.cedric.ws/opencv-simple-motion-detection). - -## Parameters - -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. - - - - 5 - 20 - - - -### Erode - -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](http://docs.opencv.org/doc/tutorials/imgproc/erosion_dilatation/erosion_dilatation.html). 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. - -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. - -### Threshold - -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. - -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. diff --git a/72_machinery/81_algorithms/1_differential_images.png b/72_machinery/81_algorithms/1_differential_images.png deleted file mode 100644 index 414c02c..0000000 Binary files a/72_machinery/81_algorithms/1_differential_images.png and /dev/null differ diff --git a/72_machinery/81_algorithms/2_background_subtraction.md b/72_machinery/81_algorithms/2_background_subtraction.md deleted file mode 100644 index 338cee1..0000000 --- a/72_machinery/81_algorithms/2_background_subtraction.md +++ /dev/null @@ -1,51 +0,0 @@ -# Background subtraction - -This Background subtraction algorithm is **a more advanced** method in comparison to the **Differential images** method. The key difference is that it uses and calculates a background image. Images taken from the capture device are then subtracted from the background image, resulting in a more robust segmentation of the foreground. As this method is more accurate, it also **consumes a lot more CPU power and memory**; the background model is adapted by every iteration. - -The algorithm is described in [**following paper**](http://personal.ee.surrey.ac.uk/Personal/R.Bowden/publications/avbs01/avbs01.pdf). - -## Parameters - -The parameters of the Background 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. - - - - true - 50 - 5 - 1 - 5 - 7 - 20 - - - -### Shadows - -The shadows parameter is a true or false. By using this parameter you can make the Background subtraction a little bit more intelligent; to **neglect shadows in the foreground model**. - -### History - -This is an integer which tells the system, **the amount of images the system should take into account (history)**, to calculate the background model. The higher the history integer, the more images it will use to calculate the background model. By **increasing the history** you get **a more stable background** model, but a **less flexibl**e. As more images from the past are taken into account, the slower the background model will adapt to a new scenario. E.g. when a car drives into your street, and stands still for 5 minutes. - -Finding the ideal history parameters, depends heavily in the application you want to use it. In practice this **is achieved by trial and error**. - -### NMixtures - -Sets the number of gaussian components in the background model. - -### Ratio - -If a foreground pixel keeps semi-constant value for about backgroundRatio*history frames, it’s considered background and added to the model as a center of a new component. - -### Erode - -Find a more detailed explanation at the [**Differential images section**](algorithms/Differential_images). - -### Dilate - -Dilate is exactly the same as the erode parameter, except that it has the reverse behaviour; instead of removing isolated pixels it will connect them. The dilate function is mainly used in segmentation techniques, to create **a more complete segment**; it fills gaps. The higher the number of the erode parameter, the more aggressive the dilating will be. - -### Threshold - -Find a more detailed explanation at the [**Differential images section**](algorithms/Differential_images). diff --git a/72_machinery/82_expositors/1_rectangle-expositor.png b/72_machinery/82_expositors/1_rectangle-expositor.png deleted file mode 100644 index 9004f7c..0000000 Binary files a/72_machinery/82_expositors/1_rectangle-expositor.png and /dev/null differ diff --git a/72_machinery/82_expositors/1_rectangle.md b/72_machinery/82_expositors/1_rectangle.md deleted file mode 100644 index 647578e..0000000 --- a/72_machinery/82_expositors/1_rectangle.md +++ /dev/null @@ -1,23 +0,0 @@ -# Rectangle - -This rectangle is a trivial expositor. A rectangle region can be defined to constrain the locations of pixels of interest; for example if you only want to have detection at your front door. The rectangle repositor will return the bounding rectangle of the pixels of interest. - -## Parameters - -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. - - - - - 0 - 0 - 1280 - 720 - - - - - -### Region - -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. diff --git a/72_machinery/82_expositors/2_hull-expositor.png b/72_machinery/82_expositors/2_hull-expositor.png deleted file mode 100644 index 4596c58..0000000 Binary files a/72_machinery/82_expositors/2_hull-expositor.png and /dev/null differ diff --git a/72_machinery/82_expositors/2_hull.md b/72_machinery/82_expositors/2_hull.md deleted file mode 100644 index 3475a91..0000000 --- a/72_machinery/82_expositors/2_hull.md +++ /dev/null @@ -1,20 +0,0 @@ -# Hull - -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. - -![Hull expositor](2_hull-expositor.png) - -## Parameters - -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. - - - - 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 - -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. diff --git a/72_machinery/83_heuristics/1_sequence-heuristic.png b/72_machinery/83_heuristics/1_sequence-heuristic.png deleted file mode 100644 index 8b5edf6..0000000 Binary files a/72_machinery/83_heuristics/1_sequence-heuristic.png and /dev/null differ diff --git a/72_machinery/83_heuristics/1_sequence.md b/72_machinery/83_heuristics/1_sequence.md deleted file mode 100644 index b224728..0000000 --- a/72_machinery/83_heuristics/1_sequence.md +++ /dev/null @@ -1,28 +0,0 @@ -# Sequence - -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. - -## Parameters - -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. - - - - 1 - 1 - 2000 - - - - -### Minimum changes - -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. - -### Minimum durations - -The minimum number of detections in a row to be a valid detection. - -### No motion delay time - -When the heuristic failed, due to not enough pixels changed or not x detections in a row, the heuristic will idle for some time. diff --git a/72_machinery/83_heuristics/2_counter-heuristic-center-of-mass.png b/72_machinery/83_heuristics/2_counter-heuristic-center-of-mass.png deleted file mode 100644 index e136722..0000000 Binary files a/72_machinery/83_heuristics/2_counter-heuristic-center-of-mass.png and /dev/null differ diff --git a/72_machinery/83_heuristics/2_counter-heuristic-trajectory.png b/72_machinery/83_heuristics/2_counter-heuristic-trajectory.png deleted file mode 100644 index b111167..0000000 Binary files a/72_machinery/83_heuristics/2_counter-heuristic-trajectory.png and /dev/null differ diff --git a/72_machinery/83_heuristics/2_counter-heuristic.png b/72_machinery/83_heuristics/2_counter-heuristic.png deleted file mode 100644 index 64c6ecd..0000000 Binary files a/72_machinery/83_heuristics/2_counter-heuristic.png and /dev/null differ diff --git a/72_machinery/83_heuristics/2_counter.md b/72_machinery/83_heuristics/2_counter.md deleted file mode 100644 index c6a1a60..0000000 --- a/72_machinery/83_heuristics/2_counter.md +++ /dev/null @@ -1,86 +0,0 @@ -# Counter - -**Counting objects/people** forms the basis for a range of high-tech solutions, including retail analytics, queue management, building management and security applications. By using the counter heuristic **you can count incoming and outgoing objects** (e.g. people). By defining two lines, the counter heuristics can count the incoming (green line) and outgoing (red line) objects. - -![Counter heuristic](2_counter-heuristic.png) - -The quality of the Counter heuristic depends heavily on the accurancy of the chosen algorithm (Differential, Background subtraction, etc). Therefore **we recommend** to use the **Background Subtraction algorithm** as this is the most accurate one; the algorithm is used for segmentation and it will distinguish background and foreground. - -After the algorithm did its magic, the segmented image is used by the Counter heuristic to calculate some features: the **center of mass** is calculated for each foreground segment, and is stored in memory together with the height and width of the segment. By using the coordinates of the center of mass a trajectory is calculated. - -$$ \texttt{mu} \_{ji}= \sum \_{x,y} \left ( \texttt{array} (x,y) \cdot (x - \bar{x} )^j \cdot (y - \bar{y} )^i \right ) $$ - -$$ \bar{x} = \frac{\texttt{m}\_{10}}{\texttt{m}\_{00}} , \; \bar{y} = \frac{\texttt{m}\_{01}}{\texttt{m}\_{00}} $$ - -![Center of mass](2_counter-heuristic-center-of-mass.png) - -While the capture device is taking images, the counter heuristic will calculate the features (as mentioned before) for every subsequent frame. When calculated **the heuristic will search for the best match**: the closest, in terms of distance, center of mass is searched from the previous calculation. When the best match is found the center of mass (with its features) is added to the feature list of the best match; or if not found, a new feature list is created. - - -The idea of the feature list is that it contains the trajectory of an object which is moving from one point to another (a person walking by). A feature list exists for every moving object in the viewport of the camera and each feature list contains the sequence of center of masses (the x- and y-coordinates of the object). - -After the center of masses are calculated, existing feature lists are expanded or new feature lists are created (the start of a new object). By using the feature lists, **the direction of the moving objects** can be calculated, as it contains the initial center of mass and the last found center of mass. - -![Trajectory](2_counter-heuristic-trajectory.png) - -As we know the trajectory of an object (and thus its direction), the intersection is calculated with the incoming (green line) and outgoing (red line). If the trajectory intersects both incoming and outgoing lines, the direction of the trajectory is used to determine which line was interesected first (and this is an incoming or outgoing object). - -## Parameters - -The parameters of the Counter 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. - - - - 5 - 90 - 1400 - true - 20 - 1000 - 100,100|100,200|200,100|200,200 - - - -### Appearance - -The appearance parameters works as a time-out value. If a feature lists hasn't been updated for x (appearance) times in a row, it's removed. The idea is that when an object has moved outside the viewport of the camera, it can't be tracked anymore. - -### Max Distance - -While calculating the center of masses, the best match is searched for each one. As the best match is calculated in function of the distance, a maximum distance is used to limit the matching process. - -### Min Area - -The center of mass is calculated for each segment which has an area which is larger than the minimum area. - -### Only true when counted - -By default the heuristic will only return true when one or more objects are marked as incoming or outgoing. However by unchecking this option you can make the heuristic return true when something changed (same behaviour as the sequence heuristic). The idea is that one wants to track the incoming and outgoing objects, but also want to have images for every change. - -### Minimum changes - -The heuristic will only procede true if enough changes have been detected. - -### No motion delay time - -When the heuristic is not valid, the heuristic will idle for some time. - -### Markers - -The start- and en-coordinates of both the incoming and outgoing lines (delimited by the pipe symbol). - -## Output - -The whole point of the counter heuristic is counting objects. Therefore when one or more incoming or outgoing objects are detected the results are added to the JSON object which is passed along the four passway. The JSON object can be retrieved by using the [**Webhook IO device**](/machinery/Outputs/webhook). - - [ - 'regionCoordinates' : [618, 317, 703, 493], - 'numberOfChanges' : 5446, - 'incoming' : 0, - 'outgoing' : 1, - 'timestamp' : '1465894497', - 'microseconds' : '5-97451', - 'token' : 695, - 'pathToImage' : '1465894497_5-97451_frontdoor_618-317-703-493_5446_695.jpg', - 'instanceName' : 'frontdoor', - ] diff --git a/72_machinery/84_Outputs/1_disk-io-privacy.png b/72_machinery/84_Outputs/1_disk-io-privacy.png deleted file mode 100755 index 68fbb95..0000000 Binary files a/72_machinery/84_Outputs/1_disk-io-privacy.png and /dev/null differ diff --git a/72_machinery/84_Outputs/1_disk-io-timestamp.png b/72_machinery/84_Outputs/1_disk-io-timestamp.png deleted file mode 100755 index 7f54a25..0000000 Binary files a/72_machinery/84_Outputs/1_disk-io-timestamp.png and /dev/null differ diff --git a/72_machinery/84_Outputs/1_disk-io.png b/72_machinery/84_Outputs/1_disk-io.png deleted file mode 100755 index 98c7a7a..0000000 Binary files a/72_machinery/84_Outputs/1_disk-io.png and /dev/null differ diff --git a/72_machinery/84_Outputs/1_disk.md b/72_machinery/84_Outputs/1_disk.md deleted file mode 100755 index b913646..0000000 --- a/72_machinery/84_Outputs/1_disk.md +++ /dev/null @@ -1,50 +0,0 @@ -# Disk - -An image can be saved to disk. - -## Parameters - -The parameters of the Disk 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. - - - - timestamp_microseconds_instanceName_regionCoordinates_numberOfChanges_token.jpg - /etc/opt/kerberosio/capture/ - false - white - false - 0 - - - -### File format - -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. - -### Directory - -The directory where the image will be saved to. By default images are saved to the **/etc/opt/kerberosio/capture** directory. - -### Mark with timestamp - -When this settings is set to **true**, the image is marked with a timestamp . - -![Disk timestamp](1_disk-io-timestamp.png) - -### Timestamp color - -A color can be defined for timestamp: white, black, red, green and blue. - -### Privacy - -The privacy mode can be activated to remove some parts from the image. This especially helpful if you want to filter out public areas. - -![Video privacy](1_privacy-mode.png) - -After updating the configuration, you'll see that the pixels outside your region of interest (ROI) are made black; the image below illustrates this. - -![Video privacy](1_disk-io-privacy.png) - -### Throttler - -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. diff --git a/72_machinery/84_Outputs/1_privacy-mode.png b/72_machinery/84_Outputs/1_privacy-mode.png deleted file mode 100644 index 52686a7..0000000 Binary files a/72_machinery/84_Outputs/1_privacy-mode.png and /dev/null differ diff --git a/72_machinery/84_Outputs/1_video-io-privacy.png b/72_machinery/84_Outputs/1_video-io-privacy.png deleted file mode 100755 index af1e545..0000000 Binary files a/72_machinery/84_Outputs/1_video-io-privacy.png and /dev/null differ diff --git a/72_machinery/84_Outputs/1_video.md b/72_machinery/84_Outputs/1_video.md deleted file mode 100755 index fcd80cf..0000000 --- a/72_machinery/84_Outputs/1_video.md +++ /dev/null @@ -1,83 +0,0 @@ -# Video - -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. - -## Parameters - -The parameters of the Video 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. - - - - - -### FPS - -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 Kerberos.io can't write the desired FPS. - - [trivial] IoVideo: framerate is too fast, can't record video at this speed (8/FPS) - -### Record after - -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. - -### Extensions - -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. - -### Codec - -The codec that is used to encode the video file. - -### File format - -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. - -### Directory - -The directory where the videos will be saved. By default videos are saved to the **/etc/opt/kerberosio/capture** directory. - -### Hardware directory - -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. - -### Enable Hardware encoding - -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. - -### Mark with timestamp - -When this settings is set to **true**, the video is marked with a timestamp (similar to the Disk device). - -![Disk timestamp](1_disk-io-timestamp.png) - -### Timestamp color - -A color can be defined for timestamp: white, black, red, green and blue. - -### Privacy - -The privacy mode can be activated to remove some parts from the video. This especially helpful if you want to filter out public areas. - -![Video privacy](1_privacy-mode.png) - -After updating the configuration, you'll see that the pixels outside your region of interest (ROI) are made black; the image below illustrates this. - -![Video privacy](1_video-io-privacy.png) - -### Throttler - -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. diff --git a/72_machinery/84_Outputs/2_TCP_client.md b/72_machinery/84_Outputs/2_TCP_client.md deleted file mode 100755 index c17ab3e..0000000 --- a/72_machinery/84_Outputs/2_TCP_client.md +++ /dev/null @@ -1,36 +0,0 @@ -# TCP/IP client - -The TCP/IP client will send a TCP packet to a server. - -## Parameters - -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. - - - - 127.0.0.1 - 1337 - it's so fluffy - 0 - - - -### Server - -The IP of the TCP server. - -### Port - -This is the port of the TCP server. - -### Message - -You can send some data to a TCP server. - -### Throttler - -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. - -## Examples - -More information can be found [here](/addons/TCP_Listener). diff --git a/72_machinery/84_Outputs/2_tcp-io.png b/72_machinery/84_Outputs/2_tcp-io.png deleted file mode 100755 index 49f8a21..0000000 Binary files a/72_machinery/84_Outputs/2_tcp-io.png and /dev/null differ diff --git a/72_machinery/84_Outputs/3_GPIO.md b/72_machinery/84_Outputs/3_GPIO.md deleted file mode 100755 index ae7dc43..0000000 --- a/72_machinery/84_Outputs/3_GPIO.md +++ /dev/null @@ -1,32 +0,0 @@ -# GPIO - -A GPIO pin can be set as output device. - -## Parameters - -The parameters of the GPIO pin 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. - - - - 17 - 5 - 100000 - 0 - - - -### Pin - -The pin that will be triggered. - -### Periods - -The number of times the pin will be triggered. - -### Period time - -The time in microseconds that the pin will be set *high*. - -### Throttler - -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. diff --git a/72_machinery/84_Outputs/3_gpio-io.png b/72_machinery/84_Outputs/3_gpio-io.png deleted file mode 100755 index 4d7f683..0000000 Binary files a/72_machinery/84_Outputs/3_gpio-io.png and /dev/null differ diff --git a/72_machinery/84_Outputs/4_webhook.md b/72_machinery/84_Outputs/4_webhook.md deleted file mode 100755 index 9430420..0000000 --- a/72_machinery/84_Outputs/4_webhook.md +++ /dev/null @@ -1,37 +0,0 @@ -# Webhook - -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 the Kerberos.io events in your own application. - -**Make sure** that the Webhook comes after the Disk device, otherwise the URL of the image is not included. -## Parameters - -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. - - - - http://kerberos.web/api/v1/webhook - 0 - - - -### Url - -This is the URL, to which Kerberos.io will send a JSON object (as a POST request). - -### Throttler - -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. - -## Output - -A JSON object is POSTed to the url you've defined. - - [ - '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', - ] diff --git a/72_machinery/84_Outputs/4_webhook.png b/72_machinery/84_Outputs/4_webhook.png deleted file mode 100755 index c0d669a..0000000 Binary files a/72_machinery/84_Outputs/4_webhook.png and /dev/null differ diff --git a/72_machinery/84_Outputs/5_script.md b/72_machinery/84_Outputs/5_script.md deleted file mode 100755 index 0f78439..0000000 --- a/72_machinery/84_Outputs/5_script.md +++ /dev/null @@ -1,46 +0,0 @@ -# Script - -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. - -## Parameters - -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. - - - - - -### Path - -The location of the script that will be executed on detection. - -### Throttler - -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. - -## Example - -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. - - #!/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. diff --git a/72_machinery/84_Outputs/6_MQTT.md b/72_machinery/84_Outputs/6_MQTT.md deleted file mode 100644 index 48dda33..0000000 --- a/72_machinery/84_Outputs/6_MQTT.md +++ /dev/null @@ -1,74 +0,0 @@ -# MQTT - -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. - -## Parameters - -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. - - - false - false - 127.0.0.1 - 1883 - kios/mqtt - - - 0 - - -### Secure - -If checked, enable SSL/TLS support. -**PLEASE NOTE**: when SSL/TLS support is enabled, the server certificate issuer is verified against the CA (Certification Authority) files available in /etc/ssl/certs. - -### Verifycn - -If checked, the MQTT server FQDN or ip address must match the CN (Common Name) of the server certificate. - -### Server - -IP address or FQDN of the MQTT broker. - -### Port - -TCP port of the MQTT broker. - -### Topic - -The topic to publish to. - -### Username - -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. - -### Password - -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. - -### Throttler - -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. - -## Output - -A JSON object is published to the topic of the MQTT broker you have configured. - - [ - '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', - ] - -## Example - -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. diff --git a/72_machinery/8_expositor-select-hull.png b/72_machinery/8_expositor-select-hull.png deleted file mode 100644 index 9ec9abd..0000000 Binary files a/72_machinery/8_expositor-select-hull.png and /dev/null differ diff --git a/72_machinery/8_expositor.md b/72_machinery/8_expositor.md deleted file mode 100644 index e76ad52..0000000 --- a/72_machinery/8_expositor.md +++ /dev/null @@ -1,20 +0,0 @@ -# Expositor - -* [Rectangle](#rectangle) -* [Hull](#hull) - -After the algorithm is executed, the expositor will determine, a region, where the changes are located. Just like the algorithm, the expositor has some simple conventions. - -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. - - -## Rectangle - -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. - - -## Hull - -A hull region can be defined to constrain the locations of pixels of interest. This is a more advanced expositor, which can be configured by using the web interface. The hull repositor will return the region of the pixels of interest. - -![Expositor select hull](8_expositor-select-hull.png) \ No newline at end of file diff --git a/72_machinery/90_heuristic.md b/72_machinery/90_heuristic.md deleted file mode 100644 index 76b5b1f..0000000 --- a/72_machinery/90_heuristic.md +++ /dev/null @@ -1,16 +0,0 @@ -# Heuristic - -* [Sequence](#sequence) -* [Counter](#counter) - -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. - - -## Sequence -In most cases motion contains a sequence of events; for example someone who walks by or a car which is parking on the street. The sequence heuristic will measure this by returning true if the recognition was positive for x times in a row. By using this heuristic most of the false-positives (invalid detections) are removed. - - -## Counter -Counting objects forms the basis for a range of high-tech solutions, including retail analytics, queue management, building management and security applications. By using this counter heuristic you can count incoming and outgoing objects (e.g. people). - -![Counter heuristic](83_heuristics/2_counter-heuristic.png) \ No newline at end of file diff --git a/72_machinery/91_output.md b/72_machinery/91_output.md deleted file mode 100644 index 199bda3..0000000 --- a/72_machinery/91_output.md +++ /dev/null @@ -1,39 +0,0 @@ -# Output - -* [Image](#image) -* [Video](#video) -* [GPIO](#gpio) -* [TCP/IP client](#tcp-ip-client) -* [Webhook](#webhook) -* [MQTT](#mqtt) -* [Script](#script) - -If the heuristic determined that the evaluation was valid, one or more IO operations can be executed. You configure which IO operations that will be executed, by modifying the configuration file or using the web interface. - - -## Image -This will save an image to disk. The directory where the images will be saved to, can be set in the configuration file or by using the webinterface. - - -## Video -This will record a video to disk. You can specify the framerate, timestamping, encoder, etc. - - -## GPIO -You can trigger a specific GPIO pin on the Raspberry Pi. - - -## TCP/IP client -The TCP/IP client will send a TCP packet to a server. - - -## Webhook -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. - - -## MQTT -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. - - -## Script -Execution of a bash script which has access to the JSON object. diff --git a/72_machinery/92_streaming.md b/72_machinery/92_streaming.md deleted file mode 100644 index c236d3c..0000000 --- a/72_machinery/92_streaming.md +++ /dev/null @@ -1,36 +0,0 @@ -# Streaming - -The machinery has the ability to stream your capture device as a MJPG stream. - -## Parameters - -The parameters for the supported streaming protocols can be found in the *config/stream.xml* 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. - - - - true - 8889 - 75 - - 75 - - - - -### Enabled - -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. - -### Stream Port - -The port on which the stream is available. - -### Quality - -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. - -### Username/password - -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: - - http://username:password@ip-camera:8899 diff --git a/73_addons/1_TCP_Listener.md b/73_addons/1_TCP_Listener.md deleted file mode 100644 index 1152b47..0000000 --- a/73_addons/1_TCP_Listener.md +++ /dev/null @@ -1,70 +0,0 @@ -# TCP Listener - -One of the addons you can use in combination with Kerberos.io is a TCP Listener. The TCP listener can execute a specific action when it received a TCP packet from Kerberos.io (TCP Client). - -## Examples - -### Text-To-Speech - -You can use **nodejs** to build a simple TCP server, this is a lot easier than if we would have to do it in C; but ofcourse that's also possible. A cool feature would be to use the **say.js** library. You can use **say.js** on OSX/Linux to execute speech to text. So you could send a message from the Kerberos.io instance to the node TCP server, and on receiving the message you could make your TCP server speak. - -For example you can configure the Kerberos.io TCP client with a message "There's someone at the frontdoor". When Kerberos.io detects something it will execute the TCP client and send a TCP packet - which includes the message - to the predefined IP address of the TCP server, afterwards the TCP server will use the say.js library to actually say the message. - - - -Install npm - - npm install say date-utils - -Create a new node file - - nano listener.js - -and copy-paste the code below - - // Import libraries - var net = require('net'); - var say = require('say'); - require('date-utils'); - // Variables - var listenerPort = 1337; - var time1 = new Date(); - net.createServer(function (socket) - { - // Handle incoming messages from the magnet controller. - socket.once('data', function (data) - { - var time2 = new Date(); - var timeBetween = time1.getSecondsBetween(time2); - if(timeBetween > 30) - { - say.speak('Victoria', data); - } - time1 = time2; - }); - }).listen(listenerPort); - // Put a friendly message on the terminal of the server. - console.log("Kerberos.io listener running at port 1337\n"); - -Run script - - node listener.js - -### Pushbullet notifications - -You can expand the Text-To-Speech feature (described above), with pushbullet notifications. Pushbullet is a free notifcation service, which you can use to send messages to your devices; smartphone, tablet, and/or workingstation. You can download the pushbullet node library with **npm**, and use it in the TCP listener. - - npm install pushbullet - -When the library is installed correctly, you can use following code in the TCP listener. - - var PushBullet = require('pushbullet'); - var pusher = new PushBullet('your key'); - pusher.devices(function(error, response) - { - var devices = response.devices; - devices.forEach(function(device) - { - pusher.note(device.device_iden, "Kerberos.io: " + data.toString(), data.toString()); - }); - }); diff --git a/73_addons/2_Cloud.md b/73_addons/2_Cloud.md deleted file mode 100644 index aea26ff..0000000 --- a/73_addons/2_Cloud.md +++ /dev/null @@ -1,27 +0,0 @@ -# Cloud - -Once Kerberos.io is installed on the Raspberry Pi, the machinery and webinterface are available. A user can browse to the IP address (e.g. http://192.168.0.13) of the Raspberry Pi to configure the machinery and view the events that were taken by the machinery. However to be able to browse to the Raspberry Pi, **a user has to be in the same internal network** as where the Raspberry Pi is located; otherwise the webpage wouldn't be accessible. To make the Raspberry Pi accessible for the public, you will need to do some **additional configurations on your router**. - -Another solution would be to use [**the cloud service**](https://cloud.kerberos.io) that Kerberos.io is offering; A user pays a monthly fee to use the Kerberos.io cloud service. You can attach multiple Kerberos.io instances to the cloud service with only one license. - -## Video - -In the video below you get a brief overview of the different features. - - - -## How does it works? - -When subscribed to Kerberos.cloud succesfully, you'll receive some credentials which you can enter in to your Kerberos.io installation. From then all the **images** or **videos** you capture are synced to the Kerberos.cloud service. - -![Cloud subcription](2_cloud_enter-credentials.png) - -When opening Kerberos.cloud you'll see your events appear and receive **in-browser notifications**, and if configured Pushbullet notifications on your other devices. - -![Cloud dashboard](2_cloud_dashboard.png) - -## Where is my data hosted? - -We don't own powerful machines to host and protect your data by ourselves, therefore we use services of Amazon Web Services (AWS). For the paranoids this means that your data is in the **cloud**. However we protect your data by the maximum: we **encrypt/decrypt** your data, and **sign** it for a specific amount of time when requested. This means that links are only accessible for x amount of seconds/minutes. - -If you feel the need to store the data in your own environment, get in touch with us. We have services to support you. \ No newline at end of file diff --git a/73_addons/2_cloud_dashboard.png b/73_addons/2_cloud_dashboard.png deleted file mode 100644 index 5ed4d62..0000000 Binary files a/73_addons/2_cloud_dashboard.png and /dev/null differ diff --git a/73_addons/2_cloud_enter-credentials.png b/73_addons/2_cloud_enter-credentials.png deleted file mode 100644 index 64b7154..0000000 Binary files a/73_addons/2_cloud_enter-credentials.png and /dev/null differ diff --git a/73_addons/3_NAS.md b/73_addons/3_NAS.md deleted file mode 100644 index f1c63f5..0000000 --- a/73_addons/3_NAS.md +++ /dev/null @@ -1,47 +0,0 @@ -# NAS - -By default images are stored on the SD card of the Raspberry Pi, in the folder **/etc/opt/kerberosio/capture**. However it's also possible to store the images directly on a NAS (e.g. WD MyBook). To achieve this, you will need to do some minimal modifications. - -## Let's get started - -You will need to **mount the NAS to the filesystem** of your Rapsberry Pi. In order to make a permanent mount you need to **edit** the **fstab file**. The approach for KiOS is slightly different. - -### KiOS - -Before you can add your NAS to KiOS, you will need to modify the **/data/etc/os.conf** file. By default the root partition is **read-only**, therefore you will need to change it to **read-write**. To do this you will need to activate **os_debug** option. - - os_debug="true" - -After you've changed the value to **true**, you need to reboot the system. You will see see that the root partition is now **writeable**, and you're able to modify the fstab file. - - nano /etc/fstab - -Add following line (replace variables **with your own credentials**): - - //ip_address_to_your_nas/directory_on_your_nas /data/machinery/capture cifs username=user_on_your_nas,password=password_for_your_nas,iocharset=utf8,file_mode=0777,dir_mode=0777 0 0 - -Mount the NAS - - mount -a - -Check if the mount was **successful**, you should see the already existing content on your referred NAS directory. - - cd /data/machinery/capture && ls -l - -### Other - - nano /etc/fstab - -Add following line (replace variables **with your own credentials**): - - //ip_address_to_your_nas/directory_on_your_nas /etc/opt/kerberosio/capture cifs username=user_on_your_nas,password=password_for_your_nas,iocharset=utf8,file_mode=0777,dir_mode=0777 0 0 - -Mount the NAS - - mount -a - -Check if the mount was **successful**, you should see the already existing content on your referred NAS directory. - - cd /etc/opt/kerberosio/capture && ls -l - -And *that's it*. From now the machinery will store the images directly on your NAS, and the web interface will visualize them. \ No newline at end of file diff --git a/73_addons/4_People_Counting.md b/73_addons/4_People_Counting.md deleted file mode 100644 index 0581b89..0000000 --- a/73_addons/4_People_Counting.md +++ /dev/null @@ -1,68 +0,0 @@ -# People Counting - -Kerberos.io can be used as a people counter by selecting the [**Counter heuristic**](/machinery/heuristics/counter). The idea is that two lines are drawn: the incoming and the outgoing line. Those two lines are necessary to know if the object is incoming or outgoing. - -![People counting](4_people_counting.png) - -If one ore more objects crossed both lines, the number of the incoming and outgoing objects are written to a JSON object (for more information see the [**Counter heuristic**](/machinery/heuristics/counter)). By using the [**Webhook IO device**](/machinery/Outputs/webhook) it's possible to fetch the JSON object and visualize it in your browser. - -![GUI for people counting](4_people_counting_gui.png) - -In this tutorial we'll show you how to configure **Kerberos.io**, so that it can be **used as a People counter**, and build a real-time counter which shows the number of incoming and outgoing objects (see screenshot above). - -## Let's get started - -To get started, make sure you have properly [**installed Kerberos.io**](/installation/KiOS) on your device. After the installation go to the settings page and change the settings to following configuration: - -* Algorithm: Background Subtraction, -* Heuristic: Counter and -* Io: Disk and Webhook. - -### Customize parameters - -To work properly on a Raspberry Pi we need to tweak the **Capture** device, the **Background Subtraction** algorithm and the **Counter** heuristic a bit. - -* Capture device: **minimize** delay times. To count properly we need to process as much images we can, therefore we need to make sure the **delay time** of the **capture device** is **set to 0**. -* Background Subtraction: **set** the **shadow** parameter to false. This is required because it consumes too much CPU, especially when running on a Raspberry Pi Zero. -* Counter: decrease the minArea parameter to 50, and experiment with it (increase it little by little). Finding the ideal minArea is done by trial and error, as it depends on your environment, distance of the camera, etc. - -[**Read this post**](https://kerberosio.zendesk.com/hc/en-us/articles/213586849-People-counter-not-working) for more details. - - -### Specific the incoming and outgoing lines - -When opening the counter heuristic, you'll see two lines (a green and red one) which you can move to the position you prefer. Important to note is that the green line is used for counting incoming objects and the red line for outgoing objects. E.g. if we want to count the people which are entering your home, you should arrange the lines as follows. - -![Lines for people counting](4_people_counting_lines.png) - -### Specify the webhook url - -The **Webhook Io device** is used to send the number of incoming and outgoing objects to your own application; therefore we need to specify an endpoint to which the webhook will post the JSON object (e.g. your own API). We will demonstrate how this works with a traditional NodeJS application, which we will create in next paragraph. The application will run on our local machine, and listen on port 25000, therefore we need to change the url of the webhook to: - - http://localhost:25000 - -Please note that if the NodeJS application runs on another machine than on which Kerberos.io is running, you should replace localhost by the ip-address of that remote machine. - -### GUI - -We will create a simple **nodejs** application using **socket.io** which will listen on port 25000 for **POST** events. When the application receives a **POST** event, it will dynamically increase the incoming and/or outgoing counters. To get started we will clone following repository: - - git clone https://github.com/cedricve/kerberosio-people-counter - cd kerberosio-people-counter - -After the repository is cloned succesfully we will download the necessary packages using **npm**. - - npm install - -Run the app with following command - - node server.js - -Following output will be generated: - - info - socket.io started - Server running on port 25000 - -Open your browser and browse to **http://localhost:25000** (or the IP-address of the remote machine on which the application is running). - -![Hostname for people counting](4_people_counting_hostname.png) \ No newline at end of file diff --git a/73_addons/4_people_counting.png b/73_addons/4_people_counting.png deleted file mode 100644 index 64c6ecd..0000000 Binary files a/73_addons/4_people_counting.png and /dev/null differ diff --git a/73_addons/4_people_counting_gui.png b/73_addons/4_people_counting_gui.png deleted file mode 100644 index 1792130..0000000 Binary files a/73_addons/4_people_counting_gui.png and /dev/null differ diff --git a/73_addons/4_people_counting_hostname.png b/73_addons/4_people_counting_hostname.png deleted file mode 100644 index 9cfa3b7..0000000 Binary files a/73_addons/4_people_counting_hostname.png and /dev/null differ diff --git a/73_addons/4_people_counting_lines.png b/73_addons/4_people_counting_lines.png deleted file mode 100644 index 8e015de..0000000 Binary files a/73_addons/4_people_counting_lines.png and /dev/null differ diff --git a/README.md b/README.md deleted file mode 100755 index ab92024..0000000 --- a/README.md +++ /dev/null @@ -1,52 +0,0 @@ -# KERBEROS.**IO** - -[![Join the chat](https://img.shields.io/gitter/room/TechnologyAdvice/Stardust.svg?style=flat)](https://gitter.im/kerberos-io/hades?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) - -This repository contains all the documentation that is displayed on the [documentation website](https://doc.kerberos.io/). The documentation is written in [markdown](http://markdowntutorial.com/) The documentation includes information about: how kerberos works, how to install it and also some technical information for developers who are willing to contribute; for example how to add a new algorithm or a new output device. - -## Vote for features - -[![Feature Requests](http://feathub.com/kerberos-io/machinery?format=svg)](http://feathub.com/kerberos-io/machinery) - -## Folder structure - -Changes are added to the **development** branch first, and will be added to the **master** branch if stable. The document folder structure looks like this: - -* branch1 - * document - * document - * ... - * document - * folder - * document - * folder - * document - * ... - * document - * folder - * ... - * folder - * ... - * folder -* branch 2 -* ... -* branch n - -Directories and documents can start with a number, followed by an underscore, to order the documents; for example *1\_documentation* and *2\_more\_documentation*. Please note that documents always come first, and thus directories second. Thus directories and documents are sorted separately; just like the folder structure above. - -## Contribute - -Writing documentation is required if you send a pull-request. No code, how excellent it may be, will be merged without documentation or tests. This will give the other contributors a better understandig of how your code works and what its purpose is. - -## How to write documentation - -To create uniform documentation some guidelines are introduced: - -* a document starts with a title. -* the title is followed by a listing of the subsections on the page. -* images start with a prefix similar to the document they belong to; for example: document "1_c" has two images *"1\_c\_this\_is \_an\_image"* and *"1\_c\_unicorn"*. -* images belong to the same directory as the document they belong to. -* documentation for new algorithms, expositors, heuristics, etc will be using following template. - * Global description of the class - * Web interface (image) - * Parameters (xml + description of each parameter)