Skip to content

#26 review README and add docs #31

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Nov 6, 2025
Merged

#26 review README and add docs #31

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b9355ec
#26 review README and add docs
edmc25 Oct 22, 2025
64b17d5
Update docs/WINDOWS_DEPENDENCIES.md
edmc25 Nov 6, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
319 changes: 45 additions & 274 deletions Readme.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,298 +1,69 @@
OpenXilEnv
==========
# OpenXilEnv

OpenXilEnv is a lightweight SIL/HIL environment. At the moment OpenXilEnv focus one SIL environment.
OpenXilEnv is a lightweight SiL/HiL environment. At the moment, OpenXilEnv focuses on SiL environments.

SIL:
====
## SiL

With a **S**oftware **I**n the **L**oop system it is possible to run and test embedded software without a target plattform and compiler. XilEnv is an environment to setup a SIL system on Windows or Linux host. It will be clean separate it own componnts from the embedded software under test with a network layer. Each component can run in an own executable, they are memory protected against each other. Communication between software under test, model and XilEnv are made with socket or on Windows Named pipe / Linux local sockets
and will be used for:
- Signal transfers.
- Virtual network (CAN and CAN FD) transfers.
With a **S**oftware **I**n the **L**oop system, it is possible to run and test embedded software without a target platform or compiler.
XilEnv provides an environment to set up a SiL system on Windows or Linux hosts. It clearly separates its own components from the embedded software under test through a network layer. Each component can run in its own executable, providing memory protection between them.

![XilEnv SIL system](OpenXilEnv_Sil.png)
Communication between the software under test, models, and XilEnv is done via sockets or (on Windows) named pipes / (on Linux) local sockets. These are used for:
- Signal transfers
- Virtual network (CAN and CAN FD) transfers

**XilEnvGui** have a configurable graphical user interface base on Qt. There exist value display/change, oscilloscope, calibration, slider, knob, ... elements for interaction.
![XilEnv SiL system](OpenXilEnv_Sil.png)

**XilEnv** have no graphical user interface and can be used for automation with no user interaction.
**XilEnvGui** provides a configurable graphical user interface based on Qt. It includes display/change widgets, oscilloscopes, calibration tools, sliders, knobs, and other interaction elements.

- Current GCC compiler with dwarf debug information is Supported. Visual Studio compiler only withot debug information.
- FMUs with FMI2.0 interface are supported (by **ExtProc_FMU2Extract(.EXE)**, **ExtProc_FMU2Loader32(.EXE)**, **ExtProc_FMU2Loader64(.EXE)**)
Partial FMI3.0 interface are supported (by **ExtProc_FMU3Extract(.EXE)**, **ExtProc_FMU3Loader32(.EXE)**, **ExtProc_FMU3Loader64(.EXE)**)
(It will be only support the additional datatypes).
- An small A2L parser is included for calibration.
- With a XCP over ethernet port a connection to a calibration systen is possible.
- Multicore support with barriers for synchronisation.
- XilEnv is automatable through a remote procedure call interface **XilEnvRpc.DLL/.so** or a buildin script interpreter.
- The software under test, FMU and the model can be a 32 or 64bit executable (a mixture is allowed). XilEnv must be a 64bit executable
- Time is simulated with a fixed configurable period with a resolution of 1ns.
- Residual bus simulation of none existing CAN (FD) bus members are available.
- A recording and stimulation is possible with text or MDF3 files.
**XilEnv** (CLI) has no graphical user interface and can be used for automation without user interaction.

The DLL/shared library **XilEnvExtProc64.DLL/.so** or **XilEnvExtProc32.DLL/.so** are the interface for the embedded test software or model.This DLL/shared libray must be load dynamically. The main module **XilEnvExtProcMain.c** will do this for you. The declaration of the interface functions lives here: **XilEnvRtProc.h**. An easy example can be found inside the folder "Samples/ExternalProcesses/ExtProc_Simple".
Main features:
- Supports current GCC compilers with DWARF debug information. Visual Studio compiler is supported but without debug information
- FMUs with FMI 2.0 interface are supported via **ExtProc_FMU2Extract(.exe)**, **ExtProc_FMU2Loader32(.exe)**, and **ExtProc_FMU2Loader64(.exe)**
- Partial FMI 3.0 support (additional datatypes only) via **ExtProc_FMU3Extract(.exe)**, **ExtProc_FMU3Loader32(.exe)**, and **ExtProc_FMU3Loader64(.exe)**
- Includes a small A2L parser for calibration
- Supports XCP over Ethernet for connection to a calibration system
- Multicore support with synchronization barriers
- Automatable via **XilEnvRpc.dll/.so** or the built-in script interpreter
- Supports 32- and 64-bit executables (mixed allowed). XilEnv itself must be 64-bit
- Time simulation with fixed, configurable period and 1 ns resolution
- Residual bus simulation for missing CAN (FD) members
- Recording and stimulation supported via text or MDF3 files

HIL option:
===========
The DLL/shared library **XilEnvExtProc64.dll/.so** or **XilEnvExtProc32.dll/.so** provides the interface for the embedded test software or model. This DLL/shared library must be loaded dynamically. The main module **XilEnvExtProcMain.c** handles this automatically.

To use OpenXilEnv as a HIL system a second PC with Linux is necessary. Currently only socket CAN (FD) are supported as hardware interfaces. A defined time response < 1ms are possible if RT-Preempt patch is installed.
Interface functions are declared in **XilEnvRtProc.h**.

To fulfill defined time response requirement XilEnv will be spit into two pieces (one with a defined time response and one without defined time response)
All component of XilEnv needed defined time response will be extracted to a shared library **LinuxRemoteMasterCore.so** the rest stays inside the XilEnv executable. The part with defined time response must be executed on a Linux systen with RT-Preempt patch installed. The part with no defined time response can be execute on Linux or Windows. Between both a local (point to point) ethernet connection should be established. If a model is needed it must be compiled for Linux and must load the shared library **LinuxRemoteMasterCore.so** If no model is needed **LinuxRemoteMaster.Out** can be used. The service **RemoteStartServer** should be installed and actived on the second PC. So XilEnv can control the second PC to copy and start all needed executable from the main PC
An example can be found in `Samples/ExternalProcesses/ExtProc_Simple`.

Table of contents
=================
## Getting Started

* [Source Code](#source-code)
* [Build Instructions](#build-instructions)
* [Windows](#windows)
* [Build options](#build-options-windows)
* [Install dependencies](#install-dependencies-window)
* [Build and install](#build-and-install-windows)
* [Run example](#run-example-windows)
* [Linux](#linux)
* [Build options](#build-options-linux)
* [Install dependencies](#install-dependencies-linux)
* [Build and install](#build-and-install-linux)
* [Run example](#run-example-linux)
* [Setting up your project](#setting-up-your-project)
* [Setup an own external process](#Setup-an-own-external-process)

# <a name='source-code'></a> Source Code
1. Install dependencies ([Windows](docs/WINDOWS_DEPENDENCIES.md) | [Linux](docs/LINUX_DEPENDENCIES.md))
2. Build the project ([Windows](docs/WINDOWS_BUILD.md) | [Linux](docs/LINUX_BUILD.md))

You can get OpenXilEnv from:
## Setting up Your Project

- <https://github.com/eclipse-openxilenv>
- [Setup an External Process](docs/EXTERNAL_PROCESS_SETUP.md)

# <a name='build-instructions'></a> Build Instructions
## HiL Option

## <a name='windows'></a> Windows
To use OpenXilEnv as a HiL system, a second Linux PC is required. Only **SocketCAN FD** interfaces are supported.

### <a name='install-dependencies-window'></a> Install dependencies
For <1 ms response times, install the **RT-Preempt** patch.

- Qt Library 5.12.9 ... 6.7.2
- MinGW 11.2
- Strawberry perl
- pugixml-1.11 (optional if -DBUILD_WITH_FMU2_SUPPORT=ON or if -DBUILD_WITH_FMU3_SUPPORT=ON)
OpenXilEnv is split into:
- **LinuxRemoteMasterCore.so** – real-time (Linux with RT-Preempt)
- **XilEnv executable** – non–real-time (Windows or Linux)

<https://pugixml.org/>
<br/>
Use a direct Ethernet connection between PCs.

- FMU Parser (optional if -DBUILD_WITH_FMU2_SUPPORT=ON or if -DBUILD_WITH_FMU3_SUPPORT=ON)
If a model is needed, compile it for Linux and link with **LinuxRemoteMasterCore.so**.
If not, use **LinuxRemoteMaster.out**.

<https://github.com/modelica/fmi-standard/releases/download/v3.0.1/FMI-Standard-3.0.1.zip>
Ensure **RemoteStartServer** is installed and running on the Linux PC to allow remote execution.

<https://github.com/modelica/fmi-standard/releases/download/v2.0.4/FMI-Standard-2.0.4.zip>
<br/>

### <a name='build-options-windows'></a> Build options
```
> -DBUILD_EXAMPLES=ON/OFF (default is ON)
> -DBUILD_WITH_FMU2_SUPPORT=ON/OFF (default is OFF)
> -DFMI2_SOURCE_PATH=<path>
> -DPUGIXML_SOURCE_PATH=<path>
> -DBUILD_WITH_FMU3_SUPPORT=ON/OFF (default is OFF)
> -DFMI3_SOURCE_PATH=<path>
> -DPUGIXML_SOURCE_PATH=<path>
> -DBUILD_ESMINI_EXAMPLE=ON/OFF (default is OFF)
> -DESMINI_LIBRARY_PATH=<path>
> -DCMAKE_BUILD_TYPE=Debug/Release (default is Release)
> -DCMAKE_INSTALL_PREFIX=../install_win
> -DBUILD_32BIT=ON/OFF (default is OFF, if you want to build the 32 bit support you need also a 32 bit MinGW)
```
### <a name='build-and-install-windows'></a> Build and install

Open a command box and enter folowing commands:

```
> mkdir xxx\openxilenv\build_win
> cd xxx\openxilenv\build_win
> set PATH=[PathToQt]\bin;%PATH%
> set PATH=[PathToGcc]\bin;%PATH%
> set PATH=[PathToStrawberry]\c\bin;%PATH%
> set PATH=[PathToCMAKE]\bin;%PATH%
> cmake -G [YOUR Compiler] [CMAKE-LIST-FILEPATH] [BUILD OPTIONS]
> cmake --build .
```

Install
```
> cmake --install .
```
Install optional (copy the Qt DLL to the install folder)
```
> cd xxx\openxilenv\install_win
> windeployqt6.exe XilEnvGui.exe
```
### <a name='run-example-windows'></a> Run example

Running the electric car sample
```
> cd xxx\openxilenv\install_win
> .\XilEnvGui.exe -ini ..\Samples\Configurations\ElectricCarSample.ini
```

## <a name='linux'></a> Linux

### <a name='install-dependencies-linux'></a> Install dependencies

- Qt Library 5.12.9 ... 6.7.2
- pugixml-1.11 (optional if -DBUILD_WITH_FMU2_SUPPORT=ON or if -DBUILD_WITH_FMU3_SUPPORT=ON)

<https://pugixml.org/>
<br/>

- FMU Parser (optional if -DBUILD_WITH_FMU2_SUPPORT=ON or if -DBUILD_WITH_FMU3_SUPPORT=ON)

<https://github.com/modelica/fmi-standard/releases/download/v3.0.1/FMI-Standard-3.0.1.zip>

<https://github.com/modelica/fmi-standard/releases/download/v2.0.4/FMI-Standard-2.0.4.zip>
<br/>

### <a name='build-and-install-linux'></a> Build and install

Open a bash and enter folowing commands:

```
> mkdir xxx/openxilenv/build_linux
> cd xxx/openxilenv/build_linux
> cmake -DBUILD_EXAMPLES=ON -DCMAKE_INSTALL_PREFIX=../install_linux -DCMAKE_BUILD_TYPE=Release ../.
> cmake --build .
```

Install
```
> cmake --install .
```

### <a name='run-example-linux'></a> Run example

Running the electric car sample
```
> cd xxx\openxilenv\install_linux
> ./XilEnvGui -ini ../Samples/Configurations/ElectricCarSample.ini
```

#### <a name='build-options-linux'></a> Build options

```
> -DBUILD_EXAMPLES=ON/OFF (default is ON)
> -DBUILD_WITH_FMU2_SUPPORT=ON/OFF (default is OFF)
> -DPUGIXML_SOURCE_PATH=<path>
> -DFMI2_SOURCE_PATH=<path>
> -DBUILD_WITH_FMU3_SUPPORT=ON/OFF (default is OFF)
> -DPUGIXML_SOURCE_PATH=<path>
> -DFMI3_SOURCE_PATH=<path>
> -DBUILD_ESMINI_EXAMPLE=ON/OFF (default is OFF)
> -DESMINI_LIBRARY_PATH=<path>
> -DCMAKE_BUILD_TYPE=Debug/Release (default is Release)
> -DCMAKE_INSTALL_PREFIX=../install_win
> -DBUILD_32BIT=ON/OFF (default is OFF)
```

# <a name='setting-up-your-project'></a> Setting up your project
# <a name='Setup-an-own-external-process'></a> Setup an own external process

An easy simple external process have to provide 4 functions.
```
void reference_varis (void)
```
This function will be called one time if the process is started. Here should be added all signals the process is needed

```
int init_test_object (void)
```
This function will be called after the reference_varis function. Here can be done some initialization stuff.

```
void cyclic_test_object (void)
```
This is the main cyclic function of the external process this will be called for each simulated time cycle.

```
void terminate_test_object (void)
```
This function will be called one time if the external process will be terminated.

Source code of ExtProc_Simple.c
(you caan find the code also inside the folder xxx\openxilenv\Samples\ExternalProcesses\ExtProc_Simple)

```
#include <stdlib.h>
#include <stdio.h>
#include <math.h>

#define XILENV_INTERFACE_TYPE XILENV_DLL_INTERFACE_TYPE
#include "XilEnvExtProc.h"
#include "XilEnvExtProcMain.c"

// Global variable of the external process
short Ramp;
double Sinus;
short Random;
double SampleTime;

// use volatile const to avoid compiler optimization
volatile const short BOTTOM_LIMIT_RAMP = 0;
volatile const short UPPER_LIMIT_RAMP = 1000;

volatile const double SINUS_AMPLITUDE = 1.0;
volatile const double SINUS_FREQUENCY = 0.2;

// This will be called first if the process is started
void reference_varis (void)
{
REFERENCE_WORD_VAR(Ramp, "Ramp");
REFERENCE_DOUBLE_VAR(Sinus, "Sinus");
REFERENCE_WORD_VAR(Random, "Random");
REFERENCE_DOUBLE_VAR(SampleTime, "XilEnv.SampleTime");
}

// This function will be called next to reference_varis
int init_test_object(void)
{
return 0; // == 0 -> No error continue
// != 0 -> Error do not continue
}

// This will call every simulated cycle
void cyclic_test_object(void)
{
static double SinusTime;
if(Ramp++ > UPPER_LIMIT_RAMP) Ramp = BOTTOM_LIMIT_RAMP;
SinusTime += 2.0 * M_PI * SampleTime * SINUS_FREQUENCY;
Sinus = SINUS_AMPLITUDE * sin(SinusTime);
Random = rand();
}

// This will be called if the external processs will be terminated
void terminate_test_object(void)
{
}
```

To bild this small sample:

On Windows:
```
> gcc -g -I xxx\openxilenv\install_win\include ExtProc_Simple.c -o ExtProc_Simple.exe
```
On Linux:
```
> gcc -g -I xxx/openxilenv/install_linux/include ExtProc_Simple.c -ldl -lpthread -o ExtProc_Simple.EXE
```

Now you should be able to start your own externel process and add this to the electric car sample:

On Windows:
```
> set PATH=%PATH%;xxx\openxilenv\install_win
> ExtProc_Simple.exe -q2 XilEnvGui.exe -ini xxx\openxilenv\Samples\Configurations\ElectricCarSample.ini
```

On Linux:
```
> export PATH=$PATH;xxx\openxilenv\install_linux
> ExtProc_Simple.EXE -q2 XilEnvGui -ini xxx/openxilenv/Samples/Configurations/ElectricCarSample.ini
```
## License
This project is part of the Eclipse Foundation and licensed under the [Apache License 2.0](LICENSE.txt).

## Contributing
Contributions are welcome! Please see the [CONTRIBUTING.md](CONTRIBUTING.md) file for details.
Loading