PHYTEC-USB-CAM Series communication protocol

Application Note No. LAN-057e Version: 1.0 Author: H. Fendrich Date: 30.09.2011 Historie: Version Changes Date Author 1.0 Creation of the document 30.09.2011 H. Fendrich PHYTEC-USB-CAM Series communication protocol Table of Contents 1 Introduction... 2 2 Properties... 3 2.1 UVC Requests... 3 2.2 Definitions... 3 2.2.1 VC_PROCESSING_UNIT... 3 2.2.2 VC_INPUT_TERMINAL... 4 2.2.3 CT_PRIVACY_CONTROL... 5 3 Register Requests... 6 4 Video Format Selection... 7 4.1 Introduction... 7 4.2 Initializing the Video Format Setting (probe/commit)... 7 4.3 Video Format - USB-CAM-x51H / x52h series... 8 4.4 Frame Rates USB-CAM x03h / x04h... 9 4.5 Frame Rates - USB-CAM x51h / x52h... 10 5 Video Data Transfer... 12 6 References... 12 List of Figures Figure 1: USB-CAM... 2 LAN-057e_1 1/12

1 Introduction The communication protocol of the PHYTEC USB-CAM series (USB-CAM- 051H / 052H / 151H / 152H and USB-CAM-003H / 004H / 103H / 104H) is based on the "USB video device class" (UVC - http://en.wikipedia.org/wiki/usb_video_device_class). Unfortunately, UVC does not fully meet the requirements of industrial cameras. It, for instance, does not provide monochrome video formats. Therefore, PHYTEC has enhanced the USB video class by the features described in this document. Please note that the Phytec Messtechnik GmbH cannot and does not take any responsibility or liability for any information contained in this document. The source code presented in this document is exclusively used for didactic purposes. PHYTEC does not assume any kind of warranty expressed or implied, resulting from the use of the content of this document or the source code. The PHYTEC reserves the right to make changes in specifications, function or design at any time and without prior notice. Figure 1: USB-CAM 2/12 LAN-057e_1

2 Properties 2.1 UVC Requests To get details about the camera parameters, a UVC driver sends requests to the camera (as for instance: - PU_BRIGHTNESS_CONTROL, PU_GAIN_CONTROL and - PU_WHITE_BALANCE_TEMPERATURE_CONTROL). The USB-CAM cameras respond normally to such requests. There is only one exception: below you will find UVC add-ons that are only valid for the USB-CAM series. Please do not use the request GET_LEN in the context of these add-ons. 2.2 Definitions The UVC Processing Unit Descriptors are used to describe the features of the video device. Pls. see chapter 3.7.2.5 of the UVC specification [1] for details. To overcome some UVC limits, we enhanced the following three Interface Descriptor Subtypes: 2.2.1 VC_PROCESSING_UNIT For The PHYTEC USB-CAM cameras the UVC interface descriptor subtype VC_PROCESSING_UNIT describes some color formats that are unknown in the UVC standard (pls. see also section Video data format selection below). Please note that the controls of this terminal are readonly. To get the color formats provided by the camera, read the terminal's value and perform an operation with the following bit values: enum COLOR_FORMAT_MONO8 = 1<<0, COLOR_FORMAT_BAYER1 = 1<<3, // RG COLOR_FORMAT_BAYER2 = 1<<4, // GR COLOR_FORMAT_BAYER3 = 1<<5, // BG COLOR_FORMAT_BAYER4 = 1<<6, // GB LAN-057e_1 3/12

enum PU_TIS_CAPABILITY = 0x20, PU_TIS_COLOR_FORMAT = 0x21, enum PU_CAPABILITY_COLOR_FORMAT = 1<<1, Example: // Checking if the device delivers COLOR_FORMAT_BAYER1 data : unsigned int av_formats =...; //... = your function to read the terminal bool issupported = (av_formats & COLOR_FORMAT_BAYER1)!= 0; 2.2.2 VC_INPUT_TERMINAL For The PHYTEC USB-CAM cameras the UVC interface descriptor subtype VC_INPUT_TERMINAL describes some features that are typical for industrial cameras but unknown in the UVC standard: enum CT_TIS_CAPABILITY = 0x20, // capability bits, see CT_CAPABILITY_* CT_TIS_PIXEL_CLOCK = 0x24, CT_TIS_PARTIAL_SCAN_WIDTH = 0x25, CT_TIS_PARTIAL_SCAN_HEIGHT = 0x26, CT_TIS_BLANKING_INFO = 0x27, CT_TIS_PARTIAL_SCAN_X = 0x28, CT_TIS_PARTIAL_SCAN_Y = 0x29, CT_TIS_BINNING = 0x2a, CT_TIS_SOFTWARE_TRIGGER = 0x2b, CT_TIS_FIRMWARE_REVISION = 0x2d, CT_TIS_DIGITAL_OUTPUT = 0x2e, CT_TIS_UART = 0x41, // special values 4/12 LAN-057e_1

enum CT_CAPABILITY_PIXEL_CLOCK = 1<<4, CT_CAPABILITY_PARTIAL_SCAN_WIDTH = 1<<5, CT_CAPABILITY_PARTIAL_SCAN_HEIGHT = 1<<6, CT_CAPABILITY_BLANKING_INFO = 1<<7, CT_CAPABILITY_BINNING = 1<<8, CT_CAPABILITY_SOFTWARE_TRIGGER = 1<<9, CT_CAPABILITY_FIRMWARE_REVISION = 1<<11, CT_CAPABILITY_DIGITAL_OUTPUT = 1<<12, CT_CAPABILITY_UART = 1<<14, 2.2.3 CT_PRIVACY_CONTROL Another typical feature of industrial cameras is the trigger input (please see http://www.industrial-camera.com/trigger.htm for details). For the PHYTEC USB-CAM cameras the UVC interface descriptor subtype CT_PRIVACY_CONTROL is used to provide this feature: setting CT_PRIVACY_CONTROL to 0x1 enables the trigger, setting it to 0x3 enables the trigger and inverts the trigger pulse polarity. LAN-057e_1 5/12

3 Register Requests Some of the parameters of PHYTEC USB-CAM cameras have to be set via registers. Please use a USB vendor request [2] with the following fields to access the camera's registers: bool bvendorreq = true; BYTE RequestTarget = 0 BYTE brequestcode = 0 WORD wvalue = 0 WORD windex = register_id register_id can be one of the following registers: MPIARegister_CamType = 0x1a MPIARegister_FrameRate = 0x3a Read MPIARegister_CamType to retrieve the type of the sensor. If bit 0x2 is 0 it is a monochrome camera, otherwise it is color camera: bool is_color_cam = (readregister( MPIARegister_CamType ) & 0x2)!= 0; Register MPIARegister_FrameRate is used to set the frame rate of USB- CAM-x03H / x04h cameras. Please see details below. 6/12 LAN-057e_1

4 Video Format Selection 4.1 Introduction Because of historical reasons, the UVC Windows drivers are based on video formats providing 16 bit color values for every pixel. In contrast to this, the PHYTEC USB-CAM cameras use - depending on the specific camera - 8 bit monochrome or 8 bit raw color data (also called "Bayer" format; please see http://knol.google.com/k/henning-b%c3%a4ssmann/color-cameras-whatis-the-origin-of-the/1s6x647mrtwu6/3# for details). Therefore, please interpret a 16 bit UVC color value as two 8 bit monochrome or raw color values. As a consequence, the images only have half the columns of their nominal resolution. For instance, a USB-CAM-x03H / x04h with a nominal resolution of 744 x 480 pixel has to be treated as a camera with 372 x 480 pixel. For industrial cameras "video format" also comprises the camera's frame rate. Additionally, the USB-CAM camera series provide a ROI (region of interest) feature. Furthermore, the USB-CAM-x51H / x52h series offers two binning modes. 4.2 Initializing the Video Format Setting (probe/commit) According to chapter 4.3 of the UVC specification [1], a probe request has to be sent to the camera. For the USB-CAM-x51H / x52h series, please perform this request using the following structure (VideoStreamingControl is described in table 4-47 of the UVC specification): VideoStreamingControl probe = 0x1, 0x1, 0x1, 333333 LAN-057e_1 7/12

In case of the USB-CAM-x03H / x04h camera series this structure has to be initialized with: VideoStreamingControl probe = 0x1, 0x1, bframeindex, 333333 Please set the field bframeindex according to the video frame index that represents the required resolution. To determine the correct video frame index, please refer to the cameras Video Streaming Uncompressed Frame Type Descriptor. This descriptor has initially been read by the UVC driver. To find more details concering bframeindex, please refer to chapter 4.3.1.1 of the UVC specification [1]. 4.3 Video Format - USB-CAM-x51H / x52h series While the video format setting of the USB-CAM-x03H / x04h camera series is mainly done by the initializing procedure described in the previous section, the USB-CAM-x51H / x52h series require more parameters to be set. First of all, you need to know the minimum and maximum resolution of the image. The camera provides you with these parameters via CT_TIS_PARTIAL_SCAN_WIDTH and CT_TIS_PARTIAL_SCAN_HEIGHT. To set the image size, please set the parameters CT_TIS_PARTIAL_SCAN_WIDTH, CT_TIS_PARTIAL_SCAN_HEIGHT, CT_TIS_PARTIAL_SCAN_X, and CT_TIS_PARTIAL_SCAN_Y. Please also note that the increment of the width is 8 pixels, while that of the height is 4 pixels. 8/12 LAN-057e_1

Another important video format parameter is the frame rate. Please see section Frame rates - USB-CAM-x03H / x04h below for details. To increase the sensors sensivity, the USB-CAM-x51H / x52h camera series provides two binning modes. Please set CT_TIS_BINNING to 2 for a 2x2 binning and 4 for a 4x4 binning. If you do not intend to use any binning mode, CT_TIS_BINNING has to be 1. Important: please set the above mentioned parameters based on the following sequence: Reset CT_TIS_BINNING to 1 (no binning) Reset CT_TIS_PARTIAL_SCAN_X and CT_TIS_PARTIAL_SCAN_Y to 0 Set your frame rate (see below) Set your image resolution (region of interest) using CT_TIS_PARTIAL_SCAN_WIDTH and CT_TIS_PARTIAL_SCAN_HEIGHT Set your image position (region of interest) using CT_TIS_PARTIAL_SCAN_X and CT_TIS_PARTIAL_SCAN_Y Set your binning mode using CT_TIS_BINNING 4.4 Frame Rates USB-CAM x03h / x04h Please set the register MPIARegister_FrameRate with the following values to determine the frame rate of the USB-CAM-x03H / x04h cameras: 320x240 Register 640x480 Register 160 fps 7 87 fps 7 120 fps 6 60 fps 6 80 fps 0 or 5 30 fps 0 or 5 60 fps 1 15 fps 2 30 fps 2 7.5 fps 3 5 fps 4 744x480 Register 76 fps 7 60 fps 6 30 fps 0 or 5 15 fps 2 7.5 fps 3 5 fps 4 LAN-057e_1 9/12

4.5 Frame Rates - USB-CAM x51h / x52h Please use the function setframerate( SIZE newdim, int64 AvgTimePerFrame) to set the camera's pixel clock. By using the parameters newdim and AvgTimePerFrame, you determine the image size and the frame rate (in units of 100 nano seconds): typedef struct tagsize int cx; int cy; SIZE; unsigned int calc_pixel_per_frame( unsigned int w, unsigned int h ) unsigned int pixel_width = w * 1; unsigned int x_blanking = BlankingInfo_getValue() & 0xFFFF; unsigned int y_blanking = (BlankingInfo_getValue() >> 16) & 0xFFFF; return (pixel_width + x_blanking) * (h + y_blanking); inline int64 AvgTPFtoFP1kS( int64 v ) return 10000000000 / v; inline int64 FP1kStoAvgTimePerFrame( int64 v ) return 10000000000 / v; int64 calc_fp1ks_for_pixelclock( const SIZE& dim, INT32 val ) int64 max_pixelclock = val; int64 pixel = calc_pixel_per_frame( dim.cx, ABS( dim.cy ) ); return (max_pixelclock * int64( 1000 )) / pixel; // frames per second * 1000 10/12 LAN-057e_1

void setframerate( SIZE newdim, int64 AvgTimePerFrame ) int64 framerate_fp1ks = AvgTPFtoFP1kS( hdr.avgtimeperframe ); int64 max_fp1ks = calc_fp1ks_for_pixelclock( newdim, PixelClock_max_getValue() ); int64 min_fp1ks = calc_fp1ks_for_pixelclock( newdim, PixelClock_min_getValue() ); int64 frmratetoset_fp1ks = CLIP( framerate_fp1ks, min_fp1ks, max_fp1ks ); int64 pixel = calc_pixel_per_frame( newdim.cx, ABS( newdim.cy ) ); int64 new_pixel_clock = (pixel * fp1ks) / int64( 1000 ); PixelClock_setValue( new_pixel_clock ); Please note: Function BlankingInfo_getValue() retrieves the value of the CT_TIS_BLANKING_INFO control (please see section VC_INPUT_TERMINAL above) PixelClock_min_getValue() is used to obtain the minimum value of the CT_TIS_PIXEL_CLOCK control PixelClock_max_getValue() gets the maximum value of the CT_TIS_PIXEL_CLOCK control PixelClock_setValue(... ) sets the value of the CT_TIS_PIXEL_CLOCK control. LAN-057e_1 11/12

5 Video Data Transfer The transfer of the video data of the USB-CAM camera series is based on the UVC standard. Every image is transferred using exactly one block with this payload header (please note it is always two bytes long): struct tpayloadheaderbase enum tuvcpayloadheaderflags uvc_fid = 0x1, uvc_eof = 0x2, BYTE len; // header BYTE bfh; // header BYTE[] data; Usually, the image device provides the size of the block. Please note that the USB-CAM cameras do not provide valid data upon such a request. Therefore, please calculate its size using the following function: unsigned int calcmaxtransfersize(const uvc::videostreamingcontrol& ctrl, unsigned int bisizeimage ) unsigned int input_frame_size = bisizeimage; unsigned int max_transfer_size = ctrl.dwmaxpayloadtransfersize; if( max_transfer_size > (input_frame_size + 2) ) max_transfer_size = input_frame_size + 2; return max_transfer_size; 6 References [1] USB Implementers Forum: Universal Serial Bus Device Class Definition for Video Devices - Revision 1.1. June 1, 2005 [2] Universal Serial Bus Specification - Revision 2.0. April 27, 2000 12/12 LAN-057e_1