Compare commits

..

64 Commits

Author SHA1 Message Date
Cédric Verstraeten
2bf6c0b442 release v1.1.0 2015-09-13 21:47:51 +02:00
Cédric Verstraeten
24693a0ff6 restructure branch make links independent of branch 2015-08-09 15:26:30 +02:00
Cédric Verstraeten
4d87828c9b reference broken image rpi camera board 2015-08-03 14:30:34 +02:00
Cédric Verstraeten
cf43cb3f29 add webhook to list of outputs 2015-08-03 13:39:02 +02:00
Cédric Verstraeten
c93147e0c6 fix webhook styling 2015-08-03 13:37:13 +02:00
Cédric Verstraeten
8eb6a1a122 add webhook 2015-08-03 13:36:16 +02:00
Cédric Verstraeten
8c48c6fbb1 ipcamera add image of web interface 2015-08-03 13:36:08 +02:00
Cédric Verstraeten
cf18a9474f Added ipcamera 2015-08-03 13:25:36 +02:00
Cédric Verstraeten
5f8c7ebcdb update checksums 2015-07-30 22:27:32 +02:00
Cédric Verstraeten
2d6b09d1bd update installation guide for machinery 2015-07-30 22:27:31 +02:00
Cédric Verstraeten
9f0da3c6d3 add installation for linux 2015-07-28 19:09:31 +02:00
Cédric Verstraeten
4f5e027f27 Update 3_installation.md 2015-07-28 14:43:09 +02:00
Cédric Verstraeten
3805b81f0e Update 3_installation.md 2015-07-28 14:42:48 +02:00
Cédric Verstraeten
e3be355fbe fix 2015-07-27 21:54:12 +02:00
Cédric Verstraeten
ae442e827e fix for linux 2015-07-27 21:52:46 +02:00
Cédric Verstraeten
396a29a888 removed unzip 2015-07-27 20:18:15 +02:00
Cédric Verstraeten
deb4075fec added checksum 2015-07-27 20:14:42 +02:00
Cédric Verstraeten
e7e8825ada update 2015-07-27 20:12:33 +02:00
Cédric Verstraeten
6fbb54b6d2 fix decompress for linux 2015-07-27 20:10:27 +02:00
Cédric Verstraeten
dff1b26c72 fix 2015-07-18 20:45:05 +02:00
Cédric Verstraeten
174417818a add note 2015-07-18 20:44:21 +02:00
Cédric Verstraeten
11c9683488 add note 2015-07-18 20:43:04 +02:00
Cédric Verstraeten
0e8a55326d add note to install 2015-07-18 20:39:54 +02:00
Cédric Verstraeten
cce18c8685 add install note 2015-07-18 20:38:02 +02:00
Cédric Verstraeten
26ee0082c1 update dev 2015-07-12 16:34:07 +02:00
Cédric Verstraeten
91660bb0a1 Update 5_FAQ.md 2015-07-11 10:58:29 +02:00
Cédric Verstraeten
ff13b28172 Update README.md 2015-07-09 11:43:31 +02:00
Cédric Verstraeten
478dfae179 Update README.md 2015-07-09 11:41:13 +02:00
Cédric Verstraeten
48cce20353 changed installation procedure 2015-07-05 20:42:03 +02:00
Cédric Verstraeten
e312ec391c change installation procedure 2015-07-05 20:41:06 +02:00
Cédric Verstraeten
1cd7410440 release 1.0.3 2015-07-05 20:23:19 +02:00
Cédric Verstraeten
dc63f9e62d release 1.0.3 2015-07-05 20:21:25 +02:00
Cédric Verstraeten
dfc74857e3 zipped images 2015-06-25 21:57:40 +02:00
Cédric Verstraeten
f243a02fd9 moved storage to google drive 2015-06-25 20:41:13 +02:00
Cédric Verstraeten
7d5818e21d hotfixes on images: resolved memory leak, optimized cloud sync 2015-06-24 07:00:15 +02:00
cedricve
9a0f4f38e4 resolved wifi issue RPI2 image 2015-06-06 22:55:40 +02:00
cedricve
35dd422f7d temporary rollback, issue with rpi 2 image. 2015-06-06 13:12:40 +02:00
cedricve
7cce2ba1b3 added release 1.0.2 2015-06-04 07:10:07 +02:00
cedricve
176bbc3554 hotfix: merge changes mrz1277 in dev 2015-06-03 21:31:21 +02:00
Cédric Verstraeten
eea221af14 Merge pull request #1 from mrz1277/master
typo
2015-06-03 21:25:21 +02:00
yakiyama-iMac
c495535212 typo 2015-06-04 04:20:20 +09:00
cedricve
b5fc5d9df9 typo 2015-06-03 00:16:35 +02:00
cedricve
ada0999cb3 styling 2015-06-03 00:16:04 +02:00
cedricve
453970f919 updated styling 2015-06-03 00:15:46 +02:00
cedricve
d7212ff2ec updated styling 2015-06-03 00:15:27 +02:00
cedricve
16b2004a0d added nas section 2015-06-03 00:12:58 +02:00
cedricve
1e29b1bb78 fix 2015-05-31 15:32:09 +02:00
cedricve
90619c9e92 fix 2015-05-31 15:31:21 +02:00
cedricve
2af1bd88e6 missing links 2015-05-31 15:28:57 +02:00
cedricve
cd0297a1e8 typo 2015-05-31 15:26:49 +02:00
cedricve
8047440c6e fix 2015-05-31 15:26:19 +02:00
cedricve
27a1982212 fix 2015-05-31 15:25:55 +02:00
cedricve
1044636cf4 added extra information for installation and GUI 2015-05-31 15:22:38 +02:00
cedricve
c31e94c9ff Merge branch 'develop' 2015-05-29 12:57:54 +02:00
cedricve
f13ff40f82 update mega.co.nz links 2015-05-29 12:57:29 +02:00
cedricve
b587135e93 typos + wrong url 2015-05-26 19:28:49 +02:00
cedricve
4c51714655 Merge branch 'develop' 2015-05-26 19:06:19 +02:00
cedricve
983a58daef fix typos + removed paragraph at section installation 2015-05-26 19:05:31 +02:00
cedricve
6c987c574b Merge branch 'master' into develop 2015-05-25 15:16:48 +02:00
cedricve
7077be57f3 missing ) 2015-05-25 15:16:33 +02:00
cedricve
f2df547479 Merge branch 'develop' 2015-05-25 15:15:02 +02:00
cedricve
85278c18fd add missing expand sd card for Raspberry Pi 2 2015-05-25 15:14:48 +02:00
cedricve
266a11ff7b Merge branch 'master' into develop 2015-05-24 10:40:40 +02:00
cedricve
9f8bcb219b update image to v1.0.1 2015-05-24 10:40:26 +02:00
132 changed files with 451 additions and 2014 deletions

View File

@@ -1,34 +0,0 @@
# Getting started
* [What is Kerberos.io](#what-is-kerberos-io)
* [How does it work](#how-does-it-work)
* [Installation](#installation)
* [Contribute](#contribute)
## Let's get started
In the video below you get a quick overview of how Kerberos works and how you can configure it. The video isn't technical but explains the different features Kerberos offers you.
<iframe src="https://player.vimeo.com/video/121532472?autoplay=0&color=943633" style="width:100%; height: 400px;" frameborder="0" webkitallowfullscreen mozallowfullscreen allowfullscreen></iframe>
<a name="what-is-kerberos-io"></a>
## What's Kerberos.io?
Kerberos is a low-budget surveillance solution created for the **Rapsberry Pi**. Kerberos is open source, so you and others, can customize the source code to your needs and share it. It has a *low-energy* footprint when deploying on the Raspberry Pi and it's *easy to install*, you only need to transfer the image to your SD card and you're done.
Use your mobile phone, tablet or PC to keep an eye on your property. View the activity with our *responsive* and *user-friendly* web interface. Look at the dashboard to get a graphical overview of the past days. *Multiple* Kerberos *instances* can be installed and can be viewed with [only one web interface](/1.0.0/addons/Cloud).
<a name="how-does-it-work"></a>
## How does it work?
Kerberos is devided into two parts: the **machinery** (Back end, C++) and the **webinterface** (Front end, PHP). The machinery is responsible for the image processing and the webinterface is used to configure the machinery and to view the events that were detected by the machinery. Both parts are installed on the device, in most cases the Raspberry Pi. The machinery can trigger multiple output devices when an event occurred; it can trigger a GPIO pin, save an image to disk or send a TCP packet.
<a name="installation"></a>
## Installation
Kerberos is **easy to install**, you just have to copy the kerberos image to your SD card, plug it into your Raspberry Pi and that's it. Kerberos can be installed on other devices than the Raspberry Pi; for development or production. Therefore you will need to compile the machinery yourself and install the webinterface with your favorite webserver; nginx, apache, etc.
<a name="contribute"></a>
## Contribute
Want to contribute? You're a front end designer, user experience guru, an ambitious programmer, or a Ph.D. in Computer Vision who wants to take kerberos.io to the next level? Then we like to welcome you to the community. Contributions are taken very seriously, besides your code, testing and documentation are very important!

View File

@@ -1,32 +0,0 @@
# Introduction
* [The web interface](#the-web-interface)
* [How does it work](#how-does-it-work)
* [Installation](#installation)
* [How to access](#how-to-access)
<a name="the-web-interface"></a>
## The web interface
Kerberos.web, the webinterface, allows you to configure the machinery and to view events that were detected by the machinery. You can use your mobile phone, tablet or desktop to view the images with the *responsive* and *intuitive* web interface.
<a name="how-does-it-work"></a>
## How does it work?
The webinterface is written in PHP using the extremely popular PHP Framework **Laravel**. It visualizes images, taken by the machinery, in a intuitive and responsive way. Besides a server-side framework, it also uses a client-side framework **Backbone** to create the dynamic behaviour. The webinterface includes the latest development tools, to increase development efficiency: RequireJS, bower, LESS, etc.
Besides visualization, the webinterface is also used to configure the machinery. On the settings page a user can select different options, for example a user could select a region where motion should be detected or could select a time range when motion could be detected, which algorithm is used, etc.
The webinterface can also be used to configure Kerberos with our [**cloud application**](/1.0.0/addons/Cloud). The setup is very easy, you only need to create an account on our cloud application, request a key, and enter it in every webinterface you want to have synced.
<a name="installation"></a>
## Installation
If Kerberos is installed from the image, the webinterface will be pre-installed and nothing is left to do. If you want to install the webinterface from source, you will need to create a new webapplication on your webbrowser and transfer the webproject.
<a name="how-to-access"></a>
## How to access
You can access the webinterface by entering the ip address of the Raspberry Pi in your favorite browser. When the webapplication is loaded you will see a login page, on which you will need to enter your credentials. The default username and password is **root**. You are able to change this password by editing the **app/config/app.php** file.
![Login page kerberos.io webinterface](1_how-to-access.png)

View File

@@ -1,40 +0,0 @@
# Project structure
* [Configuration](#configuration)
* [File structure](#file-structure)
* [Server](#server)
* [Client](#client)
The web interace contains several important concepts and this is the right place where we will explain them briefly.
<a name="configuration"></a>
## Configuration
The web interface can be used to configure the machinery and therefore provides a *settings* page where algorithms, expositors, etc can be configured. The web interface will convert the configuration files into HTML elements, so when adding new algorithms or heuristics, the parameters will be reflected in the web interface 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 **app/views/controls** directory.
The webinterface can be used to configure Kerberos with our [**cloud application**](/1.0.0/addons/Cloud). The setup is very easy, you only need to create an account on our cloud application, request a key, and enter it in every webinterface you want to have synced. Once Kerberos is configured with the cloud application, a filewatcher, **Gruntjs**, will push new images to the cloud application immediately.
<a name="file-structure"></a>
## File structure
Laravel has been used as back end framework, so if you aren't familiar with Laravel, check out their [documentation website](http://laravel.com/docs). However we will give a briefly explanation of the most important directories.
<a name="server"></a>
### Server
* **app/config/app.php** - this file contains Kerberos specific parameters; where the configuration files can be found, the user credentials to sign in, etc.
* **app/controllers** - MVC controllers
* **app/repositories** -repositories are injected into the controller.
* **app/api.php** - contains all the URI endpoints for Ajax calls.
* **app/repositories.php** - bind repositories to a specific interface - dependency injection.
* **app/routes.php** - url routing for pages.
<a name="client"></a>
### 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.

View File

@@ -1,20 +0,0 @@
# Introduction
* [The machinery](#the-machinery)
* [How does it work](#how-does-it-work)
* [Installation](#installation)
<a name="the-machinery"></a>
## The machinery
Kerberos.io, the machinery, is a video detection framework, it uses a flexible project structure that can be expanded easily. You can use your favorite **USB webcam** or the new **Raspberry Pi camera module**. The machinery uses OpenCV within its core to create new and powerful functionality, on a efficient way.
<a name="how-does-it-work"></a>
## How does it work?
More information can be found on the [project structure page](/1.0.0/machinery/project_structure).
<a name="installation"></a>
## Installation
The machinery will be installed when deploying the image on your SD card. However you can also compile and link the machinery yourself. Look at the [installation section](/1.0.0/installation) to read more about it.

View File

@@ -1,83 +0,0 @@
# Installation
* [Install from source](#install-from-source)
* [Install on Arch Linux](#install-from-source-on-arch-linux)
* [Auto start](#start-kerberos-on-boot-archlinux)
The machinery is already installed on the Kerberos image, however you can also install the machinery from source.
<a name="install-from-source"></a>
## Install from source
The machinery can be installed standalone.
<a name="install-from-source-on-arch-linux"></a>
### Install on ArchLinux
Update the ArchLinux kernel
pacman -Syyu
Install git, subversion, development tools (c++, cmake) and V4L utils.
pacman -S git subversion cmake base-devel v4l-utils eigen
Go to home directory
cd /home
Get the source code from github
git clone https://github.com/kerberos-io/machinery kerberos-io
Compile kerberos
cd kerberos-io && mkdir build && cd build
cmake .. && make && make check
Add link library to path
export DYLD_LIBRARY_PATH=$DYLD_LIBRARY_PATH:/home/kerberos-io/build/thirdparty/lib/
Give rights to config files
chmod -R 777 ../config
<a name="start-kerberos-on-boot-archlinux"></a>
#### Auto start
Create service file for kerberos
nano /etc/systemd/system/kerberos.service
Copy and paste the configuration to the kerberos.service
[Unit]
Description=Kerberos.io Video Surveillance
[Service]
Type=oneshot
ExecStart=/home/kerberos-io/bin/kerberos
[Install]
WantedBy=multi-user.target
Create timer file for kerberos
nano /etc/systemd/system/kerberos.timer
Copy and paste the configuration to the kerberos.timer
[Unit]
Description=Runs kerberos.service, 1 min after system boot.
[Timer]
OnBootSec=1min
Unit=kerberos.service
[Install]
WantedBy=multi-user.target
Enable the service to start on boot
systemctl enable kerberos.timer

View File

@@ -1,16 +0,0 @@
# Capture
* [USB camera](#usb-camera)
* [Raspberry Pi Camera Module](#raspberry-pi-camera-module)
The capture device is responsible to take images. The images are used in the four pass way.
<a name="usb-camera"></a>
## 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.
<a name="raspberry-pi-camera-module"></a>
## Raspberry Pi Camera Module
You can use the Raspberry Pi Camera Module with Kerberos, you just need to attach the camera module and you are ready to go. The Raspberry Pi Camera Module is enabled by default in the web interface. Please note that if you didn't installed Kerberos with the image, you will need to [enable the camera module](/1.0.0/FAQ#how-to-enable-camera-module) yourself.

View File

@@ -1,32 +0,0 @@
# USB Camera
You can use the Raspberry Pi Camera Module with Kerberos. You just need to attach the camera module and you're ready to go. The Raspberry Pi Camera Module is enabled by default in the web interface.
## Web interface
![Raspberry PI Camera Module](2_raspi-camera.png)
## 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 interface to modify the parameters. Below you see a default configuration file.
<captures>
<RaspiCamera>
<frameWidth type="number">800</frameWidth>
<frameHeight type="number">640</frameHeight>
<night type="number">60</night>
<day type="number">150</day>
</RaspiCamera>
</captures>
### Framewidth and -height
You can set the resolution of the camera module, make sure the resolution you've defined is valid.
### Night and day
The Raspberry Pi Camera module has additional parameters. Thanks to the MMAL library we can change the configuration of the Raspberry Pi Camera Module. The night and day parameters are gray thresholds. The night parameter defines the lower gray value/threshold; if the brightness of the image taken by the camera module will be lower than the night value, it will switch to night mode. Similar, if the brightness is higher than the day value, it will switch to day mode.
Notice that there is a kind of gray zone. If the brightness of the image is within those range, no reconfiguration will happen. This feature will be more advanced in future.

View File

@@ -1,37 +0,0 @@
# TCP/IP client
The TCP/IP client will send a TCP package to a server.
## Web interface
![TCP socket io](2_tcp-io.png)
## Parameters
The parameters of the TCP/IP client can be found in the config/io.xml file, but you can also use the web interface to modify the parameters. Below you see a default configuration file.
<ios>
<TCPSocket>
<server type="number">127.0.0.1</server>
<port type="number">1337</port>
<message type="text">it's so fluffy</message>
</TCPSocket>
</ios>
### 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.
## Examples
More information can be found [here](/1.0.0/addons/TCP_listener).

View File

@@ -1,19 +0,0 @@
# Output
* [Image](#image)
* [GPIO](#gpio)
* [TCP/IP client](#tcp-ip-client)
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.
<a name="image"></a>
## 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.
<a name="gpio"></a>
## GPIO
You can trigger a specific GPIO pin on the Raspberry Pi.
<a name="tcp-ip-client"></a>
## TCP/IP client
The TCP/IP client will send a TCP packet to a server.

View File

@@ -1,59 +0,0 @@
# Cloud
Once Kerberos 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. 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 that Kerberos is offering; A user pays a monthly fee to use the Kerberos cloud service. The events that are triggered by the machinery will be sent to our service, and are accessible by using the Kerberos cloud application. You can attach multiple Kerberos instances to the cloud service with only one license.
## Video
<iframe src="https://player.vimeo.com/video/121532472?autoplay=0&color=943633#t=13m32s" style="width:100%; height: 400px;" frameborder="0" webkitallowfullscreen mozallowfullscreen allowfullscreen></iframe>
## How it works?
Kerberos is using AWS S3 to store their images. When the machinery detected something, it will save an image to disk, and maybe trigger some other IO devices. In its turn the filewatcher, Grunt, will pick up those new files and push them to the appropriate S3 bucket, by using your credentials; the credentials you've received from the cloud application, have only permissions to write and list objects to/from your bucket.
When the file (image) is stored in the bucket, AWS Lambda will do some validation and post processing. Lambda will check if the file is realy an image, if the size is not to big, and do some post processing like facerecognition. If the image is valid, the image will be copied to our production bucket, and additional information is stored in dynamoDB.
The cloud application is attached to the production bucket, so only images that are verified will show up in the cloud application. When a user accesses the cloud application, the images from the production bucket are listed. Images that are loaded in the browser will be signed, for a specific time, before they are actually rendered. The signing will expire after 100 seconds.
## Install from source
If you installed Kerberos from the image, you don't need to follow this tutorial as the service is installed natively.
cd /home
Create a new directory
mkdir cloud && cd cloud
Checkout sync repository
git clone https://github.com/kerberos-io/sync-s3 .
Install node plugins
npm install
npm install -g grunt-cli
npm install -g forever
## Auto-start grunt
Create service file for cloud
nano /etc/systemd/system/cloud.service
Copy and paste the configuration to the cloud.service
[Unit]
Description=Sync kerberos.io events
[Service]
Type=oneshot
ExecStart= /usr/bin/forever /usr/bin/grunt --gruntfile /home/cloud/Gruntfile.js sync --force &
[Install]
WantedBy=multi-user.target
Enable the service to start on boot
systemctl enable cloud.service

View File

@@ -1,18 +0,0 @@
# Release notes
* [1.0.0](#1-0-0)
<a name="1-0-0"></a>
## 1.0.0
First commit of Kerberos.io
#### New
* 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**.

View File

@@ -16,7 +16,7 @@ In the video below you get a quick overview of how Kerberos works and how you ca
Kerberos is a low-budget surveillance solution created for the **Rapsberry Pi**. Kerberos is open source, so you and others, can customize the source code to your needs and share it. It has a *low-energy* footprint when deploying on the Raspberry Pi and it's *easy to install*, you only need to transfer the image to your SD card and you're done.
Use your mobile phone, tablet or PC to keep an eye on your property. View the activity with our *responsive* and *user-friendly* web interface. Look at the dashboard to get a graphical overview of the past days. *Multiple* Kerberos *instances* can be installed and can be viewed with [only one web interface](/dev/addons/Cloud).
Use your mobile phone, tablet or PC to keep an eye on your property. View the activity with our *responsive* and *user-friendly* web interface. Look at the dashboard to get a graphical overview of the past days. *Multiple* Kerberos *instances* can be installed and can be viewed with [only one web interface](/addons/Cloud).
<a name="how-does-it-work"></a>
## How does it work?

View File

Before

Width:  |  Height:  |  Size: 38 KiB

After

Width:  |  Height:  |  Size: 38 KiB

View File

Before

Width:  |  Height:  |  Size: 19 KiB

After

Width:  |  Height:  |  Size: 19 KiB

View File

Before

Width:  |  Height:  |  Size: 23 KiB

After

Width:  |  Height:  |  Size: 23 KiB

View File

Before

Width:  |  Height:  |  Size: 33 KiB

After

Width:  |  Height:  |  Size: 33 KiB

View File

Before

Width:  |  Height:  |  Size: 58 KiB

After

Width:  |  Height:  |  Size: 58 KiB

View File

Before

Width:  |  Height:  |  Size: 19 KiB

After

Width:  |  Height:  |  Size: 19 KiB

View File

Before

Width:  |  Height:  |  Size: 340 KiB

After

Width:  |  Height:  |  Size: 340 KiB

View File

@@ -5,8 +5,11 @@
* [Insert your SD card](#insert-your-sd-card)
* [OSX: transfer image](#osx-transfer-image)
* [Windows: transfer image](#windows-transfer-image)
* [OSX/Linux: transfer image with terminal](#transfer-image-with-terminal)
* [OSX: transfer image with terminal](#transfer-image-with-terminal-with-osx)
* [Linux: transfer image with terminal](#transfer-image-with-terminal-with-linux)
* [(Optional) Setup WIFI connection](#setup-wifi-connection)
* [Power on the Raspberry Pi](#power-on-raspberry-pi)
* [(Optional) Access the Raspberry Pi with SSH](#access-raspberry-pi)
* [Install from source](#install-from-source)
Kerberos is **easy to install**, you just have to copy the Kerberos image to your SD card, plug the SD card into your Raspberry Pi and that's it. It can also be installed on other devices than the Raspberry Pi; for development or production. Therefore you will need to compile the machinery from source and install the webinterface with your favorite webserver.
@@ -16,26 +19,51 @@ Kerberos is **easy to install**, you just have to copy the Kerberos image to you
If you want to use Kerberos.io **as a service**, this would be the preferred way. Kerberos is provided as an image, a pre-installed operating system. The only thing you have to do to make things work, is to transfer the image to your SD card. After transferring you can just plug the SD card into your Raspberry Pi and kerberos will work; isn't that great!
The're a lot of different ways to accomplish this, and they are different according the operating system you will be using to transfer the image.
<a name="download-the-image"></a>
### 1. Download the image
### 1. Download the image (v1.1.0)
First you will need to download the Kerberos image; click on the image below. The Kerberos.io image contains a Linux operating system, built on Arch Linux. The image has the machinery and webinterface installed, and ofcourse all the dependencies Kerberos needs. With this image you just have to plugin the SD card in your Raspberry Pi and you're done.
#### Raspberry Pi Model 2 (Recommended)
The Raspberry Pi 2 is the successor to the Raspberry Pi. It builds upon the original model B+ upgrading to 1 GB of RAM, and replacing the aged ARMv6l single-core with an ARMv7l Cortex-A7 quad-core.
[![Kerberos.io image](3_kerberos-image.png)](https://drive.google.com/open?id=0B-2b4NYY_1xuODZ6eEE2bXN5eXM)
Checksum
10557f21beacbceaee172bd20e420e3e
**Please note** that the image is compressed, (on Linux/OSX) open your terminal and use the "7zip" command to decompress.
OSX
7za x kerberos-io-armv7-4GB-..
Linux
7z e from/kerberos-io-armv7-4GB-..
#### Raspberry Pi Model A, A+, B and B+
The Raspberry Pi is a credit-card sized computer that plugs into your TV and a keyboard. Its a capable little PC which can be used for many of the things that your desktop PC does, like spreadsheets, word-processing and games. It also plays high-definition video.
[![Kerberos.io image](3_kerberos-image.png)](https://mega.co.nz/#!vY4WjKJD!2sZUuhzeVDFu47hSOQ94Jh27v0BLYpf6MRTBBzGfkrc)
[![Kerberos.io image](3_kerberos-image.png)](https://drive.google.com/open?id=0B-2b4NYY_1xuRkZNa19Gam5BMjg)
#### Raspberry Pi Model 2
Checksum
The Raspberry Pi 2 is the successor to the Raspberry Pi. It builds upon the original model B+ upgrading to 1 GB of RAM, and replacing the aged ARMv6l single-core with an ARMv7l Cortex-A7 quad-core.
2b67a4ca6af0cdde39f4a428047da607
[![Kerberos.io image](3_kerberos-image.png)](https://mega.co.nz/#!6AAGlAwa!dJqbpGBG_k2ZA2FACtTbY4WR2azaV2Izeur-k3_4RlU)
**Please note** that the image is compressed, (on Linux/OSX) open your terminal and use the "7zip" command to decompress.
OSX
7za x kerberos-io-armv6-4GB-..
Linux
7z e from/kerberos-io-armv6-4GB-..
<a name="insert-your-sd-card"></a>
### 2. Insert your SD Card
@@ -61,8 +89,8 @@ Ensure that you have inserted the SD card, that you wish to clone, into the SD c
* Download and install the [Win32DiskImager](http://sourceforge.net/projects/win32diskimager/files/latest/download).
* Select the image file you've downloaded earlier and the drive letter of the SD card.
<a name="transfer-image-with-terminal"></a>
### 3. OSX/Linux: transfer image with terminal
<a name="transfer-image-with-terminal-osx"></a>
### 3. OSX: transfer image with terminal
#### Locate Your SD Card
@@ -88,14 +116,45 @@ To format the SD card, enter the following command:
In Terminal, enter the following command ensuring that you identify the correct destination disc.
sudo dd if=~/Desktop/kerberos-io.img of=/dev/disk3
sudo dd if=~kerberos-io.img of=/dev/disk3
<a name="transfer-image-with-terminal-linux"></a>
### 3. Linux: transfer image with terminal
#### Format SD card
Select SD card and delete all partitions with gparted
gparted
To format the SD card, enter the following command:
sudo mkdosfs -F 16 -v /dev/sdb -I
#### Transfer image to your SD card
In Terminal, enter the following command ensuring that you identify the correct destination disc.
sudo dd if="kerberos-io-armvx-4GB-vy.img" of=/dev/sdb bs=2M
<a name="setup-wifi-connection"></a>
### 4. (Optional) Setup WIFI connection
If you will be using Kerberos.io with a WIFI dongle, then check out the [F.A.Q. page](/1.0.0/FAQ#setup-wifi).
If you will be using Kerberos.io with a WIFI dongle, then check out the [F.A.Q. page](/FAQ#setup-wifi).
<a name="power-on-raspberry-pi"></a>
### 5. Power on the Raspberry Pi
When the installation is completed, you can **plug the SD card** into your Raspberry Pi, and that's all. From this point you need to **figure out the IP address** of your Raspberry Pi. If you found your IP address (dynamic or static), you can **open your favorite browser** and type in the IP address. This will open the Kerberos login page, which you can **access** with the username: **root** and password: **root**.
![Login page kerberos.io webinterface](1_how-to-access.png)
<a name="access-raspberry-pi"></a>
### 6. (Optional) Access the Raspberry Pi with SSH
To use Kerberos you only need access to the webinterface, however you can also **[access the system with SSH](/FAQ#how-to-access-the-pi)**.
<a name="install-from-source"></a>
## Install from source
This will be the procedure if you want to contribute to Kerberos or if you want to use Kerberos on your local machine. To install Kerberos from source; you will need to [compile the machinery](/1.0.0/machinery/installation) from source and [import the webinterface](/1.0.0/web/installation) into your favorite webserver.
This will be the procedure if you want to contribute to Kerberos or if you want to use Kerberos on your local machine. To install Kerberos from source; you will need to **[compile the machinery](/machinery/installation)** from source and **[import the webinterface](/web/installation)** into your favorite webserver.

View File

Before

Width:  |  Height:  |  Size: 18 KiB

After

Width:  |  Height:  |  Size: 18 KiB

View File

Before

Width:  |  Height:  |  Size: 38 KiB

After

Width:  |  Height:  |  Size: 38 KiB

View File

Before

Width:  |  Height:  |  Size: 38 KiB

After

Width:  |  Height:  |  Size: 38 KiB

View File

@@ -17,7 +17,7 @@ The webinterface is written in PHP using the extremely popular PHP Framework **L
Besides visualization, the webinterface is also used to configure the machinery. On the settings page a user can select different options, for example a user could select a region where motion should be detected or could select a time range when motion could be detected, which algorithm is used, etc.
The webinterface can also be used to configure Kerberos with our [**cloud application**](/dev/addons/Cloud). The setup is very easy, you only need to create an account on our cloud application, request a key, and enter it in every webinterface you want to have synced.
The webinterface can also be used to configure Kerberos with our [**cloud application**](/addons/Cloud). The setup is very easy, you only need to create an account on our cloud application, request a key, and enter it in every webinterface you want to have synced.
<a name="installation"></a>
## Installation

View File

@@ -12,7 +12,7 @@ The web interace contains several important concepts and this is the right place
The web interface can be used to configure the machinery and therefore provides a *settings* page where algorithms, expositors, etc can be configured. The web interface will convert the configuration files into HTML elements, so when adding new algorithms or heuristics, the parameters will be reflected in the web interface 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 **app/views/controls** directory.
The webinterface can be used to configure Kerberos with our [**cloud application**](/dev/addons/Cloud). The setup is very easy, you only need to create an account on our cloud application, request a key, and enter it in every webinterface you want to have synced. Once Kerberos is configured with the cloud application, a filewatcher, **Gruntjs**, will push new images to the cloud application immediately.
The webinterface can be used to configure Kerberos with our [**cloud application**](/addons/Cloud). The setup is very easy, you only need to create an account on our cloud application, request a key, and enter it in every webinterface you want to have synced. Once Kerberos is configured with the cloud application, a filewatcher, **Gruntjs**, will push new images to the cloud application immediately.
<a name="file-structure"></a>
## File structure

View File

@@ -12,9 +12,9 @@ Kerberos.io, the machinery, is a video detection framework, it uses a flexible p
<a name="how-does-it-work"></a>
## How does it work?
More information can be found on the [project structure page](/dev/machinery/project_structure).
More information can be found on the [project structure page](/machinery/project_structure).
<a name="installation"></a>
## Installation
The machinery will be installed when deploying the image on your SD card. However you can also compile and link the machinery yourself. Look at the [installation section](/dev/installation) to read more about it.
The machinery will be installed when deploying the image on your SD card. However you can also compile and link the machinery yourself. Look at the [installation section](/installation) to read more about it.

View File

@@ -20,7 +20,7 @@ Update the ArchLinux kernel
Install git, subversion, development tools (c++, cmake) and V4L utils.
pacman -S git subversion cmake base-devel v4l-utils eigen
pacman -S git subversion cmake base-devel v4l-utils eigen ffmpeg curl
Go to home directory
@@ -35,10 +35,6 @@ Compile kerberos
cd kerberos-io && mkdir build && cd build
cmake .. && make && make check
Add link library to path
export DYLD_LIBRARY_PATH=$DYLD_LIBRARY_PATH:/home/kerberos-io/build/thirdparty/lib/
Give rights to config files
chmod -R 777 ../config
@@ -62,22 +58,6 @@ Copy and paste the configuration to the kerberos.service
[Install]
WantedBy=multi-user.target
Create timer file for kerberos
nano /etc/systemd/system/kerberos.timer
Copy and paste the configuration to the kerberos.timer
[Unit]
Description=Runs kerberos.service, 1 min after system boot.
[Timer]
OnBootSec=1min
Unit=kerberos.service
[Install]
WantedBy=multi-user.target
Enable the service to start on boot
systemctl enable kerberos.timer
systemctl enable kerberos.service

View File

Before

Width:  |  Height:  |  Size: 76 KiB

After

Width:  |  Height:  |  Size: 76 KiB

View File

Before

Width:  |  Height:  |  Size: 230 KiB

After

Width:  |  Height:  |  Size: 230 KiB

View File

Before

Width:  |  Height:  |  Size: 132 KiB

After

Width:  |  Height:  |  Size: 132 KiB

View File

Before

Width:  |  Height:  |  Size: 70 KiB

After

Width:  |  Height:  |  Size: 70 KiB

View File

Before

Width:  |  Height:  |  Size: 141 KiB

After

Width:  |  Height:  |  Size: 141 KiB

View File

Before

Width:  |  Height:  |  Size: 58 KiB

After

Width:  |  Height:  |  Size: 58 KiB

View File

@@ -1,6 +1,7 @@
# Capture
* [USB camera](#usb-camera)
* [IP camera](#ip-camera)
* [Raspberry Pi Camera Module](#raspberry-pi-camera-module)
The capture device is responsible to take images. The images are used in the four pass way.
@@ -10,7 +11,12 @@ The capture device is responsible to take images. The images are used in the fou
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.
<a name="ip-camera"></a>
## 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.
<a name="raspberry-pi-camera-module"></a>
## Raspberry Pi Camera Module
You can use the Raspberry Pi Camera Module with Kerberos, you just need to attach the camera module and you are ready to go. The Raspberry Pi Camera Module is enabled by default in the web interface. Please note that if you didn't installed Kerberos with the image, you will need to [enable the camera module](/1.0.0/FAQ#how-to-enable-camera-module) yourself.
You can use the Raspberry Pi Camera Module with Kerberos, you just need to attach the camera module and you are ready to go. The Raspberry Pi Camera Module is enabled by default in the web interface. Please note that if you didn't installed Kerberos with the image, you will need to [enable the camera module](/FAQ#how-to-enable-camera-module) yourself.

View File

@@ -1,6 +1,6 @@
# 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 you have updated the web interface, to make Kerberos aware you will be using an USB camera. [Be carefull](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.
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 you have updated the web interface, to make Kerberos 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.
## Web interface
@@ -15,10 +15,20 @@ The parameters of the USB capture device can be found in the *config/capture.xml
<USBCamera>
<frameWidth type="number">1280</frameWidth>
<frameHeight type="number">720</frameHeight>
<delay type="number">0</delay>
<angle type="number">0</angle>
</USBCamera>
</captures>
### 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.
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.
### 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.

View File

Before

Width:  |  Height:  |  Size: 16 KiB

After

Width:  |  Height:  |  Size: 16 KiB

View File

@@ -0,0 +1,39 @@
# IP Camera
Kerberos can be used with any IP camera, that provides a 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 interface, to make Kerberos aware you will be using an IP camera.
## Web interface
![IP camera](2_ip-camera.png)
## Parameters
The parameters of the IP capture device can be found in the *config/capture.xml* file, but you can also use the web interface to modify the parameters. Below you see a default configuration file.
<captures>
<IPCamera>
<url type="text">http://username:password@ipaddress/image.jpg</url>
<frameWidth type="number">800</frameWidth>
<frameHeight type="number">640</frameHeight>
<delay type="number">0</delay>
<angle type="number">0</angle>
</IPCamera>
</captures>
### URL
To use your IP camera, you should provide a valid MJPEG URL. Kerberos 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.

Binary file not shown.

After

Width:  |  Height:  |  Size: 20 KiB

View File

@@ -0,0 +1,34 @@
# Raspberry Camera
You can use the Raspberry Pi Camera Module with Kerberos. You just need to attach the camera module and you're ready to go. The Raspberry Pi Camera Module is enabled by default in the web interface.
## Web interface
![Raspberry PI Camera Module](3_raspi-camera.png)
## 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 interface to modify the parameters. Below you see a default configuration file.
<captures>
<RaspiCamera>
<frameWidth type="number">800</frameWidth>
<frameHeight type="number">640</frameHeight>
<delay type="number">0</delay>
<angle type="number">0</angle>
</RaspiCamera>
</captures>
### 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.

View File

Before

Width:  |  Height:  |  Size: 21 KiB

After

Width:  |  Height:  |  Size: 21 KiB

View File

Before

Width:  |  Height:  |  Size: 67 KiB

After

Width:  |  Height:  |  Size: 67 KiB

View File

Before

Width:  |  Height:  |  Size: 38 KiB

After

Width:  |  Height:  |  Size: 38 KiB

View File

Before

Width:  |  Height:  |  Size: 8.1 KiB

After

Width:  |  Height:  |  Size: 8.1 KiB

View File

Before

Width:  |  Height:  |  Size: 9.3 KiB

After

Width:  |  Height:  |  Size: 9.3 KiB

View File

Before

Width:  |  Height:  |  Size: 22 KiB

After

Width:  |  Height:  |  Size: 22 KiB

View File

Before

Width:  |  Height:  |  Size: 13 KiB

After

Width:  |  Height:  |  Size: 13 KiB

View File

Before

Width:  |  Height:  |  Size: 560 KiB

After

Width:  |  Height:  |  Size: 560 KiB

View File

Before

Width:  |  Height:  |  Size: 16 KiB

After

Width:  |  Height:  |  Size: 16 KiB

View File

Before

Width:  |  Height:  |  Size: 13 KiB

After

Width:  |  Height:  |  Size: 13 KiB

View File

@@ -1,6 +1,6 @@
# TCP/IP client
The TCP/IP client will send a TCP package to a server.
The TCP/IP client will send a TCP packet to a server.
## Web interface
@@ -22,7 +22,7 @@ The parameters of the TCP/IP client can be found in the config/io.xml file, but
### Server
The ip of the TCP server.
The IP of the TCP server.
### Port
@@ -34,4 +34,4 @@ You can send some data to a TCP server.
## Examples
More information can be found [here](/1.0.0/addons/TCP_listener).
More information can be found [here](/addons/TCP_Listener).

View File

Before

Width:  |  Height:  |  Size: 15 KiB

After

Width:  |  Height:  |  Size: 15 KiB

View File

Before

Width:  |  Height:  |  Size: 11 KiB

After

Width:  |  Height:  |  Size: 11 KiB

View File

@@ -0,0 +1,25 @@
# 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.
**Make sure that the Webhook comes after the Disk device, otherwise the URL of the image is not included.**
## Web interface
![Webhook io](4_webhook.png)
## Parameters
The parameters of the webhook can be found in the config/io.xml file, but you can also use the web interface to modify the parameters. Below you see a default configuration file.
<ios>
<Webhook>
<url type="text">http://kerberos.web/api/v1/webhook</url>
</Webhook>
</ios>
### Url
This is the URL, to which Kerberos will send a JSON object (as a POST request).

Binary file not shown.

After

Width:  |  Height:  |  Size: 13 KiB

View File

Before

Width:  |  Height:  |  Size: 964 KiB

After

Width:  |  Height:  |  Size: 964 KiB

View File

@@ -3,6 +3,7 @@
* [Image](#image)
* [GPIO](#gpio)
* [TCP/IP client](#tcp-ip-client)
* [Webhook](#webhook)
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.
@@ -16,4 +17,8 @@ You can trigger a specific GPIO pin on the Raspberry Pi.
<a name="tcp-ip-client"></a>
## TCP/IP client
The TCP/IP client will send a TCP packet to a server.
The TCP/IP client will send a TCP packet to a server.
<a name="webhook"></a>
## 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.

25
42_addons/3_NAS.md Normal file
View File

@@ -0,0 +1,25 @@
# NAS
By default images are stored on the SD card of the Raspberry Pi, in the folder **/home/kerberos-web/public/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 to the Kerberos image.
## Let's get started
First you will need to connect to the Raspberry Pi, you can find a how to **[on our FAQ page](/FAQ#how-to-access-the-pi)**.
Next 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**.
nano /etc/fstab
Add following line (replace variables **with your own credentials**):
//ip_address_to_your_nas/directory_on_your_nas /home/kerberos-web/public/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 /home/kerberos-web/public/capture && ls -l
And *that's it*. From now the machinery will store its images directly on your NAS, and the web interface will visualize them.

81
4_release_notes.md Normal file
View File

@@ -0,0 +1,81 @@
# Release notes
* [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)
<a name="1-1-0"></a>
## 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)
<a name="1-0-3"></a>
## 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.
<a name="1-0-2"></a>
## 1.0.2
#### Web
* Timezone on settings page is also used for the webinterface.
#### Machinery
* Added extra timezones to timezone.xml.
<a name="1-0-1"></a>
## 1.0.1
#### Web
* Improved error handling (date search).
#### Machinery
* Improved memory cleanup.
<a name="1-0-0"></a>
## 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**.

View File

@@ -2,6 +2,7 @@
The FAQ, Frequently Asked Questions, page contains **technical solutions** for common problems concerning the installation of Kerberos. This page does **NOT** contain non-technical questions and answers; The Raspberry Pi doesn't turn on, I don't have WIFI access, etc. Therefore you can access our [**knowledge base**](https://kerberosio.zendesk.com).
* [How to access the Raspberry Pi](#how-to-access-the-pi)
* [How to expand SD card root partition](#expand-sd-card)
* [Arch Linux](#expand-sd-card-archlinux)
* [How to backup SD card](#backup-sd-card)
@@ -10,11 +11,21 @@ The FAQ, Frequently Asked Questions, page contains **technical solutions** for c
* [Arch Linux](#how-to-enable-camera-module-archlinux)
* [Clean up disk and memory space](#clean-up-disk)
<a name="how-to-access-the-pi"></a>
## How to access the Raspberry Pi
Kerberos is built on Arch Linux, which by default is installed **without** a **Graphical User Interface**. This means that when attaching the Raspberry Pi to a monitor or connecting with SSH, will **only show you a command prompt**.
macbook:~ cedricverstraeten$ ssh root@ 192.168.0.10
root@ 192.168.0.10's password:
You can sign in with the default Arch Linux credentials: username "**root**" and password "**root**".
<a name="expand-sd-card"></a>
## How to expand SD card root partition
<a name="expand-sd-card-archlinux"></a>
### Arch Linux
### Arch Linux (Raspberry Pi A, B, B+)
After logging in you view the status of filesystem (the output can be different):
@@ -145,6 +156,116 @@ Check and it is done :-)
tmpfs 231M 0 231M 0% /tmp
/dev/mmcblk0p1 90M 24M 67M 27% /boot
### Arch Linux (Raspberry Pi 2)
After logging in you view the status of filesystem (the output can be different):
[root@alarmpi ~]# df -h
Filesystem Size Used Avail Use% Mounted on
/dev/root 3.2G 2.8G 161M 95% /
devtmpfs 427M 0 427M 0% /dev
tmpfs 431M 0 431M 0% /dev/shm
tmpfs 431M 392K 431M 1% /run
tmpfs 431M 0 431M 0% /sys/fs/cgroup
tmpfs 431M 0 431M 0% /tmp
/dev/mmcblk0p1 100M 18M 83M 18% /boot
tmpfs 87M 0 87M 0% /run/user/0
Using the command fdisk will edit the filesystem /dev/mmcblk0:
[root@alarmpi ~]# fdisk /dev/mmcblk0
Welcome to fdisk (util-linux 2.23.1).
Changes will remain in memory only, until you decide to write them.
Be careful before using the write command.
Command (m for help):
List the information and delete partition 2:
Command (m for help): p
Disk /dev/mmcblk0: 7.2 GiB, 7746879488 bytes, 15130624 sectors
Units: sectors of 1 * 512 = 512 bytes
Sector size (logical/physical): 512 bytes / 512 bytes
I/O size (minimum/optimal): 512 bytes / 512 bytes
Disklabel type: dos
Disk identifier: 0x4bce3dec
Device Boot Start End Sectors Size Id Type
/dev/mmcblk0p1 2048 206847 204800 100M c W95 FAT32 (LBA)
/dev/mmcblk0p2 206848 7000000 6793153 3.2G 83 Linux
Command (m for help): d
Partition number (1,2,5, default 5): 2
Partition 2 has been deleted.
Command (m for help):
Create a new extended partition a logical volume:
Command (m for help): n
Partition type:
p primary (1 primary, 0 extended, 3 free)
e extended
Select (default p): p
Partition number (2-4, default 2):
First sector (206848-15130623, default 206848):
Last sector, +sectors or +size{K,M,G,T,P} (206848-15130623, default 15130623):
Created a new partition 2 of type 'Linux' and of size 7.1 GiB.
Check whether top block starts in the same place as the original (start)
Command (m for help): p
Disk /dev/mmcblk0: 7.2 GiB, 7746879488 bytes, 15130624 sectors
Units: sectors of 1 * 512 = 512 bytes
Sector size (logical/physical): 512 bytes / 512 bytes
I/O size (minimum/optimal): 512 bytes / 512 bytes
Disklabel type: dos
Disk identifier: 0x4bce3dec
Device Boot Start End Sectors Size Id Type
/dev/mmcblk0p1 2048 206847 204800 100M c W95 FAT32 (LBA)
/dev/mmcblk0p2 206848 15130623 14923776 7.1G 83 Linux
Command (m for help):
If it starts again (in this case on 186368 p2 a 188416 p5) write changes and reboot.
Command (m for help): w
The partition table has been altered!
Calling ioctl() to re-read partition table.
WARNING: Re-reading the partition table failed with error 16: Device or resource busy.
The kernel still uses the old table. The new table will be used at
the next reboot or after you run partprobe(8) or kpartx(8)
Syncing disks.
[root@alarmpi ~]# reboot
After booting the system we online enlarge root partitions
[root@alarmpi ~]# resize2fs /dev/mmcblk0p2
resize2fs 1.42.12 (29-Aug-2014)
Filesystem at /dev/mmcblk0p2 is mounted on /; on-line resizing required
old_desc_blocks = 1, new_desc_blocks = 1
The filesystem on /dev/mmcblk0p2 is now 1865472 (4k) blocks long.
Check and it is done :-)
[root@alarmpi ~]# df -h
Filesystem Size Used Avail Use% Mounted on
/dev/root 7.0G 2.8G 3.9G 43% /
devtmpfs 427M 0 427M 0% /dev
tmpfs 431M 0 431M 0% /dev/shm
tmpfs 431M 392K 431M 1% /run
tmpfs 431M 0 431M 0% /sys/fs/cgroup
tmpfs 431M 0 431M 0% /tmp
/dev/mmcblk0p1 100M 18M 83M 18% /boot
tmpfs 87M 0 87M 0% /run/user/0
<a name="backup-sd-card"></a>
## How to backup SD card
@@ -157,25 +278,31 @@ You can backup your SD card, by typing following command in your terminal. This
### Installed Kerberos.io from image
When kerberos is installed with the image, you can edit the wireless.conf file on the SD card. Insert the SD card in your workstation and open the file **/boot/wireless.conf**. You will see a similar config like below, edit the ESSID property with the name of your WIFI connection and the property Key with the WIFI password.
When kerberos is installed with the image, you can edit the wireless.conf file on the SD card. Insert the SD card in your workstation and open the file **wireless.conf**. You will see a similar config like below, edit the ESSID property with the name of your WIFI connection and the property Key with the WIFI password. **Don't forget to match the Address and Gateway fields, with your internal network**.
Description='A simple WPA encrypted wireless connection'
Interface=wlan0
Connection=wireless
Security=wpa
ESSID='network-name'
Key='plain-text-password'
IP=static
Address='192.168.0.x/24'
##################
# WIFI credentials
Security=wpa
ESSID='YOUR-WIFI-SSID'
Key='YOUR-WIFI-PASSWORD'
#####################
# Static IP address
# (Don't forget to add the subnet at the end of the Address e.g. /24)
Address='192.168.0.11/24'
Gateway='192.168.0.1'
DNS=('192.168.0.1')
IP=static
# Uncomment this if your ssid is hidden
#Hidden=yes
### Installed Kerberos.io from source
#### Archlinux
@@ -249,10 +376,6 @@ Copy paste the bash script
/usr/bin/forever restartall ;
fi;
#############################################
# Only keep images of last 3 days on sd-card.
##
find /home/kerberos-web/public/capture/ -type f -name '*.jpg' -mtime +1 -exec rm {} \;
##############################################################
# Check if disk size is more than 95%, if so remove some files
@@ -260,7 +383,7 @@ Copy paste the bash script
##
if [[ $(df -h | grep /dev/root | awk -F' ' '{ print $5/1 }' | tr ['%'] ["0"]) -gt 95 ]];
then
rm -f $( ls -d -1tr /home/kerberos-web/public/capture/* | head -n 500);
rm -f $( ls -d -1tr /home/kerberos-web/public/capture/* | head -n 1000);
fi;
Give rights to bash script

View File

@@ -1,5 +1,7 @@
#KERBEROS.IO - documentation
[![Join the chat at https://gitter.im/kerberos-io/hades](https://img.shields.io/badge/GITTER-join chat-green.svg)](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.

Binary file not shown.

Before

Width:  |  Height:  |  Size: 19 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 23 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 33 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 58 KiB

View File

@@ -1,29 +0,0 @@
# Requirements
* [Which hardware do I need?](#which-hardware-do-i-need)
<a name="which-hardware-do-i-need"></a>
## Which hardware do I need?
Kerberos.io is created for the **Rapsberry Pi**. So it is obvious you will need a Raspberry Pi before you can start using Kerberos. However you can also use Kerberos.io on your local environment, but of course that is not the main goal of Kerberos.
You can select which Raspberry Pi model you need: **Raspberry Pi Model A, A+, B, B+ or Raspberry Pi 2**.
![Raspberry Pi Model A](2_raspberry-pi-a.png)
You need a **4GB or bigger SD card**, on which you will have to deploy the Kerberos.io image; look at the installation page for more information about the deployment.
![4GB SD card](2_sandisk_4gb_sd_card.png)
A **micro USB 5V** charger.
![Micro USB 5V charger](2_micro-usb-5V-charger.png)
A **USB camera** or the **Raspberry Pi camera** module.
![Raspberry Pi Camera Module](2_raspberry-camera-module.png)
*(Optional)* We can use a **WIFI dongle** instead of an ethernet cable, but this is not required. We recommend the **Edimax** ew-7811un WIFI dongle.
![Edimax WIFI dongle](2_edimax-wifi-dongle.png)
*(Optional)* The **Scorpi B+**, a flexible Mount for the Raspberry Pi Camera Board.

Binary file not shown.

Before

Width:  |  Height:  |  Size: 19 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 340 KiB

View File

@@ -1,101 +0,0 @@
# Installation
* [Install from image](#install-from-image)
* [Download the image](#download-the-image)
* [Insert your SD card](#insert-your-sd-card)
* [OSX: transfer image](#osx-transfer-image)
* [Windows: transfer image](#windows-transfer-image)
* [OSX/Linux: transfer image with terminal](#transfer-image-with-terminal)
* [(Optional) Setup WIFI connection](#setup-wifi-connection)
* [Install from source](#install-from-source)
Kerberos is **easy to install**, you just have to copy the Kerberos image to your SD card, plug the SD card into your Raspberry Pi and that's it. It can also be installed on other devices than the Raspberry Pi; for development or production. Therefore you will need to compile the machinery from source and install the webinterface with your favorite webserver.
<a name="install-from-image"></a>
## Install from image
If you want to use Kerberos.io **as a service**, this would be the preferred way. Kerberos is provided as an image, a pre-installed operating system. The only thing you have to do to make things work, is to transfer the image to your SD card. After transferring you can just plug the SD card into your Raspberry Pi and kerberos will work; isn't that great!
The're a lot of different ways to accomplish this, and they are different according the operating system you will be using to transfer the image.
<a name="download-the-image"></a>
### 1. Download the image
First you will need to download the Kerberos image; click on the image below. The Kerberos.io image contains a Linux operating system, built on Arch Linux. The image has the machinery and webinterface installed, and ofcourse all the dependencies Kerberos needs. With this image you just have to plugin the SD card in your Raspberry Pi and you're done.
#### Raspberry Pi Model A, A+, B and B+
The Raspberry Pi is a credit-card sized computer that plugs into your TV and a keyboard. Its a capable little PC which can be used for many of the things that your desktop PC does, like spreadsheets, word-processing and games. It also plays high-definition video.
[![Kerberos.io image](3_kerberos-image.png)](https://mega.co.nz/#!vY4WjKJD!2sZUuhzeVDFu47hSOQ94Jh27v0BLYpf6MRTBBzGfkrc)
#### Raspberry Pi Model 2
The Raspberry Pi 2 is the successor to the Raspberry Pi. It builds upon the original model B+ upgrading to 1 GB of RAM, and replacing the aged ARMv6l single-core with an ARMv7l Cortex-A7 quad-core.
[![Kerberos.io image](3_kerberos-image.png)](https://mega.co.nz/#!6AAGlAwa!dJqbpGBG_k2ZA2FACtTbY4WR2azaV2Izeur-k3_4RlU)
<a name="insert-your-sd-card"></a>
### 2. Insert your SD Card
Ensure that you have inserted the SD card, that you wish to clone, into the SD card reader. If your PC/Mac does'nt have an internal SD card reader, you will need to plug in an external SD card reader via a USB socket.
<a name="osx-transfer-image"></a>
### 3. OSX: transfer image
* Download the .dmg file (RPi-sd card builder v1.2)
[![RPi logo](3_rpi-logo-cloner.png)](https://mega.co.nz/#!PZc2HTTQ!eD9dtFpoKnbZqP1hkvrv43_Pvc9xadMVxRP2K-M8n88)
* Run the app
* Select the operating system distributions (.img file)
* You will prompt with this. After you connect your SD card press continue.
* Now you have to select your SD card.
* Now the program will need administrator privileges. insert your password
* Confirm that your SD card has been unmounted.
<a name="windows-transfer-image"></a>
### 3. Windows: transfer image
* Download and install the [Win32DiskImager](http://sourceforge.net/projects/win32diskimager/files/latest/download).
* Select the image file you've downloaded earlier and the drive letter of the SD card.
<a name="transfer-image-with-terminal"></a>
### 3. OSX/Linux: transfer image with terminal
#### Locate Your SD Card
Open Terminal and enter the following command to locate your SD Card:
diskutil list
Look for your SD card; you can look at the size of the disk. In most cases you will be using a 4GB or bigger SD card.
#### Unmount SD card
We located our SD card at the /dev/disk3 drive; please note that this can be another disk drive, see previous step. In Terminal, enter the following command:
diskutil unmountDisk /dev/disk3
#### Format SD card
To format the SD card, enter the following command:
sudo newfs_msdos -F 16 /dev/disk3
#### Transfer image to your SD card
In Terminal, enter the following command ensuring that you identify the correct destination disc.
sudo dd if=~/Desktop/kerberos-io.img of=/dev/disk3
<a name="setup-wifi-connection"></a>
### 4. (Optional) Setup WIFI connection
If you will be using Kerberos.io with a WIFI dongle, then check out the [F.A.Q. page](/1.0.0/FAQ#setup-wifi).
<a name="install-from-source"></a>
## Install from source
This will be the procedure if you want to contribute to Kerberos or if you want to use Kerberos on your local machine. To install Kerberos from source; you will need to [compile the machinery](/1.0.0/machinery/installation) from source and [import the webinterface](/1.0.0/web/installation) into your favorite webserver.

Binary file not shown.

Before

Width:  |  Height:  |  Size: 18 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 38 KiB

View File

@@ -1,106 +0,0 @@
# Installation
* [Install from source](#install-from-source)
* [Install on Arch Linux](#install-from-source-on-arch-linux)
The web interface is already installed on the Kerberos image, however you can also install the webinterface from source; you don't need to do this if you've deployed the Kerberos image on the SD card.
<a name="install-from-source"></a>
## Install from source
The web interface can be installed standalone, for example to host the web interface on an external server; e.g. to increase performance and to centralize multiple kerberos instances.
<a name="install-from-source-on-arch-linux"></a>
### Install on Arch Linux
Update the Arch Linux kernel
pacman -Syyu
Install git, nginx, php with extensions and nodejs
pacman -S git nginx php php-fpm php-gd php-mcrypt php-apc php-composer nodejs
Start nginx and php-fpm on boot
systemctl enable nginx
systemctl enable php-fpm
Edit nginx config
nano /etc/nginx/nginx.conf
Copy and paste following config
user http http;
worker_processes 1;
worker_rlimit_nofile 8192;
events {
worker_connections 1024;
}
http {
index index.html index.htm index.php;
include mime.types;
root /home/kerberos-web/public;
server {
server_name kerberos.rpi kerberos.rpi;
index index.php index.html index.htm;
location /{
try_files $uri $uri/ /index.php?$query_string;
}
location ~ \.php$ {
fastcgi_pass unix:/run/php-fpm/php-fpm.sock;
fastcgi_index index.php;
include fastcgi.conf;
}
}
}
Make sure you've enabled following php extensions: mcrypt, phar, gd and openssl.
nano /etc/php/php.ini
Uncomment following extensions
extension=mcrypt.so
extension=phar.so
extension=gd.so
extension=openssl.so
Add the APC extension at the end of the extensions list
extension=apcu.so
Go to home directory
cd /home
Get the source code from github
git clone https://github.com/kerberos-io/web kerberos-web
Install php packages by using composer
cd kerberos-web
composer install
Change config file: edit the "config" variable, link it to the config directory of the kerberos-io repository. If you don't have the kerberos-io repository installed on that specific server, you can make it an empty string. In this case the option "settings" won't show up in the navigation menu. Please note that the default value is set to the destination of the machinery when installed on the Raspberry Pi.
nano app/config/app.php
Change write permission on the storage directory
chmod -R 777 app/storage
Install bower globally by using node package manager, this is installed when installing nodejs.
npm -g install bower
Install Front end dependencies with bower
cd public
bower --allow-root install

View File

@@ -1,40 +0,0 @@
# Contribute
* [Versioning](#versioning)
* [Composer](#composer)
* [Laravel](#laravel)
* [Bower](#bower)
This documents describes how to contribute to Kerberos and describes all the technical stuff you will need to know. If you want to contribute you will need to install the source code on your local environment.
<a name="versioning"></a>
## Versioning
The source is managed on [Github](https://github.com/kerberos-io), and thus we are using git as our version control. For simplicity we are using following [branching model](http://nvie.com/posts/a-successful-git-branching-model/). The model includes:
* main branch
* develop branch
* hotfix and release branches
If you are a new developer, fork the development branch and send a pull request.
<a name="composer"></a>
## Composer
Make sure you have [composer installed](https://getcomposer.org/download/) on your local system. Run this in your terminal to get the latest Composer version:
curl -sS https://getcomposer.org/installer | php
Or if you don't have curl:
php -r "readfile('https://getcomposer.org/installer');" | php
<a name="laravel"></a>
## Laravel
We're using Laravel as our PHP framework. You will find all the information you need on the laravel [documentation site](http://laravel.com/docs).
<a name="bower"></a>
## Bower
Bower is used for managing our front end dependencies. Bower can be installed with npm, so make sure you have installed node.

Binary file not shown.

Before

Width:  |  Height:  |  Size: 76 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 230 KiB

View File

@@ -1,360 +0,0 @@
# Contribute
* [Versioning](#versioning)
* [CMake](#cmake)
* [CMake setup](#cmake-setup)
* [Src folder](#src-folder)
* [CMake folder](#cmake-folder)
* [Setup kerberos in your IDE](#setup-kerberos-in-your-ide)
* [OSX](#osx)
* [Create a new XCode project](#create-a-new-xcode-project)
* [Compile source with CMake](#compile-source-with-cmake)
* [Link headers and libraries](#link-headers-and-libraries)
* [Add source to project](#add-source-to-project)
* [Select libraries](#select-libraries)
* [Specifiy header- and library locations](#specify-header-and-library-locations)
* [Linux](#linux)
* [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)
This documents describes how to contribute to the machinery and describes all the technical stuff you will need to know. If you want to contribute you will need to install the source code on your local environment.
<a name="versioning"></a>
## Versioning
The source is managed on [Github](https://github.com/kerberos-io), and thus we are using git as our version control. For simplicity we are using following [branching model](http://nvie.com/posts/a-successful-git-branching-model/). The model includes:
* main branch
* develop branch
* hotfix and release branches
If you are a new developer, fork the development branch and send a pull request.
<a name="cmake"></a>
## CMake
As mentioned before on the *installation* page, the machinery is using CMake. Therefore if you want to compile the source code, you will need to have installed CMake first. When executing the **CMake** command, CMake will create the appropriate makefiles to compile the machinery.
<a name="cmake-setup"></a>
### 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.
<a name="src-folder"></a>
#### 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.
<a name="cmake-folder"></a>
#### 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.
<a name="setup-kerberos-in-your-ide"></a>
## Setup kerberos in your IDE
<a name="osx"></a>
### OSX
OSX users can use the XCode IDE to contribute to the machinery. The only hard thing will be to setup the XCode configuration files; to indicate where the headers can be found and where the dynamic libraries are located.
<a name="create-a-new-xcode-project"></a>
#### Create a new XCode project
First we will create a new XCode C++ project and checkout the machinery from [Github](https://github.com/kerberos-io).
<a name="compile-source-with-cmake"></a>
#### Compile source with CMake
Once the project has been setup, we will compile the source code with CMake. Open a terminal and go to the root of the project, enter following command.
mkdir build && cd build && cmake .. && make
<a name="link-headers-and-libraries"></a>
#### Link headers and libraries
When the source has been compiled succesfully we will modify the XCode configuration of the machinery. Therefore we will need to do three things: include the header directories, link the libraries and include the source files.
<a name="add-source-to-project"></a>
##### Add source to project
Select all the source files in the **/src** directory, and drag-and-drop them in the *Compile Sources* section.
![Add source](3_add-source.png)
<a name="select-libraries"></a>
##### Select libraries
Select all the libraries in the **/build/thirdparty/lib** directory, and drag-and-drop them in the *Link Binary With Libraries* section.
![Select libraries](3_add-libraries.png)
<a name="specify-header-and-library-locations"></a>
##### Specifiy header- and library locations
Click on the project name and select the *Build Settings* page, search for the keyword **search**.
![Select criteria](3_select-search-criteria.png)
Define the header search paths.
![Select header paths](3_header-paths.png)
Define the library search paths.
![Select header paths](3_library-paths.png)
<a name="linux"></a>
### Linux
The idea is the same as the installation for OSX, so first you will need to checkout the source code and compile it with the one liner below.
mkdir build && cd build && cmake .. && make
For the time being I didn't had the time to find a good IDE for Linux and to experiment with it. So if someone else could complete the documentation for Linux environments that would be great!
<a name="adding-a-new-class"></a>
## 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.
<a name="create-the-header-file"></a>
### 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 that. 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<AnotherAlgorithmName, AnotherAlgorithm>
{
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 unqie name for the class, this name will be used to make some kind of dependency injection possible. We will use the name to setup the configuration files, and to use it to select a specific class. 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<Algorithm>::getInstance()->create("AnotherAlgorithm");
<a name="create-the-source-file"></a>
### 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;
}
}
<a name="modifile-the-cmakelists-file"></a>
### 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
)
<a name="create-a-new-entry-in-the-config-file"></a>
### 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 interface 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 interface where we are able to add numbers.
<algorithms>
<AnotherAlgorithm>
<parameter type="number">5</parameter>
</AnotherAlgorithm>
</algorithms>
You can retrieve the parameter in the **setup** function with the settings parameter.
settings.at("algorithms.AnotherAlgorithm.parameter")
<a name="compile"></a>
### 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! However if you are compiling from the commandline you just have to go to the build folder and write **make**.
<a name="adding-a-test"></a>
## 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 how to write a simple test.
<a name="create-the-test-file"></a>
### 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<Condition>::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$

Binary file not shown.

Before

Width:  |  Height:  |  Size: 132 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 70 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 141 KiB

View File

@@ -1,131 +0,0 @@
# Project structure
* [Lifecycle](#lifecycle)
* [Capture](#capture)
* [Condition](#condition)
* [Algorithm](#algorithm)
* [Expositor](#expositor)
* [Heuristic](#heuristic)
* [Io](#io)
* [Technical design](#techinal-design)
* [Configuration](#configuration)
* [Filewatcher](#filewatcher)
* [Factory](#factory)
* [Dependencies](#dependencies)
* [Image Processing](#image-processing)
* [RapidJSON](#rapidjson)
* [Testing](#testing)
* [Continous integration](#continous-integration)
* [Unit testing / Mocking](#unit-testing-mocking)
* [File structure](#file-structure)
The machinery contains several important concepts and this is the place where we will tackle them briefly.
<a name="lifecycle"></a>
## Lifecycle
The machinery is a video recognition framework and 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. 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](4_project_structure.png)
<a name="capture"></a>
### Capture
You can choose which capture device you will be using, you can use your old USB webcam or the hi-tech and cheap Raspberry Pi Camera Module. The capture device will take some pictures and deliver them to the algorithm if the conditions (the first step of the four passway) are valid.
<a name="condition"></a>
### Condition
The condition is the first step of the four passway. In this step kerberos 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 and configured with the web interface.
<a name="algorithm"></a>
### 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.
<a name="expositor"></a>
### 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.
<a name="heuristic"></a>
### Heuristic
When the expositor detected some kind of region, a heuristic will evaluate, the current and previous detections. The heuristic is basically some kind of memory which makes decision and tells kerberos if the detection was true or false.
<a name="io"></a>
### IO
If the heuristic determined that the detection was valid, one or more IO operations can be executed. For example an image can be saved to disk or an email can be sent.
<a name="technical-design"></a>
## Technical design
Kerberos.io has some technical design concepts, the most important parts are described below.
<a name="configuration"></a>
### Configuration
When the machinery is started, the first thing it will do is reading a configuration file; an XML file. 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 interface, but could also be modified manually; in the config directory of the machinery.
<a name="filewatcher"></a>
### 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, a user want to change the time constraints, or wants to enlarge the resolution of the captured images.
<a name="factory"></a>
### 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++.
<a name="dependencies"></a>
## Dependencies
Kerberos.io 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, ..).
<a name="image-processing"></a>
### Image Processing
Kerberos.io is a video recognition framework and is therefore using a image processing library; OpenCV (Open Source Computer Vision). Thanks to this very powerful computer vision framework, developers can benefit from it and increase development time.
<a name="rapidjson"></a>
### Rapidjson
The machinery is using the rapidjson library to provide a flexible datastructure: JSON. The library is used within the core of kerberos, and is concerned within every step of the four pass way; except in the first step the condition, to be 100% correct.
<a name="testing"></a>
## Testing
<a name="continous-integration"></a>
### Continous integration
The machinery is deployed automatically on **travis-ci**, when a new commit/release is pushed.
<a name="unit-testing-mocking"></a>
### 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 test can be found in the **test** directory. You can run the test by executing following command:
make check
<a name="file-structure"></a>
## File structure
* **bin** - contains the kerberos compiled and linked executable.
* **build** - contains all the compiled dependencies and source code.
* **cmake** - information about how to compile kerberos, and were to find the dependencies.
* **config** - configuration files that are used to configure kerberos.
* **exceptions** - custom exceptions.
* **include** - kerberos header files.
* **logs** - log file, kerberos exceptions are written to.
* **src** - kerberos source files.
* **test** - google tests

Binary file not shown.

Before

Width:  |  Height:  |  Size: 58 KiB

Some files were not shown because too many files have changed in this diff Show More