mirror of
https://github.com/kerberos-io/documentation.git
synced 2026-08-23 15:18:31 +00:00
restructure branch make links independent of branch
This commit is contained in:
Cédric Verstraeten
@@ -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.
|
||||
|
||||
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -1,24 +0,0 @@
|
||||
# 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.
|
||||
|
||||
## Web interface
|
||||
|
||||
|
||||
|
||||
## Parameters
|
||||
|
||||
The parameters of the USB 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>
|
||||
|
||||
<USBCamera>
|
||||
<frameWidth type="number">1280</frameWidth>
|
||||
<frameHeight type="number">720</frameHeight>
|
||||
</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.
|
||||
@@ -1,37 +0,0 @@
|
||||
# TCP/IP client
|
||||
|
||||
The TCP/IP client will send a TCP packet to a server.
|
||||
|
||||
## Web interface
|
||||
|
||||
|
||||
|
||||
## 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).
|
||||
@@ -1,25 +0,0 @@
|
||||
# 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](/1.0.0/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.
|
||||
@@ -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](/1.0.0/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?
|
||||
|
Before Width: | Height: | Size: 38 KiB After Width: | Height: | Size: 38 KiB |
|
Before Width: | Height: | Size: 19 KiB After Width: | Height: | Size: 19 KiB |
|
Before Width: | Height: | Size: 23 KiB After Width: | Height: | Size: 23 KiB |
|
Before Width: | Height: | Size: 33 KiB After Width: | Height: | Size: 33 KiB |
|
Before Width: | Height: | Size: 58 KiB After Width: | Height: | Size: 58 KiB |
|
Before Width: | Height: | Size: 19 KiB After Width: | Height: | Size: 19 KiB |
|
Before Width: | Height: | Size: 340 KiB After Width: | Height: | Size: 340 KiB |
@@ -140,7 +140,7 @@ In Terminal, enter the following command ensuring that you identify the correct
|
||||
<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
|
||||
@@ -152,9 +152,9 @@ When the installation is completed, you can **plug the SD card** into your Raspb
|
||||
<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](/1.0.0/FAQ#how-to-access-the-pi)**.
|
||||
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.
|
||||
|
Before Width: | Height: | Size: 18 KiB After Width: | Height: | Size: 18 KiB |
|
Before Width: | Height: | Size: 38 KiB After Width: | Height: | Size: 38 KiB |
|
Before Width: | Height: | Size: 38 KiB After Width: | Height: | Size: 38 KiB |
@@ -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
|
||||
@@ -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
|
||||
@@ -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.
|
||||
|
Before Width: | Height: | Size: 76 KiB After Width: | Height: | Size: 76 KiB |
|
Before Width: | Height: | Size: 230 KiB After Width: | Height: | Size: 230 KiB |
|
Before Width: | Height: | Size: 132 KiB After Width: | Height: | Size: 132 KiB |
|
Before Width: | Height: | Size: 70 KiB After Width: | Height: | Size: 70 KiB |
|
Before Width: | Height: | Size: 141 KiB After Width: | Height: | Size: 141 KiB |
|
Before Width: | Height: | Size: 58 KiB After Width: | Height: | Size: 58 KiB |
@@ -13,4 +13,4 @@ Kerberos supports a whole range of USB cameras. You will find a complete list [h
|
||||
<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.
|
||||
|
Before Width: | Height: | Size: 16 KiB After Width: | Height: | Size: 16 KiB |
|
Before Width: | Height: | Size: 21 KiB After Width: | Height: | Size: 21 KiB |
|
Before Width: | Height: | Size: 67 KiB After Width: | Height: | Size: 67 KiB |
|
Before Width: | Height: | Size: 38 KiB After Width: | Height: | Size: 38 KiB |
|
Before Width: | Height: | Size: 8.1 KiB After Width: | Height: | Size: 8.1 KiB |
|
Before Width: | Height: | Size: 9.3 KiB After Width: | Height: | Size: 9.3 KiB |
|
Before Width: | Height: | Size: 22 KiB After Width: | Height: | Size: 22 KiB |
|
Before Width: | Height: | Size: 13 KiB After Width: | Height: | Size: 13 KiB |
|
Before Width: | Height: | Size: 560 KiB After Width: | Height: | Size: 560 KiB |
|
Before Width: | Height: | Size: 16 KiB After Width: | Height: | Size: 16 KiB |
|
Before Width: | Height: | Size: 13 KiB After Width: | Height: | Size: 13 KiB |
@@ -34,4 +34,4 @@ You can send some data to a TCP server.
|
||||
|
||||
## Examples
|
||||
|
||||
More information can be found [here](/dev/addons/TCP_Listener).
|
||||
More information can be found [here](/addons/TCP_Listener).
|
||||
|
Before Width: | Height: | Size: 15 KiB After Width: | Height: | Size: 15 KiB |
|
Before Width: | Height: | Size: 11 KiB After Width: | Height: | Size: 11 KiB |
|
Before Width: | Height: | Size: 964 KiB After Width: | Height: | Size: 964 KiB |
@@ -4,7 +4,7 @@ By default images are stored on the SD card of the Raspberry Pi, in the folder *
|
||||
|
||||
## Let's get started
|
||||
|
||||
First you will need to connect to the Raspberry Pi, you can find a how to **[on our FAQ page](/dev/FAQ#how-to-access-the-pi)**.
|
||||
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**.
|
||||
|
||||
@@ -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](/dev/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!
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 38 KiB |
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 |
@@ -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**.
|
||||
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
A **micro USB 5V** charger.
|
||||
|
||||
|
||||
|
||||
A **USB camera** or the **Raspberry Pi camera** module.
|
||||
|
||||
|
||||
|
||||
*(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.
|
||||
|
||||
|
||||
|
||||
*(Optional)* The **Scorpi B+**, a flexible Mount for the Raspberry Pi Camera Board.
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 19 KiB |
BIN
dev/2_scorpi.png
BIN
dev/2_scorpi.png
Binary file not shown.
|
Before Width: | Height: | Size: 340 KiB |
@@ -1,160 +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: 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.
|
||||
|
||||
<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!
|
||||
|
||||
<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 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.
|
||||
|
||||
[](https://drive.google.com/open?id=0B-2b4NYY_1xuUmxxOURISjQweGc)
|
||||
|
||||
Checksum
|
||||
|
||||
c1234d6cc3df8f81510b36cd1589e2c5
|
||||
|
||||
**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. It’s 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.
|
||||
|
||||
[](https://drive.google.com/open?id=0B-2b4NYY_1xuMWpLcU8zWjl2cTg)
|
||||
|
||||
Checksum
|
||||
|
||||
689343d72bcfae8a6b13f86b0d9c3075
|
||||
|
||||
**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
|
||||
|
||||
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)
|
||||
|
||||
[](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-osx"></a>
|
||||
### 3. OSX: 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=~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).
|
||||
|
||||
<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**.
|
||||
|
||||
|
||||
|
||||
<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](/1.0.0/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.
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 18 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 38 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 38 KiB |
@@ -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
|
||||
@@ -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.
|
||||
@@ -1,63 +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 ffmpeg curl
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
|
||||
Enable the service to start on boot
|
||||
|
||||
systemctl enable kerberos.service
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 76 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 230 KiB |
@@ -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.
|
||||
|
||||
|
||||
|
||||
<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.
|
||||
|
||||
|
||||
|
||||
<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**.
|
||||
|
||||
|
||||
|
||||
Define the header search paths.
|
||||
|
||||
|
||||
|
||||
Define the library search paths.
|
||||
|
||||
|
||||
|
||||
<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 |
@@ -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.
|
||||
|
||||
|
||||
|
||||
<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 |
@@ -1,22 +0,0 @@
|
||||
# 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.
|
||||
|
||||
<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="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.
|
||||
@@ -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.
|
||||
|
||||
<a name="time"></a>
|
||||
## 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.
|
||||
|
||||
<a name="enabled"></a>
|
||||
## Enabled
|
||||
|
||||
A user can select a checkbox to enable Kerberos.
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 16 KiB |
@@ -1,25 +0,0 @@
|
||||
# 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.
|
||||
|
||||
## Web interface
|
||||
|
||||
|
||||
|
||||
## 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>
|
||||
</IPCamera>
|
||||
|
||||
</captures>
|
||||
|
||||
### 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.
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 20 KiB |
@@ -1,32 +0,0 @@
|
||||
# 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
|
||||
|
||||
|
||||
|
||||
## 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.
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user