User Tools

This is an old revision of the document!


Preface

Controlling the camera is done via writing “registers” - think of them as address locations. There are generally 4 ways to interface with the camera from a host:

  1. standard UVC - this one is automagically supported by any UVC 1.1 compliant OS, which in the year 2017 would be “any modern OS”. This interface covers the universally standardized controls for USB Video Class
  2. (Gen 3 and Gen 4) direct I²C access via Cypress's FX3 interface, using control port 0x20. This allows access to all sensor's registers (at your own risk!). For more information search the web for documentation on the sensor in your camera (as of October 2017 that would be OmniVision 10823 sensor). Gen5 is using a sensor via an SLVS-EC interface which doesn't provide direct I²C access so one should use FX3 API (or, better yet - rely on SUB2r-lib for all your camera control needs)
  3. FX3 Host Vendor Command Interface - this interfaces with the Cypress's FX3 and is the primary FX3 API
  4. FPGA I²C Access - a “window” into a host of additional commands that are performed on FPGA, this is highly dependent on the FPGA model used and camera's generation and is not exactly intended for direct use outside of developing FX3 APIs and during development cycle of GUI implementation. The FPGA register maps are defined on this page

If you are set on writing your own UI and don't want to be bothered too much with figuring out how to communicate with the camera you have an option of using the SUB2r-lib library (which should be your preference anyways).

More details

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 (defined on this page) and to access FPGA's mapped registers. 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::FX3 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::FX3 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;
    fx3.open(0);
    uint8_t        buf[1]{0};
    // LED green is mapped to register 0x0A ONLY for Gen3 and Gen4, won't work for Gen5
    const uint16_t clrChannel{0x0A};
    fx3.vrCmd(Cmd::i2c_bridge_fpga, OpType::read, 0, clrChannel, buf, 1);
    buf[0] += buf[0] / 4;  // yes, this can totally overflow
    fx3.vrCmd(Cmd::i2c_bridge_fpga, OpType::write, buf[0], clrChannel);
}

Firmware Version Info

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

Bit layout

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

3 2 1 0
7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0
buildNo[12:5] buildNo[4:0] releaseType productId hwCfgId vendorId

Firmware version info C/C++-struct

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

FX3 Version Info

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

<VendorID>_<HardwareID>_<ProductID>_<ReleaseType>_<BuildNumber>
Code Value
Vendor ID
1Cypress
Hardware ID
1FX3 Gen1
Product ID
1reserved for Gen 1 camera, a.k.a. “Moon landing”
2reserved for Gen 2 camera, a.k.a. “Piggy”
3Gen 3 camera (Alpha), a.k.a. “Frankie” (from Frankenstein's Monster)
4Gen 3 camera, Production
5Gen 4 camera, a.k.a. “Vitreledonella”
6Gen 5 camera, either “Square One” or “Studio”
Release type
0Private build: Private build for debugging and similar purposes
1Alpha: feature-incomplete early development cycle “somewhat stable” build
2Beta: feature-complete, but not very stable build (lots of bugs)
3Evaluation: Tech preview
4Release candidate: feature complete and stable
5Release: general availability
6Backport: backport of a feature from next gen camera
7Emergency bug fix: a critical post-release bugfix
Build number
#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 that represents a vendor of the main computation unit

Code Value
1Xilinx (AMD)
2Altera (Intel)

Hardware ID for VendorId 1 (Xylinx)

Code Value
1Artix-7 100T
2Artix-7 200T
3Artix UltraScale+ XCAU25P

Hardware ID for VendorId 2 (Altera)

Code Value
1Cyclone 10 GX

Product ID

Code Value
1reserved
2reserved
3Gen 3 camera (Alpha), a.k.a. “Frankie”
4Gen 3 camera, Production
5Gen 4 camera, a.k.a. “Vitreledonella”
6Gen 5 camera, prosumer grade “Square One”
7Gen 5 camera, professional grade “Studio”

Release type

Code Value
0Private build
1Alpha
2Beta
3Eval/Tech preview
4Release candidate
5Release
6Backport
7Emergency bug fix

Build number

Code Value
#11 bits of a build number (the range is 1..2047). Increments on each build

Firmware Versioning evolution

FX3 Version Info

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

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

FX3 version info C/C++-struct

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;
#ifdef OLD_VER_FMT
    unsigned releaseType : 5;
    unsigned buildNo     : 11;
#else
    unsigned releaseType : 3;
    unsigned buildNo     : 13;
#endif
};
static_assert(sizeof(FwVersion) == 4);

Prior to FPGA v. 89 there was no standard-compliant way of representing the version info in a C struct though (which is exactly what prompted the rework in the first place).

Bit layout

The bits are laid out in 4 sequential bytes as follows (depending on the version):

version 3 2 1 0
7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0
fx3<102
fpga<77
buildNo[7:0] releaseType buildNo[10:8] productId vendorId hwCfgId
fx3<103 buildNo[10:3] buildNo[2:0] releaseType productId hwCfgId vendorId
fx3>=103
fpga>=77
buildNo[12:5] buildNo[4:0] releaseType productId hwCfgId vendorId

Because of the change in bit layout different byte sequences shown below are needed to produce the same result (exact same component values for the sake of simplicity and only as an illustration):

version byte sequence (API return buffer)
.vendorId = 1
.hwCfgId = 1
.productId = 5
.releaseType = 3
.buildNo = 0x67
fx3>=102
fpga<77
0x21 0x05 0x18 0x67
fx3<103 0x09 0x05 0xE3 0x0C
fx3>=103
fpga>=77
0x09 0x05 0x3B 0x03

Vendor ID

Code Value
1Cypress

Hardware ID

Code Value
1FX3

Product ID

Code Value
1reserved for Gen 1 camera, a.k.a. “Moon landing”
2reserved for Gen 2 camera, a.k.a. “Piggy”
3Gen 3 camera (Alpha), a.k.a. “Frankie” (from Frankenstein's Monster)
4Gen 3 camera, Production
5Gen 4 camera, a.k.a. “Vitreledonella”
6Gen 5 camera, either “Square One” or “Studio”

Release type

Code Name Meaning
0Private build Private build for debugging and similar purposes
1Alpha feature-incomplete early development cycle “somewhat stable” build
2Beta feature-complete, but not very stable build (lots of bugs)
3Evaluation Tech preview
4Release candidate feature complete and stable
5Release general availability
6Backport backport of a feature from next gen camera
7Emergency 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

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

Code Value
1Xilinx (AMD)
2Altera (Intel)

Hardware ID

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

VendorIdCode Value
11Artix-7 100T
12Artix-7 200T
13Artix UltraScale+ XCAU25P
21Cyclone 10 GX

Product ID

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

Code Value
1reserved
2reserved
3Gen 3 camera (Alpha), a.k.a. “Frankie”
4Gen 3 camera, Production
5Gen 4 camera, a.k.a. “Vitreledonella”
6Gen 5 camera, prosumer grade “Square One”
7Gen 5 camera, professional grade “Studio”

Release type

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

Code Value
0Private build
1Alpha
2Beta
3Eval/Tech preview
4Release candidate
5Release
6Backport
7Emergency bug fix

Build number

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

Code Value
#Increments on each build

FPGA config status - SPI codes

These are the status bits that indicate the FPGA programming (reconfiguring) process:

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 busySet to 1 while the config is not busy

This website uses cookies. By using the website, you agree with storing cookies on your computer. Also, you acknowledge that you have read and understand our Privacy Policy. If you do not agree, please leave the website.

More information