This page describes FX3/FPGA API for Square1 and Studio (gen5) products.

For gen4 and earlier API see FX3/FPGA API spec up to REX.

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.

Here's a sample code that shows how to send commands to both the FX3 Host and to FPGA I²C bridge (registers' map). 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);
}

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:

This versatile API allows single/bulk access to an arbitrary device on I²C and supports 8, 16, 32-bit addressing and data. Single (non-bulk) access is always an immediate, non-cached execution while bulk access is always cached. For bulk operations the result is queried/polled until it is acquired or has failed.

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

The SPI flash memory (either \(128\)MB or \(256\)MB) is partitioned into \(65\)KB sectors, each comprised of \(256\) pages. Each page is \(256\) bytes long.

As of FX3 version 58 the following internal structures are supported:

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:

Info for performing Auto White-Balance adjustments on the image

Name	Offset	Bytes	Access	Notes
AWB Red adjustment	0x0008	2	R/W	a signed 16-bit value of an adjustment to apply to every pixel in Red channel. Default is \(0\)
AWB Green adjustment	0x0009	2	R/W	a signed 16-bit value of an adjustment to apply to every pixel in Green channel. Default is \(0\)
AWB Blue adjustment	0x000A	2	R/W	a signed 16-bit value of an adjustment to apply to every pixel in Blue channel. Default is \(0\)
Reserved	0x000B
AWB Red total	0x000C	4	R/O
AWB Green total	0x000D	4	R/O
AWB Blue total	0x000E	4	R/O
AWB count total	0x000F	4	R/O	A count of pixels that were used to calculate the \(R/G/B\) totals

A combination of data in 0x0033[1:0] (pixel bit depth) and 0x32[7:4] (video format) used for UVC is mapped into standard FOURCC codes as summarized in the following table:

0x0033[1:0]\0x0032[7:4]	0 (RAW)	1 (RGB)	2 (packed YUV 4:4:43))	3 (packed YUV 4:2:24))	7 (planar YUV 4:2:05))
0 (8 bit)	BA81/BYR1/GREY/Y8/Y800 (8bpp)	BI_RGB/RGB (24bpp)	Y444/IYU2 (24bpp)	YUY2/YUYV (16 bpp)	NV12 (12bpp)
1 (10 bit)	Y106) (16bpp7))	BI_BITFIELDS (48bpp)	Y410 (32bpp8))	Y210 (32bpp) YUVP?/Y42T (24bpp?)	P010 (32bpp)
2 (12 bit)	BYR2 (16pbb9))	BI_BITFIELDS (48bpp)	Y41210) (40bpp11))	Y21212) (32bpp13))	P01214) (32bpp15))
3 (14 bit)	Y1616) (16bpp17))	BI_BITFIELDS (48bpp)	Y41418) (48bpp19))	Y21420) (32bpp21))	P01422) (32bpp23))

Below is the table that lists codes for supported SDI FPS settings set in 0x0032[3:0]:

“Green screen”, a.k.a. “Chroma Key” on-board optimization is designed to replace a range of colors with a single solid one

If enabled these setting take precedence over other 3 bands

Name	Offset	Bytes	Access	Notes
CK control	0x80	1	R/W	7:1 reserved 0 enable/disable Chroma Key control
CK saturation min	0x81	1	R/W	[0..255] to specify the minimum saturation threshold
CK saturation max	0x82	1	R/W	[0..255] to specify the maximum saturation threshold
CK luma min	0x83	1	R/W	[0..255] to specify the minimum brightness threshold
CK luma max	0x84	1	R/W	[0..255] to specify the maximum brightness threshold
CK hue	0x85	2	R/W	14 bits of a signed hue value, its [-8K..+8K] range is mapped into [-180°..+180°]
CK tolerance	0x86	2	R/W	13 bits of an unsigned hue tolerance value, 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 red	0x87	2	R/W
CK green	0x88	2	R/W
CK blue	0x89	2	R/W
Reserved	0x8A-0x8F

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 0x0090-0x009F

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 0x00A0-0x00AF

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 0x00B0-0x00BF

This applies to both FX3 and FPGA firmware version info data structures.

The bits are laid out in 4 sequential bytes as follows:

The FX3 version structure is as follows (little-endian memory layout):

firmware-version.h

struct FwVersion{
    unsigned vendorId    : 3;
    unsigned hwCfgId     : 5;
    unsigned productId   : 8;
    unsigned releaseType : 3;
    unsigned buildNo     : 13;
};
static_assert(sizeof(FwVersion) == 4);

The version id is also encoded into the firmware image file name as:

<VendorID>_<HardwareID>_<ProductID>_<ReleaseType>_<BuildNumber>

The version id is also encoded into the firmware image file name as:

<VendorID>_<HardwareID>_<ProductID>_<ReleaseType>_<BuildNumber>