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 descriptor `8` - 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 address `mask` - 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 modified `data` - 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` - Reserved `1` - HDR mode `0` - RAW mode	`1` - chose between HDR(`1`) or linear (`0`) sensor mode `0` - select RAW mode (`1`) or Processed Video (`0`) for video pipeline N.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

Name	Offset	wIndex	wValue	Access type	Byte length	Return buffer bits	Notes
Sysinfo	`0xA8`	data structure version: `1` for FX3 vv.52-59 `2` for FX3 v.60+)	bitmask of additional checks to perform: `0` - check memory integrity `1` - check DMA integrity `2` - FX3 v60+: reinit FPGA and/or sensor if needed `3`-`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`

0xA8

data structure version:
1 for FX3 vv.52-59
2 for FX3 v.60+)

bitmask of additional checks to perform:
0 - check memory integrity
1 - check DMA integrity
2 - FX3 v60+: reinit FPGA and/or sensor if needed
3-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	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 ID `28:24` HW_CFG_ID `23:16` Product ID `15:11` Release type `10: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 ID `28:24` HW_CFG_ID `23:16` Product ID `15:11` Release type `10: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`	`15:8` - table `7:0` - starting index	`15:8` - version `7: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)¹⁾ `100` - Lightness vs. Lightness (`12` bits) `101` - Hue vs. Lightness (`12` bits)²⁾ `110-111` - reserved Starting 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	`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 Implemented in v.115

0xB3-0xB7

Name	Offset	wIndex	wValue	Access type	Byte length	Return buffer bits	Notes
Reserved	`0xB3`
Reserved	`0xB4`
Reserved	`0xB5`
Reserved	`0xB6`
Reserved	`0xB7`

0xB8

Name	Offset	wIndex	wValue	Access type	Byte length	Return buffer bits	Notes
FPGA stats	`0xB8`	statistics type	0	RO	see notes	see notes	Read out various stats from FPGA, see table below for details (FX3 v.`59`+, FPGA v.`74`+)

FPGA stats' details

Name	Value	Return type	Notes
MIPI FPS	`0x01`	float	IEEE float32 format, x86 LE number derived from MIPI-observed time between first pixel output of two consecutive video frames received by FPGA

0xB9

Name	Offset	wIndex	wValue	Access type	Byte length	Return buffer bits	Notes
Reserved	`0xB9`

0xBA - SDI control

Name	Offset	wIndex	wValue	Access type	Byte length	Return buffer bits	Notes
Reserved	`0xBA`	0	1	R/W	1	0 - SDI on/off	SDI control, for now only on/off with the default video mode of 1080p@60fps 10bit YUV `4:2:0` packed

0xBB-0xBF

Name	Offset	wIndex	wValue	Access type	Byte length	Return buffer bits	Notes
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 128MB or 256MB) 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` - poll `1` - 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	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	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` - reserved `1` - get the struct	version: `0`..`58` - reserved `60` - FX3 v.59 `90` - 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`

¹⁾ , ²⁾

scheduled for later

SUB2r

User Tools