Skip to content

Commit

Permalink
First commit rpisurv 3
Browse files Browse the repository at this point in the history
  • Loading branch information
@SvenVD
SvenVD committed Dec 29, 2020
1 parent 7c18766 commit 2c78aa4
Show file tree
Hide file tree
Showing 29 changed files with 1,049 additions and 941 deletions.
107 changes: 74 additions & 33 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,49 +1,89 @@
# Rpisurv 2 - Raspberry pi surveillance an RPI IP Camera Monitor
# Rpisurv 3 - Raspberry Pi surveillance
Join the community on https://community.rpisurv.net (Please use this place for support questions instead of github issues).<br/>
Bug tracking https://github.com/SvenVD/rpisurv/issues.<br/>
Follow us on facebook https://www.facebook.com/rpisurv.<br/>
Have a chat on https://gitter.im/rpisurv/general.<br/>

If you like this software please consider donating:
You can help sustain our activities by donating here:
<a href="https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=QPJU9K2KZ8D94" target="_blank" rel="nofollow"><img src="https://www.paypal.com/en_US/i/btn/x-click-but21.gif" alt="" /></a>

## Release notes
## What is Rpisurv?

Rpisurv is a free application that transforms your Raspberry Pi into a dedicated device to display video streams or images.

Take a look at some [showcases](https://www.tapatalk.com/groups/rpisurv/showcases-f8/)

See [RELEASE_NOTES](https://github.com/SvenVD/rpisurv/blob/master/RELEASE_NOTES.md)
## Features
##### Self-healing and health monitoring including watchdogs
- Every stream will be monitored by an external watchdog process, if the stream gets killed somehow, the watchdog will try to restart the stream/process. This gives you a very robust surveillance screen.
- Stream up/down detection and autorepositioning of connectable streams on the screen layout.
For example: if you stop a camera (or just stop the server on the camera), Rpisurv will detect this and will recalculate/redraw the screen with the still available streams. The same is true if a previous unconnectable stream becomes connectable. All without any user interaction.

## Goal
Rpisurv is designed to be simple to use (no need to fiddle with coordinates or detailed layout configs, although you [can](https://gist.github.com/SvenVD/0cb1a40261b7c7f2d4cffac24dc9181d) if you really want) and to be able to run unattended for long periods of time. Therefore watchdogs and autohealing logic have been implemented.
Version 2 adds functionality to define multiple screens which can be cycled between.
##### Automatically position streams (no manual coordinates calculation needed)
- Autocalculcate coordinates for every stream displayed.
- If you are not happy with the autocalculations you [can](https://gist.github.com/SvenVD/7b973cde2ce5dce6c8284606434e3a14) customize yourself.

## Description
You can think of rpisurv as a wrapper for omxplayer with following features (Rpisurv uses omxplayer to fully make use of the GPU of the raspberry pi).
##### Rotation of screens (autorotate or with keyboard control)
- You can configure multiple screens and cycle between them in an automated way or via the keyboard.
- In the case of dual displays, you can configure multiple screens to be cycled between for each display.

- Rpisurv implements a watchdog for every stream displayed, if the process gets killed somehow. It will try to restart the stream/process. This gives you a very robust surveillance screen.
- Autocalculcate coordinates for every stream displayed. The last stream defined will be stretched to make use of the complete screen but only if some pixels are unused (if autostretch option is True).
- Stream up/down detection and autorearrange of the screen layout (if disable_probing_for_all_streams is False). So for example if you stop a camera (or just stop the server on the camera), rpisurv will detect this and will recalculate/redraw the screen with the still available cameras. The same is true if a previous unconnectable rtsp stream becomes connectable. All without any user interaction.
- All this behaviour is available per screen, but as of version 2 you can configure multiple screens and cycle between them in an automated way or via the keyboard.
- Since 2.1.0 you can now also specify "image streams", to display images next to or instead of camera streams. The images will be auto-updated if they change remotely.
##### Multiple types of streams
- You can also specify "image streams", to display images next to or instead of camera streams. The images will be auto-updated if they change remotely.

##### Dual Hdmi support
- Rpisurv will auto-detect if a second display is connected at boot and will automatically start the configured screens for the second display.

## How to get started
In short: The idea is to connect your raspberry pi to a monitor and tell rpisurv which stream(s) and screen(s) it should display or cycle between. Rpisurv will autocalculate all the rest.
- Get a monitor or a TV
- Get a raspberry pi dedicated for rpisurv, and install raspbian on it. Make sure your monitor is operating at the correct resolution
In short: The idea is to connect your Raspberry Pi to a monitor and tell Rpisurv which stream(s) and screen(s) it should display or cycle between. Rpisurv will autocalculate all the rest.
- Get a monitor or a TV ( or 2 )
- Get a Raspberry Pi dedicated for Rpisurv, and install Raspberry Pi OS on it.
- If you are going to have multiple streams, add gpu_mem=512 to your /boot/config.txt
- git clone this repository: `git clone https://github.com/SvenVD/rpisurv`
- move into folder `cd rpisurv`
- OPTIONAL: checkout a specific branch, for example `git checkout v2_latest`, if you want to override the default version on master
- OPTIONAL: checkout a specific branch, for example `git checkout v3_latest`, if you want to override the default version on master
- run `sudo ./install.sh`
- Get the correct stream url for your ip camera(s), there are some examples in /etc/rpisurv.conf
- Configure your screen(s) and stream(s) in /etc/rpisurv.conf. Remove all example config first! This dummy config is for documentation only, you will fail to start rpisurv if you do not remove these examples.
- OPTIONAL: configure optional options per screen or per camera stream in /etc/rpisurv.conf, the [example config file](https://github.com/SvenVD/rpisurv/blob/master/surveillance/conf/surveillance.yml) file explains them all
- reboot

## How to update <a name="how-to-update"></a>
- Enjoy the demo showcase

## Configuration

Rpisurv has the following config files
- `/etc/rpisurv/general.yml` => General config, mostly not needed to touch this.
- `/etc/rpisurv/display1.yml` => Define screens and streams used for first monitor.
- `/etc/rpisurv/display2.yml` => Define screens and streams used for second monitor.
Which monitor will be display1 or display2 depends on which HDMI port you plug it in.
If you only plug one monitor then only one of the config files will be read (display1.yml or display2.yml).

A screen consists out of multiple streams.
A display is the equivalent of a monitor. On a display you can define multiple screens which can be cycled between.

For full config explanation with all possible options consult the config files in /etc/rpisurv after install.

## URL sources

#### file://
This is a path on disk, by default a videofile is expected. This videofile will then be played in an endless loop.
If used with imageurl: true then an image file is expected. If the image changes on disk then Rpisurv will also reload the stream with the new image.
Note in dual displays mode imageurl type streams are only displayed on 1 display (`/etc/rpisurv/display1.yml`).
TIP: If an external program rotates the images on disk then Rpisurv can thus be used as a frontend for a digital picture frame.
#### http:// and https://
This is a remote location with a video file or video stream
If used with imageurl: true then an image file is expected. If the remote image changes then Rpisurv will also reload the stream with the new image.
Note in dual displays mode imageurl type streams are only displayed on 1 display (`/etc/rpisurv/display1.yml`).
TIP: This can be used as part of a digital signage setup: several Rpisurv clients can be steered centrally by changing the image(s) on the central location.
Rpisurv will autodetect interruptions and tries to restore the stream.
#### rtsp://
This is a remote location with a video stream, Rpisurv will do its best to display the stream, it will autodetect interruptions and tries to restore the stream.

## How to update Rpisurv to new version <a name="how-to-update"></a>
- `cd rpisurv; git pull`
- OPTIONAL: checkout a specific branch, for example `git checkout v2_latest`, if you want to override the default version on master
- OPTIONAL: checkout a specific branch, for example `git checkout v3_latest`, if you want to override the default version on master
- run `sudo ./install.sh` (The installer will ask if you want to preserve your current config file)
- `systemctl restart rpisurv`

## Release notes

See [RELEASE_NOTES]((https://github.com/SvenVD/rpisurv/releases))

## Placeholder images
After installation you may change the placeholder images to something you like.
- /usr/local/bin/rpisurv/images/connecting.png is shown when a camera stream is starting up
Expand All @@ -53,7 +93,7 @@ After installation you may change the placeholder images to something you like.

## Rpisurv in operation

If you used the install.sh script, you can configure your streams in /etc/rpisurv.conf. Do not forget to reboot afterwards.
If you used the install.sh script, you can configure your streams in /etc/rpisurv. After editing the config files you need to restart Rpisurv for the changes to be in effect.

If you are connected via keyboard/keypad, you can force the next screen by pressing and holding n or space (or keypad "+") for some seconds in case multiple screens were defined (this takes longer depending on amount of unconnectable streams and they thus need to wait for timeout, keep holding until screen changes. Note, you can change probe_timeout per camera stream if needed).

Expand All @@ -68,28 +108,29 @@ The width of the screen is divided in four sections,
- Touching In the last section, a next screen event.
Note that a mouse can be used, however mouse cursor is hidden by default.

In case of dual HDMI then the screens on both displays will be controlled at the same time.


## Troubleshooting

- I advise you to test your urls in vlc or omxplayer (command line) first. It should work in these applications before attempting to use them in rpisurv
- I advise you to test your urls in vlc (command line) first. It should work before attempting to use them in rpisurv.

- If you used the install.sh script, logs are created at /usr/local/bin/rpisurv/logs/. You can use them for troubleshooting. Enable DEBUG logging for very detailed output of what is going on. see [logging_config](https://github.com/SvenVD/rpisurv/blob/master/surveillance/conf/logging.yml)

- If you are connected via keyboard/keypad, you can stop rpisurv by pressing and holding q (or backspace or keypad "/") (this can take some seconds) .
- If you are connected via keyboard/keypad, you can stop Rpisurv by pressing and holding q (or backspace or keypad "/") (this can take some seconds) .

- To manage the screen without rebooting use systemctl
- `sudo systemctl stop rpisurv` to stop the screen
- `sudo systemctl start rpisurv` to start the screen
- `sudo systemctl status rpisurv` to see last log and status of service

- If you want to stream rtsp over tcp please add `rtsp_over_tcp: true` to the stream in /etc/rpisurv.conf.
See [example config file](https://github.com/SvenVD/rpisurv/blob/master/surveillance/conf/surveillance.yml) for an example.
- If you want to stream rtsp over tcp please add `rtsp_over_tcp: true` to the stream in /etc/rpisurv.
See in /etc/rpisurv for examples.
If you have a "smearing" effect this option may resolve it.
Note that you need a version of omxplayer which is released after 14 March 2016 (https://github.com/popcornmix/omxplayer/pull/433) to do this.

- On a raspberry pi 3 and 4 it seems the default overscan settings are not good. If full screen is not used, if you have an unused bar in the bottom -> try to set `disable_overscan=1` in /boot/config.txt
- On a Raspberry Pi 3 and 4 it seems the default overscan settings are not good. If full screen is not used, if you have an unused bar in the bottom -> try to set `disable_overscan=1` in /boot/config.txt

- Users on a raspberry pi 4 which experience flickering can try to set `disable_overscan=1` in /boot/config.txt. As reported here: [link](https://www.tapatalk.com/groups/rpisurv/camera-flickering-not-sure-what-is-the-issue-t48.html#p192).
- Users on a Raspberry Pi 4 which experience flickering can try to set `disable_overscan=1` in /boot/config.txt. As reported here: [link](https://www.tapatalk.com/groups/rpisurv/camera-flickering-not-sure-what-is-the-issue-t48.html#p192).


## Feature requests
Expand Down
73 changes: 11 additions & 62 deletions RELEASE_NOTES.md
View file
Original file line number Diff line number Diff line change
@@ -1,63 +1,12 @@
# rpisurv 2 release notes
## Changes in 2.1.9
A long requested feature [link](https://www.tapatalk.com/groups/rpisurv/grid-lay-out-show-one-stream-bigger-then-others-t5.html) has now finally made it to rpisurv.
Instead of letting rpisurv calculate the layout for you, you can now create complex custom layouts yourself. [Examples click here](https://gist.github.com/SvenVD/0cb1a40261b7c7f2d4cffac24dc9181d)

## Changes in 2.1.8
[nicolake](https://github.com/SvenVD/rpisurv/pull/100) provided some code to be able for touch screens to control rpisurv with basic commands.
This has been incorporated into rpisurv.

## Changes in 2.1.7
Http probe did not handle all exceptions which could crash rpisurv on rare occasions like described in the [link](https://www.tapatalk.com/groups/rpisurv/viewtopic.php?p=339#p339).
Fixed by inserting a fallback exception handler in the http probe logic.

## Changes in 2.1.6
Added "aidx" option to be able to enable audio for a particular stream [link](https://www.tapatalk.com/groups/rpisurv/audio-t11-s20.html).
This is a one to one mapping with the omxplayer aidx (Audio stream index) option, the default for rpisurv is the value -1 (audio disabled).
To enable audio for a stream try setting this to 1.

## Changes in 2.1.5
Fixed bug in freeform_advanced_omxplayer_options option

## Changes in 2.1.4
Introduced freeform_advanced_omxplayer_options option, so that advanced users have all the advanced omxplayers features at their disposal.
For example, dual display configuration when running on a raspberry 4 [link](https://www.tapatalk.com/groups/rpisurv/raspberry-pi-4-t32.html#p199).

## Changes in 2.1.3
Fixing potential failure of fetching images from remote servers with a WAF.
This change has been requested on [link](https://www.tapatalk.com/groups/rpisurv/can-t-get-image-to-load-t45.html).

## Changes in 2.1.2
The "comma" key can now be used to resume rotation, also the "backspace" key can now be used to quit rpisurv. This to allow german keypads to have all the needed functions.
This change has been requested on [link](https://www.tapatalk.com/groups/rpisurv/on-keypad-operation-change-rotation-key-from-to-t28.html).

## Bugfix in 2.1.1
Do not crash rpisurv if there is something wrong with loading the image.

## New features 2.1.0
It is now possible to show an image instead of a camerastream. The image is fetched from a choosen remote url. On top of that this remote url is watched for changes.
If the image is changed on the remote site, rpisurv will detect this and will also fetch the new image and update it on screen. The polling frequency is controlled by ```advanced: interval_check_status``` config option in /etc/rpisurv.conf.
The "image stream" follows the same health checks as a normal camera stream. This means if the specified image is unavailable it will not be shown on-screen by default (you can override this).
This feature has been requested on [link](https://www.tapatalk.com/groups/rpisurv/show-random-images-from-an-accessible-url-instead--t6.html).


## Upgrade notes from 1.0
The config file is still a yaml file but the keys have been changed to support the configuration of multiple screen in a rotation
You must manually convert your 1.0 config file to the new version 2 config file format. However the format is still as clear to use, but it is still a yaml file. So as always watch the indentations and do not use tabs, see [example config file](https://github.com/SvenVD/rpisurv/blob/v2.0_branch/surveillance/conf/surveillance.yml)
The normal update [procedure](https://github.com/SvenVD/rpisurv/blob/master/README.md#how-to-update) can be followed for upgrading.

## Features and changes since 1.0
- Implemented "Automatic cycle through list of cameras/screens" [link](https://feathub.com/SvenVD/rpisurv/+4).
- Pressing keys F1 to F12 (or keypad 0 to 9) on an attached keyboard/keypad, will force the equal numbered screen to be shown onscreen (this takes longer depending on amount of unconnectable streams and they thus need to wait for timeout, keep holding until screen changes. Note, you can change probe_timeout per camera stream if needed). Example use case: you can define one '2x2' screen and 4 1x1 screens with the same camera streams. That way you can select one camera stream out of the 2x2 by pressing F2-F5 and go back to 2x2 by pressing F1 [link](https://feathub.com/SvenVD/rpisurv/+3).
- Disable rotation (as in pause rotation, as in fix the current displayed screen) dynamically during runtime. Press "p" to pause and "r" to resume/rotate. This overrides the disable_autorotation option if this has been set in the config file.
- There is virtually no limit(hardware or software) for the amount of screens that can be defined.
- Implemented "Add mjpeg camera support" [link](https://feathub.com/SvenVD/rpisurv/+5) but not limited to mjpeg support, all omxplayer supported http/https streams can be configured.
- Possibility to force next screen in a carousel/slideshow by pressing "n" or "space" (or keypad "+") on an attached keyboard/keypad.
- Enabling the user to configure the duration of each screen in the carousel/slideshow by overriding the default with the "duration" option, see [example config file](https://github.com/SvenVD/rpisurv/blob/master/surveillance/conf/surveillance.yml).
- Enabling the user to specify a "probe_timeout" per camera stream. This for slow connecting streams to not be regarded as unconnectable by rpisurv, see [example config file](https://github.com/SvenVD/rpisurv/blob/master/surveillance/conf/surveillance.yml).
- "keep_first_screen_layout" option in v1.0 has been replaced by "disable_probing_for_all_streams" option in version 2 and has become a per screen configuration, which effect is roughly the same. (Not recommended to enable this though).
- All existing functionality from v1.0 is still available. If you only define one screen you essentially get the rpisurv v1.0 behaviour.
- rtps_urls config option which was already deprecated in v1.0 is now completely removed.
- "autostretch" and "nr_of_columns" options are now per-screen configuration options.
- Installer has been updated to request the user to preserve his current configuration file.
# Rpisurv release notes
See [https://github.com/SvenVD/rpisurv/releases](https://github.com/SvenVD/rpisurv/releases)










Loading

0 comments on commit 2c78aa4

Please sign in to comment.