Quick start

Hardware Connection

---

Note

In this illustrator, the different colors of the jumper wires are just to make it easier to distinguish them from each other.

The order of those colors varies from item to item, so it may not match the one on your hand.

Therefore, instead of its color, you should rely on the position of the wire to correctly connect the jumpers.

Software Guide

---

Supported Platforms and OS

---

Note for Supported Platform and OS
Platform	Bookworm(rpicam/libcamera)	Bullseye(libcamera)	Buster(raspistill)
Raspberry Pi 5
Raspberry Pi 4B / 3B+ / 3A+ / Zero / Zero 2 W		√	√
Raspberry Pi CM3 / CM3+ / CM4 (extra adapter board required)		√	√

---

Device Tree Configuration

---

• For OV5647 PTZ Camera kit

For the configuration of OV5647 Pan-tilt-zoom camera kit under different os/platform, please refer to the following section:
Software Configuration - OV5647

• For IMX219 PTZ Camera kit

For the configuration of IMX219 Pan-tilt-zoom camera kit under different os/platform, please refer to the following section:
Software Configuration - IMX219

• For IMX477 PTZ Camera kit

For the configuration of IMX477 Pan-tilt-zoom camera kit under different os/platform, please refer to the following section:
Software Configuration - IMX477

Help Center

If you can not find your camera, please contact us directly.(support@arducam.com)

Run PTZ Kits on Raspberry Pi5(Bookworm)

---

Platform	OS	Supported Sensors
Raspberry Pi 5	Bookworm	OV5647
Raspberry Pi 5	Bookworm	IMX219
Raspberry Pi 5	Bookworm	IMX477

• OV5647/IMX219 PTZ Kit

The method of using OV5647 and IMX219 PTZ kits on Raspberry Pi5 is the same as that on Pi4. But please note that you need to config the device tree under Pi5(Bookworm). For other steps, you can directly refer to the content of Bullseye Section below:

Run PTZ Kits in Bullseye OS

• IMX477 PTZ Kit

Install the dependencies

sudo apt update
sudo apt install -y libatlas-base-dev python3-opencv python3-picamera2
sudo apt install python3-numpy

Download the Source Code

sudo apt update
sudo apt install -y libatlas-base-dev python3-opencv python3-picamera2
sudo apt install python3-numpy

Enable the camera module

sudo nano /boot/firmware/config.txt 
#Find the line: camera_auto_detect=1, update it to:
camera_auto_detect=0
#Find the line: [all], add the following item under it:
dtoverlay=imx477
#Save and reboot.

> If you want to enable the camera kit on the `cam0` port of Pi5, please refer to the following modifications:

sudo nano /boot/firmware/config.txt 
#Find the line: camera_auto_detect=1, update it to:
camera_auto_detect=0
#Find the line: [all], add the following item under it:
dtoverlay=imx477,cam0
#Save and reboot.

Enable i2c

1. sudo raspi-config
2. Select Interface Options and enter

3. Select i2c and enter

4. Select `YES` and press `enter` to confirm

5. exit and reboot your Pi to take effect

Run the FocuserExample.py

• cd PTZ-Camera-Controller/B016712MP
• python3 FocuserExample.py

> Please note that after opening the program, press the `T` key first and wait for about `8` seconds. The mode will switch from 'Fix' to 'Adjust'. You can use the keyboard to control Zoom, Focus, IR-CUT, etc. at 'Adjust' mode.

For more details, please refer to our github documentation.

Run PTZ Kits on Bullseye OS

---

Step 1. Install the OpenCV

sudo apt-get install python3-opencv

Step 2. Download the source code

git clone https://github.com/ArduCAM/PTZ-Camera-Controller.git

Step 3. Enable i2c

1. sudo raspi-config
2. Select Interface Options and enter

3. Select i2c and enter

4. Select `YES` and press `enter` to confirm

5. exit and reboot your Pi to take effect

Step 4. Enable camera driver

Please refer to the following section according to the camera you are using:

Raspberry Pi Camera - Device Tree Configuration

Step 5. Run the demo

OV5647/IMX219 Camera

cd PTZ-Camera-Controller
python3 FocuserExample.py

IMX477 Camera

cd PTZ-Camera-Controller/B016712MP
python3 FocuserExample.py

For more details, please refer to our github documentation.

Run PTZ Cameras on Ubuntu OS

---

Step 1. Installing dependencies

sudo apt-get update && sudo apt-get upgrade
sudo apt install -y cmake
sudo apt install libyaml-dev
sudo apt install libpng-dev
sudo apt install -y libcamera-dev libepoxy-dev libjpeg-dev libtiff5-dev
sudo apt install -y python3-pip git
sudo pip3 install jinja2
sudo apt install -y libboost-dev
sudo apt install -y libgnutls28-dev openssl libtiff5-dev
sudo apt install -y qtbase5-dev libqt5core5a libqt5gui5 libqt5widgets5
sudo apt install -y meson
sudo pip3 install pyyaml ply
sudo pip3 install --upgrade meson
sudo apt install -y libglib2.0-dev libgstreamer-plugins-base1.0-dev    
sudo apt install -y cmake libboost-program-options-dev libdrm-dev libexif-dev
sudo apt-get install python-opencv
sudo apt-get install python3-smbus

Step 2. Compiling libcamera

git clone git://linuxtv.org/libcamera.git
cd libcamera
meson build --buildtype=release -Dpipelines=raspberrypi -Dipas=raspberrypi -Dv4l2=true -Dgstreamer=enabled -Dtest=false -Dlc-compliance=disabled -Dcam=disabled -Dqcam=enabled -Ddocumentation=disabled -Dpycamera=enabled
ninja -C build   # use -j 2 on Raspberry Pi 3 or earlier devices
sudo ninja -C build install
#Adding dynamic link libraries to __int_py will not copy successfully
sudo cp -r ~/libcamera/build/src/py/libcamera/ /usr/local/lib/python3.10/dist-packages/
sudo rm /usr/local/lib/python3.10/dist-packages/libcamera/__init__.py
sudo bash -c 'cat /home/#your account name#/libcamera/build/src/py/libcamera/__init__.py >> /usr/local/lib/python3.10/dist-packages/libcamera/__init__.py'

Step 3. Compiling libcamera-apps

git clone https://github.com/raspberrypi/libcamera-apps.git
cd libcamera-apps
mkdir build
cd build
cmake .. -DENABLE_DRM=1 -DENABLE_X11=1 -DENABLE_QT=1 -DENABLE_OPENCV=0 -DENABLE_TFLITE=0
make -j4  # use -j1 on Raspberry Pi 3 or earlier devices
sudo make install
sudo ldconfig # this is only necessary on the first build

Step 4. Compiling python-kms++

git clone https://github.com/tomba/kmsxx.git
cd kmsxx
git submodule update --init
meson build
sudo ninja -C build install 
sudo cp -r ~/kmsxx/build/py/pykms/ /usr/local/lib/python3.10/dist-packages/
sudo ldconfig

Step 5. picamera2

sudo apt install -y python3-pyqt5 python3-prctl libatlas-base-dev ffmpeg python3-pip
pip3 install numpy --upgrade
pip3 install picamera2

Step 6. Modify configuration file

sudo vi /boot/firmware/config.txt

Find the line where camera_auto_detect is and change it to camera_auto_detect=0

add dtoverlay= at the end of the line

For example:

dtoverlay=imx477

Step 7. Allow accessing /dev/dma_heap on Ubuntu

# add rule in /etc/udev/rules.d/raspberrypi.rules and add rule
SUBSYSTEM=="dma_heap", GROUP="video", MODE="0660"
# Add user to video group Then reboot
sudo usermod -a -G video $USER 

Step 8. Run project

git clone https://github.com/ArduCAM/PTZ-Camera-Controller.git
cd PTZ-Camera-Controller
sudo python3 FocuserExample.py

Related Docs

---

Troubleshooting - Lens Shading Calibration

Github - PTZ Camera Controller on Raspberry Pi