I3C Examples (Blocking API) =========================== Overview -------- The blocking I3C examples include multiple scenarios. Current documented examples: - Basic API: - C: ``examples/blocking_api/i3c/basic/c/`` - C++: ``examples/blocking_api/i3c/basic/cpp/`` - CCC API: - C: ``examples/blocking_api/i3c/ccc/c/`` - C++: ``examples/blocking_api/i3c/ccc/cpp/`` - DAA API: - C: ``examples/blocking_api/i3c/daa/c/`` - C++: ``examples/blocking_api/i3c/daa/cpp/`` - HDR-DDR API: - C: ``examples/blocking_api/i3c/hdr-ddr/c/`` - C++: ``examples/blocking_api/i3c/hdr-ddr/cpp/`` - Hot-Join + IBI API: - C: ``examples/blocking_api/i3c/hj-ibi/c/`` - C++: ``examples/blocking_api/i3c/hj-ibi/cpp/`` I3C Basic API Examples ---------------------- Hardware setup ~~~~~~~~~~~~~~ Required hardware: 1. One Binho **Supernova** 2. One **Binho I3C Target Board** 3. One STMicroelectronics **STEVAL-MKI239A** 4. One Bosch Sensortec **BMI323 Shuttle Board 3.0** 5. One Adafruit **I2C FRAM Breakout Board** (legacy I2C target on the I3C bus) Useful references: - Binho I3C Target Board: `binho.io/test-measurement/products/usb-host-adapters/accessories/i3c-target-board/ `__ - STMicroelectronics STEVAL-MKI239A: `st.com/en/evaluation-tools/steval-mki239a.html `__ - Bosch Sensortec BMI323: `bosch-sensortec.com/products/motion-sensors/imus/bmi323/ `__ - Adafruit I2C FRAM breakout: `adafruit.com/product/1895 `__ What The Basic I3C Examples Do ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1. Connect to the adapter and print host device information. 2. Set I3C VTARG to ``3300 mV``. 3. Initialize the I3C controller and then reconfigure I3C parameters. 4. Read and print the target device table. 5. Initialize the I3C bus with dynamic discovery and print the updated table. 6. Reset the bus. 7. Re-initialize the bus with a static target table (including I3C + legacy I2C target entries) and print the resulting table. 8. Update target configuration and print the table again. Notes ~~~~~ - These examples exercise the **basic I3C controller API** (bus init/reset, table management, and target configuration updates). - The C and C++ examples implement the same flow with their corresponding API wrappers. See also: - C API I3C reference: :doc:`../../api/c/i3c` - C++ blocking I3C reference: :doc:`../../api/cpp_blocking/i3c` Build and Run (I3C Basic C/C++) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ I3C basic example directories build binaries with the following names: - C (``examples/blocking_api/i3c/basic/c/``): - ``example_c_dynamic`` - ``example_c_static`` - C++ (``examples/blocking_api/i3c/basic/cpp/``): - ``example_cpp_dynamic`` - ``example_cpp_static`` CCC Examples ------------ Hardware setup ~~~~~~~~~~~~~~ Required hardware: 1. One Binho **Supernova** 2. One **Binho I3C Target Board** 3. One STMicroelectronics **STEVAL-MKI239A** 4. One Bosch Sensortec **BMI323 Shuttle Board 3.0** Useful references: - Binho I3C Target Board: `binho.io/test-measurement/products/usb-host-adapters/accessories/i3c-target-board/ `__ - STMicroelectronics STEVAL-MKI239A: `st.com/en/evaluation-tools/steval-mki239a.html `__ - Bosch Sensortec BMI323: `bosch-sensortec.com/products/motion-sensors/imus/bmi323/ `__ What The CCC Examples Do ~~~~~~~~~~~~~~~~~~~~~~~~ 1. Connect to the adapter and initialize the I3C controller and bus. 2. Retrieve and print the target device table. 3. Execute representative CCC reads: - ``GETPID``, ``GETBCR``, ``GETDCR``, ``GETCAPS`` - ``GETMRL`` and ``GETMWL`` 4. Execute representative CCC writes and controls: - ``SETMRL`` and ``SETMWL`` (direct and broadcast) - ``DISEC`` and ``ENEC`` (direct and broadcast) - ``RSTACT`` (direct and broadcast) 5. Emit ``Target Reset Pattern`` and ``HDR Exit Pattern``. Build and Run (I3C CCC C/C++) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ I3C CCC example directories build binaries with the following names: - C (``examples/blocking_api/i3c/ccc/c/``): - ``example_c_dynamic`` - ``example_c_static`` - C++ (``examples/blocking_api/i3c/ccc/cpp/``): - ``example_cpp_dynamic`` - ``example_cpp_static`` DAA Examples ------------ Hardware setup ~~~~~~~~~~~~~~ Required hardware: 1. One Binho **Supernova** 2. One **Binho I3C Target Board** 3. One STMicroelectronics **STEVAL-MKI239A** 4. One Bosch Sensortec **BMI323 Shuttle Board 3.0** Useful references: - Binho I3C Target Board: `binho.io/test-measurement/products/usb-host-adapters/accessories/i3c-target-board/ `__ - STMicroelectronics STEVAL-MKI239A: `st.com/en/evaluation-tools/steval-mki239a.html `__ - Bosch Sensortec BMI323: `bosch-sensortec.com/products/motion-sensors/imus/bmi323/ `__ What The DAA Examples Do ~~~~~~~~~~~~~~~~~~~~~~~~ 1. Connect to the adapter and initialize the I3C bus. 2. Run DAA-related command flows in separate stages: - ``SETDASA`` to assign dynamic addresses from known static addresses. - ``SETAASA`` to adopt static addresses as dynamic addresses. - ``ENTDAA`` to run dynamic address assignment arbitration. - ``SETNEWDA`` to reassign an already assigned dynamic address. 3. Read and print the target table after each stage to visualize address changes. Build and Run (I3C DAA C/C++) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ I3C DAA example directories build binaries with the following names: - C (``examples/blocking_api/i3c/daa/c/``): - ``example_c_dynamic`` - ``example_c_static`` - C++ (``examples/blocking_api/i3c/daa/cpp/``): - ``example_cpp_dynamic`` - ``example_cpp_static`` HDR-DDR Examples ---------------- Hardware setup ~~~~~~~~~~~~~~ Required hardware: 1. One Binho **Supernova** 2. One Binho **mikroBUS Adapter Board** 3. One MikroE **6DOF IMU 14 Click** Important board configuration for I3C: - On 6DOF IMU 14 Click, the ``COMM SEL`` hardware jumpers (``JP2``, ``JP3``, ``JP4``) select protocol. - Default factory position is **SPI** (left position). - For I2C/I3C operation, move all three jumpers to the **right position** (I2C selection). Useful references: - Binho mikroBUS Adapter Board: `binho.io/test-measurement/products/usb-host-adapters/accessories/mikrobus-adapter-board/ `__ - 6DOF IMU 14 Click product page: `mikroe.com/6dof-imu-14-click `__ - 6DOF IMU 14 Click schematic: `download.mikroe.com/documents/add-on-boards/click/6dof-imu-14-click/6DOF_IMU_14_click_v100_Schematic.PDF `__ - ICM-42688-P datasheet: `invensense.tdk.com/download-pdf/icm-42688-p-datasheet/ `__ What The HDR-DDR Examples Do ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1. Connect to the adapter and initialize I3C. 2. Execute an HDR-DDR write to a target register path. 3. Reset the target register pointer with an SDR command. 4. Execute an HDR-DDR read and print returned bytes. Build and Run (I3C HDR-DDR C/C++) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ I3C HDR-DDR example directories build binaries with the following names: - C (``examples/blocking_api/i3c/hdr-ddr/c/``): - ``example_c_dynamic`` - ``example_c_static`` - C++ (``examples/blocking_api/i3c/hdr-ddr/cpp/``): - ``example_cpp_dynamic`` - ``example_cpp_static`` Hot-Join + IBI Examples ----------------------- Hardware setup ~~~~~~~~~~~~~~ Required hardware: 1. One Binho **Supernova** 2. One Microchip **PIC18F16Q20 Curiosity Nano** 3. One Binho **PIC18F16Q20 Curiosity Nano I3C Target Demo Board** 4. One Adafruit **I2C FRAM Breakout Board** 5. On-board **W25Q64JV** SPI flash (integrated on the Binho PIC18F16Q20 demo board) Firmware and setup notes: - The PIC firmware project archive is provided in: ``examples/blocking_api/i3c/hj-ibi/assets/pic18f16q20-fw-mplabx-project/pic18f16q20-i3c-multi-protocol-translator-modified.zip``. - Informative illustrations of the hardware setup and firmware flow are included in ``examples/blocking_api/i3c/hj-ibi/assets/pictures``. - This firmware implements an I3C-to-I2C/SPI translator. - Initialize the Supernova I3C controller first, then power up the PIC board so it joins the bus via Hot-Join. - I3C bus voltage in this setup is ``1.2 V``. Important IBI payload limit: - Read responses are returned via IBI payloads. - Supernova supports IBI payloads up to 8 bytes total, including MDB. - Therefore translator read requests should be limited to ``<= 7`` data bytes. Useful references: - Binho PIC18F16Q20 Curiosity Nano I3C Target Demo Board: `binho.io/test-measurement/products/usb-host-adapters/accessories/pic18f16q20-curiosity-nano/ `__ - Adafruit I2C FRAM breakout: `adafruit.com/product/1895 `__ What The Hot-Join + IBI Examples Do ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1. Connect to the adapter and initialize I3C controller + bus. 2. Wait for PIC Hot-Join and capture dynamic address from notification callback. 3. Issue translator commands over I3C SDR for downstream I2C: - Write bytes to FRAM - Reset FRAM internal pointer - Request FRAM read and receive data via IBI 4. Issue translator commands over I3C SDR for downstream SPI flash: - Read JEDEC ID (response via IBI) - Write Enable - Write Status Register-1 - Read Status Register-1 (response via IBI) 5. Use event-based synchronization between callback and main flow to wait for Hot-Join/IBI events. Build and Run (I3C Hot-Join + IBI C/C++) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ I3C Hot-Join + IBI example directories build binaries with the following names: - C (``examples/blocking_api/i3c/hj-ibi/c/``): - ``example_c_dynamic`` - ``example_c_static`` - C++ (``examples/blocking_api/i3c/hj-ibi/cpp/``): - ``example_cpp_dynamic`` - ``example_cpp_static``