First steps with the UltraZohm

Aim of the tutorial

In this tutorial the initial steps, which are needed to get the UltraZohm running after cloning the repository, are shown.

Requirements

The following tutorial requires:

• Complete Xilinx Toolchain (Vivado, Vitis) installation

• Git installation

• Java installation

• Cloned the UltraZohm repositories from Bitbucket

• Generated Vitis workspace

• UltraZohm connected to your PC by Ethernet and USB (JTAG)

UltraZohm Setup

The UltraZohm has to be connected to a PC by Ethernet and USB (JTAG-Programmer).

Initial steps

1. Open the Git terminal inside the cloned UltraZohm repository, or alternatively do the following steps via your git-client (e.g. Sourcetree (git GUI)).

2. Change your active branch from main to develop by using the checkout keyword (e.g. git checkout develop ).

   • The develop is the current development branch with the latest merged changes made to the UltraZohm repository. Every new feature branch will be created from this point.

   • The main branch is the latest stable version.

   • For further information see Contribution Workflow.

3. Create a new local branch with an appropriate name (e.g. name_tutorial) on which the changes made throughout the tutorial will be made.

   Warning

   This branch is only used locally for the tutorials. Do not push any changes to the remote repository.

4. Start Vitis and open up the workspace folder ( ultrazohm_sw/vitis/workspace ) of the UltraZohm repository.

   • Vitis is used, when changes to the code-base on the Processor (PS) have to be made. E.g. if you want to run a control-algorithm on the ARM-Cortex processors of the UltraZohm, you have to make changes in Vitis.

   • Vivado is used, when changes to the programmable logic (PL) on the FPGA have to be made.

5. Build the project by clicking on the red highlighted hammer visible in Fig. 1.

   • Whenever changes have been made to the code base. This button has to always be pressed.

   • If this button is not pressed after changes have been made, these changes can’t be flashed onto the UltraZohm and the previousely build binary is programmed (without the changes!).

   

   Fig. 1 Building the workspace

6. If you haven’t made any changes to the code-base after the generation of the Vitis workspace, the build will lead to errors depicted below.

   • Whenever you made changes to the codebase and the build leads to errors, they have to be fixed, otherwise the UltraZohm can not be flashed properly. This is because the errors stop the compiler from compiling the entire workspace.

   • Whilst Warnings do not prohibit the UltraZohm from working, they should be fixed nonetheless.

   

   Fig. 2 Errors after building the workspace

7. These errors exist, because the file uz_global_configuration.h doesn’t exist.

   • This file is the configuration file for the UltraZohm and has to be adjusted to your specific needs.

   • For how to create this missing file see Global configuration.

   • After you copied the contents of default_uz_global_configuration.h into the new file, no changes except the UZ_HARDWARE_VERSION have to be made. Adjust this number to the version number of your UltraZohm.

8. Build the workspace again. No error should pop up anymore.

9. Flash the UltraZohm by either pressing the debug or the run icon in the green highlighted area in Fig. 3 and select Debug Configurations …. Vitis will remember the last selection, which means, that for a future flashing operation, the last debug config is already preselected.

10. Use for the debug/run selection the Debug_FreeRTOS_Baremetal_FPGA configuration.

    

    Fig. 3 Debug configuration in Vitis.

11. If the flashing was successful, the Ready LED will blink slowly.

12. Make sure, that you have configured your Ethernet-to-USB adapter according to this guide.

13. Start the uz_GUI in the folder ultrazohm_sw/javascope by double clicking on the UZ_GUI.jar file or executing the javascope_run.bat file.

14. Press the Connect button in the GUI. Now the GUI should be up and running.

    • If the connection was successful, the field left of the IP-address is moving.

    • If nothing happens, checkout the known issues section.

15. Five default channels are visible in the scope after pressing the Run/Stop and the sendSelectData (all) button.

    • To get the signals into the scope view, adjust the scaling of the first 3 channels.

    • Adjust the time base of the Scope via the setTime button and the dropdown menu to x10 .

    • FYI, the values for the channels theta_mech and ua are in the default case 0.

    

    Fig. 4 Visible signals after GUI has been connected.

16. Get yourself familiar with the GUI by trying different things in the GUI. For further information read the sections about the Setup Scope Page, Control Page and Logging Panel.

17. In the next tutorial changes will be made to the code-base and the GUI will be customized.