Differences
This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revisionNext revision | Previous revisionLast revisionBoth sides next revision | ||
code:fx3_hvci_and_fpga_i_c_commands [2024/02/07 19:06] – [mFT lense access: 0xC0] Igor Yefmov | code:fx3_hvci_and_fpga_i_c_commands [2024/02/17 15:41] – [General image stats and adjustments] Igor Yefmov | ||
---|---|---|---|
Line 1: | Line 1: | ||
====== FX3/FPGA API spec ====== | ====== FX3/FPGA API spec ====== | ||
- | This page describes | + | FX3 API specification has been moved to [[fx3_api|this location]] |
- | + | ||
- | For gen4 and earlier API see [[code: | + | |
- | + | ||
- | ====== Preface ====== | + | |
- | %%SUB2r%% camera is built on a Cypress FX3 chipset that facilitates the '' | + | |
- | + | ||
- | On Windows the device is registered with a GUID '' | + | |
- | + | ||
- | Here's a sample code that shows how to send commands to both the '' | + | |
- | + | ||
- | <code c++>// set a new auto-functions' | + | |
- | // just issue the command directly to FX3's vendor request interface | + | |
- | void setAUInterval(){ | + | |
- | S2R::I2C fx3; | + | |
- | fx3.open(0); | + | |
- | fx3.vrCmd(S2R:: | + | |
- | } | + | |
- | + | ||
- | // 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:: | + | |
- | } | + | |
- | + | ||
- | // increase LED's green brightness by 25% | + | |
- | // utilize the FPGA's I²C bridge | + | |
- | void lightUpTheGreen() | + | |
- | { | + | |
- | using Cmd = S2R:: | + | |
- | using OpType = S2R:: | + | |
- | + | ||
- | S2R::FX3 fx3; // `S2R::I2C fx3;` works as well | + | |
- | fx3.open(0); | + | |
- | uint8_t | + | |
- | const uint16_t clrChannel{0x0A}; | + | |
- | fx3.vrCmd(Cmd:: | + | |
- | buf[0] += buf[0] / 4; // yes, this can totally overflow | + | |
- | fx3.vrCmd(Cmd:: | + | |
- | } | + | |
- | + | ||
- | + | ||
- | </ | + | |
- | + | ||
- | ---- | + | |
- | + | ||
- | ====== FX3 API Reference ====== | + | |
- | The following tables provide information on how to access the camera' | + | |
- | ===== 0x00-0x9F ===== | + | |
- | ^Name ^Offset ^wIndex ^wValue ^Access type ^Byte length ^Return buffer bits ^Notes ^ | + | |
- | |Reserved|'' | + | |
- | + | ||
- | + | ||
- | ===== Global controls ===== | + | |
- | ^Name ^Offset ^wIndex ^wValue ^Access type ^Byte length ^Return buffer bits ^Notes ^ | + | |
- | |Bootloader check|'' | + | |
- | |MS OS Descr.|'' | + | |
- | |:!: Run DPC calibration|'' | + | |
- | |Reserved|'' | + | |
- | ===== I²C access ===== | + | |
- | ^Name ^Offset ^wIndex ^wValue ^Access type ^Byte length ^Return buffer bits ^Notes ^ | + | |
- | |:!: FPGA I²C Bridge|'' | + | |
- | |:!: Sensor I²C bridge (\(8\)-bit configuration registers)|'' | + | |
- | |:!: Generic I²C access|'' | + | |
- | + | ||
- | ==== Generic I²C access details ==== | + | |
- | 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/ | + | |
- | + | ||
- | === Generic I²C command selector === | + | |
- | ^Code ^Name ^Description ^ | + | |
- | | \(0\) | read |This command issues an immediate read on I²C if a single address is requested or batches up the reads for a background task otherwise. Use `status` to know when it is ok to retrieve data via a call to `get results`| | + | |
- | | \(1\) | write |same as `read`, but for I²C writes| | + | |
- | | \(2\) | status |Call this repeatedly while the return code is `still in progress` (code \(0x80\)), until it returns either a `success` (code \(0\)) or any of the `fail` codes, at which point call the `results`| | + | |
- | | \(3\) | results |Once the `read` operation completes successfully, | + | |
- | + | ||
- | === Status codes === | + | |
- | ^Code ^Description ^ | + | |
- | | '' | + | |
- | | '' | + | |
- | | '' | + | |
- | | '' | + | |
- | | '' | + | |
- | | '' | + | |
- | | '' | + | |
- | | '' | + | |
- | | '' | + | |
- | + | ||
- | === Generic I²C width selector === | + | |
- | ^Value ^Width (bits) ^ | + | |
- | | \(0\) | \(8\) | | + | |
- | | \(1\) | \(16\) | + | |
- | | \(2\) | \(32\) | + | |
- | + | ||
- | + | ||
- | + | ||
- | ===== Video mode select ===== | + | |
- | ^Name ^Offset ^wIndex ^wValue ^Access type ^Byte length ^Return buffer bits ^Notes ^ | + | |
- | |:!: Video Mode Select|'' | + | |
- | + | ||
- | ===== Sysinfo ===== | + | |
- | ^Name ^Offset ^wIndex ^wValue ^Access type ^Byte length ^Return buffer bits ^Notes ^ | + | |
- | |:!: Sysinfo|'' | + | |
- | |Reserved|'' | + | |
- | + | ||
- | ===== Versioning and reprogramming ===== | + | |
- | ^Name ^Offset ^wIndex ^wValue ^Access type ^Byte length ^Notes ^ | + | |
- | |Erase SPI Flash|'' | + | |
- | |FX3 version|'' | + | |
- | |:!: FPGA version|'' | + | |
- | |:!: FPGA config. ctrl.|'' | + | |
- | |:!: FPGA config. status - SPI codes|'' | + | |
- | |SPI Flash write enable|'' | + | |
- | + | ||
- | ==== FPGA config status - SPI codes ==== | + | |
- | ^ Bit position^ 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| | + | |
- | + | ||
- | ===== FPS control ===== | + | |
- | ^Name ^Offset ^wIndex ^wValue ^Access type ^Byte length ^Return buffer bits ^Notes ^ | + | |
- | |:!: FPS|'' | + | |
- | + | ||
- | ===== Bulk color grading ===== | + | |
- | ^Name ^Offset ^wIndex ^wValue ^Access type ^Byte length ^Return buffer bits ^Notes ^ | + | |
- | |:!: Bulk color grading|'' | + | |
- | + | ||
- | ===== Color correction matrix (a.k.a. CCM or CMX) ===== | + | |
- | See [[isp: | + | |
- | ^Name ^Offset ^wIndex ^wValue ^Access type ^Byte length ^Return buffer bits ^Notes ^ | + | |
- | |:!: Color correction matrix|'' | + | |
- | + | ||
- | ===== 0xB3-0xB7 ===== | + | |
- | ^Name ^Offset ^wIndex ^wValue ^Access type ^Byte length ^Return buffer bits ^Notes ^ | + | |
- | |Reserved|'' | + | |
- | |Reserved|'' | + | |
- | |Reserved|'' | + | |
- | |Reserved|'' | + | |
- | |Reserved|'' | + | |
- | + | ||
- | ===== FPGA stats ===== | + | |
- | ^Name ^Offset ^wIndex ^wValue ^Access type ^Byte length ^Return buffer bits ^Notes ^ | + | |
- | |:!: FPGA stats|'' | + | |
- | + | ||
- | ==== FPGA stats' details === | + | |
- | ^Name ^Value ^Return type ^Notes ^ | + | |
- | | :!: Sensor FPS | '' | + | |
- | + | ||
- | ===== 0xB9 ===== | + | |
- | ^Name ^Offset ^wIndex ^wValue ^Access type ^Byte length ^Return buffer bits ^Notes ^ | + | |
- | |Reserved|'' | + | |
- | + | ||
- | ===== SDI control ===== | + | |
- | ^ Name ^ Offset | + | |
- | |:!: SDI control| | + | |
- | + | ||
- | ===== 0xBB-0xBF ===== | + | |
- | ^Name ^Offset ^wIndex ^wValue ^Access type ^Byte length ^Return buffer bits ^Notes ^ | + | |
- | |Reserved|'' | + | |
- | |Reserved|'' | + | |
- | |Reserved|'' | + | |
- | |Reserved|'' | + | |
- | |Reserved|'' | + | |
- | + | ||
- | + | ||
- | ===== SPI flash management ===== | + | |
- | 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. | + | |
- | ^Name ^Offset ^wIndex ^wValue ^Access type ^Byte length ^Return buffer bits ^Notes ^ | + | |
- | |SPI command byte|'' | + | |
- | |SPI command with 24-bit address|'' | + | |
- | |SPI flash write page|'' | + | |
- | |SPI flash read page|'' | + | |
- | |SPI flash sector erase/ | + | |
- | |SPI flash cmd 24|'' | + | |
- | |Reserved|'' | + | |
- | |Reserved|'' | + | |
- | + | ||
- | ===== 0xC8-0xCF ===== | + | |
- | ^Name ^Offset ^wIndex ^wValue ^Access type ^Byte length ^Return buffer bits ^Notes ^ | + | |
- | |Reserved|'' | + | |
- | |Reserved|'' | + | |
- | |Reserved|'' | + | |
- | |Reserved|'' | + | |
- | |Reserved|'' | + | |
- | |Reserved|'' | + | |
- | |Reserved|'' | + | |
- | |Reserved|'' | + | |
- | + | ||
- | ===== Auto exposure configuration ===== | + | |
- | ^Name ^Offset ^wIndex ^wValue ^Access type ^Byte length ^Return buffer bits ^Notes ^ | + | |
- | |:!: AE Setpoint|'' | + | |
- | |Reserved|'' | + | |
- | |Reserved|'' | + | |
- | |Reserved|'' | + | |
- | |Reserved|'' | + | |
- | |Reserved|'' | + | |
- | |Reserved|'' | + | |
- | |Reserved|'' | + | |
- | + | ||
- | ===== Auto white balance configuration ===== | + | |
- | ^Name ^Offset ^wIndex ^wValue ^Access type ^Byte length ^Return buffer bits ^Notes ^ | + | |
- | |:!: AWB Setpoint|'' | + | |
- | |Reserved|'' | + | |
- | |Reserved|'' | + | |
- | |Reserved|'' | + | |
- | + | ||
- | ===== Auto-functions' | + | |
- | ^Name ^Offset ^wIndex ^wValue ^Access type ^Byte length ^Return buffer bits ^Notes ^ | + | |
- | |Auto Update Period|'' | + | |
- | + | ||
- | ===== FX3 reset ===== | + | |
- | ^Name ^Offset ^wIndex ^wValue ^Access type ^Byte length ^Return buffer bits ^Notes ^ | + | |
- | |FX3 reset|'' | + | |
- | + | ||
- | ===== Camera peripherals ===== | + | |
- | ^Name ^Offset ^wIndex ^wValue ^Access type ^Byte length ^Notes ^ | + | |
- | | LED | '' | + | |
- | | Fan control and monitoring | '' | + | |
- | | Temperature sensor(s)|'' | + | |
- | |Reserved|'' | + | |
- | |Reserved|'' | + | |
- | |Reserved|'' | + | |
- | |Reserved|'' | + | |
- | |Reserved|'' | + | |
- | + | ||
- | ====== LED function selector ====== | + | |
- | ^Function ^Value ^Byte length^ Notes ^ | + | |
- | | Unified LED color | \(0\) | \(3\) | For both gen4 and gen5 this allows to get/set the single \(24\)-bit RGB triplet for LED pixel(s) color. When reading from multi-pixel setup the value of the first pixel is returned | | + | |
- | | Left-side LED color | \(1\) | \(3\) | Gen5 has two sides for pixels, this allows to get/set the color of the left group. When reading the value of the first pixel in a group is returned | | + | |
- | | Right-side LED color | \(2\) | \(3\) | Gen5 has two sides for pixels, this allows to get/set the color of the right group. When reading the value of the first pixel in a group is returned | | + | |
- | | \(8\)-pixel LED mode | \(3\) | \(24\) | Gen5 comes with a total of 8 LED pixels, individually controllable with this API. The command always operates (gets/sets) the full array of \(8\) \(3\)-byte RGB pixels | | + | |
- | + | ||
- | ====== Fan control and monitoring function selector ====== | + | |
- | ^Function ^Value ^Type ^Byte length^ Notes ^ | + | |
- | | FPGA-controlled fan on/off | \(0\) | < | + | |
- | | EMC2101' | + | |
- | | EMC2101' | + | |
- | + | ||
- | ====== Temperature sensor monitoring function selector ====== | + | |
- | ^Function ^Constant ^Value ^Byte length^ Notes ^ | + | |
- | | EMC2101' | + | |
- | + | ||
- | ===== 0xE9-0xEF ===== | + | |
- | |Reserved|'' | + | |
- | |Reserved|'' | + | |
- | |Reserved|'' | + | |
- | |Reserved|'' | + | |
- | |Reserved|'' | + | |
- | |Reserved|'' | + | |
- | |Reserved|'' | + | |
- | + | ||
- | ===== 0xF0-0xF9 ===== | + | |
- | ^Name ^Offset ^wIndex ^wValue ^Access type ^Byte length ^Return buffer bits ^Notes ^ | + | |
- | |Reserved|'' | + | |
- | |Reserved|'' | + | |
- | |Reserved|'' | + | |
- | |Reserved|'' | + | |
- | |Reserved|'' | + | |
- | |Reserved|'' | + | |
- | |Reserved|'' | + | |
- | |Reserved|'' | + | |
- | |Reserved|'' | + | |
- | |Reserved|'' | + | |
- | + | ||
- | + | ||
- | ===== [Debug] Get raw descriptor ===== | + | |
- | ^Name ^Offset ^wIndex ^wValue ^Access type ^Byte length ^Return buffer bits ^Notes ^ | + | |
- | |Get raw descriptor|'' | + | |
- | + | ||
- | ==== Get raw descriptor commands ==== | + | |
- | ^Cmd (wIndex) ^Meaning ^ | + | |
- | |\(0\)|get a \(2\)-byte descriptive text label' | + | |
- | |\(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' | + | |
- | + | ||
- | ==== Get raw descriptor structure types ==== | + | |
- | As of FX3 version '' | + | |
- | ^wValue ^ Details ^ | + | |
- | |\(0\)|reserved (unused)| | + | |
- | |\(1\)|USB device descriptor HS| | + | |
- | |\(2\)|USB device descriptor SS| | + | |
- | |\(3\)|USB Device Qualifier descriptor| | + | |
- | |\(4\)|USB BOS (Binary Object Store) descriptor| | + | |
- | |\(5\)|MS OS Platform Capability descriptor version 2.0| | + | |
- | |\(6\)|Full-Speed (2.0) USB Configuration descriptor| | + | |
- | |\(7\)|High-Speed (2.0) USB Configuration descriptor| | + | |
- | |\(8\)|Super-Speed (3.0) USB Configuration descriptor| | + | |
- | + | ||
- | ===== OS runtime info ===== | + | |
- | ^Name ^Offset ^wIndex ^wValue ^Access type ^Byte length ^Return buffer bits ^Notes ^ | + | |
- | |:!: OS runtime info|'' | + | |
- | + | ||
- | ^wValue ^wIndex ^Description ^ | + | |
- | | :!: \(0\) | | get number of user trheads | | + | |
- | | :!: \(1\) | \(0\)-based thread' | + | |
- | + | ||
- | ===== 0xFC-0xFF - Reserved for debug APIs ===== | + | |
- | ^Name ^Offset ^wIndex ^wValue ^Access type ^Byte length ^Return buffer bits ^Notes ^ | + | |
- | |Reserved|'' | + | |
- | |Reserved|'' | + | |
- | |Reserved|'' | + | |
- | |Reserved|'' | + | |
- | + | ||
====== FPGA I²C bridge (registers' | ====== FPGA I²C bridge (registers' | ||
Line 334: | Line 16: | ||
===== FPGA basic status and controls ===== | ===== FPGA basic status and controls ===== | ||
^Name ^Offset ^Bytes ^Access ^Bit mapping ^Notes ^ | ^Name ^Offset ^Bytes ^Access ^Bit mapping ^Notes ^ | ||
- | |:!: FPGA Version|'' | + | |:!: FPGA Version|'' |
|:!: FPGA status|'' | |:!: FPGA status|'' | ||
|::: | |::: | ||
Line 385: | Line 67: | ||
|:!: FPS|'' | |:!: FPS|'' | ||
|:!: Y average|'' | |:!: Y average|'' | ||
- | | ||||| | + | |
- | ^ Color Correction Matrix (a.k.a. CCM or CMX) | + | ===== Color Correction Matrix (a.k.a. CCM or CMX) |
- | | | + | See [[isp: |
+ | |||
+ | ^Name ^Offset ^Bytes ^Access ^Notes ^ | ||
|:!: CCM_00|'' | |:!: CCM_00|'' | ||
|:!: CCM_01|'' | |:!: CCM_01|'' | ||
Line 508: | Line 192: | ||
- | ==== mFT lense access: 0xC0 ==== | + | ==== mFT lense access ==== |
^Name ^Offset ^Bytes ^Access ^Notes ^ | ^Name ^Offset ^Bytes ^Access ^Notes ^ | ||
Line 538: | Line 222: | ||
static_assert(std:: | static_assert(std:: | ||
</ | </ | ||
- | ====== 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 ^^^^^^^^ | ||
- | ^ 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: | ||
- | |||
- | ===== Firmware version info C/ | ||
- | The FX3 version structure is as follows (little-endian memory layout): | ||
- | |||
- | <code cpp firmware-version.h> | ||
- | struct FwVersion{ | ||
- | unsigned vendorId | ||
- | unsigned hwCfgId | ||
- | unsigned productId | ||
- | unsigned releaseType : 3; | ||
- | unsigned buildNo | ||
- | }; | ||
- | static_assert(sizeof(FwVersion) == 4); | ||
- | </ | ||
- | |||
- | |||
- | ===== FX3 Version Info ===== | ||
- | The version id is also encoded into the firmware image file name as: | ||
- | < | ||
- | |||
- | |Code |Value | | ||
- | ^ Vendor ID ^^ | ||
- | |1|Cypress| | ||
- | ^ Hardware ID ^^ | ||
- | |1|FX3 Gen1| | ||
- | ^ Product ID ^^ | ||
- | |1|reserved for Gen 1 camera, a.k.a. "Moon landing" | ||
- | |2|reserved for Gen 2 camera, a.k.a. " | ||
- | |3|Gen 3 camera (Alpha), a.k.a. " | ||
- | |4|Gen 3 camera, Production| | ||
- | |5|Gen 4 camera, a.k.a. " | ||
- | |6|Gen 5 camera, either " | ||
- | ^ Release type ^^ | ||
- | |0|Private build: Private build for debugging and similar purposes | | ||
- | |1|Alpha: feature-incomplete early development cycle " | ||
- | |2|Beta: feature-complete, | ||
- | |3|Evaluation: | ||
- | |4|Release candidate: feature complete and stable | | ||
- | |5|Release: general availability | | ||
- | |6|Backport: | ||
- | |7|Emergency bug fix: a critical post-release bugfix | | ||
- | ^ Build number | ||
- | |# | ||
- | |||
- | |||
- | ===== FPGA Version Info ===== | ||
- | The version id is also encoded into the firmware image file name as: | ||
- | < | ||
- | |||
- | |Code |Value | | ||
- | ^ Vendor ID that represents a vendor of the main computation unit ^^ | ||
- | |1|Xilinx (AMD)| | ||
- | |2|Altera (Intel)| | ||
- | ^ Hardware ID for %%VendorId%% 1 (Xylinx) | ||
- | |1|Artix-7 100T| | ||
- | |2|Artix-7 200T| | ||
- | |3|Artix %%UltraScale+%% XCAU25P| | ||
- | ^ Hardware ID for %%VendorId%% 2 (Altera) | ||
- | |1|Cyclone 10 GX| | ||
- | ^ Product ID ^^ | ||
- | |1|reserved| | ||
- | |2|reserved| | ||
- | |3|Gen 3 camera (Alpha), a.k.a. " | ||
- | |4|Gen 3 camera, Production| | ||
- | |5|Gen 4 camera, a.k.a. “Vitreledonella”| | ||
- | |6|Gen 5 camera, prosumer grade " | ||
- | |7|Gen 5 camera, professional grade " | ||
- | ^ Release type ^^ | ||
- | |0|Private build| | ||
- | |1|Alpha| | ||
- | |2|Beta| | ||
- | |3|Eval/ | ||
- | |4|Release candidate| | ||
- | |5|Release| | ||
- | |6|Backport| | ||
- | |7|Emergency bug fix| | ||
- | ^ Build number | ||
- | |# | ||
- | |||