Skip to content

Transform your Raspberry PI in an ethernet multicamera device for machine vision using USB / CSI cameras.

License

Notifications You must be signed in to change notification settings

improvess/raspberry-as-gige-camera

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

raspberry-as-gige-camera

Transform your Raspberry PI in an ethernet multicamera device for machine vision systems using USB / CSI cameras.

TL;DR;

Expose your USB/CSI cameras as an ethernet device using Raspberry PI's gigabyte ethernet port. In other words, you can access your remote cameras just like you do with your local devices.

rpiasgige has an OpenCV-style API for C++ and Python 3 (JavaScript & Java API's on the way). Check out the examples below:

  • C++
#include "rpiasgige/client_api.hpp"

using namespace rpiasgige::client;

int main(int argc, char **argv) {

    Device camera("192.168.2.3", 4001);

    camera.open();

    cv::Mat image;
    camera.retrieve(image);

    cv::imshow(image);
    camera.release();
    cv::waitKey();
    
    return 0;
}
  • Python 3
from rpiasgige.client_api import Device

camera = Device("192.168.2.3", 4001)

camera.open()

ret, frame = camera.read()

cv.imshow("frame", frame)
cv.waitKey()

camera.release():

Multicamera synchronization for machine vision

Due to caches, buffers and other video streaming features, sychronizing multi IP camera systems is not easy (see OpenCV VideoCapture lag due to the capture buffer for example). This is easier to achieve with rpiasgige:

In the example above, 6 USB cameras are attached to 2 Raspberry Pis and frames are grabbed at 30 FPS. The clock in the image is a millisecond precision clock. As the image shows, the max time difference between the images is about ±30 ms.

image

Getting started

Check out the Step-by-step rpiasgige tutorial.

Why?

A real gigabyte camera (see gigE) is great but not cheap and in many situations cameras like this aren't available at all on stock/suppliers. In scenarios like this, you can use your Raspberry Pi as an alternative to provide an ethernet interface for your USB cameras and grab images them from via ethernet network even from long ranges.

Examples of setup

Examples of usage

Grabbing images at 100-150 fps with resolution 320x240 using a Sony Playstation 3 Eye camera:

image

Achieving 14-19 fps at 1280x720 using a Microsoft Lifecam Studio.

image

See also: Accessing Raspberry CSI Camera Module remotely

Instructions how to build and run rpiasgige are shown below.

Building & run

rpiasgige has two code sets:

  • server: the application which runs on raspberry pi to expose the USB camera as an ethernet device
  • client: API and utilities to allow programs to access the camera remotely

In this section, it is shown how to build the server side application. Check the next sections to know how to use the program client API's and see other ways to acess your camera from a remote computer.

Building the server side

This repo uses CMake and OpenCV to build the code on a Raspberry PI OS or similar operating system.

Install pre-requisites:

$ sudo apt-get install binutils-dev -y
$ sudo apt-get install libboost-all-dev -y
$ git clone https://github.com/doleron/raspberry-as-gige-camera.git
$ cd raspberry-as-gige-camera/code/server
$ mkdir build
$ cd build
$ cmake ..
$ make -j4

Obs. 1: Check here, here or here to learn how to install OpenCV on Raspberry PI.

Obs. 2: If not yet, do not forget to install git, cmake and gcc before building:

sudo apt install git build-essential cmake

Running the rpiasgige server on Raspberry Pi

After building rpiasgige, run the server as follows:

pi@raspberrypi:~/raspberry-as-gige-camera/build $ ./rpiasgige -port=4001 -device=/dev/video0
DEBUG - /dev/video0 - Not initialized. Initializing now.
DEBUG - /dev/video0 - successfuly initialized.
DEBUG - /dev/video0 - Waiting for client

Once the rpiasgige server is running, it is ready to respond to incoming TCP requests.

Building & running the clients

There are four ways to access the rpiasgige server:

  • Sending command-line requests using native SO utilities: check the examples.
  • Using the provided client programs: check the example.
  • Using the provided client API's: check the API.
  • Writing your own remote calls using the rpiasgige protocol

Note that the python client requires websocket-client

pip3 install websocket-client

Building and running the tests

rpiasgige is shipped with a set of unit tests. You can build and run it as follows:

$ cd raspberry-as-gige-camera/code/server/build
$ cmake -DBUILD_TESTS=ON ..
$ make

Obs.: cmake will automatically donwload googletest for you.

Once everything is build, run the tests just by:

$ ./test_rpiasgige 

Limitations

According to this, the L2 shared cache of Raspberry PI 4 processor is set to 1MB whereas the same cache is constrained to only 512 KB in RPI 3 boards. This bottleneck eventually reduces the amount of traffic data/FPS sent/received.

Note that some RPI boards - such as model A and zero - don't have a built-in ethernet interface whereas some old models do not have even a wifi interface. For narrowed boards like this you can attach a USB-to-ethernet adapter as a very last alternative. But be aware to achieve a not so high data throughtput though.

That said, rpiasgige is a suitable alternative to retrieve frames at at most 150 fps for low resolutions such as 640x480 or less. Of course, your camera must support the speed and resolution as well.

What rpiasgige not is

  • rpiasgige is not a surveillance system, OS, library or so. Check motionEyeOS if your are looking for a great surveillance tool for your Raspberry PI/home.

  • rpiasgige is not a licensed gigE vision device. See Disclaimer below.

  • rpiasgige is not an implementation of RTSP or NOVIF protocols.

Disclaimer

This code is in its early stages yet. It is not battle-tested neither ready for production yet at all.

Note also that this repository does not follow the gigE Vision standard and it is not licensed as a gigE Vision device.

How to Contribute

Contributions are very welcome! Check below for next steps. Reviews are also useful. Do not hesitate to file an issue if you find something weird or wrong. PR's are super welcome as well!

TODO: Next steps

  • Improving protocol description
  • tests
  • More tests
  • Test a bit more, man!
  • C'mon tests are always welcome! More tests doleron!
  • Considering removing OpenCV dependency
  • Resovle the cmaera path (for ex.: /dev/video2) by the USB bus address
  • Coding remote C++ API
  • Coding remote client example
  • Supporting big-endian clients
  • Adding Python client API
  • Adding JavaScript client API
  • Adding Java client API
  • Adding callback to decorate frame before send

About

Transform your Raspberry PI in an ethernet multicamera device for machine vision using USB / CSI cameras.

Topics

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages