====== Zybo Z7-20 Pmod ToF Demo User Guide ====== Digilent provides a Pmod ToF demo targeting the Digilent Zybo Z7-20 board, to be used with the Xilinx SDK development environment.\\ The library accesses the Pmod ToF hardware in order to implement Pmod ToF functionality. It has multiple software modules, corresponding to different hardware modules.\\ It is designed to run on the Digilent Zybo Z7-20 board, which acts as a system board for the Pmod ToF. The Pmod ToF is attached to the Zybo Z7-20, and is accessed using digital pins over the Pmod connector.\\ ===== Overview ===== The main chapters of this user guide are: * [[#hardware_configuration|Hardware Configuration (Vivado Block Design)]] * [[#demo_overall_structure|Demo Overall Structure]] * [[#demo_modules|Demo Modules]] ===== Prerequisites ===== ===Hardware=== * **Zybo Z7-20 board** * **Pmod ToF** * **Micro-USB cable** ===Software=== * **Vivado Design Suite & Xilinx SDK 2019.1** * //Version 2019.1 must be used to generate the project// * **Digilent Board Support Files for Vivado** * //Follow the [[vivado:boardfiles|Vivado Board Files for Digilent 7-Series FPGA Boards]] guide on how to install Board Support Files for Vivado.// * **Vivado-Hierarchies** * //Follow the [[learn:programmable-logic:tutorials:vivado-hierarchical-blocks:start]] guide on how to add a Pmod Hierarchical Block.// ------- ===== Downloads ===== Zybo Z7-20 Pmod ToF Project Repository [[https://github.com/Digilent/ZyboZ7-20-PmodToF-Demo/releases/download/v2019.1-1/ZyboZ7-20-PmodToF-Demo-2019.1-1.zip|ZIP]] [[https://github.com/Digilent/ZyboZ7-20-PmodToF-Demo.git|Git Repo]] ===== Download and Launch the ZyboZ7-20 Pmod ToF Demo ===== >1) For this demo follow the steps 1), 2) and 5) for SDK from the [[:learn:programmable-logic:tutorials:github-demos:start|Using Digilent Github Demo Projects]] Tutorial. >2) Make sure that you have your Pmod ToF plugged into your ZyboZ7-20's Pmod port JB. \\ Please read the [[pmod:pmodtof:libraryuserguide#pmod_tof_hardware_and_calibration_details|Pmod ToF Hardware and Calibration Details]] section for additional information when using this demo. ===== Hardware Configuration ===== The Vivado hardware configuration (Vivado Block Design) implemented for this demo has the following features: * Basic Zynq configuration, with UART_PS1 enabled * Pmod ToF Hierarchical Block (found in vivado-library's hierarchies branch, See [[#prerequisites|Prerequisites]] section) which contains the following IPs: * AXI IIC * AXI GPIO * Pmod Bridge The Pmod ToF must be inserted into Pmod connector JB on Zybo-Z7-20 for this demo. The user can choose to use a different Pmod connector but the pins constrained in the XDC file must be changed for the new Pmod connector. \\ The user must connect the Pmod ToF's pullup jumpers (JP1, JP2, JP3 and JP4) when using the Pmod ToF Hierarchical Block. The following image shows the block design.\\ {{ :reference:pmod:pmodtof:blockdesignlib.png |}} The following image shows the Pmod ToF Hierarchical Block design (PmodToF_0 expanded). {{ :reference:pmod:pmodtof:pmodtofhier.png |}} ===== Demo Overall Structure ===== The following image shows the demo modules and the links between them. {{ :reference:pmod:pmodtof:libstructure.png |}} ===== Description ===== This demo was created to show the functionalities of the Pmod ToF. Please consult the Pmod ToF Hierarchical Block Library documentation for an overall description of the Hierarchical Block that includes the drivers of the Pmod. 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.\\ ===== Demo Modules ===== Besides the Pmod ToF library modules that can be consulted in the Pmod ToF Hierarchical Block Library documentation, there are two more modules that extend the Pmod ToF functionality. These modules are described below: *PmodToFCMD Module *UART Module ===== PmodToFCMD Module ===== The PmodToFCMD Module implements a command interpreter that has the following functionality: - The module listens over UART for individual Pmod ToF commands. The user must provide these commands by using a terminal connected to the USB port corresponding to the connected Zybo Z7-20 board. - The commands are recognized by the PmodToFCMD Module and are implemented by calls to necessary modules. - The command interpreter send the command's output messages over UART (see the UART module), which can be seen in the terminal.\\ It is important to comply with each command's expected formalism. The command interpreter loop is implemented in the PmodToFCMD_CheckForCommand function.\\ The following list enumerates the commands implemented in the PmodToFCMD module: * ToFMeasure * ToFStartCalib * ToFSaveCalib * ToFRestoreFactCalib * ToFReadSerialNo For details about calibration, see the [[pmod:pmodtof:libraryuserguide#calibration|Calibration]] section in [[pmod:pmodtof:libraryuserguide|Pmod ToF Hierarchical Block Library]] documentation.\\ \\ ==== PmodToFCMD_CheckForCommand ==== === Synopsis: === >void PmodToFCMD_CheckForCommand(); === Parameters: === > === Return Value: === > === Description: === >This function checks on UART if a command was received.\\ >It compares the received command with the commands defined in the commands array. If recognized, the command is processed accordingly.\\ === Example: === >#include "PmodToFCMD.h"\\ >PmodToFCMD_CheckForCommand(); \\ ==== ToFMeasure ==== === Syntax: === >“ToFMeasure” === Description: === >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. === Parameters: === > === Response: === > After issuing the command: “OK,Distance measured D = x mm.” \\ ==== ToFStartCalib ==== === Syntax: === >“ToFStartCalib,” === Parameters: === | | This is the real distance value in meters for which the manual calibration is performed.\\ Distance must be more than 5 cm (0.05 m). | === Example: === >“ToFStartCalib,1.5”\\ Calibration is performed at a distance of 1.5 m. === Description: === >This command performs a manual calibration. It calls all 3 calibration routines as described in the [[https://www.renesas.com/us/en/www/doc/application-note/an1724.pdf|ISL29501 Firmware Routines (an1724.pdf)]] documentation. === 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. | \\ ==== ToFSaveCalib ==== === Syntax: === >“ToFSaveCalib” === Parameters: === > === Description: === >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. | \\ ==== ToFRestoreFactCalib ==== === Syntax: === >“ToFRestoreFactCalib” === Parameters: === > === Description: === >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. | \\ ==== ToFReadSerialNo ==== === Syntax: === >“ToFReadSerialNo” === Description: === >This command retrieves the 12 digit serial number information from EEPROM and displays the Pmod's serial number over UART. === Parameters: === > === 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. | \\ ===== UART Module ===== The UART Module implements the functionality needed to communicate with the host computer using the UART_PS1 hardware interface of the Zybo Z7-20 board, connected to the USB - UART.\\ For example, using this module, UART communication between the Zybo Z7-20 and a PC can be implemented over a USB cable. Connecting the Zybo Z7-20 to the PC creates a new COM port which can be used in a simple terminal application.\\ The module initializes the UART without interrupts. The polling method is used to receive available characters.\\ This module has no PmodToF functionality. It is just included to provide communication capabilities. It doesn't have to be include in an application that doesn't need communication (for example an application that uses an LCD connected to the Zybo Z7-20 board). We recommend initializing the module at a **baud rate of 115200** for a basic application.\\ This module is only accessed by PmodToFCMD Module.\\ The module provides:\\ - Initialization function:\\ * UART_Init\\ - Character string transmit function:\\ * UART_PutString\\ - Character string receive function:\\ * UART_GetString\\ ==== UART_Init ==== === Synopsis: === >u8 UART_Init(u32 dwBaudRate); === Parameters: === | u32 dwBaudRate | UART baud rate\\ for example 115200 corresponds to 115200 baud | === Return Value: === uint8_t - The error code: |ERRVAL_SUCCESS| 0|success| |ERRVAL_DMM_UARTERROR| 0xEE |UART Init error| === Description: === >This function initializes the UART-PS controller at the specified baud rate.\\ === Example: === >#include "uart.h"\\ >UART_Init(115200); ==== UART_PutString ==== === Synopsis: === >void UART_PutString(char szData[]) === Parameters: === |char szData[]|the zero terminated string containing characters to be transmitted over UART| === Return Value: === > === Description: === >This function transmits all the characters from a null-terminated string over UART1.\\ The terminating null character is not sent.\\ === Example: === >#include "uart.h"\\ >UART_PutString("Hello World\r\n"); ==== UART_GetString ==== === Synopsis: === >uint8_t UART_GetString(char* pchBuff, int cchBuff) === Parameters: === |char* pchBuff|pointer to a char buffer to hold the received zero terminated string| |int cchBuff|size of the buffer to hold the zero terminated string| === Return Value: === > === Description: === >This function provides a null-terminated string received over UART1 which was placed in the circular buffer by the UART interrupt handler.\\ >If a received string is available in the circular buffer, the string is copied in the pchBuff string and its length is returned.\\ >Otherwise, the function returns 0. === Example: === >#include "uart.h"\\ >cchi = UART_GetString(uartCmd, 0x40); \\ ---- {{tag>pmod pmodtof zynq-demo}}