QX5 USB microscope: Difference between revisions

From LinuxTVWiki
Jump to navigation Jump to search
No edit summary
(Add instructions for compilation of cpia2 driver on recent linux)
 
(6 intermediate revisions by 4 users not shown)
Line 1: Line 1:
The '''QX5 USB microscope''' is a computer-only microscope with magnification power of 10x, 60x and 200x. The QX5 is sold by Intel Play. Intel Play claims that the QX5 is not supported under GNU/Linux, but in fact the cpia2 kernel module supports it well.
The '''QX5 USB microscope''' is a discontinued, computer-only microscope with magnification power of 10x, 60x and 200x. The QX5 was sold by Intel Play. Intel Play did not officially support QX5 for use with GNU/Linux, but the cpia2 kernel module supports it well. The 200x magnification setting requires good lighting, and benefits from external lighting sources.


== Revisions ==
The [[Cpia2]] driver was recently ported to v4l2 and version 2.0 of the driver was released in September 2005; in February 2006 it was accepted into Andrew Morton's 2.6.16-rc4-mm2 experimental kernel branch; cf. [http://kernel.org/pub/linux/kernel/people/akpm/patches/2.6/2.6.16-rc4/2.6.16-rc4-mm2/broken-out/add-cpia2-camera-support.patch submission patch]. It will likely make it into the 2.6.16 kernel.

The QX5 is an improved version of the [[QX3 USB microscope]]. Both devices have an upper portion that is removable from the base while in operation. The QX5 replaces the QX3's incandescent bulbs with LEDs. There were at least two versions of the QX5 produced. QX5 revision 2 identifies itself as 093a:050f. While the QX3 maxpower is reported as 500mA, the QX5 (revision 2) maxpower is reported as 100mA.

{| class="wikitable"
! USB id
! Driver Name
! Vendor Name
! Device Name
|-
| 0813:0001
| cpia1
| Mattel, Inc.
| Intel Play QX3 Microscope
|-
| 0553:0151
| cpia2
| STMicroelectronics Imaging Division (VLSI Vision)
| Digital Blue QX5 Microscope
|-
| 093a:050f
| mars
| Pixart Imaging, Inc.
| 1.3M PC-CAM
|}

In Linux version 4.19.0-5-amd64 (Debian 4.19.37-5), the QX3 and QX5 are both recognized and functional after installing v4l-utils and vlc.

QX5 recognition:
[ 269.688503] usb 1-1.3: new full-speed USB device number 4 using ehci-pci
[ 269.798590] usb 1-1.3: New USB device found, idVendor=093a, idProduct=050f, bcdDevice= 1.00
[ 269.798594] usb 1-1.3: New USB device strings: Mfr=0, Product=2, SerialNumber=0
[ 269.798595] usb 1-1.3: Product: 1.3M PC-CAM
[ 269.824108] media: Linux media interface: v0.10
[ 269.846567] videodev: Linux video capture interface: v2.00
[ 269.871931] gspca_main: v2.14.0 registered
[ 269.873538] gspca_main: mars-2.14.0 probing 093a:050f
[ 269.873608] usbcore: registered new interface driver mars

QX5 v4l2-ctl device information (device "video0" because there is no internal webcam, otherwise would be "video1"):
$ v4l2-ctl --device=/dev/video0 --all
Driver Info:
Driver name : mars
Card type : 1.3M PC-CAM
Bus info : usb-0000:00:1a.0-1.3
Driver version : 4.19.37
Capabilities : 0x85200001
Video Capture
Read/Write
Streaming
Extended Pix Format
Device Capabilities
Device Caps : 0x05200001
Video Capture
Read/Write
Streaming
Extended Pix Format
Priority: 2
Video input : 0 (mars: ok)
Format Video Capture:
Width/Height : 640/480
Pixel Format : 'JPEG' (JFIF JPEG)
Field : None
Bytes per Line : 640
Size Image : 115790
Colorspace : JPEG
Transfer Function : Default (maps to sRGB)
YCbCr/HSV Encoding: Default (maps to ITU-R 601)
Quantization : Default (maps to Full Range)
Flags :
Streaming Parameters Video Capture:
Frames per second: invalid (0/0)
Read buffers : 2
User Controls
brightness 0x00980900 (int) : min=0 max=30 step=1 default=15 value=15 flags=slider
saturation 0x00980902 (int) : min=0 max=255 step=1 default=200 value=200 flags=slider
gamma 0x00980910 (int) : min=0 max=3 step=1 default=1 value=1 flags=slider
sharpness 0x0098091b (int) : min=0 max=2 step=1 default=1 value=1 flags=slider
illuminator_1 0x00980925 (bool) : default=0 value=0 flags=update
illuminator_2 0x00980926 (bool) : default=0 value=0 flags=update

For at least this version (revision 2) of the QX5, illuminator_1 refers to the scope/upper light, and illuminator_2 refers to the stage/lower light, opposite of the QX3 behavior. If both illuminator values are set to "1", the microscope will deactivate the first light and activate the most recent assigned light. If the value for that illuminator is set back to 0, that light will switch back off, and the first light will switch back on.

QX3 recognition:
[ 929.139954] usb 1-1.3: new full-speed USB device number 5 using ehci-pci
[ 929.270696] usb 1-1.3: New USB device found, idVendor=0813, idProduct=0001, bcdDevice= 1.60
[ 929.270699] usb 1-1.3: New USB device strings: Mfr=2, Product=1, SerialNumber=0
[ 929.270700] usb 1-1.3: Product: Intel Play QX3 Microscope
[ 929.270702] usb 1-1.3: Manufacturer: Mattel Inc.
[ 929.292248] gspca_main: cpia1-2.14.0 probing 0813:0001
[ 929.593307] input: cpia1 as /devices/pci0000:00/0000:00:1a.0/usb1/1-1/1-1.3/input/input21
[ 929.593639] usbcore: registered new interface driver cpia1


QX3 v4l2-ctl device information (device "video0" because there is no internal webcam, otherwise would be "video1"):
$ v4l2-ctl --device=/dev/video0 --all
Driver Info:
Driver name : cpia1
Card type : Intel Play QX3 Microscope
Bus info : usb-0000:00:1a.0-1.3
Driver version : 4.19.37
Capabilities : 0x85200001
Video Capture
Read/Write
Streaming
Extended Pix Format
Device Capabilities
Device Caps : 0x05200001
Video Capture
Read/Write
Streaming
Extended Pix Format
Priority: 2
Video input : 0 (cpia1: ok)
Format Video Capture:
Width/Height : 352/288
Pixel Format : 'CPIA' (GSPCA CPiA YUV)
Field : None
Bytes per Line : 352
Size Image : 262144
Colorspace : sRGB
Transfer Function : Default (maps to sRGB)
YCbCr/HSV Encoding: Default (maps to ITU-R 601)
Quantization : Default (maps to Full Range)
Flags :
Streaming Parameters Video Capture:
Frames per second: invalid (0/0)
Read buffers : 2
User Controls
brightness 0x00980900 (int) : min=0 max=100 step=1 default=50 value=50 flags=slider
contrast 0x00980901 (int) : min=0 max=96 step=8 default=48 value=48 flags=slider
saturation 0x00980902 (int) : min=0 max=100 step=1 default=50 value=50 flags=slider
power_line_frequency 0x00980918 (menu) : min=0 max=2 default=1 value=1
illuminator_1 0x00980925 (bool) : default=0 value=0
illuminator_2 0x00980926 (bool) : default=0 value=0
compression_target 0x00981000 (menu) : min=0 max=1 default=0 value=0

== Installation on Linux post 2023 ==

The "cpia2" driver was removed from the Linux kernel in early 2023.
Without it, the camera will not be listed by v4l2 and cannot be used.
At least with Arch Linux 6.6.52-1-lts, it was still possible to compile the deleted source files and load the kernel module.
It is likely that at some point in the future, Linux will change in ways incompatible with the unmaintained driver code, and compilation will start to fail.

# Go to [https://github.com/torvalds/linux/tree/ba47652ba65523ccadac3f8d50dc0e0d560477b2/drivers/staging/media/deprecated/cpia2 Github commit be8cebc] and download all source files (.c and .h) to a new directory <code>cpia2</code>.
# Create a text file called <code>Makefile</code> in this folder, and enter the text below.
# Make sure the kernel headers are present on the system. You can probably install them with your package manager.
# Run <code>make all</code>. If all goes well, it should complete and create some files in the directory. Among those should be <code>cpia2.ko</code>.
# Execute <code>sudo insmod cpia2.ko</code> to load the driver. The camera should now be listed. If insmod throws an error about unknown symbols, try running <code>modprobe videodev</code> first.

'''Makefile'''
obj-m += cpia2.o
cpia2-objs := cpia2_v4l.o cpia2_usb.o cpia2_core.o
KDIR := /lib/modules/$(shell uname -r)/build
PWD := $(shell pwd)
all:
$(MAKE) -C $(KDIR) M=$(PWD) modules
clean:
$(MAKE) -C $(KDIR) M=$(PWD) clean

== Installation on Debian 4.19.37-5 with QX3 or QX5 ==

To install vlc and v4l-utils:
sudo apt-get update
sudo apt-get install vlc
sudo apt-get install v4l-utils

Then insert your microscope USB cable, and launch vlc. You can specify the video device as the output in the command line. Note again that if your system has an internal webcam, replace "video0" with "video1":

vlc v4l2:///dev/video0

In the vlc display, you can find the microscope lighting controls by clicking the "show extended settings" button at the bottom of the window, then clicking on the "v4l2 controls" tab. There will be check boxes for illuminator_1 and illuminator_2.

Alternatively, you can set the lighting from the command line using v4l2-ctl (omit the part in parenthesis):

v4l2-ctl --device=/dev/video0 --set-ctrl=illuminator_1=1 (turn on QX3: stage/lower light, QX5: scope/upper light)
v4l2-ctl --device=/dev/video0 --set-ctrl=illuminator_1=0 (turn off QX3: stage/lower light, QX5: scope/upper light)
v4l2-ctl --device=/dev/video0 --set-ctrl=illuminator_2=1 (turn on QX3: scope/upper light, QX5: stage/lower light)
v4l2-ctl --device=/dev/video0 --set-ctrl=illuminator_2=0 (turn off QX3: scope/upper light, QX5: stage/lower light)

To allow the user to take videos and snapshots (just like the bundled software allows): Under the "View" menu in vlc, check the "Advanced Controls" box. This will show a bar at the bottom of the window that allows recording and snapshots. The storage location should default to the user's "Videos" folder in their home folder for video recordings, and to the user's "Pictures" folder in their home folder for snapshots.

== Error Messages ==

While in operation in Linux version 4.19.0-5-amd64 (Debian 4.19.37-5), the devices generate error logs during normal operation.

QX5 (revision 2) console output:
[ 269.873608] usbcore: registered new interface driver mars
[ 340.818723] mars 1-1.3:1.0: alt 5 - bandwidth not wide enough, trying again
[ 358.293774] mars 1-1.3:1.0: frame overflow 119184 > 118784
[ 360.821761] mars 1-1.3:1.0: frame overflow 119105 > 118784
[ 362.613719] mars 1-1.3:1.0: frame overflow 119039 > 118784
[ 363.093723] mars 1-1.3:1.0: frame overflow 119118 > 118784
[ 400.949336] mars 1-1.3:1.0: frame overflow 118983 > 118784
[ 402.645385] mars 1-1.3:1.0: frame overflow 119090 > 118784
[ 409.365305] mars 1-1.3:1.0: frame overflow 119086 > 118784
[ 432.756880] mars 1-1.3:1.0: urb status: -2
[ 432.756905] gspca_main: usb_submit_urb() ret -1
[ 432.788855] mars 1-1.3:1.0: urb status: -2
[ 432.788871] gspca_main: usb_submit_urb() ret -1
[ 432.820883] mars 1-1.3:1.0: urb status: -2
[ 432.820909] gspca_main: usb_submit_urb() ret -1
[ 709.967805] mars 1-1.3:1.0: alt 5 - bandwidth not wide enough, trying again
[ 760.497427] mars 1-1.3:1.0: frame overflow 119290 > 118784
[ 773.105374] mars 1-1.3:1.0: frame overflow 118913 > 118784
[ 791.728939] mars 1-1.3:1.0: urb status: -2
[ 791.728963] gspca_main: usb_submit_urb() ret -1


QX3 console output:
[ 929.593639] usbcore: registered new interface driver cpia1
[ 986.332235] cpia1 1-1.3:1.0: alt 3 - bandwidth not wide enough, trying again
[ 986.515529] cpia1 1-1.3:1.0: alt 2 - bandwidth not wide enough, trying again
[ 1007.795979] gspca_cpia1: usb_control_msg a7, error -32
[ 1114.874236] cpia1 1-1.3:1.0: urb status: -2
[ 1114.874247] gspca_main: usb_submit_urb() ret -1
[ 1114.906294] cpia1 1-1.3:1.0: urb status: -2
[ 1114.906311] gspca_main: usb_submit_urb() ret -1
[ 1114.938245] cpia1 1-1.3:1.0: urb status: -2
[ 1114.938267] gspca_main: usb_submit_urb() ret -1
[ 1114.939131] gspca_cpia1: usb_control_msg be, error -32
[ 1114.939884] gspca_cpia1: usb_control_msg be, error -32
[ 1114.940633] gspca_cpia1: usb_control_msg be, error -32
[ 1114.941383] gspca_cpia1: usb_control_msg be, error -32
[ 1114.941386] gspca_cpia1: ReadVPRegs(30,4,9,8) - failed: -32
[ 1114.942134] gspca_cpia1: usb_control_msg b2, error -32
[ 1114.942883] gspca_cpia1: usb_control_msg b2, error -32
[ 1114.943632] gspca_cpia1: usb_control_msg b2, error -32
[ 1114.944387] gspca_cpia1: usb_control_msg b2, error -32
[ 1114.946004] gspca_cpia1: usb_control_msg be, error -32
[ 1114.946760] gspca_cpia1: usb_control_msg be, error -32
[ 1114.947513] gspca_cpia1: usb_control_msg be, error -32
[ 1114.948262] gspca_cpia1: usb_control_msg be, error -32
[ 1114.948265] gspca_cpia1: ReadVPRegs(30,4,9,8) - failed: -32
[ 1114.949009] gspca_cpia1: usb_control_msg b2, error -32

== Kernel 2.6.x ==

The [[Cpia2]] driver was ported to v4l2 and version 2.0 of the driver was released in September 2005; in February 2006 it was accepted into Andrew Morton's 2.6.16-rc4-mm2 experimental kernel branch; cf. [http://kernel.org/pub/linux/kernel/people/akpm/patches/2.6/2.6.16-rc4/2.6.16-rc4-mm2/broken-out/add-cpia2-camera-support.patch submission patch].

This driver comes with two small applications:

* mview, a modified version of gqcam to view the output, and
* qx5view, a viewer that also controls the lights on the qx5 microscope. MJPEG Tools


This driver comes with two small applications: mview, a modified version of gqcam to view the output, and qx5view, a viewer that also controls the lights on the qx5 microscope. MJPEG Tools
[http://mjpeg.sourceforge.net MJPEG Tools] can be used to record.
[http://mjpeg.sourceforge.net MJPEG Tools] can be used to record.


Until the driver reaches mainline, you will need to get the latest version of cpia2 and qx5view from the [http://cpia2.sourceforge.net/download.php cpia2 CVS] in order to use the QX5 with a 2.6.x Linux kernel.
The latest version of cpia2 and qx5view is available at the [http://cpia2.sourceforge.net/download.php cpia2 CVS] in order to use the QX5 with a 2.6.x Linux kernel.


To build and load cpia2, you only have to do
To build and load cpia2, you only have to do
Line 14: Line 259:
You will then be able to start qx5view which should detect your microscope.
You will then be able to start qx5view which should detect your microscope.


Oops! qx5view doesn't compile since kernel 2.6.38 or so, but the QX5 does work as a capture device in vlc as /dev/video0. The lights can be controlled from the command line while vlc is running using:
qx5view doesn't compile since kernel 2.6.38 or so, but the QX5 does work as a capture device in vlc as /dev/video0. The lights can be controlled from the command line while vlc is running using:


lights off: $ v4l2-ctl --set-ctrl=lights=0
lights off: $ v4l2-ctl --set-ctrl=lights=0
top light only $ v4l2-ctl --set-ctrl=lights=1
bottom light only $ v4l2-ctl --set-ctrl=lights=2
both lights $ v4l2-ctl --set-ctrl=lights=3


If you'd like a gui to control lights and other QX5 features try qv4l2 while vlc is running. v4l2-ctl and qv4l2 are parts of the v4l-utils package in Debian Wheezy. This all worked with kernel version 3.1.0-1-686-pae.
top light only $ v4l2-ctl --set-ctrl=lights=1

== Ubuntu 12.04LTS+ and Intel Play QX3 Microscope ==

This was for the most part already working in Ubuntu 12.04LTS. The only exception was the installation of v4l-utils with "sudo apt-get install v4l-utils". I already had VLC present on the system and got it up and running quickly:

* Open VLC
* Click on "Media"
* Click on "Open Capture Device"
* Set "Video Device Name" to /dev/video1 (or whatever is appropriate for your system)
* Click on "Play"

You should now have a window output with what the scope sees.

Capturing images is done via Video->Take Snapshot (saves to ~/Pictures directory)


For controlling lights:

You will need to specify --device=/dev/video1 if your computer has a built-in webcam. My laptop has a built-in webcam using /dev/video0 so all my instructions below will use /dev/video1. Omitting --device=/dev/video1 will make it default to using /dev/video0.

use v4l-ctl --all to query the device. The output should show something similar to below:

$ v4l2-ctl --device=/dev/video1 --all
Driver Info (not using libv4l2):
Driver name : cpia1
Card type : Intel Play QX3 Microscope
Bus info : usb-0000:0f:00.0-2
Driver version: 3.2.46
Capabilities : 0x05000001
Video Capture
Read/Write
Streaming
Format Video Capture:
Width/Height : 352/288
Pixel Format : 'CPIA'
Field : None
Bytes per Line: 352
Size Image : 262144
Colorspace : SRGB
Video input : 0 (cpia1: ok)
Streaming Parameters Video Capture:
Frames per second: invalid (0/0)
Read buffers : 2

Next, use --list-ctrls to list the device's controls (outputs to device) We are interested in "illuminator_1" and "illuminator_2" below.

$ v4l2-ctl --device=/dev/video1 --list-ctrls
brightness (int) : min=0 max=100 step=1 default=50 value=50
contrast (int) : min=0 max=96 step=8 default=48 value=48
saturation (int) : min=0 max=100 step=1 default=50 value=50
light_frequency_filter (menu) : min=0 max=2 default=1 value=1
illuminator_1 (bool) : default=0 value=0
illuminator_2 (bool) : default=0 value=0
compression_target (menu) : min=0 max=1 default=0 value=0
bottom light only $ v4l2-ctl --set-ctrl=lights=2
both lights $ v4l2-ctl --set-ctrl=lights=3
Now, all we need to do is use v4l2-ctl to turn them on!

If you'd like a gui to control lights and other QX5 features try qv4l2 while vlc is running. v4l2-ctl and qv4l2 are parts of the v4l-utils package in Debian Wheezy. This all worked with kernel version 3.1.0-1-686-pae.


v4l2-ctl --device=/dev/video1 --set-ctrl=illuminator_1=1 (for stage/lower light)


v4l2-ctl --device=/dev/video1 --set-ctrl=illuminator_2=1 (for scope/upper light)


Using "=0" instead of "=1" will turn off the respective light.




== Linux Mint 16 ==


As of 15 Dec 2013 the QX5 appears not to work under Linux Mint 16 (Linux version 3.11.0-12-generic). VLC does not connect.


== External Links ==
== External Links ==
* [http://ygingras.net/images/wasp-eye2-60x.jpg image taken under GNU/Linux]
* [http://ygingras.net/images/wasp-eye2-60x.jpg image taken under GNU/Linux]
* [http://cpia2.sourceforge.net/ cpia2 driver on sourceforge]
* [http://cpia2.sourceforge.net/ cpia2 driver on sourceforge]
* [http://www.playdigitalblue.com/products/qx5/info/ product website]
* [https://web.archive.org/web/20061022111556/http://www.playdigitalblue.com/products/qx5/info/ product website (archived version)]
[[Category:Hardware]]
[[Category:Hardware]]

Latest revision as of 11:52, 30 September 2024

The QX5 USB microscope is a discontinued, computer-only microscope with magnification power of 10x, 60x and 200x. The QX5 was sold by Intel Play. Intel Play did not officially support QX5 for use with GNU/Linux, but the cpia2 kernel module supports it well. The 200x magnification setting requires good lighting, and benefits from external lighting sources.

Revisions

The QX5 is an improved version of the QX3 USB microscope. Both devices have an upper portion that is removable from the base while in operation. The QX5 replaces the QX3's incandescent bulbs with LEDs. There were at least two versions of the QX5 produced. QX5 revision 2 identifies itself as 093a:050f. While the QX3 maxpower is reported as 500mA, the QX5 (revision 2) maxpower is reported as 100mA.

USB id Driver Name Vendor Name Device Name
0813:0001 cpia1 Mattel, Inc. Intel Play QX3 Microscope
0553:0151 cpia2 STMicroelectronics Imaging Division (VLSI Vision) Digital Blue QX5 Microscope
093a:050f mars Pixart Imaging, Inc. 1.3M PC-CAM

In Linux version 4.19.0-5-amd64 (Debian 4.19.37-5), the QX3 and QX5 are both recognized and functional after installing v4l-utils and vlc.

QX5 recognition: 

[  269.688503] usb 1-1.3: new full-speed USB device number 4 using ehci-pci
[  269.798590] usb 1-1.3: New USB device found, idVendor=093a, idProduct=050f, bcdDevice= 1.00
[  269.798594] usb 1-1.3: New USB device strings: Mfr=0, Product=2, SerialNumber=0
[  269.798595] usb 1-1.3: Product: 1.3M PC-CAM
[  269.824108] media: Linux media interface: v0.10
[  269.846567] videodev: Linux video capture interface: v2.00
[  269.871931] gspca_main: v2.14.0 registered
[  269.873538] gspca_main: mars-2.14.0 probing 093a:050f
[  269.873608] usbcore: registered new interface driver mars

QX5 v4l2-ctl device information (device "video0" because there is no internal webcam, otherwise would be "video1"): 

$ v4l2-ctl --device=/dev/video0 --all
Driver Info:
	Driver name      : mars
	Card type        : 1.3M PC-CAM
	Bus info         : usb-0000:00:1a.0-1.3 
	Driver version   : 4.19.37
	Capabilities     : 0x85200001
		Video Capture
		Read/Write
		Streaming
		Extended Pix Format
		Device Capabilities
	Device Caps      : 0x05200001
		Video Capture
		Read/Write
		Streaming
		Extended Pix Format
Priority: 2
Video input : 0 (mars: ok)
Format Video Capture:
	Width/Height      : 640/480
	Pixel Format      : 'JPEG' (JFIF JPEG)
	Field             : None
	Bytes per Line    : 640
	Size Image        : 115790
	Colorspace        : JPEG
	Transfer Function : Default (maps to sRGB)
	YCbCr/HSV Encoding: Default (maps to ITU-R 601)
	Quantization      : Default (maps to Full Range)
	Flags             : 
Streaming Parameters Video Capture:
	Frames per second: invalid (0/0)
	Read buffers     : 2

User Controls
                    brightness 0x00980900 (int)    : min=0 max=30 step=1 default=15 value=15 flags=slider
                    saturation 0x00980902 (int)    : min=0 max=255 step=1 default=200 value=200 flags=slider
                         gamma 0x00980910 (int)    : min=0 max=3 step=1 default=1 value=1 flags=slider
                     sharpness 0x0098091b (int)    : min=0 max=2 step=1 default=1 value=1 flags=slider
                 illuminator_1 0x00980925 (bool)   : default=0 value=0 flags=update
                 illuminator_2 0x00980926 (bool)   : default=0 value=0 flags=update

For at least this version (revision 2) of the QX5, illuminator_1 refers to the scope/upper light, and illuminator_2 refers to the stage/lower light, opposite of the QX3 behavior. If both illuminator values are set to "1", the microscope will deactivate the first light and activate the most recent assigned light. If the value for that illuminator is set back to 0, that light will switch back off, and the first light will switch back on.

QX3 recognition: 

[  929.139954] usb 1-1.3: new full-speed USB device number 5 using ehci-pci
[  929.270696] usb 1-1.3: New USB device found, idVendor=0813, idProduct=0001, bcdDevice= 1.60
[  929.270699] usb 1-1.3: New USB device strings: Mfr=2, Product=1, SerialNumber=0
[  929.270700] usb 1-1.3: Product: Intel Play QX3 Microscope
[  929.270702] usb 1-1.3: Manufacturer: Mattel Inc.
[  929.292248] gspca_main: cpia1-2.14.0 probing 0813:0001
[  929.593307] input: cpia1 as /devices/pci0000:00/0000:00:1a.0/usb1/1-1/1-1.3/input/input21
[  929.593639] usbcore: registered new interface driver cpia1


QX3 v4l2-ctl device information (device "video0" because there is no internal webcam, otherwise would be "video1"): 

$ v4l2-ctl --device=/dev/video0 --all
Driver Info:
	Driver name      : cpia1
	Card type        : Intel Play QX3 Microscope
	Bus info         : usb-0000:00:1a.0-1.3
	Driver version   : 4.19.37
	Capabilities     : 0x85200001
		Video Capture
		Read/Write
		Streaming
		Extended Pix Format
		Device Capabilities
	Device Caps      : 0x05200001
		Video Capture
		Read/Write
		Streaming
		Extended Pix Format
Priority: 2
Video input : 0 (cpia1: ok)
Format Video Capture:
	Width/Height      : 352/288
	Pixel Format      : 'CPIA' (GSPCA CPiA YUV)
	Field             : None
	Bytes per Line    : 352
	Size Image        : 262144
	Colorspace        : sRGB
	Transfer Function : Default (maps to sRGB)
	YCbCr/HSV Encoding: Default (maps to ITU-R 601)
	Quantization      : Default (maps to Full Range)
	Flags             : 
Streaming Parameters Video Capture:
	Frames per second: invalid (0/0)
	Read buffers     : 2

User Controls

                    brightness 0x00980900 (int)    : min=0 max=100 step=1 default=50 value=50 flags=slider
                      contrast 0x00980901 (int)    : min=0 max=96 step=8 default=48 value=48 flags=slider
                    saturation 0x00980902 (int)    : min=0 max=100 step=1 default=50 value=50 flags=slider
          power_line_frequency 0x00980918 (menu)   : min=0 max=2 default=1 value=1
                 illuminator_1 0x00980925 (bool)   : default=0 value=0
                 illuminator_2 0x00980926 (bool)   : default=0 value=0
            compression_target 0x00981000 (menu)   : min=0 max=1 default=0 value=0

Installation on Linux post 2023

The "cpia2" driver was removed from the Linux kernel in early 2023. Without it, the camera will not be listed by v4l2 and cannot be used. At least with Arch Linux 6.6.52-1-lts, it was still possible to compile the deleted source files and load the kernel module. It is likely that at some point in the future, Linux will change in ways incompatible with the unmaintained driver code, and compilation will start to fail.

  1. Go to Github commit be8cebc and download all source files (.c and .h) to a new directory cpia2.
  2. Create a text file called Makefile in this folder, and enter the text below.
  3. Make sure the kernel headers are present on the system. You can probably install them with your package manager.
  4. Run make all. If all goes well, it should complete and create some files in the directory. Among those should be cpia2.ko.
  5. Execute sudo insmod cpia2.ko to load the driver. The camera should now be listed. If insmod throws an error about unknown symbols, try running modprobe videodev first.

Makefile 

obj-m += cpia2.o
cpia2-objs := cpia2_v4l.o cpia2_usb.o cpia2_core.o
KDIR := /lib/modules/$(shell uname -r)/build
PWD := $(shell pwd)
all:
    $(MAKE) -C $(KDIR) M=$(PWD) modules
clean:
    $(MAKE) -C $(KDIR) M=$(PWD) clean

Installation on Debian 4.19.37-5 with QX3 or QX5

To install vlc and v4l-utils: 

sudo apt-get update
sudo apt-get install vlc
sudo apt-get install v4l-utils

Then insert your microscope USB cable, and launch vlc. You can specify the video device as the output in the command line. Note again that if your system has an internal webcam, replace "video0" with "video1": 

vlc v4l2:///dev/video0

In the vlc display, you can find the microscope lighting controls by clicking the "show extended settings" button at the bottom of the window, then clicking on the "v4l2 controls" tab. There will be check boxes for illuminator_1 and illuminator_2.

Alternatively, you can set the lighting from the command line using v4l2-ctl (omit the part in parenthesis): 

v4l2-ctl --device=/dev/video0 --set-ctrl=illuminator_1=1   (turn on  QX3: stage/lower light, QX5: scope/upper light) 
v4l2-ctl --device=/dev/video0 --set-ctrl=illuminator_1=0   (turn off QX3: stage/lower light, QX5: scope/upper light)  
v4l2-ctl --device=/dev/video0 --set-ctrl=illuminator_2=1   (turn on  QX3: scope/upper light, QX5: stage/lower light) 
v4l2-ctl --device=/dev/video0 --set-ctrl=illuminator_2=0   (turn off QX3: scope/upper light, QX5: stage/lower light)

To allow the user to take videos and snapshots (just like the bundled software allows): Under the "View" menu in vlc, check the "Advanced Controls" box. This will show a bar at the bottom of the window that allows recording and snapshots. The storage location should default to the user's "Videos" folder in their home folder for video recordings, and to the user's "Pictures" folder in their home folder for snapshots.

Error Messages

While in operation in Linux version 4.19.0-5-amd64 (Debian 4.19.37-5), the devices generate error logs during normal operation.

QX5 (revision 2) console output: 

[  269.873608] usbcore: registered new interface driver mars
[  340.818723] mars 1-1.3:1.0: alt 5 - bandwidth not wide enough, trying again
[  358.293774] mars 1-1.3:1.0: frame overflow 119184 > 118784
[  360.821761] mars 1-1.3:1.0: frame overflow 119105 > 118784
[  362.613719] mars 1-1.3:1.0: frame overflow 119039 > 118784
[  363.093723] mars 1-1.3:1.0: frame overflow 119118 > 118784
[  400.949336] mars 1-1.3:1.0: frame overflow 118983 > 118784
[  402.645385] mars 1-1.3:1.0: frame overflow 119090 > 118784
[  409.365305] mars 1-1.3:1.0: frame overflow 119086 > 118784
[  432.756880] mars 1-1.3:1.0: urb status: -2
[  432.756905] gspca_main: usb_submit_urb() ret -1
[  432.788855] mars 1-1.3:1.0: urb status: -2
[  432.788871] gspca_main: usb_submit_urb() ret -1
[  432.820883] mars 1-1.3:1.0: urb status: -2
[  432.820909] gspca_main: usb_submit_urb() ret -1
[  709.967805] mars 1-1.3:1.0: alt 5 - bandwidth not wide enough, trying again
[  760.497427] mars 1-1.3:1.0: frame overflow 119290 > 118784
[  773.105374] mars 1-1.3:1.0: frame overflow 118913 > 118784
[  791.728939] mars 1-1.3:1.0: urb status: -2
[  791.728963] gspca_main: usb_submit_urb() ret -1


QX3 console output: 

[  929.593639] usbcore: registered new interface driver cpia1
[  986.332235] cpia1 1-1.3:1.0: alt 3 - bandwidth not wide enough, trying again
[  986.515529] cpia1 1-1.3:1.0: alt 2 - bandwidth not wide enough, trying again
[ 1007.795979] gspca_cpia1: usb_control_msg a7, error -32
[ 1114.874236] cpia1 1-1.3:1.0: urb status: -2
[ 1114.874247] gspca_main: usb_submit_urb() ret -1
[ 1114.906294] cpia1 1-1.3:1.0: urb status: -2
[ 1114.906311] gspca_main: usb_submit_urb() ret -1
[ 1114.938245] cpia1 1-1.3:1.0: urb status: -2
[ 1114.938267] gspca_main: usb_submit_urb() ret -1
[ 1114.939131] gspca_cpia1: usb_control_msg be, error -32
[ 1114.939884] gspca_cpia1: usb_control_msg be, error -32
[ 1114.940633] gspca_cpia1: usb_control_msg be, error -32
[ 1114.941383] gspca_cpia1: usb_control_msg be, error -32
[ 1114.941386] gspca_cpia1: ReadVPRegs(30,4,9,8) - failed: -32
[ 1114.942134] gspca_cpia1: usb_control_msg b2, error -32
[ 1114.942883] gspca_cpia1: usb_control_msg b2, error -32
[ 1114.943632] gspca_cpia1: usb_control_msg b2, error -32
[ 1114.944387] gspca_cpia1: usb_control_msg b2, error -32
[ 1114.946004] gspca_cpia1: usb_control_msg be, error -32
[ 1114.946760] gspca_cpia1: usb_control_msg be, error -32
[ 1114.947513] gspca_cpia1: usb_control_msg be, error -32
[ 1114.948262] gspca_cpia1: usb_control_msg be, error -32
[ 1114.948265] gspca_cpia1: ReadVPRegs(30,4,9,8) - failed: -32
[ 1114.949009] gspca_cpia1: usb_control_msg b2, error -32

Kernel 2.6.x

The Cpia2 driver was ported to v4l2 and version 2.0 of the driver was released in September 2005; in February 2006 it was accepted into Andrew Morton's 2.6.16-rc4-mm2 experimental kernel branch; cf. submission patch.

This driver comes with two small applications:

  • mview, a modified version of gqcam to view the output, and
  • qx5view, a viewer that also controls the lights on the qx5 microscope. MJPEG Tools

MJPEG Tools can be used to record.

The latest version of cpia2 and qx5view is available at the cpia2 CVS in order to use the QX5 with a 2.6.x Linux kernel.

To build and load cpia2, you only have to do

make install
modprobe cpia2

You will then be able to start qx5view which should detect your microscope.

qx5view doesn't compile since kernel 2.6.38 or so, but the QX5 does work as a capture device in vlc as /dev/video0. The lights can be controlled from the command line while vlc is running using: 

lights off:       $ v4l2-ctl --set-ctrl=lights=0  
top light only    $ v4l2-ctl --set-ctrl=lights=1 
bottom light only $ v4l2-ctl --set-ctrl=lights=2 
both lights       $ v4l2-ctl --set-ctrl=lights=3

If you'd like a gui to control lights and other QX5 features try qv4l2 while vlc is running. v4l2-ctl and qv4l2 are parts of the v4l-utils package in Debian Wheezy. This all worked with kernel version 3.1.0-1-686-pae.

Ubuntu 12.04LTS+ and Intel Play QX3 Microscope

This was for the most part already working in Ubuntu 12.04LTS. The only exception was the installation of v4l-utils with "sudo apt-get install v4l-utils". I already had VLC present on the system and got it up and running quickly:

  • Open VLC
  • Click on "Media"
  • Click on "Open Capture Device"
  • Set "Video Device Name" to /dev/video1 (or whatever is appropriate for your system)
  • Click on "Play"

You should now have a window output with what the scope sees.

Capturing images is done via Video->Take Snapshot (saves to ~/Pictures directory)


For controlling lights:

You will need to specify --device=/dev/video1 if your computer has a built-in webcam. My laptop has a built-in webcam using /dev/video0 so all my instructions below will use /dev/video1. Omitting --device=/dev/video1 will make it default to using /dev/video0.

use v4l-ctl --all to query the device. The output should show something similar to below: 

$ v4l2-ctl --device=/dev/video1 --all
Driver Info (not using libv4l2): 
	Driver name   : cpia1
	Card type     : Intel Play QX3 Microscope
	Bus info      : usb-0000:0f:00.0-2
	Driver version: 3.2.46
	Capabilities  : 0x05000001
		Video Capture
		Read/Write
		Streaming
Format Video Capture:
	Width/Height  : 352/288
	Pixel Format  : 'CPIA'
	Field         : None
	Bytes per Line: 352
	Size Image    : 262144
	Colorspace    : SRGB
Video input : 0 (cpia1: ok)
Streaming Parameters Video Capture:
	Frames per second: invalid (0/0)
	Read buffers     : 2

Next, use --list-ctrls to list the device's controls (outputs to device) We are interested in "illuminator_1" and "illuminator_2" below. 

$ v4l2-ctl --device=/dev/video1 --list-ctrls
                     brightness (int)    : min=0 max=100 step=1 default=50 value=50
                       contrast (int)    : min=0 max=96 step=8 default=48 value=48
                     saturation (int)    : min=0 max=100 step=1 default=50 value=50
         light_frequency_filter (menu)   : min=0 max=2 default=1 value=1
                  illuminator_1 (bool)   : default=0 value=0
                  illuminator_2 (bool)   : default=0 value=0
             compression_target (menu)   : min=0 max=1 default=0 value=0

Now, all we need to do is use v4l2-ctl to turn them on! 

v4l2-ctl --device=/dev/video1 --set-ctrl=illuminator_1=1   (for stage/lower light)

v4l2-ctl --device=/dev/video1 --set-ctrl=illuminator_2=1   (for scope/upper light)

Using "=0" instead of "=1" will turn off the respective light.


Linux Mint 16

As of 15 Dec 2013 the QX5 appears not to work under Linux Mint 16 (Linux version 3.11.0-12-generic). VLC does not connect.

External Links

Retrieved from "https://www.linuxtv.org/wiki/index.php?title=QX5_USB_microscope&oldid=36752"