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.

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);
}

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:

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 128MB or 256MB) is partitioned into 65KB sectors, each comprised of 256 pages. Each page is 256 bytes long.

List of commands supported by this API:

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:

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

0x49[1:0]\0x48[6:3]	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 st in 0x48[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	Access	Bit mapping	Notes
CK control	0x80	R/W	7:1 reserved 0 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	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°]
	0x87		7:6 reserved 5:0 hue MSB
CK tolerance	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
	0x89		7:5 reserved 4:0 tolerance MSB
CK red	0x8A	R/W	7:0 red LSB
	0x8B		7:0 red MSB
CK green	0x8C	R/W	7:0 green LSB
	0x8D		7:0 green MSB
CK blue	0x8E	R/W	7:0 blue LSB
	0x8F		7:0 blue MSB

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

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

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

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	0xD0	R/W	7:0 LSB	\(CCM_{00}\)
	0xD1		7:0 MSB
CCM_01	0xD2	R/W	7:0 LSB	\(CCM_{01}\)
	0xD3		7:0 MSB
CCM_02	0xD4	R/W	7:0 LSB	\(CCM_{02}\)
	0xD5		7:0 MSB
CCM_10	0xD6	R/W	7:0 LSB	\(CCM_{10}\)
	0xD7		7:0 MSB
CCM_11	0xD8	R/W	7:0 LSB	\(CCM_{11}\)
	0xD9		7:0 MSB
CCM_12	0xDA	R/W	7:0 LSB	\(CCM_{12}\)
	0xDB		7:0 MSB
CCM_20	0xDC	R/W	7:0 LSB	\(CCM_{20}\)
	0xDD		7:0 MSB
CCM_21	0xDE	R/W	7:0 LSB	\(CCM_{21}\)
	0xDF		7:0 MSB
CCM_22	0xE0	R/W	7:0 LSB	\(CCM_{22}\)
	0xE1		7:0 MSB

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

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

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 bits are laid out in 4 sequential bytes as follows (depending on the version):

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

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

A 3-bit number that represents a vendor of the main computation unit

A 5-bit number that represents a model from the list in the following table:

An 8-bit number, unique to each product type from the table below:

Lower 3 bits of this 5-bit value map to a type of build below, the upper 2 bits are reserved for future use and must be b00

11 bits of a build number (the range is 1..2047)