APIC Howto – How to Configure the CoreEngine Runtime

← Back to Howto Index Full reference doc →

Follow these steps to build the runtime configuration JSON that controls folders, threading, CPU affinity, startup state, and recording policies in APIC.

1. Define Folders

Set the logical directories used by the system.

Field	Description
`setups`	Directory containing setup configuration files.
`tests`	Directory containing test scenarios.

{
  "folders": {
    "setups": "./setups",
    "tests": "./tests"
  }
}

2. Configure the RealTime Thread

Control the main real-time processing thread.

Field	Description
`affinity`	CPU core binding (comma and range supported).
`priority`	Thread scheduling priority (higher = more critical).
`bTimingFixTime`	If true, enforces fixed-cycle timing compensation.

Affinity example: "0,3,4-6" binds to cores 0, 3, 4, 5, 6.

{
  "RealTime": {
    "affinity": "0,3,4-6",
    "priority": 6,
    "bTimingFixTime": true
  }
}

3. Configure the Keyboard Thread

Handles interactive keyboard control.

Field	Description
`affinity`	Dedicated CPU core binding.
`priority`	Thread priority.
`active`	Enable/disable keyboard monitoring.

{
  "Keyboard": {
    "affinity": "2",
    "priority": 9,
    "active": true
  }
}

4. Configure the Reflector

This thread connects the CoreEngine out to a running Reflector app instance and streams this engine's shared memory to it for remote monitoring and interaction.

Field	Description
`affinity`	CPU binding.
`priority`	Thread priority.

{
  "Reflector": {
    "affinity": "1",
    "priority": 9
  }
}

5. Set the Startup Mode

Define the system boot behavior with the bootmode field:

"play" — start execution immediately.
"stop" — start paused.

{
  "startup": {
    "bootmode": "play"
  }
}

6. Configure the Recorder

Control recording subsystem behavior.

Field	Description
`priority`	Recorder thread priority.
`path`	Output directory for recordings.
`flushAfterFrames`	Flush buffer after N frames.
`recordOnlyOnChange`	Global setup — record only when data changes.

{
  "recorder": {
    "priority": 9,
    "path": "C:/temp/rec_test",
    "flushAfterFrames": 5,
    "recordOnlyOnChange": true
  }
}

7. (Optional) Fine-Tune DBSim Recording

Use the optional DBSim block for fine-grained control over which signals are recorded and how, including wildcard patterns.

Field	Description
`engSize`	-1 = use actual data size, 0 = disabled, >0 = fixed number of elements.
`rawSize`	-1 = use actual data size, 0 = disabled, >0 = fixed number of elements.
`recordOnlyOnChange`	true (default) = record only on value change; false = record every frame.

Useful when recording arrays with dynamic length but requiring a fixed storage size.

{
  "DBSim": {
    "CAM.cam.timestamp": {},
    "IMU.*": {},    // Wildcard example: records all IMU signals with default settings
    "CAM.cam.frame": {
      "recordOnlyOnChange": true,   //default
      "engSize": -1
    }
  }
}

8. (Optional) Enable EngineSync

EngineSync synchronizes engine time using an external telemetry element, typically for deterministic replay or hardware-aligned simulation. It is disabled by default.

{
  "EngineSync": {
    "stream": "SocketTCPTLMStream",
    "element": "LRU_KZ.TLMAiding.SystemEventNumber",
    "syncPerMS": "1000",
    "affinity": "0,1,3,4-6",
    "priority": 6
  }
}

9. Apply Threading & Design Guidelines

Pin the RealTime thread to multiple cores for deterministic workload distribution.
Isolate Keyboard and Reflector threads on dedicated cores.
Reserve high priority (9) for latency-sensitive tasks.
Configure the Recorder to minimize disk I/O overhead via buffered flushing.
Use CPU affinity and explicit thread priority for deterministic, modular configuration (EngineSync and DBSim are optional subsystems).

Best practice: avoid overlapping CPU affinity between real-time and high-priority auxiliary threads unless hyper-threading behavior is fully characterized.