roamingthings / spyglass

A simple mjpeg server for Picamera2

Spyglass

Please note that this project is in a very early stage. Use at your own risk. Think about contributing to the project if you find that something is not working, and you are able to fix it. Every contribution is appreciated.

A simple mjpeg server for Picamera2.

With Spyglass you are able to stream videos from a camera that is supported by libcamera like the Raspberry Pi Camera Module 3.

Current version: 0.13.0

Prerequisites

• Raspberry Pi OS Bullseye
• Picamera2 - Already installed on Raspberry Pi OS Bullseye
• Python 3.8+
• A camera supported by libcamera and connected to the Raspberry Pi

Quick Start

The server can be started with

./run.py

This will start the server with the following default configuration:

• Address the server binds to: 0.0.0.0
• Port: 8080
• Resolution: 640x480
• Framerate: 15fps
• Stream URL: /stream
• Snapshot URL: /snapshot

Configuration

On startup the following arguments are supported:

Argument	Description	Default
-b, --bindaddress	Address where the server will listen for new incoming connections.	0.0.0.0
-p, --port	Port where the server will listen for new incoming connections.	8080
-r, --resolution	Resolution of the captured frames. This argument expects the format x	640x480
-f, --fps	Framerate in frames per second (fps).	15
-st, --stream_url	Sets the URL for the mjpeg stream.	/stream
-sn, --snapshot_url	Sets the URL for snapshots (single frame of stream).	/snapshot
-af, --autofocus	Autofocus mode. Supported modes: manual, continuous	continuous
-l, --lensposition	Set focal distance. 0 for infinite focus, 0.5 for approximate 50cm. Only used with Autofocus manual	0.0
-s, --autofocusspeed	Autofocus speed. Supported values: normal, fast. Only used with Autofocus continuous	normal
-ud --upsidedown	Rotate the image by 180° (see below)
-fh --flip_horizontal	Mirror the image horizontally (see below)
-fv --flip_vertical	Mirror the image vertically (see below)
-or --orientation_exif	Set the image orientation using an EXIF header (see below)
-tf --tuning_filter	Set a tuning filter file name.
-tfd --tuning_filter_dir	Set the directory to look for tuning filters.
Starting the server without any argument is the same as

./run.py -b 0.0.0.0 -p 8080 -r 640x480 -f 15 -st '/stream' -sn '/snapshot' -af continuous -l 0.0 -s normal

The stream can then be accessed at http://<IP of the server>:8080/stream

Maximum resolution

Please note that the maximum recommended resolution is 1920x1080 (16:9).

The absolute maximum resolution is 1920x1920. If you choose a higher resolution spyglass may crash.

Image Orientation

There are two ways to change the image orientation.

To use the ability of picamera2 to transform the image you can use the following options when starting spyglass:

• -ud or --upsidedown - Rotate the image by 180°
• -fh or --flip_horizontal - Mirror the image horizontally
• -fv or --flip_vertical - Mirror the image vertically

Alternatively you can create an EXIF header to modify the image orientation. Most modern browsers should respect the this header.

Use the -or or --orientation_exif option and choose from one of the following orientations

• h - Horizontal (normal)
• mh - Mirror horizontal
• r180 - Rotate 180
• mv - Mirror vertical
• mhr270 - Mirror horizontal and rotate 270 CW
• r90 - Rotate 90 CW
• mhr90 - Mirror horizontal and rotate 90 CW
• r270 - Rotate 270 CW

For example to rotate the image 90 degree clockwise you would start spyglass the following way:

./run.py -or r90

Tuning filter

Tuning filters are used to normalize or modify the camera image output, for example, using an NoIR camera can lead to a pink color, whether applying a filter to it you could remove its tone pink. More information here: https://github.com/raspberrypi/picamera2/blob/main/examples/tuning_file.py

Predefined filters can be found at one of the picamera2 directories:

• ~/libcamera/src/ipa/rpi/vc4/data
• /usr/local/share/libcamera/ipa/rpi/vc4
• /usr/share/libcamera/ipa/rpi/vc4
• /usr/share/libcamera/ipa/raspberrypi

You can also define your own directory of filter by using parameter tuning_filter_dir.

list the files present there and you can use it in our config. eg.: ov5647_noir.json

Using Spyglass with Mainsail

If you want to use Spyglass as a webcam source for Mainsail add a webcam with the following configuration:

• URL Stream: /webcam/stream
• URL Snapshot: /webcam/snapshot
• Service: V4L-MJPEG

Install as application

If you want to install Spyglass globally on your machine you can use python -m pip install . to do so.

Install and run as a service

Install

Quite simple:

cd ~/spyglass
make install

This will ask you for your sudo password.
After install is done, please reboot to ensure service starts properly

To uninstall the service simply use

cd ~/spyglass
make uninstall

Using Moonraker Update Manager

To be able to use Moonraker update manager, add the following lines to moonraker.conf:

[update_manager spyglass]
type: git_repo
channel: beta
path: ~/spyglass
origin: https://github.com/roamingthings/spyglass.git
managed_services: spyglass

Make sure moonraker.asvc contains spyglass in the list: cat ~/printer_data/moonraker.asvc | grep spyglass.

If not there execute: make upgrade-moonraker

Configuration

You should find a configuration file in ~/printer_data/config/spyglass.conf.

Please see spyglass.conf for an example

Restart the service

To restart the service use systemctl:

sudo systemctl restart spyglass

Start Developing

If you want to setup your environment for development perform the following steps:

Setup your Python virtual environment:

python -m venv .venv                  # Create a new virtual environment
. .venv/bin/activate                  # Activate virtual environment
python -m pip install --upgrade pip   # Upgrade PIP to the current version
pip install -r requirements.txt       # Install application dependencies
pip install -r requirements-test.txt  # Install test dependencies
pip install -r requirements-dev.txt   # Install development dependencies

The project uses commitizen to check commit messages to comply with Conventional Commits. When installing the development dependencies git-hooks will be set up to check commit messages pre commit.

Problems when Committing to your Branch

You may get the following error message when you try to push to your branch:

fatal: ambiguous argument 'origin/HEAD..HEAD': unknown revision or path not in the working tree.
Use '--' to separate paths from revisions, like this:
'git <command> [<revision>...] -- [<file>...]'

This error occurs when your HEAD branch is not properly set (Stack Overflow) To fix this run the following command:

git remote set-head origin -a

spyglass's Issues

Add support for usage with Fluidd

Spyglass doesn't seem to work well with Fluidd, as it (Fluidd) adds extra parameters to the URI which Spyglass does not recognize.

http://voron0.local/webcam/?action=snapshot&cacheBust=1683694863063 (or anything) returns a 404. Browsing to it shows the stream/snapshot as expected, but Fluidd seems to always add that cacheBust parameter.

Typo on autofocus description and default example

in the description for autofocus it lists two options, there is a typo for the option "continuous", it is currently listed as "continous"
also in the "Starting the server without any argument" default example the same typo for continuous is shown.

Issue with Spyglass starting

I followed the instructions to install Spyglass as a service but when trying to start it I get the following

spyglass.service - spyglass - Picamera2 MJPG Streamer
   Loaded: loaded (/etc/systemd/system/spyglass.service; enabled; vendor preset: enabled)
   Active: activating (auto-restart) (Result: exit-code) since Wed 2023-02-15 22:40:49 GMT; 2s ago
     Docs: https://github.com/roamingthings/spyglass
  Process: 9073 ExecStart=/usr/local/bin/spyglass (code=exited, status=1/FAILURE)
 Main PID: 9073 (code=exited, status=1/FAILURE)

Looking at journalctl I can see:

Feb 15 22:03:20 mainsailos systemd[1]: Started spyglass - Picamera2 MJPG Streamer.
Feb 15 22:03:20 mainsailos crowsnest[927]: Version Control: rtsp-simple-server new version available: v0.20.2 (v0.19.1).
Feb 15 22:03:20 mainsailos spyglass[920]: Python 2.7.16
Feb 15 22:03:20 mainsailos spyglass[920]: INFO: Configuration file found in /home/pi/printer_data/config/spyglass.conf
Feb 15 22:03:20 mainsailos spyglass[920]: INFO: Print Configfile: '/home/pi/printer_data/config/spyglass.conf'
Feb 15 22:03:20 mainsailos spyglass[920]:                 NO_PROXY="true"
Feb 15 22:03:20 mainsailos spyglass[920]:                 HTTP_PORT="8080"
Feb 15 22:03:20 mainsailos spyglass[920]:                 RESOLUTION="640x480"
Feb 15 22:03:20 mainsailos spyglass[920]:                 FPS="15"
Feb 15 22:03:20 mainsailos spyglass[920]:                 STREAM_URL="/stream"
Feb 15 22:03:20 mainsailos spyglass[920]:                 SNAPSHOT_URL="/snapshot"
Feb 15 22:03:20 mainsailos spyglass[920]:                 AUTO_FOCUS="continuous"
Feb 15 22:03:20 mainsailos spyglass[920]:                 FOCAL_DIST="0.0"
Feb 15 22:03:20 mainsailos spyglass[920]:                 AF_SPEED="normal"
Feb 15 22:03:20 mainsailos spyglass[920]: Traceback (most recent call last):
Feb 15 22:03:20 mainsailos spyglass[920]:   File "/home/pi/spyglass/run.py", line 3, in <module>
Feb 15 22:03:20 mainsailos spyglass[920]:     from spyglass.cli import main
Feb 15 22:03:20 mainsailos spyglass[920]:   File "/home/pi/spyglass/spyglass/cli.py", line 121
Feb 15 22:03:20 mainsailos spyglass[920]: SyntaxError: Non-ASCII character '\xc2' in file /home/pi/spyglass/spyglass/cli.py on line 121, but no encoding declared; see http://python.org/dev/peps/pep-0263/ for details
Feb 15 22:03:20 mainsailos systemd[1]: spyglass.service: Main process exited, code=exited, status=1/FAILURE
Feb 15 22:03:20 mainsailos systemd[1]: spyglass.service: Failed with result 'exit-code'.

OS info

cat /etc/os-release
PRETTY_NAME="Raspbian GNU/Linux 11 (bullseye)"
NAME="Raspbian GNU/Linux"
VERSION_ID="11"
VERSION="11 (bullseye)"
VERSION_CODENAME=bullseye
ID=raspbian
ID_LIKE=debian

FR: Use venv for developing and running spyglass

Spyglass should use a Python virtual environment for development and runtime.

FR: Add a release process to allow versioning of the application

At the moment spyglass does not have a release process. Changes/pull requests are directly merged into the main branch.

For the future it would be nice to have a release process with versioning.

As a versioning scheme like semver seems reasonable.

At the moment there are a lot of questions:

• How to manage last/current versions in branches?
• How is the process of creating a new release?
  • GitHub and/or PiPy?
  • Use GitHub Actions or a custom script?

Maximum resolution is limited to 1920x1920

As mentioned in raspberrypi/picamera2#473 it's currently not possible to capture snapshots/streams with more than 1920x1920.

To prevent users from running into issues due to misconfigured resolution #31 will raise an error in this case.

Impossible to install spyglass!!

hi,
few hours ago i try to install spyglass for use a pi camerza module 3 with mainsail and crowsnest.
but when i launch command i have ab error and when i clone manually the repo impossible to launch install what s wrong?

can you tell me how install it on my pi 4 please?

i ve tried that:
cd ~

git clone https://github.com/roamingthings/spyglass

cd spyglass

./run.py

but no way i ve tried wit sudo too but same results. i ve tried to create folder manually with no results again

How do I uninstall spyglass?

FR: Add Support for Moonraker Update Manager

Add the ability to update an installation of Spyglass using the Moonraker update manager

FR: Add support for USB cameras

The use-case we are targeting with spyglass my include setups where Raspberry Pi cameras are used along with general USB cameras.

It's important to note that spyglass will only allow to use one camera at a time (e.g. if there is more than one camera you have to start spyglass multiple times).

Spyglass should be able to use USB cameras to capture images and videos.

Questions

• Why do we need to support USB cameras
• Are there any other projects that suite this use-case better than wie can/will do?
• If there are other projects does this imply performance issues on the system that we aim to support (Raspberry Pi with restricted resources)

FR: Update what, how and when things are logged

We need to find a balance that provides enough information when spyglass is running in normal operation and the ability to have extended logging when it's neccessary to investigate some problem.

Spyglass should provide the following log levels:

• quiet - A minimum an logging information. Mostly warnings and errors will be displayed in this mode
• verbose - More information what's going on without low level details
• debug - Log every detail

Since spyglass is integrated into other applications like crowsnest we need a cli argument to set logging level.

FR: Add option to rotate the image

Sometimes camera modules will be mounted at a rotated angle. To compensate for that it would be helpful to have an option that rotates the image so it will be displayed correctly.

Automatic updating broken?

I've installed Spyglass following these steps:

1. git clone https://github.com/roamingthings/spyglass.git
2. make install
3. Restarted the Raspberry Pi
4. Installed the updater part inside the moonraker config.'
5. Restarted Moonraker
6. See Spyglass in the update list as 'Invalid'

• Soft recovery gives: Recovery attempt failed, repo state not pristine
• Hard recovery gives: Repo has not been verified, clone aborted

How can I fix this?

EDIT:
I've tried running make upgrade-moonraker, but still the same issue.

Runs for a few minutes, then freezes. Errors in dmesg log.

Trying this because Klipper's Crowsnest stopped working after a recent update. I'm running mailsailos on Raspberry Pi 4 with Raspberry Pi HQ camera connected via ribbon cable. Spyglass runs for a random amount of time (usually less than 5 minutes) and then image hangs. I check dmesg log and see this:

[ +19.760237] bcm2835-codec bcm2835-codec: Failed setting ctrl 00990a67, ret -3
[Jul26 10:36] edt_ft5x06 10-0038: Unable to fetch data, error: -121
[  +1.050539] i2c-bcm2835 fe205000.i2c: i2c transfer timed out
[  +0.000028] edt_ft5x06 10-0038: Unable to fetch data, error: -110

Restarting Spyglass works... but only for a few minutes at most, then errors out again.

NOTE: The first message in the log there happens when it starts, the other two when it freezes.

FR: Enable HDR for RPi camera v3

The Raspberry Pi camera module v3 is able to capture images in HDR (high dynamic range).

Configuration of the feature is a bit more complex. In addition an Profile has to be enabled.

Documentation for adding Spyglass as a service

I added Spyglass as a systemctl service, so it autostarts and is controllable like crowsnest. This could maybe be added to the Readme:

Step 1: Create and open a service description
sudo nano /etc/systemd/system/spyglass.service

Step 2: Insert the following text:

[Unit]
Description=Spyglass

[Service]
Type=simple
ExecStart=/usr/bin/python3 /run.py

[Install]
WantedBy=multi-user.target

Step 3: Reload systemcontrol
sudo systemctl daemon-reload

Step 4: Enable Autostart of Spyglass
sudo systemctl enable spyglass.service

Step 4.5: Maybe you have to disable crowsnest first, to prevent port collision:
sudo systemctl stop crowsnest.service && sudo systemctl disable crowsnest.service

Step 5: Start your new Spyglass Service:
sudo systemctl start spyglass.service

Note that as far as I know, this only works on debian-based systems like Raspberry Pi OS and MainsailOS

FR: Allow customisation of all camera controls offered by picamera2

Picamera2 provides a rich set of camera controls that allow to adjust the camera operation.

Spyglass should allow the user to configure these controls to optimize image, stream and video quality.

Questions

• How should the controls be configured?
  • cli
  • configuration file (specified by cli argument)
  • HTTP/REST endpoint
• Should it be possible to update the controls during streaming or just at the start of spyglass?

Reduce resource usage of spyglass

I have been experiencing MCU 'mcu' shutdown: Timer too close errors lately suggesting that my RPi is overloaded.
I noticed that spyglass service is running 8 processes and consuming over 30% cpu.

Is there any option to reduce this?

I have unsuccessfully tried:

• updating to the latest spyglass
• looking through your code, but haven't seen where you specify the number of handlers for a server or a way to reduce threads.
• reduce the resolution of the camera

In a resource constrained situation, I would rather have the camera server fail / be reduced to snapshots than the print shutting down.

[FR] Rotation flag

It would be a great feature to rotate the image, as many camera mounts for printers are upside down (for Ender 3 at least).

Error during install as service - missing config directory

Hi,

I am not using this with any printer software. It seems spyglass was made for some software that uses the path ~/printer_data/config

I assume there is a missing mkdir ~/printer_data/config somewhere. I might create a PR for this, but if I do I would also change the config dir to /etc/spyglass.

How to reproduce on vanilla raspian OS:

root@hakkebo:~# git clone https://github.com/roamingthings/spyglass.git
Cloning into 'spyglass'...
remote: Enumerating objects: 443, done.
remote: Counting objects: 100% (208/208), done.
remote: Compressing objects: 100% (103/103), done.
remote: Total 443 (delta 134), reused 131 (delta 96), pack-reused 235
Receiving objects: 100% (443/443), 104.73 KiB | 674.00 KiB/s, done.
Resolving deltas: 100% (232/232), done.

root@hakkebo:~# cd spyglass/

root@hakkebo:~/spyglass# make install

Copying systemd service file ...

Copying Spyglass launch script ...

Copying basic configuration file ...
cp: cannot create regular file '/home/root/printer_data/config': No such file or directory
make: *** [Makefile:27: install] Error 1

Regards
Stian