Real-Sim FIXS Development Guide

Guide for working with Real-Sim FIXS (Flexible Interface for XIL Simulation), a multi-resolution X-in-the-loop (XIL) simulation framework for connected and automated vehicle testing developed by ORNL as part of the DOE-VTO-EEMS Real-Sim project.

What This Skill Does

This skill provides comprehensive guidance for developing with Real-Sim FIXS, including:

Architecture Overview

Real-Sim FIXS connects traffic simulators (VISSIM, SUMO), vehicle dynamics tools (CarMaker, Simulink), and virtual environments (Carla) using a client-server socket architecture.

**Core Components:**

**Key Helper Classes:**

Step-by-Step Instructions

1. Understand Project Structure

When starting work on this codebase:

1. **Read the main CLAUDE.md file** to understand the overall architecture

2. **Examine the core components**:

- Start with TrafficLayer/TrafficLayer/mainTrafficLayer.cpp to see the main entry point

- Review CommonLib helper classes (ConfigHelper, SocketHelper, TrafficHelper, MsgHelper)

- Check VehDataMsgDefs.h for message field definitions

3. **Review the build system documentation** in doc/BUILD.md for comprehensive details

4. **Check dependencies.yaml** to understand tool versions and required software

2. Set Up Build Environment

Before building:

1. **Verify prerequisites are installed**:

- Visual Studio 2022 (Community, Professional, or Enterprise)

- CMake 3.10+

- Optional: MATLAB 2024a, CarMaker 13.1.3/11.1.2, dSPACE ConfigurationDesk 2024-A

2. **Review dependencies.yaml** to understand version requirements

3. **Build external libraries first** (if not using full dispatch):

```

scripts\dispatch\1_external_libraries.bat

```

This builds yaml-cpp and libevent using CMake with Visual Studio 17 2022 generator.

3. Build the Project

**For full release build:**

```

dispatch.bat

```

This automatically builds all components and copies them to the `build/` directory, including:

**For development iteration (faster):**

```

Core components only

scripts\dispatch\2_core_components.bat

VISSIM driver models only

scripts\dispatch\3_vissim_components.bat

CarMaker (auto-generates BuildConfig files)

powershell -ExecutionPolicy Bypass -File scripts\dispatch\4a_carmaker_components.ps1

dSPACE libraries

powershell -ExecutionPolicy Bypass -File scripts\dispatch\4b_carmaker_dspace.ps1

MATLAB MEX file

powershell -ExecutionPolicy Bypass -File scripts\dispatch\5_mex_realsim_socket.ps1

```

**Build configuration:**

4. Configure a Simulation

Simulations are configured via config.yaml files:

1. **Review existing test configs** in the tests/ directory for examples

2. **Key sections to configure**:

- **SimulationSetup**: Core settings

- `SelectedTrafficSimulator`: 'VISSIM' or 'SUMO'

- `EnableExternalDynamics`: Allow external control (SUMO)

- `VehicleMessageField`: Array of fields to exchange (see README.md Appendix)

- `SimulationMode`: Sync behavior (0=sync from start, 1=wait for ego entry, 4=wait for specified time)

- **ApplicationSetup**: Application layer subscriptions

- **XilSetup**: XIL system configuration

- **VirtualEnvironmentSetup**: Carla settings

3. **Enable verbose logging for debugging**:

```yaml

EnableVerboseLog: true

```

5. Run Test Scenarios

Test scenarios are organized in the tests/ directory:

1. **Navigate to a test directory**:

```

cd tests/CoordMerge

```

2. **Run the test batch file**:

```

runCoordMergeSUMO.bat

```

3. **Check log files**:

- TrafficLayer.err in TrafficLayer.exe directory

- DriverModelError.txt and DriverModelLog.txt (VISSIM)

6. Modify Simulator Interfaces

To modify how the system interfaces with simulators:

1. **Edit TrafficHelper** (CommonLib/TrafficHelper.h) for general simulator interface code

2. **For VISSIM-specific changes**: Modify code in ProprietaryFiles/VISSIMserver

3. **For SUMO-specific changes**: Work with CommonLib/libsumo integration

4. **Rebuild affected components** using the appropriate dispatch script

5. **Test with existing scenarios** to verify changes

7. Add New Message Fields

To add new vehicle data fields:

1. **Update VehDataMsgDefs.h** (CommonLib/VehDataMsgDefs.h) with the new field definition

2. **Update MsgHelper** pack/unpack logic to handle the new field

3. **Add the field to config.yaml** in VehicleMessageField array

4. **Rebuild core components**:

```

scripts\dispatch\2_core_components.bat

```

5. **Test with a simple scenario** to verify data exchange

8. Create New Controllers

To add a new application-level controller:

1. **Use CoordMerge as a template** (ControlLayer/CoordMerge)

2. **Implement similar socket communication** using SocketHelper

3. **Subscribe to necessary vehicle/detector data** via config.yaml ApplicationSetup

4. **Add build configuration** to appropriate dispatch script

5. **Create a test scenario** with corresponding config.yaml

9. Debug Common Issues

When troubleshooting:

1. **Check error logs**:

- TrafficLayer.err

- DriverModelError.txt and DriverModelLog.txt (VISSIM)

- scripts/dispatch/build.log and build_summary.log

2. **Enable verbose logging** in config.yaml:

```yaml

EnableVerboseLog: true

```

3. **Verify socket connections**:

- Check IP addresses and port numbers in config.yaml

- Ensure no port conflicts with other applications

4. **Check simulator-specific issues**:

- VISSIM: See doc/VISSIMdoc.md

- SUMO: See doc/SUMOdoc.md

- CarMaker: See doc/CarMakerDoc.md

5. **Verify message field compatibility** between config.yaml and VehDataMsgDefs.h

10. Advanced Development

For advanced modifications:

1. **Multi-vehicle scenarios**: Use numbered components (1-20) for VehicleClient and controllers

2. **CarMaker integration**: Review CarMaker/ utilities and HIL integration with Simulink

3. **Virtual environment setup**: Configure VirtualEnvironmentSetup section for Carla integration

4. **Custom build configurations**: Modify dependencies.yaml and corresponding dispatch scripts

5. **Version management**: Update dependencies.yaml when changing tool versions; BuildConfig files auto-regenerate

Important Notes

References