BeamNG.tech Support for MATLAB and Simulink Add-On

BeamNG.tech Support for MATLAB and Simulink allows connecting the Mathworks products with the BeamNG.tech software with three different methods:

• MATLAB $\leftrightarrow$ BeamNGpy $\leftrightarrow$ BeamNG.tech
• Simulink (S-function) $\leftrightarrow$ BeamNG.tech (co-simulation tool)
• Simulink (FMI) $\leftrightarrow$ BeamNG.tech (vehicle-lua controller)

Both the bridges can be use independently from each other and have different scopes. However, they can be really handy when used together as in this example .

Table of Contents

• MATLAB bridge

  • Getting Started with MATLAB bridge
  • Examples

• Simulink bridge

  • Setting up Simulink
  • S-function
  • Instructions
  • Examples
  • Disclaimer
  • FMI
  • Instructions
  • Examples

• Compatibility

• Troubleshooting

• Contributions

• License

1. MATLAB bridge

The MATLAB bridge with BeamNG.tech is implementation of BeamNgpy in MATLAB through the MATLAB-python integration.

1.1 Setup a compatible python version

After installing the compatible python version with MATLAB, make sure to include the path of executable python file (exe) in your in "path" variable of "environment variables" as explained here.

1.2 Test python engine in MATLAB

make sure that python engine is connected to your MATLAB engine

pe = pyenv;
pe.Version % This should return your python version linked with your MATLAB
pyenv(ExecutionMode="OutOfProcess") % This should return paths for your python executable, library, etc.

1.3 Examples

you can see some examples here of MATLAB scripts that uses BeamNGpy to connect with BeamNG.tech.

2. Simulink bridge

Tightly-coupled systems involve two processes running simultaneously and interacting with each other in a dependent way. This involves one side sending data to the other process and vice versa, on a regular cycle. BeamNG can be coupled to a third party (such as MathWorks Simulink) in this manner. This page outlines some considerations which the user should understand when attempting co-simulation with BeamNG.tech.

2.1 Setting up Simulink:

Just follow this link, and install the toolbox from the MathWorks file exchange.

2.2 BeamNG.tech integration with Simulink S-function

The Co-Simulation Editor allows the BeamNG.tech user to set up a tightly-coupled system between a BeamNG vehicle and third-party software (such as Mathworks Simulink). A GUI-based tool facilitates the creation of .csv files which are used as a contract to describe the parameters of the message-passing between the two sides of the coupling. The user can use the mouse to choose from a multitude of properties across the vehicle (kinematic properties, wheel data, vehicle electrics data, powertrain data, etc) - properties which are to be sent to the third party. Incoming properties (from the third party) are also selected in a similar way.

2.2.1 Instructions

To establish a tight-coupling communication with Simulink through S-function, follow the following steps:

1. Start the BeamNG.tech simulation in your favorite map.

2. Click F11 to access the World Editor .

3. Click on the Co-Simulation Editor.

   

   Figure 1: The Co-Simulation Editor window

4. If you have a your coupling-configuration csv file in your user-folder (it is located in %USERPROFILE%\AppData\Local\BeamNG.tech\0.3x by default), you have to reload the csv by clicking on Start/stop coupling with 3rd party button, then another File dialog window will appear to load your csv.

   

   Figure 2: The File dialog window to load your csv.

5. If you want to create your signals file, click on Open the available signal for this vehicle button, it will open another window where you can select your signals From and To for sending and receiving signals.

   

   Figure 3: The available signal list window.

6. Save your csv by click on save the current signals configuration, for this vehicle, to disk button.

   

   Figure 4: The File dialog window to save your configuration as csv file.

7. Click on Start/stop coupling with 3rd party button at your Co-Simulation Editor window to start the coupling.

8. Open your Simulink model, add your S-function.

9. double-click on your S-function, and type the path of your csv file.

10. Load your csv signals file to your S-function.

    

    Figure 5: Loading csv file window in S-function.

11. Set the Simulation time in Simulink in model settings use Fixedstep type and calculate your Fixed-step size to match the simulation time in BeamNG, using the following formula:

    ceil(SimulinkDt / physicsDt) * physicsDt

    where SimulinkDt is the Simulink computation time, physicsDt is the BeamNG physics step time (fixed at 0.0005 seconds), and ceil is the ceiling operator. Figure below shows where this is set (highlighted in yellow).

    

    Figure 6: The Configuration Parameters window of Simulink model.

12. Run your S-function model in Simulink.

13. To stop coupling, stop coupling at BeamNG.tech end by pressing on the same button that started the coupling i.e., Start/stop coupling with 3ed party , or click on CTRL+R to reload the vehicle, then press on Stop Simulink end.

2.2.2 Examples

We have some examples here that shows basic controller that have S-function connected with BeamNG.tech.

2.2.3 Disclaimer

It's recommended open only one instance of S-function, having more than one instance of S-function might disturb the coupling.

2.3 BeamNG.tech integration with Simulink FMI

A BeamNG FMI for the Functional Mock-up Interface allows the BeamNG.tech user to set up a tightly-coupled system between a BeamNG vehicle and third-party software (such as Mathworks Simulink). The vehicleSystemsCoupling lua controller will facilitates the communication and signal selection.

2.3.1 Run BeamNG FMI in Simulink

The Lua controller must be loaded in order to start the tight coupling. We can do this with the following three steps:

1. Launch the BeamNG.drive simulator and navigate to the main menu.
2. Select the "Freeroam" option to enter the free-roaming mode.
3. Choose your preferred map from the available options.
4. Access the Lua console debug window by pressing the backtick (`) key or the tilde (~) key.
5. The vehicle should then be selected at the bottom-left of this screen (usually this will be “BeamNG - Current Vehicle”).
6. The following command should be typed into the command bar, to load the controller: controller.loadControllerExternal('tech/vehicleSystemsCoupling', 'vehicleSystemsCoupling', {}), or you can use the shortcut for the specific controller i.e., CTRL+V
7. Open your Simulink and add your FMI block.
8. Configure your FMI model by using this format at your Command Window in MATLAB fmudialog.createBusType('<YOUR_MODEL>/<FMI_BLOCK>'). This command should list your inputs and outputs.
9. Run your FMI model.
10. To stop coupling, stop coupling at BeamNG.tech end by pressing on CTRL+V to stop the coupling or CTRL+R to reload the vehicle, then Simulink end.

Figure 7 shows the bar at the bottom of the console window in detail. Note the vehicle selection menu on the left, and the command bar on the right, where one can enter commands.

The Simulink process should also be started. If BeamNG is not running, Simulink will block its execution until it receives a message from BeamNG. The reverse is also true; if Simulink is not executing, BeamNG will block execution.

When communication has been established over the UDP send and receive sockets (after both ends of the communication have started executing), the tight coupling process will commence.

Figure 7: The Console Window Command Bar

2.3.2 Examples

you can see some examples here with Simulink examples, and Simulink only example. To make your custom FMU model, follow the BeamNG FMU repository.

3. Compatibility

Running the BeamNG-MATLAB-Simulink generic interface requires three individual software components, here is a list of compatible versions.

BeamNG.tech	BeamNGpy	BeamNG-MATLAB-Simulink-integration	MATLAB	Python
0.32	1.29	1.3.0	R2023b & later	3.9
0.31	1.28	1.2.0	R2022b & later	3.9
0.30	1.27.1	1.1.0	R2022b & later	3.9
0.29	1.26.1	1.0.0	R2022b & later	3.9

4. Troubleshooting

This section lists common issues with BeamNG-MATLAB-Simulink generic interface in particular. Since this library is closely tied to BeamNG.tech, it is also recommended to consult the support in documentation website on BeamNG.tech

If you can not see the toolbox in your Simulink library Browser, you may have to add the toolbox path to MATLAB search path, please do the following steps:

1- open your MATLAB and navigate to your toolbox folder i.e., %USERPROFILE%\AppData\Roaming\MathWorks\MATLAB Add-Ons\Toolboxes

2- from current folder window, right-click on the toolbox folder, and click on Remove from path, select Selected Folders as shown below

Figure 8: Remove toolbox folder from path

3-Then, right click on the folder and from add path, select Selected Folders and Subfolders as shown below

Figure 9: Add toolbox folder and Subfolders to path

3-Lastly you have to save this changes in MATLAB search path, look for Set Path option and click Save

Figure 10: Save the changes in Set Path

5. Contributions

We always welcome user contributions, be sure to check out our contribution guidelines first, before starting your work.

6. License

Copyright © 2024, BeamNG GmbH. All rights reserved. This project is licensed under the BSD 3-Clause License - see the LICENSE file for details.

The BeamNG FMU is a fork of the Reference FMUs by Modelica Association Project, which are a fork of the Test FMUs by Dassault Systèmes, which are a fork of the FMU SDK by QTronic, all of which are released under the 2-Clause BSD License.