PLEASE READ: this tutorial assumes that the Dragonfly Java App has been already setup following the instructions available starting from this page.

A Raspberry Pi (RPI) is a cheap, flexible and power-efficient platform that can easily be used as a wireless remote camera for Dragonfly. It can easily stream a video over Ethernet, WiFi or LTE with the proper equipment.

1 – RPI Hardware

The required hardware to create a Raspberry Pi streaming kit is the following one. Everything is very easy to find and to buy online, some ready-to-go kits are also available but usually don’t include a camera.

  • Raspberry Pi motherboard: two different options are available.
    • Raspberry Pi 3 B+: this is the most recent and powerful version of the RPI. For streaming, its main advantage is to have an integrated 5 GHz WiFi controller, which provides a much better connection than the older 2.4 GHz WiFi controller of the other boards.
    • Raspberry Pi Zero W: this is the most compact and power efficient version of the RPI. It is also cheaper than the Raspberry Pi 3 B+, but it only comes with a weak 2.4 GHz WiFi controller.
  • Micro SD card: 16 GB are sufficient to run the OS smoothly. We recommend to purchase a class 10 card to avoid the RPI to be too slow.
  • Raspberry Pi fish eye camera: anyway any RPI wide angle camera with a frame-rate above 30 fps @ 640 x 480 can be used (with a preference for cameras with a FOV lower or equal to 160 degrees – because they are easier to calibrate). Our recommendation is this SainSmart Wide Angle Fish-Eye Camera.
  • (OPTIONAL) the following equipment can be useful in some cases:
    • USB power bank: any USB connector is sufficient to power the RPI. Having a USB power bank allows to have a very mobile streaming device. The power consumption of a RPI is very low and can run hours on the smallest available power bank. Feel free to choose among the most compact power banks capable of providing an output of at least 2 Ampere.
    • Case for the RPI: there are a bunch a cases for the different RPI models. They are often already provided with ready-to-go kits.
    • Case/enclosure for the RPI camera.
    • HDMI cable, USB keyboard and USB mouse: useful if you want to use the user interface to configure the RPI the first time. It is also possible to configure the RPI in headless mode though, as explained below.

USB ASTAR stereo camera ​is not compatible with Raspberry Pi ​​up to 3B+ because the USB 2.0 port does not deliver enough power. It might work on a Raspberry Pi 4 (it needs to be tested).

2 – RPI setup

2.1 – Camera physical connection

Those marked in BLUE are the slots to be used to connect the SainSmart Wide Angle Fish-Eye Camera to the RPI.

Raspberry Pi 3 B+ board

Raspberry Pi Zero W board

2.2 – Setup Raspbian Buster

OPTION 1 – Using the RPI graphic interface

Install the operating system

  1. Download on your computer the latest version of Raspbian Buster with desktop here. We can only guarantee correct operation on Stretch and Buster.
  2. Download on your computer Etcher here.
  3. Insert your micro SD card in your computer, and use Etcher to flash it with the downloaded image of Raspbian Buster with desktop.
  4. Insert the micro SD card in the Raspberry Pi.
  5. Plug your RPI to a monitor, plug a USB keyboard and mouse, and power the RPI.
  6. Follow the configuration wizard and connect your RPI to a Wi-Fi network.

Enable the SSH server and the Camera interface

You need to plug the camera to your RPI before following the instructions below.

  1. Open the LX Terminal on your RPI.
  2. Run the command:
  3. Select Interfacing Options > SSH and enable the SSH server.
  4. Select Interfacing Options > Camera and enable the Camera interface.
  5. Select Advanced Options > Expand filesystem.
  6. Go back to the main screen click on Finish and confirm the reboot.

OPTION 2 – Without the RPI graphic interface (headless mode)

Install the operating system

  1. Download on your computer the latest version of Raspbian Buster Lite here. We can only guarantee correct operation on Stretch and Buster.
  2. Download on your computer Etcher here.
  3. Insert your micro SD card in your computer, and use Etcher to flash it with the downloaded image of Raspbian Buster Lite.
  4. Open a terminal window and cd to the micro SD card using the following command:
  5. In the boot drive, create a file called ssh. Just an empty file with exactly that name.
  6. In the boot drive, create a file called  wpa_supplicant.conf.
  7. Take an editor of your choice and add this to wpa_supplicant.conf and change YOUR_SSID and YOUR_PSK parts according to your environment:
  8. Insert the micro SD card in RPI and power it ON.

Connection problems: if you have problems connecting your RPI to the WiFi network please look at this thread.

Enable the Camera interface

You need to plug the camera to your RPI before following the instructions below.

  1. Open the terminal on your machine (Linux or macOS).
  2. Find the local IP assigned to your RPI (from now on ip_of_the_pi) using one of the methods of this guide OR launching this command (after having installed nmap):
  3. Run the following command and put raspberry as a password when requested:
  4. Run the command:
  5. Select Interfacing Options > Camera and enable the Camera interface.
  6. Select Advanced Options > Expand filesystem.
  7. Go back to the main screen click on Finish and confirm the reboot.

2.3 – Setup Gstreamer

We use Gstreamer to stream the video. To install it enter the following commands on your RPI:

2.4 – Make your RPI a RTSP server

To make the RPI video stream a RTSP stream accessible you have to enter the following commands on your RPI:

  1. Check which Gstreamer version has been installed at point 2.3 using this command:
  2. On this site look for the URL of the Gstreamer RTSP server compatible with the Gstreamer version installed at point 2.3
  3. Install the Gstreamer RTSP server using the following commands but please remember to edit the WGET command with the URL of the compatible version of the Gstreamer RTSP server:
  4. Install the raspivid wrapper gst-rpicamsrc using these commands:
  5. Check, if gst-rpicamsrc is installed launching this command:

3 – Make the video stream available to the Dragonfly Java App

  1. If not already done please setup the Dragonfly Java App following carefully the instructions available starting from this page.
  2. Launch the Dragonfly Java App.
  3. Click on the Configuration tab:
    1. set the CAM_SOURCE parameter to the following string (where ip_of_the_pi is the local IP address assigned to the RPI):

    2. set the CAM IMAGE WIDTH and HEIGHT to 640 x 480.
  4. Click on Save and Restart.

4 – Calibration of the camera

4.1 – Enable the RTSP stream

  1. On the RPI launch this command:
  2. The command above should return this:
  3. Leave this terminal opened and DON’T STOP THIS COMMAND.

4.2 – Calibrate the camera

  1. Click on the Calibration tab of the Dragonfly Java App.
  2. Download the calibration pattern at this link.
  3. Open it on the screen of your PC or print it out on an A4 or Letter paper and place it on a plain table/desk or stick the calibration pattern on a cardboard cover. Do not perform the calibration with wobbly paper in your hand. Those results are unusable.
  4. Measure the distance in millimeters (NO inches no centimeters!) of the HDIST line visible inside the calibration pattern.
  5. Configure the distance just measured inside the field HDIST.
  6. Select 640 x 480 as Video Resolution of your camera from the drop down menu.
  7. Do not enable the Fisheye Lens. Leave the assisted mode enabled.
  8. Start the calibration by clicking on START.
  9. The server presents you a  pulsating color pattern overlay, surrounded by a black frame with a positioning indicator in the top-left corner.
  10. If you hold your calibration pattern plate into the camera, you should see the black dots being connected by colored lines.
  11. Your challenge is now to match the pattern displayed on the screen with your calibration pattern plate. The snapshots are made automatically.
  12. It doesn’t matter whether you move the camera over the calibration pattern or the calibration pattern in front of the camera.
  13. The server will present at least 21 poses, which all need to be matched. TIP: if it helps you to coordinate your movements, you can have the image displayed mirrored by clicking on the button Flip View.
  14. After you have finally made it, the server automatically start the computation of the calibration parameters of your camera and will be notified once this process is finished. T
  15. At the end of the calibration process:
    • click on the Download button and download the JSON calibration file generated by the calibration tool.
    • place the JSON calibration file inside the config folder of the Dragonfly Java App (cd dragonfly_linux/application/Dragonfly2Java_jar/config).
    • set the CAM_CALIBRATION_FILE parameter under the Configuration tab to the name of the JSON calibration file placed inside the config folder (cd dragonfly_linux/application/Dragonfly2Java_jar/config)

The Raspberry Pi can now be used as a remote camera for Dragonfly. All the information about the Dragonfly Java App can be found inside this page.

IMPORTANT NOTE: please remember to enable the RTSP stream on the RPI before clicking on START POSITIONING inside the Dragonfly Java App. To enable the RTSP stream follow the instructions inside section 4.1.