Knowledge Base

Welcome to OPAL-RT’s Knowledge Base

OPAL-RT offers a repository of support information for optimal use of its technology.

Please note that OPAL-RT knowledge base is not fully optimized for mobile platforms.

For optimal experience, use a desktop computer.

Reference Number: AA-02086 // Views: 1 // Created: 2022-08-09 16:19:54 // Last Updated: 2022-08-10 08:57:34
General Article
Getting Started With Git and RT-LAB

This article presents a few possible workflows to version RT-LAB projects with Git. 


What is Git?


"Git is a DevOps tool used for source code management. It is a free and open-source version control system used to handle small to very large projects efficiently. Git is used to tracking changes in the source code enabling multiple developers to work together on non-linear development"

Definition from https://www.simplilearn.com/tutorials/git-tutorial/what-is-git

In other words, the tracking capability of Git made this tool extremely popular that is often used in project development, esp. for projects with several developers. 

A full training course can be found here: https://www.simplilearn.com/tutorials/git-tutorial


NOTE: attached to this article, you will find a git ignore file that can be used as a starting point for your project (remove the .txt at the end). It lists the most common extension files that are not required. 


What is the Architecture of an RT-LAB Project?

To understand how to efficiently use Git with an RT-LAB project, the first step is to understand the architecture under the hood.

Let's start by looking at the files created in a simple 1 subsystem model (one SM and one SC): 


The figure above shows the tree of all the main files created. Most of them are created during compilation and thus are not mandatory to version as a model can be recompiled.

The main files are:


Name of File
Description
 <Name of Project>.llp
This is the main project file. For instance, It is used by the Python API  to connect to that project.
<Name of Model>.llm
In this file are saved all the configurations for the RT-LAB project. For instance, when the extra files are added in the 'Files' tab, or if variables such as 'DISABLE_FLASH_UPDATE', they are written in this file.

<Name of Model>.mdl or .slx
The main Simulink file
<Name of Model>.probe
The settings for the Probe Control are saved in this file. 
Configuration Folder
In this folder are saved the different configuration sets, IO interfaces, mapping done to the drivers, etc. Do not modify as they are using hash identifier. Trying to modify one link will most likely break some links.

Note that there are more files depending on the feature used. For instance, if eHS is used, there are some extra files for the FPGA model.



Limitations of RT-LAB with Git

1. Since there are several files automatically created, projects can become quite big quite fast.

2. There is a file called LoadParam.json that is automatically created when opening a project and adds a suffix, which creates issues when pulling into an existing project. This is not a problem when using only one computer, but it will be problematic when using two or more computers.

3. Do not forget that there is a limit of 256 characters for the complete path. Therefore the git directory should be as close as C:\ as possible, since RT-LAB creates many sub-folders automatically.

4. When updating to a new RT-LAB version, it is recommended to use a new workspace. Therefore, the git directory needs to change accordingly.

5. When we pull a project into an existing workspace, but as a new project, this project will not appear in the RT-LAB GUI. It needs to be imported.

6. The targets are not saved inside the workspace. They are saved in C:\ProgramData\OPAL-RT\RT-LAB\<version>\Config

7. Recall that spaces are not supported in the path.

8. For the Schematic Editor, the model must be exported before committing (and reimported when pulling). This is because the Schematic Editor is saving the models into a local database.



Workflow 1: Commit the Whole Workspace

The simplest approach is to commit all the files. 

The only limitation is that it must always be pulled into an empty directory and afterwards the workspace can be opened in RT-LAB. 


In the screenshot below, we can see that the import of a full workspace into 'C:/gitExample2/' was successful and RT-LAB could open and see all the projects in it.





Workflow 2: Keeping Only the Essential Files and Rebuild the Project from Scratch

This require a certain knowledge of the required files. The main required files are described above, but depending on the model, there could be more files required.

Here is an example with an RT-LAB and eFPGASIM model (using the S-Function workflow) and GitHub as versioning tool.


Step 0: Make sure your model is working as expected. Don't be the colleague that is committing something that is broken ;)

In this example, there are no drivers (i.e. no IO interfaces), therefore, we create git repository directly at the model's level.

NOTE:
 If you have an IO interface configured, you can follow the section 'Extra Information' to create simpler files to export.

Step 1: Create a new repository at the same level than the






Step 2: Exclude All non-required files. For a model with eFPGASIM (S-Function workflow) and RT-LAB, only the following files are mandatory:

a. Bitstream file (.bin) + configuration file (.conf)

b. CPU model (.mdl or .slx)

c. FPGA model (.mdl or .slx)

d. <model name>.llm.

e. <model name>.probe

f. ParametersInitialization.m




Step 3. Commit to main.



Step 4. In the case of GitHub, we also need to publish to the repository to GitHub




Step 5. Verify that the files are properly uploaded:




Step 6: Download the files (whether using a git pull / clone or by downloading them directly).




Step 7: Create a new RT-LAB Project (note: two projects cannot have the same name inside one workspace).



Step 8. Import the files



You are done!


NOTE: If you don't want to create the RT-LAB project manually, you can follow this article to use a Python script to do it automatically: RT-LAB Python API Script Example to Create a New Project



Workflow 3: Committing Only Zip Packages

it is possible to create packages of the project that can be easily imported. It is also possible to export a whole workspace (.rtlab) and to reimport the whole workspace afterwards.



Extra Information: Using Python to export IO interface and Connections

Did you know it is possible to export the IO interfaces as a .rios file and the Connections as .csv? This way, there is no need to version the whole Configuration folder!

How To Export and Import IO Interfaces

How To Export and Import IO Connections





gitignore.opal-rtlinux.x86_64.txt327 bDownload File