Camera Module

A lightweight Python module for controlling an external camera server. It lets you seamlessly integrate capturing pictures, recording videos, and streaming of the live camera feeds into your applications.

Guide

• Getting Started
  • Hardware Needed
  • Server Setup
  • Driver Setup
• class CameraDriver
  • method capture
  • method start_video
  • method stop_video
  • method read_barcode
  • method read_qrcode
  • method start_stream
  • method stop_stream
• Example

Getting Started

Hardware Needed

• RaspberryPi 4 (Model B, 4GB)
• RaspberryPi Camera Module (Version 3, Wide)
• MicroSD Card (Samsung, UHS-I, Class 10, 64GB)
• Additional Periphery: Power Cable, Ethernet Cable

While equivalent modules may work with minor adjustments, this code has been developed and tested specifically for the components listed above. To ensure full compatibility and seamless performance, it is strongly recommended to use the exact hardware.

Server Setup

1. Install the Raspberry Pi OS Lite (64-bit) operating system on the storage SD - ensure an internet connection, mDNS support and enable SSH. Set HOSTNAME to camera, USERNAME to admin, and choose your PASSWORD. For more information, follow the step-by-step installation guide on the RaspberryPi website.
   
   
2. Insert the SD card, install the camera module, connect the LAN cable - either directly to PC or via mDNS supporting router - and insert the power cable to start-up the device.
   
3. Access the RaspberryPi with

   ssh admin@camera.local
   

   enter yes to continue connecting and log in with your password.
   
   
4. Quick Setup with the command below: Automatically clones this repo, installs all neccessary dependencies, and creates an @reboot cronjob.

   curl -sSL https://raw.githubusercontent.com/ChemistryTobias/CameraModule/main/setup.sh | sudo bash
   

   A conformation message will appear, if the installation was successfull and the camera can be immediatly used after rebooting.
   
   

Tip

SETTING UP CUSTOM IP ADDRESS
In some applications the camera module can not be accessed via WiFi (extract IP adress with command: ip address show wlan0) or mDNS (IP adress: camera.local). But rather with a wired ethernet connection using specific ip_adress, mask, gateway, and dns. One can copy the command below, adapt to their own connection parameter <...>, and execute in the terminal.

sudo nmcli con mod "Wired connection 1" ipv4.addresses <ip_adress>/<mask>
sudo nmcli con mod "Wired connection 1" ipv4.gateway <gateway>
sudo nmcli con mod "Wired connection 1" ipv4.dns "<dns>"
sudo nmcli con mod "Wired connection 1" ipv4.method manual
sudo nmcli con up "Wired connection 1"

Driver Setup

All libraries used for this driver are part of the current Python Standard Library (3.11). Path to this python wrapper is main/client/camera_driver.py and CameraDriver class can be directly imported from camera_driver.py.

from camera_driver.py import CameraDriver

class CameraDriver

This driver establishes a socket connection to the camera server. Commands are send over the TCP CMD_PORT, which are processed by the RaspberryPi and a response will send back with acknowledgement or an error message. The RaspberryPi server sends the data recorded by the camera to the client via the TCP DATA_PORT or the UPD STREAM_PORT, which can then be processed further. Exceptions are the read_barcode and read_qrcode methods, where the whole processing is done on the sever itself and the resulting message will be tranferred using the CMD_PORT.

CameraDriver(IP, CMD_PORT=8000, DATA_PORT=8001, STREAM_PORT=8002)

Parameter	Description
IP	IP address of the camera (RasperryPi) server. TYPE: str
CMD_PORT	Port for sending and receiving ascii commands and responses. TYPE: int DEFAULT: 8000
DATA_PORT	Port for receiving the camera data (picture, videos). TYPE: int DEFAULT: 8001
STREAM_PORT	Port for video streaming via UDP socket. TYPE: int DEFAULT: 8002

method capture

Captures image with external camera (server) of specified format, resolution, and focus settings. Receive the image data over the data socket and save it to disk at the given path.

capture(file_path='.',
        file_format='jpeg',
        resolution=(4608, 2592)
        autofocus=True,
        focus_length=0.0)

Parameter	Description
file_path	Relative or absolute file path, where the file will be saved to. Default is the driver working directory. TYPE: str DEFAULT: .
file_format	Supported are the following file formats: jpeg, png, bmp, and gif. TYPE: str DEFAULT: jpeg
resolution	Height and width of the RGB array. TYPE: tuple DEFAULT: (4608, 2592)
autofocus	Triggers standard autofocus cycle of PiCamera2 library True = 'autofocus on', False = 'autofocus off' TYPE: bool DEFAULT: True
focus_length	Lens position must only set manually, if before autofocus=False. The minimum value for the lens position is most commonly 0.0 (meaning infinity). For the maximum, a value of 10.0 would indicate that the closest focal distance is 1 / 10 metres, or 10cm. Default values might often be around 0.5 to 1.0, implying a hyperfocal distance of approximately 1m to 2m. TYPE: float DEFAULT: 0.0

method start_video

Records a H.264 video stream from the external camera (server) for a specified duration or until explicitly stopped. Saves the incoming .h264 data to disk at the given path.

start_video(file_name,
            file_path=".",
            resolution=(1280, 720),
            duration=5)

Parameter	Description
file_name	Base name for the output file ('.h264' extension will be automatically appended). TYPE: str
file_path	Relative or absolute directory where the .h264 file will be saved. Default is the driver working directory. TYPE: str DEFAULT: .
resolution	Width and height of the video stream. TYPE: tuple DEFAULT: (1280, 720)
duration	Duration in seconds to record. If None or 0, streaming continues until stop_video() is called. TYPE: int DEFAULT: 5

method stop_video

Sends a stop_video command to the camera server to end any active H.264 video stream. The file will be automatically saved to disk.

stop_video()

method read_barcode

Warning

Not Implemented.

method read_qrcode

Warning

Not Implemented.

method start_stream

Starts streaming H.264-encoded video from the external camera server to the UDP STREAM_PORT.
Can be accessed with any H.264 decodable video player (e.g. VLC) or the ffplay library with ffplay -f mpegts -probesize 32 <udp_stream_link>.

start_stream(resolution=(1280, 720), 
             IP_out=None)

Parameter	Description
resolution	Width and height of the streamed video frames. TYPE: tuple DEFAULT: (1280, 720)
IP_out	Destination IP address of the UDP stream for the camera server. If None, defaults to the client’s IP. TYPE: str DEFAULT: None

method stop_stream

Sends a stop_stream command to the camera server to end any active UDP video stream.

stop_stream()

Example

from camera_driver.py import CameraDriver
import time

camera = CameraDriver("camera.local")

camera.capture(file_name="photo_test")
camera.start_video(file_name="video_test", duration=5)