Quick Start in VSCode Basic

This guide will give a PROTOS miniHIL user a basic understanding of the PROTOS miniHIL hardware and software by showing them how to run a simple example project in VSCode.

Note Before following this guide, you will have to set up your VSCode IDE to enable the necessary miniHIL and eTrice plugins. The steps to do this can be found in the VSCode IDE guide.

Prerequisites

Included in the PROTOS miniHIL package you should find:

  • the PROTOS miniHIL board

  • a 24V power supply

  • Wire jumpers

  • USB cable

You should also have received login details for the PROTOS download site where you can download the latest version of the miniHIL software packages (https://dl.protossoftware.de).

Overview over the hardware

The picture below gives an overview over the PROTOS miniHIL hardware.

SimulatorCommented

In the Hardware section you can find the detailed definitions and functionalities of PROTOS miniHIL hardware.

Setting up the hardware

  1. Connect the ST-Link debugger to the SWD port on the miniHIL board and the PC

  2. Connect the USB-1 port on the miniHIL board to the PC

  3. Connect the power supply to the miniHIL board and plug it in to a power socket.

The correct hardware configuration is shown in the image below. Notice the two green LED’s on the top left of the board, which will turn on when the miniHIL board is powered correctly.

miniHILConnected

Installing the software

To install the software, follow the VSCode IDE guide and install the necessary plugins. To verify that the plugins were installed correctly, navigate to the extensions tab in VSCode and see if the eTrice and miniHIL plugins appear like in the images below.

Extensions

Another way to verify the correct installation of the plugins when working on the example projects is to look for Open Structure Diagram | Open Behavior Diagram in the MiniHilProject.room files. They should appear directly above the ActorClass Application after the language server has started.

We can now begin by navigating to the PROTOS miniHIL download page (https://dl.protossoftware.de/minihil) and downloading the following zip files:

  • Example Project

  • Template Project for use with miniHIL hardware

  • External Tools

Now create a folder called "miniHIL" in your computer’s root directory. The path of this folder should be C:\miniHIL. Then extract the contents of each .zip file into the newly created miniHIL directory and copy the .zip files of the Example Project and the Template Project into this folder as well. Ensure that you haven’t created subfolders inside tools after extracting the zip files.

Note Use 7-Zip to extract the zip files, not the built-in Windows extraction tool. Some files in the IDE package have long path names that the Windows extractor cannot handle correctly.

Create a new empty folder named workspaces, which is where the workspace data from your projects will be stored. Create a second new empty folder named protosLicense, which is where you will place your miniHIL software license file once you receive it. Inside the C:\miniHIL directory you should now see this:

C:\miniHIL\
├── MiniHilProject_Examples\
├── MiniHilProject_Template_cube\
├── tools\
│   ├── arm-gcc\
│   ├── cube-programmer\
│   ├── gradle\
│   ├── graphviz\
│   ├── jlink\
│   ├── jre\
│   ├── python\
│   ├── st-link\
│   ├── trace2uml\
│   └── ...
├── protosLicense\
└── workspaces\
Note While following this user Guide you will apply changes to the Example Project and the Template Project, but also might want to access an unchanged Project later. You can then simply delete the existing top-level project folder and extract the project from the .zip file again.

Verifying the miniHIL installation

Software license

The miniHIL IDE requires a valid software license to start. If you haven’t already placed a license in the correct folder, a license error dialog will appear on your screen telling you where the license should be placed and disabling the language server.

For older versions of the plugin, the license check may not yet be implemented, in which case the license error dialog won’t appear despite not having a license. This is intended behavior and means you currently do not require a license and don’t need to request one.

Note

If the license dialog appears: this is your quickest way to obtain your Host ID (also called Node ID or Machine Key). The dialog displays your Host ID directly – copy it from there and include it in your license request email to minihil@protos.de.

Once you have received your .lic license file, place it in C:\miniHIL\protosLicense and relaunch the IDE. See the Setup miniHIL Software License guide for full details.
license error
The license error dialog, showing searched folders and your machine key.

Running your first project

The first project we will run on the miniHIL is in the MiniHilProject_Examples folder and to begin we will need to open this folder in VSCode. To do so either navigate to C:/miniHIL/MiniHilProject_Examples in your file explorer, right click in the folder and click "Open in Code", or open VSCode and in the topleft, select file→open folder and navigate to the C:/miniHIL/MiniHilProject_Examples folder. You should then see the following file structure in VSCode:

VSCodeFileStructure

It is important that the following folders and files are contained and these will also be the main files you work on in miniHIL projects:

  • HilSimGUI: The miniHIL dashboard for executing tests and seeing outputs

  • minihillib: miniHIL library containing miniHIL software

  • MiniHilProject.room: The actual project

  • gradlew.bat: A gradle file for building and flashing the project

At this point you can begin experimenting with the VSCode miniHIL plugins by examining the code in C:/miniHIL/MiniHilProject_Examples/MiniHilProject/model-user/MiniHilProject.room. Here you can navigate to the ActorClass Application and open a structure diagram by either pressing Ctrl + Shift + Alt + S while the ActorClass is focused, or by pressing the open structure diagram button. Opening a behavior diagram won’t work here because the ActorClass’s behavior isn’t defined.

StructureDiagramCode
Structure diagram button in VSCode.
StructureDiagram
Structure diagram in VSCode.

Feel free to experiment with the code after completing this tutorial.

First build and flash

In the bottom left corner of VSCode, underneath the file explorer, there is a section labeled MINIHIL PROJECTS that allows you to build and flash projects to the miniHIL. See the VSCode IDE guide for more details.

ExtensionFlash

  1. Make sure the miniHIL’s ST-Link debugger and USB-1 port are connected to your PC as described above.

  2. Click the flash button to build and run your project on the miniHIL board. Alternatively build and flash the project by running the terminal commands .\gradlew.bat build and .\gradlew.bat flash in the folder C:/miniHIL/MiniHilProject_Examples.

Using the miniHIL dashboard and executing tests

  • In the miniHIL Projects section in the bottom left, click the "Run Dashboard" button to start up the GUI. A command line window should open up, after a short moment the gui (dashboard) should open in a new browser tab.

  • At the top left corner of the newly opened browser tab, ensure that the "USB" connection is selected and that the Port selection dropdown window next to it has "Automatic" selected. If the board was detected correctly the connection should have automatically been established.

dashboard connection bar
Connecting the dashboard to the miniHIL board

  • If the connection has been established successfully the example test suite should be visible on the left. To verify if everything is working as intended you should run this testsuite. To run the test suite, navigate to the CaGe menu on the left, select Heartbeat_TestSuite and click on Run Tests button at the top.

run heartbeat testsuite
Running tests from the dashboard

  • If the tests ran successfully, you will see passed after each of the tests executed. Additionally the right side of the dashboard window will show you the trace which has been recorded during test execution. You have now verified that your miniHIL installation is setup correctly.

post run heartbeat testsuite
Dashboard after executing the example test case

Connecting a Device Under Test (DUT)

Included in your miniHIL package, you should find an STM32F303 Nucleo-64 board. We will use this board to demonstrate the Target Device functionality of the miniHIL board.

Connect the Nucleo board to the miniHIL board as shown in the picture below.

DUT 1

When connecting a Nucleo board to the miniHIL, you should change the power mode of the Nucleo board, so that it gets its 5V via the miniHIL and not via the USB connector.

5VoltJumper
In Order to do so you have to put the Jumpers as shown in this picture.

The STM32F303 also uses an ST-Link debugger. If you have the miniHil-ST-Link and the DUT-ST-Link connected to your PC at the same time, the IDE won’t know which debugger to choose if you want to flash your Project.
Simply disconnect the device you don’t want to flash right now.

How to Find the Serial Number (SN) of your ST-Links:

  1. Open the console and navigate to the:

    tools\cube-programmer\bin

  2. Run the following command:

    .\STM32_Programmer_CLI.exe --list

This command will display a list of all connected ST-Link devices along with their respective serial numbers (SN).

Troubleshooting

Note If no ST-Link device is detected, try installing the ST-Link driver located at: 
tools\cube-programmer\Drivers\stsw-link009_v3