This is an old revision of the document!
Preface
SUB2r camera is built on a Cypress FX3 chipset that facilitates the Super-Speed USB 3.0+
communication between the device and a host system. Every component of the camera, be it an FPGA or an image sensor, receives user commands via that Cypress FX3.
On Windows the device is registered with a GUID {36FC9E60-C465-11CF-8056-444553540000}
and if you are not planning on using the SUB2r-lib
for your development - that would be the GUID to search for to properly connect to the command channel.
Whether you use SUB2r-lib
or not you need to install the provided driver for the OS to properly configure the device in order to be able to connect to its control endpoints.
Here's a sample code that shows how to send commands to both the FX3 Host
and to FPGA I²C bridge
. The code lacks error checking (for clarity) and this should go without saying that if you copy-paste it into your code you must add error handling :)
// set a new auto-functions' update interval to 2x the default // just issue the command directly to FX3's vendor request interface void setAUInterval(){ S2R::I2C fx3; fx3.open(0); fx3.vrCmd(S2R::FX3::af_au_period, S2R::FX3::write, 6000, 0); } // run DPC calibration - also just a straight-up vendor request command to FX3 void runDPC(UCHAR _threshold = 240){ S2R::I2C fx3; fx3.open(0); fx3.vrCmd(S2R::FX3::calibrate_dpc, S2R::FX3::write, _threshold, 0); } // increase LED's green brightness by 25% // utilize the FPGA's I²C bridge void lightUpTheGreen() { using Cmd = S2R::FX3::Fx3Cmd; using OpType = S2R::FX3::VrCmdOpType; S2R::FX3 fx3; // `S2R::I2C fx3;` works as well fx3.open(0); uint8_t buf[1]{0}; const uint16_t clrChannel{0x0A}; // LED green fx3.vrCmd(Cmd::i2c_bridge, OpType::read, 0, clrChannel, buf, 1); buf[0] += buf[0] / 4; // yes, this can totally overflow fx3.vrCmd(Cmd::i2c_bridge, OpType::write, buf[0], clrChannel); }
FX3 API Reference
The following tables provide information on how to access the camera's functionality for FX3 Host Vendor Command Interface
. The address space is split into smaller chunks, grouped by common functionality:
0x00-0x9F
Name | Offset | wIndex | wValue | Access type | Byte length | Return buffer bits | Notes |
---|---|---|---|---|---|---|---|
Reserved | 0x00 -0x9F | Think of this as “system address space” |
0xA0-0xA7
Name | Offset | wIndex | wValue | Access type | Byte length | Return buffer bits | Notes |
---|---|---|---|---|---|---|---|
Bootloader check | 0xA0 | R/W | Check if a bootloader is running, the result is in the command's status code (success/failure interpreted as true /false ) |
||||
MS OS Descr. | 0xA1 | bits 3:0 - see notes | R/O | 174 | MS OS Platform Descriptor | For details on the structure and valid parameters' values refer to Microsoft's documentation for Microsoft OS 2.0 Descriptors Specification The 4 LSB of the wIndex field are the descriptor's index. Valid values are:7 - MS OS 2.0 descriptor8 - MS OS 2.0 set alternative enumeration (currently not supported) |
|
Run DPC calibration | 0xA2 | DPC Threshold | W/O | Start the dynamic DPC calibration with the given DPC Threshold in range [0..255] | |||
Reserved | 0xA3 | ||||||
FPGA I²C Bridge | 0xA4 | FPGA register offset | FPGA data (write) | R/W | 0 or 1 | 7:0 - FPGA data | FPGA write returns 0 byte buffer, FPGA read returns 1 byte buffer. Read/write is requested via control endpoint's direction attribute being set to DIR_FROM_DEVICE /DIR_TO_DEVICE .For details on individual commands refer to FPGA I²C bridge |
Sensor I²C bridge (8-bit configuration registers) | 0xA5 | [15:0 ] - sensor register address | mask and data (if writing) - see Notes column for details | R/W | 0 or 1 | 7:0 - sensor register's data | register - a 16 bit register addressmask - an 8-bit MSB that specifies which bits to affect during a write operation - only the bits that are set in mask will be affected by bits in data . Setting mask to 0 ultimately turns a write operation into a read one as no bits are getting modifieddata - an 8-bit LSB that specifies the new data to write into sensor's register. The write only affects the bits that are set in mask Read operation returns an 8-bit register's value Read/write is requested via control endpoint's direction attribute being set to DIR_FROM_DEVICE /DIR_TO_DEVICE .For details on each sensor's register's function refer to the sensor's specification |
Reserved for future I²C bridge | 0xA6 | ||||||
Video Mode Select | 0xA7 | R/W | 1 | 7:2 - Reserved1 - HDR mode0 - RAW mode | 1 - chose between HDR(1 ) or linear (0 ) sensor mode0 - select RAW mode (1 ) or Processed Video (0 ) for video pipelineN.B. “Raw mode” has been moved here from 0xA5 in FX3 version 46 |
0xA8-0xA9 - sysinfo
Name | Offset | wIndex | wValue | Access type | Byte length | Return buffer bits | Notes |
---|---|---|---|---|---|---|---|
Sysinfo | 0xA8 | data structure version:1 for FX3 vv.52-592 for FX3 v.60+) | bitmask of additional checks to perform:0 - check memory integrity1 - check DMA integrity2 - FX3 v60+: reinit FPGA and/or sensor if needed3 -7 : reserved | R/O | V1: 39 V2: 54 | struct SysInfoV1 struct SysInfoV2 | Get various internal system info on the guts of the RTOS and the firmware running on FX3, as well as overall configuration and health check results. Returned bytes: Version 1 (FX3 #52): SysInfoV1 Version 2 (FX3 #60): SysInfoV2 |
Reserved | 0xA9 |
0xAA-0xAF - versioning and reprogramming
Name | Offset | wIndex | wValue | Access type | Byte length | Return buffer bits | Notes |
---|---|---|---|---|---|---|---|
Erase SPI Flash | 0xAA | W/O | Any write to this location invalidates the FX3 SPI Flash and causes the FX3 to reset itself to a bootloader mode for reprogramming | ||||
FX3 version | 0xAB | R/O | 4 | 31:29 Vendor ID28:24 HW_CFG_ID23:16 Product ID15:11 Release type10:0 Build number | Get detailed version information of the FX3, for more details refer to FX3 Version Info | ||
FPGA version | 0xAC | R/O | 4 | 31:29 Vendor ID28:24 HW_CFG_ID23:16 Product ID15:11 Release type10:0 Build number | Get detailed version information of the FPGA, for more details refer to FPGA Version Info | ||
FPGA config. ctrl. | 0xAD | W/O | Any write to this location will put the FPGA into configuration mode | ||||
FPGA config. status - SPI codes | 0xAE | R/O | 2 | see below for details | Retrieve detailed status of the FPGA configuration operation | ||
SPI Flash write enable | 0xAF | W/O | Reconfigure the FX3 IOMatrix to disable GPIF and enable SPI to be re-written |
FPGA config status - SPI codes
Bit name | Description |
---|---|
15 Program SwitchWord OK | |
14 Verify OK | Verification succeeded |
13 Program OK | Programming completed successfully |
12 Erase OK | SPI erase was successful |
11 Erase SwitchWord OK | |
10 Check ID OK | |
9 Initialize OK | |
8 Config started | Config operation has started |
7 CRC error | |
6 Timeout error | |
5 Program error | Error while programming the SPI |
4 Erase error | Encountered an error while erasing SPI |
3 IdCode error | |
2 Config error | Configuration operation errored out |
1 Config done | Configuration operation is complete |
0 Config not busy | Set to 1 while the config is not busy |
0xB0 - FPS control
Name | Offset | wIndex | wValue | Access type | Byte length | Return buffer bits | Notes |
---|---|---|---|---|---|---|---|
FPS | 0xB0 | R/W | 4 | float32 FPS | FPS value is in IEEE float32 format, x86 LE and is exchanged in data phase of the USB control request (both IN and OUT) |
0xB1 - Bulk color grading
Name | Offset | wIndex | wValue | Access type | Byte length | Return buffer bits | Notes |
---|---|---|---|---|---|---|---|
Bulk color grading | 0xB1 | 7:4 - table3:0 - starting index | 7:4 - version4:0 - count | R/W | count x 2 | Currently only version 1 is supported.The table is a value from this list: 000 - Hue vs. Hue (14 bits)001 - Hue vs. Saturation (12 bits )010 - Lightness vs. Saturation (12 bits)011 - Saturation vs. Saturation (12 bits)1)100 - Lightness vs. Lightness (12 bits)101 - Hue vs. Lightness (12 bits)2)110-111 - reservedStarting index is a 0-based offset of the first written/read color grading value Version is currently 1 Count - how many entries to write/read The buffer is exchanged in data phase of the USB control request (both IN/OUT) |
0xB2 - Color correction matrix (a.k.a. CCM or CMX)
See Color correction matrix article in this Wiki's ISP section for more details.
Name | Offset | wIndex | wValue | Access type | Byte length | Return buffer bits | Notes |
---|---|---|---|---|---|---|---|
Color correction matrix (needs actual implementation in FX3) | 0xB2 | 0 | 0x0303 | R/W | 32 | packed C-array float[3][3] | That data buffer could also be defined as float[9] or as byte* for the same exact memory layout on LE systems |
0xB3-0xBF
Name | Offset | wIndex | wValue | Access type | Byte length | Return buffer bits | Notes |
---|---|---|---|---|---|---|---|
Reserved | 0xB3 | ||||||
Reserved | 0xB4 | ||||||
Reserved | 0xB5 | ||||||
Reserved | 0xB6 | ||||||
Reserved | 0xB7 | ||||||
Reserved | 0xB8 | ||||||
Reserved | 0xB9 | ||||||
Reserved | 0xBA | ||||||
Reserved | 0xBB | ||||||
Reserved | 0xBC | ||||||
Reserved | 0xBD | ||||||
Reserved | 0xBE | ||||||
Reserved | 0xBF |
0xC0-0xC1
Name | Offset | wIndex | wValue | Access type | Byte length | Return buffer bits | Notes |
---|---|---|---|---|---|---|---|
Reserved | 0xC0 | ||||||
Reserved | 0xC1 |
0xC2-0xC4 - SPI flash management
The SPI flash memory (either 128
MB or 256
MB) is partitioned into 65KB sectors, each comprised of 256
pages. Each page is 256
bytes long.
Name | Offset | wIndex | wValue | Access type | Byte length | Return buffer bits | Notes |
---|---|---|---|---|---|---|---|
SPI flash write page | 0xC2 | 16:0 page address | W/O | 256 | write a page of SPI flash (same command as Cypress' examples). The flash page size is fixed to 256 bytes |
||
SPI flash read page | 0xC3 | 16:0 page address | R/O | 256 | page's content | read a page of SPI flash (same command as Cypress' examples). The flash page size is fixed to 256 bytes |
|
SPI flash sector erase/poll | 0xC4 | 7:0 - sector | 0 - poll1 - erase | R/W | either erase a SPI flash sector, or poll SPI busy status (same command as Cypress' examples) sector's byte address is computed by multiplying wIndex by 65536 For Erase SPI flash sector function: - wValue = 0x0001 - wIndex = SPI flash sector address - wLength = 0x0000 No data phase associated with this command For Check SPI busy status function: - wValue = 0x0000 - wIndex = 0x0000 - wLength = 0x0001 Data phase indicates flash busy status: - 0x00 means SPI flash has finished write/erase operation- non-zero value means that SPI flash is still busy processing previous write/erase command. |
0xC5-0xCB
Name | Offset | wIndex | wValue | Access type | Byte length | Return buffer bits | Notes |
---|---|---|---|---|---|---|---|
Reserved | 0xC5 | ||||||
Reserved | 0xC6 | ||||||
Reserved | 0xC7 | ||||||
Reserved | 0xC8 | ||||||
Reserved | 0xC9 | ||||||
Reserved | 0xCA | ||||||
Reserved | 0xCB |
0xCC - FPGA temperature sensor
Name | Offset | wIndex | wValue | Access type | Byte length | Return buffer bits | Notes |
---|---|---|---|---|---|---|---|
FPGA core temperature (still needs to be implemented) | 0xCC | R/O | FPGA temperature read from the on-board sensor (not implemented yet) |
0xCD-0xCF
Name | Offset | wIndex | wValue | Access type | Byte length | Return buffer bits | Notes |
---|---|---|---|---|---|---|---|
Reserved | 0xCD | ||||||
Reserved | 0xCE | ||||||
Reserved | 0xCF |
0xD0-0xD7 - Auto exposure configuration
Name | Offset | wIndex | wValue | Access type | Byte length | Return buffer bits | Notes |
---|---|---|---|---|---|---|---|
AE Setpoint | 0xD0 | AE Setpoint | R/W | 0 or 1 | 7:0 AE Setpoint | Target Auto Exposure Luminance Setpoint [0..255] Default: 105 This controls the “average luminance” of the whole frame that we are trying to achieve. The higher the value the brighter the result is going to be |
|
deprecated AE Hysteresis | 0xD1 | AE Hysteresis | R/W | 0 or 2 | 15:0 AE Hysteresis | Auto Exposure Hysteresis Value UFIX 8.8 Default 3.0 This controls how far can we diverge from the set target luminance before we begin the correction. In other words the higher this value the further we allow the luminance to drift away from the target before correcting it |
|
deprecated AE Error Tolerance | 0xD2 | AE Err Tol | R/W | 0 or 2 | 15:0 AE Err Tol | Auto Exposure Error Tolerance Value UFIX 8.8 Default 1.0 Specifies the “close enough” tolerance at which point the correction can be stopped. Normally this value is (at least somewhat) lower than the AE Hysteresis |
|
deprecated AE Exposure Scaling | 0xD3 | AE Exp Scale | R/W | 0 or 2 | 15:0 AE Exp Scale | Auto Exposure Exposure Scaling Value UFIX 8.8 Default 100.0 Controls the speed (stepping) at which the correction is happening. Higher values will result in large brightness jumps and a value too high may cause an oscillation while a value that is too low will cause the correction process to be too slow and seamingly unresponsive |
|
deprecated AE C Gain Divisor | 0xD4 | AE C Gain Divisor | R/W | 0 or 2 | 15:0 AE C Gain Divisor | Auto Exposure C Gain Divisor Value UFIX 8.8 Default 4.0 Value between 0 and 255 that is inversely proportional to the rate at which the C gain is adjusted in response to exposure errors. (i.e. the larger the value, the slower C gain will adjust) |
|
Reserved | 0xD5 | ||||||
Reserved | 0xD6 | ||||||
Reserved | 0xD7 |
0xD8-0xDE - Auto white balance configuration
Name | Offset | wIndex | wValue | Access type | Byte length | Return buffer bits | Notes |
---|---|---|---|---|---|---|---|
AWB Setpoint | 0xD8 | AWB Setpoint | R/W | 0 or 2 | 15:0 AWB Setpoint | Auto White Balance G Gain Setpoint [0..2047] Default 1024 The pinned value for Green Gain that is used as the basis for the rest of the white balance adjustments. Only change this value if you need to make your picture brighter and you have exhausted both the Exposure and the Global Gain options |
|
deprecated AWB Hysteresis | 0xD9 | AWB Hysteresis | R/W | 0 or 2 | 15:0 AWB Hysteresis | Auto White Balance Hysteresis Value UFIX 8.8 Default 3.0 How far can the error drift before we start adjusting it |
|
deprecated AWB Error Tolerance | 0xDA | AWB Err Tol | R/W | 0 or 2 | 15:0 AWB Err Tol | Auto White Balance Error Tolerance Value UFIX 8.8 Default 1.0 A.k.a. “good enough” approximation - controls when we stop the correction process, having achieved a “close enough” result. Generally this setting is at least somewhat lower than the AWB Hysteresis value |
|
deprecated AWB Adjustment Scaling | 0xDB | AWB Adj Scale | R/W | 0 or 2 | 15:0 AWB Adj Scale | Auto White Balance Adjustment Scaling Value UFIX 8.8 Default 4.0 Value between 0 and 255 that is inversely proportional to the rate at which the R and B gains are adjusted in response to white balance errors. (i.e. the larger the value, the slower R and B gains will adjust) |
|
Reserved | 0xDC | ||||||
Reserved | 0xDD | ||||||
Reserved | 0xDE |
0xDF - Auto-functions' timing
Name | Offset | wIndex | wValue | Access type | Byte length | Return buffer bits | Notes |
---|---|---|---|---|---|---|---|
Auto Update Period | 0xDF | Auto Update Period | R/W | 0 or 2 | 15:0 Auto Update Period | Auto Update Period [0..65535]) Default 17 Determines how long we wait before trying to apply a new update for both exposure and white balance (when auto functions are enabled), as well as other up-keep operations, like pushing data over I²C bus. This is an asynchronous update rate. That value is approximately in milliseconds |
0xE0 - FX3 reset
Name | Offset | wIndex | wValue | Access type | Byte length | Return buffer bits | Notes |
---|---|---|---|---|---|---|---|
FX3 reset | 0xE0 | W/O | Cypress vendor command to soft reset FX3 |
0xE1-0xEF
Name | Offset | wIndex | wValue | Access type | Byte length | Return buffer bits | Notes |
---|---|---|---|---|---|---|---|
Reserved | 0xE1 | ||||||
Reserved | 0xE2 | ||||||
Reserved | 0xE3 | ||||||
Reserved | 0xE4 | ||||||
Reserved | 0xE5 | ||||||
Reserved | 0xE6 | ||||||
Reserved | 0xE7 | ||||||
Reserved | 0xE8 | ||||||
Reserved | 0xE9 | ||||||
Reserved | 0xEA | ||||||
Reserved | 0xEB | ||||||
Reserved | 0xEC | ||||||
Reserved | 0xED | ||||||
Reserved | 0xEE | ||||||
Reserved | 0xEF |
0xF0-0xF9
Name | Offset | wIndex | wValue | Access type | Byte length | Return buffer bits | Notes |
---|---|---|---|---|---|---|---|
Reserved | 0xF0 | ||||||
Reserved | 0xF1 | ||||||
Reserved | 0xF2 | ||||||
Reserved | 0xF3 | ||||||
Reserved | 0xF4 | ||||||
Reserved | 0xF5 | ||||||
Reserved | 0xF6 | ||||||
Reserved | 0xF7 | ||||||
Reserved | 0xF8 | ||||||
Reserved | 0xF9 |
0xFA - [Debug] Get raw descriptor
Name | Offset | wIndex | wValue | Access type | Byte length | Return buffer bits | Notes |
---|---|---|---|---|---|---|---|
Get raw descriptor | 0xFA | command (see below) | struct to return | R/O | varies by command (see below) | struct's byte buffer | See below for details |
List of commands supported by this API:
Cmd (wIndex) | Meaning |
---|---|
0 | get a 2-byte descriptive text label's length (not including the C-style null-terminator) |
1 | get descriptive text label (up to 4096 bytes without a C-style null-terminator) |
2 | get a 2-byte size of the structure in bytes |
3 | get structure's byte buffer |
As of FX3 version 58
the following internal structures are supported:
Index (wValue) | Details |
---|---|
0 | reserved (unused) |
1 | USB device descriptor 2.0 |
2 | USB device descriptor 3.0 |
3 | USB Device Qualifier descriptor |
4 | USB BOS (Binary Object Store) descriptor |
5 | Full-Speed (2.0) USB Configuration descriptor |
6 | High-Speed (2.0) USB Configuration descriptor |
7 | Super-Speed (3.0) USB Configuration descriptor |
8 | MS OS Platform Capability descriptor version 2.0 |
0xFB - Get internal state
Name | Offset | wIndex | wValue | Access type | Byte length | Return buffer bits | Notes |
---|---|---|---|---|---|---|---|
Get internal state | 0xFB | command:0 - reserved1 - get the struct | version:0 ..58 - reserved60 - FX3 v.5990 - FX3 v.60 | RO | 84 | CachedGlobalState | for the actual definitions see: v59 - CachedGlobalStatus_v0x01 v60 - CachedGlobalStatus_v0x02 |
0xFC - OS runtime info
Name | Offset | wIndex | wValue | Access type | Byte length | Return buffer bits | Notes |
---|---|---|---|---|---|---|---|
OS runtime info, v.60+ | 0xFC | see below | see below | R/O | see below | see below | Query for OS internal info. A type of query is specified in wValue field and, along with other fields, is described in the table below |
wValue | wIndex | Description |
---|---|---|
0 | get number of user trheads | |
1 | 0-based thread's index | get info on the thread, see struct OsThreadInfo for details |
0xFD-0xFF - Reserved for debug APIs
Name | Offset | wIndex | wValue | Access type | Byte length | Return buffer bits | Notes |
---|---|---|---|---|---|---|---|
Reserved | 0xFD | ||||||
Reserved | 0xFE | ||||||
Reserved | 0xFF |
FPGA I²C bridge (registers' map)
The following tables provide information on how to access the camera's functionality for an FPGA I²C bridge.
Here's a sample code (skipping all error checking) that sets the LED to bright-yellow color:
S2R::FX3 dev; // auto-open device #0 using S2R::FX3; dev.vrCmd(FX3Cmd::i2c_bridge, VrCmdOpType::write, 255, 0x08); // red dev.vrCmd(FX3Cmd::i2c_bridge, VrCmdOpType::write, 255, 0x0A); // green dev.vrCmd(FX3Cmd::i2c_bridge, VrCmdOpType::write, 0, 0x0C); // blue
The address space is broken down into smaller chunks, grouped by common functionality:
0x00-0x07 - FPGA general access
Name | Offset | Access | Bit mapping | Notes |
---|---|---|---|---|
FPGA Version #0 | 0x00 | R/O | 7:5 Vendor ID4:0 HW_CFG_ID | |
FPGA Version #1 | 0x01 | R/O | 7:0 Product ID | |
FPGA Version #2 | 0x02 | R/O | 7:3 Release type2:0 Build number MSB | Build number is split into 2 MSB and 8 LSB for a combined total width of 10 bits |
FPGA Version #3 | 0x03 | R/O | 7:0 Build number LSB |
|
FPGA config status #0 | 0x04 | R/O | see SPI codes for details | LSB (bits 7 -0 ) of the FPGA config status |
FPGA config status #1 | 0x05 | R/O | see SPI codes for details | MSB (bits 15 -8 ) of the FPGA config status |
FPGA control | 0x06 | R/W | Global control of the FPGA's functionality | |
7 FPGA config enable | If bit 7 is set, the GPIF becomes read only and waits for an update bitstream |
|||
6 on-board fan | (FPGA-72+) 1 turns the on-board fan on, 0 turns it off |
|||
5 RAW Mode | Setting bit 5 and clearing bit 0x06::2 will enable RAW mode output (4K Only) |
|||
4 Video Format | Bit 4 selects between NV12 ('1') and YUY2 ('0') output formats |
|||
3 DPC enable | Setting bit 3 along with bit 0x06::0 will perform a DPC correction |
|||
2 | 2 is to enable/disable Horizontal Subsampling |
|||
1 Audio enable | Bit 1 is to enable/disable on-board microphones |
|||
0 Video enable | Bit 0 enables/disables video streaming |
|||
FPGA core temperature | 0x07 | R/O | 7:0 - temperature in Farenheits | Reading of the FPGA's internal temperature sensor in degrees of Farenheits |
0x08-0x0D - LED
Name | Offset | Access | Bit mapping | Notes |
---|---|---|---|---|
LED_RED_L | 0x08 | R/W | 7:0 Red LED | LSB of LED's red intensity in range [0..255] |
LED_RED_H | 0x09 | R/W | Reserved | |
LED_GREEN_L | 0x0A | R/W | 7:0 Green LED | LSB of LED's green intensity in range [0..255] |
LED_GREEN_H | 0x0B | R/W | Reserved | |
LED_BLUE_L | 0x0C | R/W | 7:0 Blue LED | LSB of LED's blue intensity in range [0..255] |
LED_BLUE_H | 0x0D | R/W | Reserved |
0x0E-0x0F - Noise Reduction
Name | Offset | Access | Bit mapping | Notes |
---|---|---|---|---|
Chroma NR Control | 0x0E | R/W | 7 Reserved, must be 0 6:0 value | Chroma (color or an \(H\) component of the \(H/S/L\) pixel data) noise reduction in range \([0\%..100\%]\) mapped into \([0..127]\). Setting this to 0 effectively turns the chroma denoising off |
Luma NR Control | 0x0F | R/W | 7 Reserved, must be 0 6:0 value | Luma (brightness or an \(L\) component of the \(H/S/L\) pixel data) noise reduction in range \([0\%..100\%]\) mapped into \([0..127]\). Setting this to 0 effectively turns the luma denoising off |
0x10-0x1F - Basic UVC controls
Name | Offset | Access | Bit mapping | Notes |
---|---|---|---|---|
Brightness_L | 0x10 | R/W | 7:0 LSB | 16 bits of brightness are split into 8 bits of LSB and MSB |
Brightness_H | 0x11 | R/W | 7:0 MSB |
|
Contrast_L | 0x12 | R/W | 7:0 LSB | 16 bits of contrast are split into 8 bits of LSB and MSB |
Contrast_H | 0x13 | R/W | 7:0 MSB |
|
Saturation_L | 0x14 | R/W | 7:0 LSB | 16 bits of saturation are split into 8 bits of LSB and MSB |
Saturation_H | 0x15 | R/W | 7:0 MSB |
|
Sharpness_L | 0x16 | R/W | 7:0 LSB | 16 bits of sharpness are split into 8 bits of LSB and MSB |
Sharpness_H | 0x17 | R/W | 7:0 MSB |
|
Gamma_L | 0x18 | R/W | 7:0 LSB | 16 bits of gamma are split into 8 bits of LSB and MSB |
Gamma_H | 0x19 | R/W | 7:0 MSB |
|
Hue_L | 0x1A | R/W | 7:0 LSB | 16 bits of hue are split into 8 bits of LSB and MSB |
Hue_H | 0x1B | R/W | 7:0 MSB |
|
Reserved | 0x1C | |||
Reserved | 0x1D | |||
Reserved | 0x1E | |||
Reserved | 0x1F |
0x20-0x27 - Defective pixel cancellation
Name | Offset | Access | Bit mapping | Notes |
---|---|---|---|---|
DPC Threshold LSB | 0x20 | R/W | 7:0 LSB | 16 bit of DPC Threshold are split into 8 bits of LSB and MSB |
DPC Threshold MSB | 0x21 | R/W | 7:0 MSB |
|
DPC count LSB | 0x22 | R/O | 7:0 LSB | Once the DPC calibration is done the 16-bit value is stored in these 2 registers |
DPC count MSB | 0x23 | R/O | 7:0 MSB |
|
Grey threshold | 0x24 | R/W | 7:0 | If the full range of incoming \(R,G,B\) triplet is up to that number (inclusive), force both the \(H\) and \(S\) to be 0 |
Reserved | 0x25 | |||
Reserved | 0x26 | |||
Reserved | 0x27 |
0x28-0x3F - General image statistics
Name | Offset | Access | Bit mapping | Notes |
---|---|---|---|---|
Y average | 0x28 | R/O | 7:0 value | |
flags | 0x29 | R/O | 7:0 value | flags for OverExposure and SFP+ cage device. The following bits are currently defined:7:3 - reserved2 - set to 1 if there is an active device in SFP+ cage 3)1 - indicates whether a red overexposure is detected0 - set if there is a general overexposure detected |
FPS_L | 0x2B | R/O | 7:0 LSB | 16-bit unsigned value representing number of 10μs units between frame start signals from the image sensor, e.g. a value of 1000 means it took 10ms between 2 frame start signals, which corresponds to 100FPS |
FPS_H | 0x2C | R/O | 7:0 MSB |
|
Reserved | 0x2D | |||
AWB Y limit | 0x2E | R/W | 7:0 value | Lower bound brightness threshold for pixels to qualify for AWB statistic counter, default value 100 |
AWB S limit | 0x2F | R/W | 7:0 value | Upper bound saturation threshold for pixels to qualify for AWB statistic counter, default value 10 |
Reserved | 0x30 | |||
AWB Red total counter | 0x33-0x31 | R/O | 24-bit value | 0x33 is MSB, 0x31 is LSB |
Reserved | 0x34 | |||
AWB Green total counter | 0x37-0x35 | R/O | 24-bit value | 0x37 is MSB, 0x35 is LSB |
Reserved | 0x38 | |||
AWB Blue total counter | 0x3B-0x39 | R/O | 24-bit value | 0x39 is MSB, 0x3B is LSB |
AWB total pixel counter | 0x3F-0x3C | R/O | 32-bit value | 0x3F is MSB, 0x3C is LSB |
0x40-0x45 - AWB adjustments
Name | Offset | Access | Bit mapping | Notes |
---|---|---|---|---|
AWB Red adjustment | 0x40 | R/W | 7:0 - value | a signed 8-bit value of an adjustment to apply to every pixel in Red channel. Default is 0 |
reserved | 0x41 | |||
AWB Green adjustment | 0x42 | R/W | 7:0 - value | a signed 8-bit value of an adjustment to apply to every pixel in Green channel. Default is 0 |
reserved | 0x43 | |||
AWB Blue adjustment | 0x44 | R/W | 7:0 - value | a signed 8-bit value of an adjustment to apply to every pixel in Blue channel. Default is 0 |
reserved | 0x45 |
0x46-0x4F - Media setup
Name | Offset | Access | Bit mapping | Notes |
---|---|---|---|---|
Media output modules | 0x46 | R/W | 7 - res6 - res (headphones)5 - res (UAC)4 - res3 - res2 - SDI video1 - SFP+ video0 - UVC | Enable/disable state of individual media output modules for video and audio streams |
Video transform blocks | 0x47 | R/W | 7 - res (sharpness)6 - res5 - res4 - res3 - res2 - HSL pipeline1 - CCM0 - res (UVC Gamma) | Enable/disable individual transformation blocks in video pipeline |
Video output format | 0x48 | R/W | 7 - res6:3 - UVC2:0 - SDI | Bit depth for all video formats is set in register 0x49 UVC video formats: 0 - “RAW” greyscale pre-debayer pixels1 - 4:4:4 RGB2 - res (packed YCbCr 4:4:4)3 - packed YCbCr 4:2:24 - res (packed YCbCr 4:2:0)5 - res (planar YCbCr 4:4:4)6 - res (planar YCbCr 4:2:2)7 - planar YCbCr 4:2:08-15 - res (MJPEG, H.26x, etc)SDI and SFP+ video output formats are always in unison: 0 - res1 - res (4:4:4 RGB)2 - res (packed YCbCr 4:4:4)3 - res (packed YCbCr 4:2:2)4 - packed YCbCr 4:2:05 - res (planar YCbCr 4:4:4)6 - res (planar YCbCr 4:2:2)7 - res (planar YCbCr 4:2:0) |
Video output pixel bit depth | 0x49 | R/W | 7:6 - res5:4 - SDI3:2 - SFP+1:0 - UVC | Pixel bit depths \(d_p\) is calculated from a 2-bit value \(N\) as: \[d_p = (N+4)*2\] |
MIPI configuration | 0x4A | R/W | 7:2 - res1:0 - MIPI bit depth | MIPI bit depth controls the data packing format for the pixels coming through MIPI interface. MIPI bit depth \(d_p\) is calculated from a 2-bit value \(N\) as: \[d_p = (N+4)*2\] |
Reserved | 0x4B | |||
Audio transform blocks | 0x4C | R/W | 7:0 - res | Enable/disable individual transformation blocks in audio pipeline |
Reserved | 0x4D | |||
Reserved | 0x4E | |||
Reserved | 0x4F |
FOURCC formats
A combination of data in 0x49[1:0]
(pixel bit depth) and 0x48[6:3]
(video format) is mapped into standard FOURCC codes as summarized in the following table:
0x50-0x5F - Reserved
Name | Offset | Access | Bit mapping | Notes |
---|---|---|---|---|
Reserved | 0x50 -0x5F |
0x60-0x6F - Reserved
Name | Offset | Access | Bit mapping | Notes |
---|---|---|---|---|
Reserved | 0x60 -0x6F |
0x70-0x7F - Reserved
Name | Offset | Access | Bit mapping | Notes |
---|---|---|---|---|
Reserved | 0x70 -0x7F |
0x80-0xBF - Green Screen enhancer
“Green screen”, a.k.a. “Chroma Key” on-board optimization is designed to replace a range of colors with a single solid one
0x80-0x8F - band #0
If enabled these setting take precedence over other 3 bands
Name | Offset | Access | Bit mapping | Notes |
---|---|---|---|---|
CK control | 0x80 | R/W | 7:1 reserved0 enable | enable/disable Chroma Key control |
CK status | 0x81 | reserved | ||
CK saturation min | 0x82 | R/W | 7:0 sat. min | [0..255] to specify the minimum saturation threshold |
CK saturation max | 0x83 | R/W | 7:0 sat. max | [0..255] to specify the maximum saturation threshold |
CK luma min | 0x84 | R/W | 7:0 luma min | [0..255] to specify the minimum brightness threshold |
CK luma max | 0x85 | R/W | 7:0 luma max | [0..255] to specify the maximum brightness threshold |
CK hue LSB | 0x86 | R/W | 7:0 hue LSB | 14 bits of a signed hue value are split into 8 LSB and 6 MSB, its [-8K..+8K] range is mapped into [-180°..+180°] |
CK hue MSB | 0x87 | R/W | 7:6 reserved5:0 hue MSB |
|
CK tolerance LSB | 0x88 | R/W | 7:0 tolerance LSB | 13 bits of an unsigned hue tolerance value are split into 8 LSB and 5 MSB, valid range is [0..8K], which is mapped into [0°..180°]. That value specifies how far to stretch the CK hue value both ways (symmetrically). If the CK tolerance is above 90° the covered color space is over 50% of values |
CK tolerance MSB | 0x89 | R/W | 7:5 reserved4:0 tolerance MSB |
|
CK red LSB | 0x8A | R/W | 7:0 red LSB | |
CK red MSB | 0x8B | R/W | reserved | |
CK green LSB | 0x8C | R/W | 7:0 green LSB | |
CK green MSB | 0x8D | R/W | reserved | |
CK blue LSB | 0x8E | R/W | 7:0 blue LSB | |
CK blue MSB | 0x8F | R/W | reserved |
0x90-0x9F - band #1
Color substitution (if enabled) takes place after the first band had a chance to process the pixels
The layout of the settings is identical to that of band #0 just shifted down by a paragraph and occupying address block 0x90-0x9F
0xA0-0xAF - band #2
Color substitution (if enabled) takes place after the first and second bands had a chance to process the pixels
The layout of the settings is identical to that of band #0 just shifted down by 2 paragraphs and occupying address block 0xA0-0xAF
0xB0-0xBF - band #3
Color substitution (if enabled) takes place after other bands had a chance to process the pixels
The layout of the settings is identical to that of band #0 just shifted down by 3 paragraphs and occupying address block 0xB0-0xBF
0xC0-0xCF - Color grading
Name | Offset | Access | Bit mapping | Notes |
---|---|---|---|---|
switch | 0xC0 | W | Controls what information is being read/written by accessing the next set of registers (0xC2..0xC3 ) |
|
7:5 table switch | 000 - Hue vs. Hue (14 bits)001 - Hue vs. Saturation (12 bits )010 - Lightness vs. Saturation (12 bits)011 - Saturation vs. Saturation (12 bits)7)100 - Lightness vs. Lightness (12 bits)101 - Hue vs. Lightness (12 bits)8)110-111 - reserved |
|||
4:1 page | Reserved for a page number in the table, currently is always set to 0 |
|||
0 access mode | the only valid value right now is 0 , which is “normal mode”, in which all the subsequent access to the registers in this API block are governed by the values in 0xC0 and 0xC1 1 would be used for “bulk access” where after a read or write access to register 0xC2 the “Index” value will auto-increment by one so that the next pair will access the subsequent table slot |
|||
Index LSB | 0xC1 | W | 7:0 index LSB | index into a page in the table (we only use 6 bits today and the rest are ignored) |
Value L | 0xC2 | R/W | 7:0 LSB | 16 bits split into 8 LSB and 8 MSB - for a “Hue vs. Hue” table the 14 bits signed value is in range [-8192..+8192] which maps linearly into a Hue angle range -180°..+180° - for a “Hue vs. Saturation” table (as well as for similar tables LvS and SvS) the 12 bit unsigned value in range [0..+1280] maps linearly into a Saturation range [0%..1000%] where 100% is the neutral position and 0% produces a greyscale image- (until FPGA v.72) for a “Lightness vs. Lightness” table (as well as for similar table HvL) the 12 bit unsigned value in range [0..+4095] maps linearly into a Lightness absolute range [0..255] where 0 is pitch black and 255 is the maximum possible pixel luminosity value- (starting with FPGA v.73) for a “Lightness vs. Lightness” table (as well as for similar table HvL) the 13 bit signed value in range [-4096..+4095] maps linearly into a Lightness *relative* (adjustment) range [-256..255] where 0 is no adjustment to pixel luminosity value |
Value H | 0xC3 | R/W | 7:0 MSB |
|
Reserved | 0xC4 -0xCF |
0xD0-0xE1 - Color Correction Matrix (a.k.a. CCM or CMX)
See Color correction matrix article in this Wiki's ISP section for more details. The 16-bit (MSB-LSB) value is defined as 7+9 bits, where MSB[7:1] are the integer part and MSB[0]LSB[7:0] is the fractional part (effectively that value is 512 times larger than the original fractional part).
Name | Offset | Access | Bit mapping | Notes |
---|---|---|---|---|
CCM_00_L | 0xD0 | R/W | 7:0 LSB | \(CCM_{00}\) |
CCM_00_H | 0xD1 | R/W | 7:0 MSB |
|
CCM_01_L | 0xD2 | R/W | 7:0 LSB | \(CCM_{01}\) |
CCM_01_H | 0xD3 | R/W | 7:0 MSB |
|
CCM_02_L | 0xD4 | R/W | 7:0 LSB | \(CCM_{02}\) |
CCM_02_H | 0xD5 | R/W | 7:0 MSB |
|
CCM_10_L | 0xD6 | R/W | 7:0 LSB | \(CCM_{10}\) |
CCM_10_H | 0xD7 | R/W | 7:0 MSB |
|
CCM_11_L | 0xD8 | R/W | 7:0 LSB | \(CCM_{11}\) |
CCM_11_H | 0xD9 | R/W | 7:0 MSB |
|
CCM_12_L | 0xDA | R/W | 7:0 LSB | \(CCM_{12}\) |
CCM_12_H | 0xDB | R/W | 7:0 MSB |
|
CCM_20_L | 0xDC | R/W | 7:0 LSB | \(CCM_{20}\) |
CCM_20_H | 0xDD | R/W | 7:0 MSB |
|
CCM_21_L | 0xDE | R/W | 7:0 LSB | \(CCM_{21}\) |
CCM_21_H | 0xDF | R/W | 7:0 MSB |
|
CCM_22_L | 0xE0 | R/W | 7:0 LSB | \(CCM_{22}\) |
CCM_22_H | 0xE1 | R/W | 7:0 MSB |
0xE2-0xEF
Name | Offset | Access | Bit mapping | Notes |
---|---|---|---|---|
Reserved | 0xE2 | |||
Reserved | 0xE3 | |||
Reserved | 0xE4 | |||
Reserved | 0xE5 | |||
Reserved | 0xE6 | |||
Reserved | 0xE7 | |||
Reserved | 0xE8 | |||
Reserved | 0xE9 | |||
Reserved | 0xEA | |||
Reserved | 0xEB | |||
Reserved | 0xEC | |||
Reserved | 0xED | |||
Reserved | 0xEE | |||
Reserved | 0xEF |
0xF0-0xFF
Name | Offset | Access | Bit mapping | Notes |
---|---|---|---|---|
Reserved | 0xF0 | |||
Reserved | 0xF1 | |||
Reserved | 0xF2 | |||
Reserved | 0xF3 | |||
Reserved | 0xF4 | |||
Reserved | 0xF5 | |||
Reserved | 0xF6 | |||
Reserved | 0xF7 | |||
Reserved | 0xF8 | |||
Reserved | 0xF9 | |||
Reserved | 0xFA | |||
Reserved | 0xFB | |||
Reserved | 0xFC | |||
Reserved | 0xFD | |||
Reserved | 0xFE | |||
Reserved | 0xFF |
FX3 Version Info
The version id is also encoded into the firmware image file name as:
<VendorID>_<HardwareID>_<ProductID>_<ReleaseType>_<BuildNumber>
Vendor ID
Code | Value |
---|---|
1 | Cypress |
Hardware ID
Code | Value |
---|---|
1 | FX3 |
Product ID
Code | Value |
---|---|
1 | reserved for Gen 1 camera, a.k.a. “Moon landing” |
2 | reserved for Gen 2 camera, a.k.a. “Piggy” |
3 | Gen 3 camera (Alpha), a.k.a. “Frankie” (from Frankenstein's Monster) |
4 | Gen 3 camera, Production |
5 | Gen 4 camera, a.k.a. “REX” |
Release type
Code | Name | Meaning |
---|---|---|
0 | Private build | Private build for debugging and similar purposes |
1 | Alpha | feature-incomplete early development cycle “somewhat stable” build |
2 | Beta | feature-complete, but not very stable build (lots of bugs) |
3 | Evaluation | Tech preview |
4 | Release candidate | feature complete and stable |
5 | Release | general availability |
6 | Backport | backport of a feature from next gen camera |
7 | Emergency bug fix | a critical post-release bugfix |
Build number
Code | Value |
---|---|
# | Increments on each build |
FPGA Version Info
The version id is also encoded into the firmware image file name as:
<VendorID>_<HardwareID>_<ProductID>_<ReleaseType>_<BuildNumber>
Vendor ID
Code | Value |
---|---|
1 | Xilinx |
Hardware ID
Code | Value |
---|---|
1 | Artix-7 100T |
2 | Artix-7 200T |
3 | Artix UltraScale+ XCAU25P |
Product ID
Code | Value |
---|---|
1 | reserved |
2 | reserved |
3 | Gen 3 camera (Alpha), a.k.a. “Frankie” |
4 | Gen 3 camera, Production |
5 | Gen 4 camera, a.k.a. “REX” |
Release type
Code | Value |
---|---|
0 | Private build |
1 | Alpha |
2 | Beta |
3 | Eval/Tech preview |
4 | Release candidate |
5 | Release |
6 | Backport |
7 | Emergency bug fix |
Build number
Code | Value |
---|---|
# | Increments on each build |