CreatBot/CreatBotCrowsnest
CreatBot/CreatBotCrowsnest
7
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs(readme): refactor readme.md

Browse Source 
Moves more parts to official docs

Signed-off-by: Stephan Wendel <me@stephanwe.de>
This commit is contained in:
Stephan Wendel 2023-05-28 13:10:32 +02:00
parent b0c011b4ef
commit 09f4cb1ed2
No known key found for this signature in database
GPG Key ID: F465B83ACBA45639
1 changed files with 41 additions and 428 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

469
README.md
View File

@ -10,11 +10,23 @@
# crowsnest
A webcam daemon for Raspberry Pi OS Lite images like [MainsailOS](https://github.com/mainsail-crew/MainsailOS)
A wrapper script for webcam streaming on Raspberry Pi OS Lite images like [MainsailOS](https://github.com/mainsail-crew/MainsailOS). Mainly written in bash.
- [Why is it called crowsnest?](#why-is-it-called-crowsnest)
- [Support](#support)
- [Documentation](#documentation)
- [Compatibility](#compatibility)
- [Contribute](#contribute)
- [How to support us?](#how-to-support-us)
- [CustomPiOS-module](#custompios-module)
- [What 'Backends' uses crowsnest?](#what-backends-uses-crowsnest)
- [Credits](#credits)
---
## It inherited his name from sailing ships crow's nest.
## Why is it called crowsnest?
**It inherited his name from sailing ships crow's nest.**
> A crow's nest is a structure in the upper part of the main mast of a ship or a structure that is used as a lookout point. \
> See https://en.wikipedia.org/wiki/Crow's_nest
@ -23,77 +35,24 @@ So, this will be the 'lookout point' for your printer.
---
<br>
<br>
<br>
## Support
## Index:
Please read carefully on [how to configure](https://crowsnest.mainsail.xyz/) crowsnest to your needs! Check out the [FAQ](https://crowsnest.mainsail.xyz/) section for first aid or join our [Discord](https://discord.gg/mainsail) server if you need further help. For some topics that are not covered in the documentation, just read below.
- [Foreword](#foreword)
- [Installation](#installation)
<br>
- [Configuration :exclamation: **READ THIS** :exclamation:](#simple-configuration)
<br>
- [FAQ :exclamation: **READ THIS** :exclamation:](#faq)
- [I get / keep getting Error 127 in line 31](#question-i-get--keep-getting-error-127-in-line-31-what-can-i-do)
- [I have twice the same model of a USB Cam, cant get both to show up](#question-i-have-twice-the-same-model-of-a-usb-cam-cant-get-both-to-show-up-what-can-i-do)
- [How to install/use a Raspicam (V1/V2 are tested, HQ Variant untested)](#question-how-to-installuse-a-raspicam-v1v2-are-tested-hq-variant-untested)
- [I use a Raspicam and a USB one but I cant get them both for unknown reason](#question-i-use-a-raspicam-and-a-usb-one-but-i-cant-get-them-both-for-unknown-reason-how-do-i-fix-that)
<br>
- [How do I contribute the best way](#question-how-do-i-contribute-the-best-way)
- [I want to support you in person, because \<fillinyourreason>! - How? ](#question-but-kwad-i-want-to-support-you-in-person-because-fillinyourreason-how)
<br>
- [CustomPiOS-module](#custompios-module)
- [What 'Backends' uses crowsnest?](#what-backends-uses-crowsnest)
- [Credits](#credits)
<br>
<br>
<br>
_**PS: Do not open issues that are based on misconfiguration! This makes it harder for me to keep track of problems in my code.**_
---
<br>
## Documentation
## Foreword
We have decided to move crowsnest's documentation to a new location.\
Please go to [https://crowsnest.mainsail.xyz/](https://crowsnest.mainsail.xyz/)
Thank you for choosing crowsnest as your stream service.
**Please read carefully on [how to configre](#simple-configuration) crowsnest to your needs!**
If you have any trouble that isn't corelated to my bad code :wink:
see [FAQ](#faq) section for first aid. :rotating_light:
Please join our [Discord](https://discord.gg/mainsail) server if you need further help.
Do not open issues that are based on misconfiguration!
This makes it harder for me to keep track of issues in my code.
Thanks in advance \
Regards KwadFan
<br>
If there is something in our documentation that is not covered, is described in a way that is misunderstood, or simply is missing, please let us know!
---
<br>
## Installation
cd ~
git clone https://github.com/mainsail-crew/crowsnest.git
cd ~/crowsnest
sudo make install
## Compatibility
Tested on the following distributions:
@ -105,7 +64,9 @@ Not available: :heavy_minus_sign:
| Operating System | X86 Architecture | ARM Architecture |
| :-------------------------------: | :----------------: | :----------------------: |
| MainsailOS (<0.7.1) | :heavy_minus_sign: | :heavy_check_mark: (rpi) |
| Raspberry Pi OS (buster) | :heavy_minus_sign: | :x: ([Hint](#hint)) |
| Raspberry Pi OS (bullseye) | :heavy_minus_sign: | :heavy_check_mark: |
| MainsailOS (<0.7.1) | :heavy_minus_sign: | :x: ([Hint](#hint)) |
| MainsailOS (>1.0.0) | :heavy_minus_sign: | :heavy_check_mark: (rpi) |
| Armbian | :question: | :heavy_check_mark: |
| Ubuntu Server 20.04 | :heavy_check_mark: | :question: |
@ -116,391 +77,43 @@ Not available: :heavy_minus_sign:
_If you test that on other distributions, feel free to open a Pull Request to enhance documentation._
After successful installation you should consider to add
#### Hint
[update_manager crowsnest]
type: git_repo
path: ~/crowsnest
origin: https://github.com/mainsail-crew/crowsnest.git
install_script: tools/install.sh
OS images that are based on Debian 10 (codename 'buster') are no longer supported with Crowsnest version 4 (current `master` branch)!
to your _moonraker.conf_, to get latest and possibly greatest features.
### To uninstall 'crowsnest'
cd ~/crowsnest
make uninstall
### Are there more options?
Yes.
cd ~/crowsnest
make
or
make help
For advanced users it is possible to configure the installer.
Simply run:
make config
Please use the `legacy/v3` branch for these OS types.\
See the [README.md](https://github.com/mainsail-crew/crowsnest/tree/legacy/v3) of this branch for usage instructions.
---
<br>
## Simple Configuration
All you need to get your camera up and running is a small block of code in your _crowsnest.conf_ \
In MainsailOS you can do that in mainsail web interface. \
Open the 'config' section, there should be the mentioned file.
By default it look like this:
[crowsnest]
log_path: ~/printer_data/logs/crowsnest.log
log_level: quiet
[cam 1]
mode: ustreamer
port: 8080
device: /dev/video0
resolution: 640x480
max_fps: 15
What that basicly means is:
log_path: ~/printer_data/logs/crowsnest.log
**:warning: _Do not change after installation! This will prevent logrotate properly handling the log file rotation!_ :warning:**
You can choose:
log_level: quiet
This option shows a bare minimum logfile. \
For example:
[06/16/22 09:57:01] crowsnest: crowsnest - A webcam Service for multiple Cams and Stream Services.
[06/16/22 09:57:01] crowsnest: Version: v2.4.0-15-ge42799b
[06/16/22 09:57:01] crowsnest: Prepare Startup ...
[06/16/22 09:57:01] crowsnest: INFO: Checking Dependencys
[06/16/22 09:57:01] crowsnest: Dependency: 'crudini' found in /usr/bin/crudini.
[06/16/22 09:57:02] crowsnest: Dependency: 'find' found in /usr/bin/find.
[06/16/22 09:57:02] crowsnest: Dependency: 'logger' found in /usr/bin/logger.
[06/16/22 09:57:02] crowsnest: Dependency: 'xargs' found in /usr/bin/xargs.
[06/16/22 09:57:02] crowsnest: Dependency: 'ffmpeg' found in /usr/bin/ffmpeg.
[06/16/22 09:57:02] crowsnest: Dependency: 'ustreamer' found in bin/ustreamer/ustreamer.
[06/16/22 09:57:02] crowsnest: Dependency: 'rtsp-simple-server' found in bin/rtsp-simple-server/rtsp-simple-server.
[06/16/22 09:57:02] crowsnest: INFO: Detect available Devices
[06/16/22 09:57:02] crowsnest: INFO: Found 1 total available Device(s)
[06/16/22 09:57:02] crowsnest: Detected 'Raspicam' Device -> /dev/video0
[06/16/22 09:57:02] crowsnest: INFO: No usable CSI Devices found.
[06/16/22 09:57:02] crowsnest: V4L2 Control:
[06/16/22 09:57:02] crowsnest: No parameters set for [cam 1]. Skipped.
[06/16/22 09:57:02] crowsnest: Try to start configured Cams / Services...
[06/16/22 09:57:03] crowsnest: INFO: Configuration of Section [cam 1] looks good. Continue...
[06/16/22 09:57:03] crowsnest: Starting ustreamer with Device /dev/video0 ...
[06/16/22 09:57:05] crowsnest: ... Done!
The next option is
log_level: verbose
This gives you a little more informations. \
It prints out you existing _webcam.conf_ and shows a detailed info about your configured ( and connected ) cams.
You will find an example log [here](log-example.md).
This is useful to determine what the hardware encoder of your camera is capable of. \
In this case a "cheap" raspicam for about 7€ was used. \
So, truly made for 'Helper for Setup' purposes.
If you want to get the full details, please use
log_level: debug
This will show you barely the same as 'verbose' but it prints also your configured start parameters ( and the defaults ), \
also it shows the output of your choosen streamer. \
This option ist more for debugging purposes and has a tendency to overwhelm you if you are not familiar with that.
---
Another option that affects the 'logging' behavior is
delete_log: true
If you enable that option, everytime you restart, your existing log file will be deleted.
If you want to run crowsnest without any proxy set up, \
you can use
no_proxy: true
This forces ustreamer to listen on all available network interfaces.
---
Now the more interessting part.
[cam 1]
mode: ustreamer
enable_rtsp: false
rtsp_port: 8554
port: 8080
device: /dev/video0
resolution: 640x480
max_fps: 15
_**Note:** You can name the cam, how you want! ex.: [cam raspicam]_
**Attention: Do not skip the keyword 'cam'**
---
This section should be pretty much self explantory.
mode: ustreamer
means your choosen streamservice will be ustreamer with the well known mjpg-protocol. \
You can choose:
mode: camera-streamer
This let you use the newer stream service 'camera-streamer'
To use RTSP functionality you need to set
enable_rtsp: true
To view the stream use a proper player like [VLC](https://www.videolan.org/).
**The stream url will be _rtsp://\<printeriporname\>:8554/\<yourcamerasectionname\>_** \
As an example: _rtsp://mainsail.local:8554/1_ \
> _There will be no preview in your Browser!_
---
port: 8080
This will only affect the used port of ustreamer.
> **_Ports 8080 - 8084 are covered by nginx reverse proxy in MainsailOS_** \
> **_According to that 8080 will be /webcam, port 8081 will be /webcam2 and so on._**
---
device: /dev/video0
This setting defines what video device will be used by the selected service.
If you are not using a Raspberry Pi then `/dev/video0` might not work and you might encounter an "`Video capture not supported by the device`" error in the `crowsnest.log` log file.
In this case you should use the direct device ID for the USB camera found in the `/dev/v4l/by-id` directory, like in the following example:
device: /dev/v4l/by-id/usb-PixArt_Imaging_Inc._USB2.0_Camera-video-index0
Please be aware that all available devices are always listed in the `crowsnest.log` log file, so you can always copy the appropriate device ID from there.
---
resolution: 640x480
Your desired FPS settings has to match what your camera able to deliver! \
> _For the most part ignored in rtsp mode!_
max_fps: 15
This last option only affects ustreamer: \
This needs some to read further information.
custom_flags:
If you enable this in your `[cam whatevernameyouset]`, \
you can add parameters according to your needs. \
Those will be appended to the default/preconfigured parameters.
> **_These are seperated by a single space not comma seperated!_**
To setup services to your need you have to take a closer look to the documentation of the project. \
As a pointer in the right direction:
- ustreamer
- For sake of simplicity I converted ustreamers manpage to [ustreamer's manpage](./ustreamer_manpage.md)
---
### Feature V4L2 Control:
v4l2ctl:
This optional parameter allows you to setup your Cam due v4l2-ctl options. \
Unfortunatly this is a complex topic. \
But I try to explain it, as good I can.
### As an Example
You own a Logitech C920 Camera, these camera needs some tweaks to get a sharp picture. \
A solution was to use a cronjob (timed actions due scripts) that runs a script with some v4l2-ctl commands.
v4l2-ctl -d /dev/video0 -c focus_auto=0
v4l2-ctl -d /dev/video0 -c focus_absolute=30
That script gets executed when th Pi boots up. \
Not a comfortable solution.
[_alexz_](https://github.com/zellneralex) from the [mainsail-crew](https://github.com/orgs/mainsail-crew/people) mentioned it would be a good move when this could happen by crowsnest, hassle free for the user.
Take a look at [alexz webcam.conf](https://github.com/zellneralex/klipper_config/blob/11f4f8db8ac0e273e25134b571d0a93291f3511e/webcam.conf)
So, here we go.
Simply add
v4l2ctl: focus_auto=0,focus_absolute=30
to your camera setup section. \
Restart webcamd via mainsail (or your used UI) and you're good to go.
To determine which options or better said parameters your webcam provides, set at least
log_level: verbose
This will show you a list with available options. Like this:
[04/02/22 15:07:44] webcamd: Supported Controls:
[04/02/22 15:07:44] webcamd: brightness 0x00980900 (int) : min=1 max=255 step=1 default=128 value=128
[04/02/22 15:07:44] webcamd: contrast 0x00980901 (int) : min=1 max=255 step=1 default=128 value=128
[04/02/22 15:07:44] webcamd: saturation 0x00980902 (int) : min=1 max=255 step=1 default=128 value=128
[04/02/22 15:07:44] webcamd: white_balance_temperature_auto 0x0098090c (bool) : default=1 value=1
[04/02/22 15:07:44] webcamd: gain 0x00980913 (int) : min=1 max=100 step=1 default=50 value=50
[04/02/22 15:07:45] webcamd: power_line_frequency 0x00980918 (menu) : min=0 max=2 default=1 value=1
[04/02/22 15:07:45] webcamd: 0: Disabled
[04/02/22 15:07:45] webcamd: 1: 50 Hz
[04/02/22 15:07:45] webcamd: 2: 60 Hz
[04/02/22 15:07:45] webcamd: white_balance_temperature 0x0098091a (int) : min=2800 max=6500 step=1 default=4650 value=4650 flags=inactive
[04/02/22 15:07:45] webcamd: sharpness 0x0098091b (int) : min=1 max=255 step=1 default=128 value=128
[04/02/22 15:07:45] webcamd: exposure_auto 0x009a0901 (menu) : min=0 max=3 default=0 value=0
[04/02/22 15:07:45] webcamd: 0: Auto Mode
[04/02/22 15:07:45] webcamd: 2: Shutter Priority Mode
[04/02/22 15:07:46] webcamd: exposure_absolute 0x009a0902 (int) : min=5 max=2500 step=1 default=5 value=5 flags=inactive
[04/02/22 15:07:46] webcamd: exposure_auto_priority 0x009a0903 (bool) : default=0 value=0
You have to "play around" with those settings if it matches your needs. \
simply repeat the commands as mentioned earlier in your ssh connection. \
If you have discoverd your setup write that to your _webcam.conf_ as described.
---
<br>
## FAQ
---
#### :question: I get / keep getting Error 127 in line 31. What can I do?
**Solution:**
Simple fix. For what ever reason ustreamer wont start. Run the following commands please.
sudo systemctl stop crowsnest.service
cd ~/crowsnest
make buildclean
make build
sudo systemctl start crowsnest.service
Did it work? If your answer is yes... Was easy right? :wink: \
If it doesn't work for you, you probably updated a Debian "Buster" to latest "Bullseye" right? \
Here is the catch, Buster uses a proprietary Firmware for the GPU called OpenMaxIL. \
This isn't included any more in "Bullseye". \
These files are located in `/opt/vc`. \
Please backup these files and delete this folder by
sudo rm -rf /opt/vc
Now run the commands mentioned in the beginning.
#### :question: I have twice the same model of a USB Cam, cant get both to show up. What can I do?
**Solution:**
Easy fix: Run
ls -l /dev/v4l/by-path
Grab the two equal named devices, ending with `index0` \
Use that paths as device path in your _crowsnest.conf_!
---
#### :question: How to install/use a Raspicam (V1/V2 are tested, HQ Variant untested)?
**Solution:**
Well...
If your device is a Raspberry Pi, one of the mentioned cameras **and** your OS is a Raspberry Pi OS based one, simply do nothing! \
I tried as much as I can to reduce the steps to get that done. \
Use `/dev/video0` as device in your _crowsnest.conf_ \
That is the device path I try to force for Raspicams.
---
#### :question: I use a Raspicam and a USB one but I cant get them both for unknown reason. How do I fix that?
**Solution:**
My "force action" for Raspicams has a downside. If your USB Cam was attached before you extended a raspicam, the path `/dev/video0` is blocked by that USB Cam.
To fix that please unplug the USB one and reboot. \
Plug the USB Cam in, after the stream of the raspicam is shown. \
After that use the `/dev/v4l/by-id/<whateveryourdeviceidis>-index0` for the USB one and restart crowsnest. \
---
#### :question: How do I contribute the best way?
**Solution:**
Well...
## Contribute
1. Create an Issue related to your topic.
2. Prepare an _tested_ Pull Request against the develop branch
2. Prepare an _tested_ Pull Request against the `develop` branch
- Please use commits formatted according to [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/)
- Make sure not to ignore code formating as provided via [_.editorconfig_](.editorconfig) of this repo
3. Be patient. Every PR has to pass some sort of "internal gates" before it will hit the master branch, unless an immediate reaction is crutial.
- Make sure you do not ignore the code formatting as provided by the [_.editorconfig_](.editorconfig) of this repo
3. Be patient. Every PR has to go through some sort of "internal gates" before it reaches the master branch, unless an immediate response is crucial.
---
#### :question: But Kwad I want to support you in person, because \<fillinyourreason>! How?
## How to support us
**Solution:**
Buy [KwadFan](https://github.com/KwadFan) a coffee at [ko-fi.com](https://ko-fi.com/KwadFan) or [support the mainsail project](https://docs.mainsail.xyz/about/sponsors#support-mainsail)
Buy me a coffee at [ko-fi.com](https://ko-fi.com/U7U2GK66P)
Please consider hitting the :star: button in the upper right hand corner to show some love for this project.
---
## CustomPIOS Module
I have decided to provide an [CustomPiOS Module](https://github.com/guysoft/CustomPiOS) to make it easier to integrate to other distributions like MainsailOS or similar. \
Please see [README.md](./custompios/README.md) in the module folder for further informations.
I have decided to provide a [CustomPiOS Module](https://github.com/guysoft/CustomPiOS) to make it easier to integrate with other distributions like MainsailOS or similar. \
Please see [README.md](./custompios/README.md) in the module folder for more information.
---
## What 'Backends' does crowsnest use?
- ustreamer - A streamserver from Pi-KVM project \
active maintained by [Maxim Devaev](https://github.com/mdevaev) \
[ustreamer on github](https://github.com/pikvm/ustreamer)
- camera-streamer
- This server provides mjpg, snapshots, webrtc and rtsp\
Currently limited to Raspberry SBC's and at least kernel 5.15.84!\
[camera-streamer](https://github.com/ayufan/camera-streamer) is written by [ayufan](https://github.com/ayufan)
Please see the according [FAQ](https://crowsnest.mainsail.xyz/faq/backends-from-crowsnest) section in our documentation.
---
@ -514,7 +127,7 @@ Thank you, mates :) Proud to be a part of.
Thanks to [Pedro Lamas](https://github.com/pedrolamas), for the ISSUE_TEMPLATES.
Thanks to ayufan for keep going on camera-streamer, even I stressed him to get rid of some bugs ;)
Thanks to [ayufan](https://github.com/ayufan) for keep going on camera-streamer, even I stressed him to get rid of some bugs ;)
---
@ -524,4 +137,4 @@ Thanks to ayufan for keep going on camera-streamer, even I stressed him to get r
**So, with all that said, get your position seaman! Prepare to get wet feets on your journey.**
## ARRRR yooo rrready to sail?
## Are you ready to sail?