Both sides previous revisionPrevious revisionNext revision | Previous revision |
code:fx3_api [2024/02/17 15:19] – [Preface] Igor Yefmov | code:fx3_api [2024/04/26 23:21] (current) – [Camera peripherals] Igor Yefmov |
---|
====== FX3/FPGA API spec ====== | ====== FX3/FPGA API spec ====== |
This page describes FX3/FPGA API for Square1 and Studio (gen5) products. | This page describes FX3 API for Frankie (gen3), Rex (gen4), Square1 and Studio (gen5) products. |
| |
For gen4 and earlier API see [[code:fx3_fpga_api_spec_rex|FX3/FPGA API spec up to REX]]. | For gen4 and earlier API see [[code:fx3_fpga_api_spec_rex|FX3/FPGA API spec up to REX]]. |
| |
====== 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 ''[[code:sub2r-lib|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_registers_map|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 :) | |
| |
<code c++>// 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); | |
} | |
| |
| |
</code> | |
| |
---- | |
| |
====== FX3 API Reference ====== | ====== FX3 API Reference ====== |
===== I²C access ===== | ===== I²C access ===== |
^Name ^Offset ^wIndex ^wValue ^Access type ^Byte length ^Return buffer bits ^Notes ^ | ^Name ^Offset ^wIndex ^wValue ^Access type ^Byte length ^Return buffer bits ^Notes ^ |
|:!: 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 (registers' map)|FPGA I²C bridge]]| | |:!: FPGA I²C Bridge|''0xA4''|FPGA register offset|FPGA data (write)|R/W|\(0\) or \(1\)|[\(7:0\)] - FPGA data| **DEPRECATED in Gen5+** - use the ''Generic I²C access'' instead\\ **Up to Gen4** - 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_registers_map|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 | | |:!: 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 | |
|:!: Generic I²C access|''0xA6''|[\(15:8\)] \(8\)-bit I²C bus address\\ [\(7:6\)] [[#Generic I²C command selector|command selector]]\\ [\(5:3\)] [[#Generic I²C width selector|data width selector]]\\ [''2:0''] [[#Generic I²C width selector|address width selector]]|[\(7:0\)] - number of data elements to read/write|R/W| | |single/bulk read/write to/from an arbitrary device on I²C bus, supports \(8\), \(16\), \(32\) bit addressing and same for data OR poll for status or get result of a bulk I2C operation, see [[#Generic I²C access details|next section]] for details| | |:!: Generic I²C access|''0xA6''|[\(15:8\)] \(8\)-bit I²C bus address\\ [\(7:6\)] [[#Generic I²C command selector|command selector]]\\ [\(5:3\)] [[#Generic I²C width selector|data width selector]]\\ [''2:0''] [[#Generic I²C width selector|address width selector]]|[\(7:0\)] - number of data elements to read/write|R/W| | |single/bulk read/write to/from an arbitrary device on I²C bus, supports \(8\), \(16\), \(32\) bit addressing and same for data OR poll for status or get result of a bulk I2C operation, see [[#Generic I²C access details|next section]] for details| |
| Fan control and monitoring | ''0xE2'' | See [[#Fan control and monitoring function selector]] | depends on selected function | R/W | \(1\) or \(2\) | This API is available in gen4 v.114 and gen5 v.1\\ \\ For function selector values refer to [[#Fan control and monitoring function selector]] | | | Fan control and monitoring | ''0xE2'' | See [[#Fan control and monitoring function selector]] | depends on selected function | R/W | \(1\) or \(2\) | This API is available in gen4 v.114 and gen5 v.1\\ \\ For function selector values refer to [[#Fan control and monitoring function selector]] | |
| Temperature sensor(s)|''0xE3''| See [[#Temperature sensor monitoring function selector]] | depends on selected function | R/O | \(1\) | This API is available in gen4 v.114 and gen5 v.1\\ \\ For function selector values refer to [[#Temperature sensor monitoring function selector]] below | | | Temperature sensor(s)|''0xE3''| See [[#Temperature sensor monitoring function selector]] | depends on selected function | R/O | \(1\) | This API is available in gen4 v.114 and gen5 v.1\\ \\ For function selector values refer to [[#Temperature sensor monitoring function selector]] below | |
|Reserved|''0xE4''| | | | | |mFT|''0xE4''| see Notes | see Notes | R/W | varies | This API requires gen5 v.1\\ For reads:\\ wValue is the number of data bytes to read from the last mFT command's response or a ''0'' to get the status, defined as follows:\\ <code c++>struct MftStatus final{ |
| bool ready : 1; // LSB |
| bool cmd_done : 1; |
| bool in_fifo_empty : 1; |
| bool in_fifo_full : 1; |
| bool crc_error : 1; |
| bool to_error : 1; |
| uint8_t res0 : 2; |
| uint8_t res1; |
| uint8_t in_fifo_data_count; |
| uint8_t res2; // MSB |
| };</code> For writes:\\ - wIndex MSB: command type\\ - wIndex LSB: command code\\ - wValue MSB: param1\\ - wValue LSB: param2 | |
|Reserved|''0xE5''| | | | | |Reserved|''0xE5''| | | | |
|Reserved|''0xE6''| | | | | |Reserved|''0xE6''| | | | |