Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
programmable-logic:zybo-z7:demos:pmod-tof [2022/09/12 13:49] – changed forum.digilentinc.com to forum.digilent.com Jeffreyprogrammable-logic:zybo-z7:demos:pmod-tof [2023/08/25 00:36] (current) – Move to direct file links for downloads Arthur Brown
Line 1: Line 1:
 +====== Zybo Z7-20 Pmod ToF Demo ======
  
 +{{:programmable-logic:zybo-z7:demos:demo_setup.jpg?500|}}
 +
 +----
 +
 +===== Description ========= 
 +
 +This demo was created to show the functionalities of the [[pmod:pmodtof:start|Pmod ToF (Time of Flight)]] connected to the Zybo Z7-20's Pmod port. 
 +
 +Please consult the [[pmod:pmodtof:zynqlibraryuserguide|Pmod ToF Hierarchical Block Library]] documentation for an overall description of the Hierarchical Block that includes the drivers of the Pmod. The initial demo user guide containing more details regarding the implementation can be found [[pmod:pmodtof:demouserguide|here]].
 +
 +Besides these functionalities, the demo provides two extra modules that extend the functionality of the Pmod ToF.
 +   * The UART Module provides the communication between the UART interface of the system board (USB - UART interface) and the host computer.
 +   * The PmodToFCMD Module is used for interpreting UART commands.
 +
 +----
 +
 +===== Inventory =====
 +
 +  * Zybo Z7-20 with a MicroUSB Programming Cable
 +  * Vivado and Vitis installations compatible with the latest release of this demo
 +    * //See [[programmable-logic:guides:installing-vivado-and-vitis|Installing Vivado, Vitis, and Digilent Board Files]] for installation instructions.//
 +  * Serial Terminal application to communicate with the board
 +    * //See [[programmable-logic:guides:serial-terminals:start]] for more information.//
 +  * Pmod ToF
 +
 +----
 +
 +===== Download and Usage Instructions =====
 +
 +First and foremost, releases - consisting of a set of files for download - are only compatible with a specific version of the Xilinx tools, as specified in the name of the release (referred to as a //release tag//). In addition, releases are only compatible with the specified variant of the board. For example, a release tagged "20/DMA/2020.1" for the Zybo Z7 is only to be used with the -20 variant of the board and Xilinx tools (Vivado and Vitis) version 2020.1.
 +
 +The latest release version for this demo is highlighted in green.
 +
 +**Note:** //Releases for FPGA demos from before 2020.1 used a different git structure, and used a different release tag naming scheme.//
 +
 +^ Board Variant  ^ Release Tag                     ^ Release Downloads                                                                                    ^ Setup Instructions  ^
 +| Zybo Z7-20     | @#C0EEBD: 20/Pmod-ToF/2022.1-1  | {{https://github.com/Digilent/Zybo-Z7/releases/download/20/Pmod-ToF/2022.1-1/Zybo-Z7-20-Pmod-ToF-hw.xpr.zip}} \\ {{https://github.com/Digilent/Zybo-Z7/releases/download/20/Pmod-ToF/2022.1-1/Zybo-Z7-20-Pmod-ToF-sw.ide.zip}}  | See //Using the Latest Release//, below  |
 +| Zybo Z7-20     | 20/Pmod-ToF/2021.1-1            | {{https://github.com/Digilent/Zybo-Z7/releases/download/20/Pmod-ToF/2021.1-1/Zybo-Z7-20-Pmod-ToF-hw.xpr.zip}} \\ {{https://github.com/Digilent/Zybo-Z7/releases/download/20/Pmod-ToF/2021.1-1/Zybo-Z7-20-Pmod-ToF-sw.ide.zip}}  | See //Using the Latest Release//, below  |
 +| Zybo Z7-20     | 20/Pmod-ToF/2020.1-1            | {{https://github.com/Digilent/Zybo-Z7/releases/download/20/Pmod-ToF/2020.1-1/Zybo-Z7-20-Pmod-ToF-hw.xpr.zip}} \\ {{https://github.com/Digilent/Zybo-Z7/releases/download/20/Pmod-ToF/2020.1-1/Zybo-Z7-20-Pmod-ToF-sw.ide.zip}}  | See //Using the Latest Release//, below  |
 +| Zybo Z7-20     | 20/Pmod-ToF/2019.1-1            | [[https://github.com/Digilent/ZyboZ7-20-PmodToF-Demo/releases/tag/v2019.1-1|Release ZIP Downloads]]  | [[https://github.com/Digilent/ZyboZ7-20-PmodToF-Demo|v2019.1-1 README]]  |
 +
 +**Note for Advanced Users:** //GitHub sources for this demo can be found in the [[https://github.com/digilent/zybo-z7/tree/20/Pmod-ToF/master|20/Pmod-ToF/master]] branch of the Zybo-Z7 repository. Further documentation on the structure of this repository can be found on this wiki's [[programmable-logic:documents:git]] page.//
 +----
 +Instructions on the use of the latest release can be found in this dropdown:
 +
 +--> Using the Latest Release #^
 +<WRAP group>
 +
 +{{page>programmable-logic:guides:using-github-releases#baremetal_release_no_build&noheader}}
 +
 +{{page>programmable-logic:guides:using-github-releases#baremetal_release_workaround_before_programming&noheader}}
 +
 +--> Build a Vitis Application #
 +<WRAP group>
 +{{page>programmable-logic:guides:vitis-build-software&noheader}}
 +</WRAP>
 +<--
 +
 +--> Set up the Zybo Z7 #
 +<WRAP group>
 +<WRAP group>
 +Plug the Zybo Z7-20 into the computer via the microUSB programming cable and power on the board. Make sure the JP5 jumper is set to JTAG.
 +
 +Plug the ToF Pmod into JB Pmod port of the Zybo.
 +</WRAP>
 +</WRAP>
 +----
 +<--
 +
 +{{page>programmable-logic:guides:using-github-releases#baremetal_release_programming&noheader}}
 +
 +At this point, the demo is now running on your board. Refer to the [[#description|Description]] section of this document for more information on what it does.
 +----
 +Additional steps beyond here present how you can use the other archive provided in the release, containing the hardware project, to rebuild the Vivado project, and use a newly exported XSA file to update the platform in Vitis.
 +----
 +{{page>programmable-logic:guides:using-github-releases#baremetal_update_specification&noheader}}
 +</WRAP>
 +<--
 +
 +----
 +
 +===== Functionality ======
 +
 +After the board is programmed and a terminal window (such as Tera Term) is opened, the user is shown all the possible options and is prompted to type the code related to the desired command.
 +
 +{{:programmable-logic:zybo-z7:demos:tof_terminal_print.png?direct&500|}}
 +
 +**Note**://The functionality has been changed slightly since the 2020.1 version. Before it, the demo options were chosen by Copy-Paste-ing the entire command names into the terminal.//
 +
 +----
 +
 +=== 1. ToFMeasure   < m >===
 +> This command initiates a measurement and displays the distance measured by the device over UART. Before running this command, it is important that a manual calibration was performed or that a calibration was stored in then imported from the EEPROM user area or that factory calibration was restored from EEPROM.
 +
 +> If the measurement is performed correctly, the response of the command should be: //“OK,Distance measured D = x mm.”//
 +
 +   * //In case the program crashes during this command, try to power off the board. Then power it back on and program it once again//
 +
 +----
 +
 +=== 2. ToFStartCalib   < c > ===
 +
 +> This command performs a manual calibration. It calls all 3 calibration routines (magnitude, crosstalk, and distance).
 +
 +  * Response:           
 +                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        
 +^ Answer      ^ Meaning       ^
 +| "OK,Starting calibration..."    | The calibration distance parameter is greater than 5 cm.     |
 +| "ERROR, Incorrect calibration distance(distance is less than 5 cm)."    | ERROR, distance value parameter is less than 5 cm. |
 +| "ERROR, Failed starting manual calibration."    | ERROR, failed to start calibration, EEPROM or ISL29501 device is busy.     |
 +
 +
 +For details about how to perform a manual calibration, see the [[pmod:pmodtof:libraryuserguide#calibration|Calibration]] section in  [[pmod:pmodtof:libraryuserguide|Pmod ToF Hierarchical Block Library]] documentation.
 +
 +----
 +
 +=== 3. ToFSaveCalib   < s > ===
 +
 +> This command is used to write calibration data into the user calibration area of EEPROM. 
 +> This command should be issued after changes were made in calibration data(after a manual calibration), in order to save them in the non-volatile memory.
 +
 +  * Response:           
 +              
 +^ Response                                          ^ Meaning                                                           ^
 +| “OK, Calibration stored to EEPROM user space."  | Success.                                                          |
 +| "ERROR, ToF read over I2C error."               | ERROR, failed to read ISL29501 registers over I2C communication.  |
 +| "ERROR, EPROM write over I2C error."            | ERROR, failed to write EEPROM memory over I2C communication.      |
 +
 +----
 +
 +=== 4. ToFRestoreFactCalib   < r > ===
 +> This command it is used to restore the factory calibration data from EEPROM. When this command is run, the factory calibration data from EEPROM is read and then written into the user calibration area of EEPROM and into ISL29501 registers.
 +
 +   * Response:
 +
 +^ Response                                 ^ Meaning                                                           ^
 +| “OK,Factory calibration restored."     | Success.                                                          |
 +| "ERROR, Invalid EEPROM magic number."  | ERROR, wrong CRC when reading data from EEPROM.                   |
 +| "ERROR, Invalid EEPROM checksum."      | ERROR, wrong Magic Number when reading data from EEPROM.          |
 +| "ERROR, ToF read over I2C error."      | ERROR, failed to read ISL29501 registers over I2C communication.  |
 +| "ERROR, EEPROM write over I2C error."  | ERROR, failed to write EEPROM memory over I2C communication.      |
 +
 +
 +----
 +
 +=== 5. ReadSerialNo   < n > ===
 +
 +> This command retrieves the 12 digit serial number information from EEPROM and displays the Pmod's serial number over UART.
 +
 +----
 +
 +=== 6. Quit   < q > ===
 +
 +> This command determines the program to exit the command loop, being unable to receive any other commands.
 +
 +----
 +
 +===== Additional Resources =====
 +
 +All materials related to the use of the Zybo Z7 can be found on its [[..:start|Resource Center]].
 +
 +All materials related to the use of the list other products here can be found on their resource centers, linked below: 
 +
 +  * Pmod ToF [[pmod:pmodtof:start| Resource Center]]
 +
 +For a walkthrough of the process of creating a simple baremetal software project in Vivado and Vitis, see [[programmable-logic:guides:getting-started-with-ipi]]. Information on important parts of the GUIs, and indirect discussion of the steps required to modify, rebuild, and run this demo in hardware can also be found here.
 +
 +For technical support, please visit the [[https://forum.digilent.com/forum/4-fpga/|FPGA]] section of the Digilent Forum.
 +
 +----