APIC – State Architecture & Guide

APIC Runtime Configuration Guide

This document describes the JSON configuration structure used to control runtime behavior, threading, CPU affinity, startup state, and recording policies in APIC.

Usage

Pass the path to the configuration file to the application on startup:

projectApp.exe config="[path]/config.json"

The config argument is optional. If it is omitted, the CoreEngine looks for config.json in the process's current working directory.

1. Folders

Defines logical directories used by the system. This section is optional — any entry (or the whole block) can be commented out to fall back to the built-in default paths.

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

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

2. RealTime Thread

Controls the main real-time processing thread.

Field	Description
`affinity`	CPU core binding. Supports single cores, comma lists, ranges, and the `*` wildcard.
`priority`	Thread scheduling priority (higher = more critical).
`bTimingFixTime`	If true, enforces fixed-cycle timing compensation.

Affinity syntax: "0,3,4-6" binds to cores 0, 3, 4, 5, 6. Adding * to the list, e.g. "0,3,4-6,*", additionally includes every remaining core not explicitly assigned elsewhere — use it when a thread should also be free to run on any leftover core instead of being strictly limited to the ones listed.

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

3. CrashDump

Configures automatic crash dump capture if the application terminates unexpectedly.

Field	Description
`dumpPath`	Directory where crash dump files are written.
`dumpSize`	Amount of process state captured in the dump: `"mini"` – Small dump with basic thread/stack/exception info. Fast to write, good default for production. `"full"` – Full process memory dump. Much larger, but includes everything needed for deep post-mortem debugging.
`active`	Enable/disable crash dump capture (`1`/`0`).

{
  "CrashDump": {
    "dumpPath": "./crashdump",
    "dumpSize": "mini", // "mini" or "full"
    "active": 1
  }
}

4. 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": 1
  }
}

5. Reflector

Controls the CoreEngine-side thread that connects 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
  }
}

6. Startup Mode

Defines system boot behavior.

Field	Description
`bootmode`	Startup state. Possible values: `"play"` – Start execution immediately. `"stop"` – Start paused.

{
  "startup": {
    "bootmode": "play" //"stop"
  }
}

7. Recorder

Controls recording subsystem behavior, including the nested per-signal DBSim recording overrides (see below).

JSON object keys are case-sensitive — the recorder subsystem is configured under the lowercase "recorder" key. A stray, differently-cased key such as "Recorder" is a separate, unrelated key as far as the parser is concerned and will not configure the recording subsystem — double-check casing if recorder settings don't seem to take effect.

Field	Description
`affinity`	Recorder thread CPU binding.
`priority`	Recorder thread priority.
`path`	Output directory for recordings.
`flushAfterFrames`	Flush buffer after N frames.
`recordOnlyOnChange`	Global default, record only when data changes; can be overridden per-signal in `DBSim`.
`DBSim`	Optional. Fine-grained per-signal recording overrides — see the next section.

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

8. DBSim recording Configuration (Optional)

Nested inside recorder, this allows fine-grained control over which signals are recorded and how. Supports 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 = the default, only record when the value changes false = record every frame regardless of value changes

engSize/rawSize are especially useful when recording arrays with dynamic length but requiring a fixed storage size. An empty {} entry (e.g. "LRU_KZ.TLMAiding": {}) records that signal with default settings.

{
  "recorder": {
    ...
    "DBSim": {
      "LRU_KH.VirtualMessage": {
        "recordOnlyOnChange": true, //default
        "engSize": -1
      },
      "LRU_FC.Status": {
        "recordOnlyOnChange": true, //default
        "engSize": -1 //-1 means use the size of the data, 0 disabled. otherwise use the specified size. This is useful for arrays where the size may change but you want to record a fixed number of elements.
        //"rawSize": 100
      },
      "LRU_KZ.FC_SensorsData35": {
        "recordOnlyOnChange": true, //default
        "engSize": -1
      }
    }
  }
}

9. EngineSync (Optional – Disabled)

Synchronizes engine time using an external telemetry element. Typically used for deterministic replay or hardware-aligned simulation. Comment out the block (as below) to leave it disabled.

Field	Description
`stream`	Name of the stream that carries the sync telemetry element.
`element`	ICD element used as the sync source.
`syncPerMS`	Sync interval in milliseconds.
`scale`	Optional. Rescales the raw sync element value before use. `engType` — engineering type to interpret the value as (e.g. `"float"`). `scale` — multiplier applied to the raw value.
`affinity`	CPU binding for the EngineSync thread.
`priority`	Thread priority.

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

Threading & Scheduling Strategy

RealTime thread pinned to multiple cores for deterministic workload distribution.
Keyboard and Reflector isolated on dedicated cores.
High priority (9) reserved for latency-sensitive tasks.
Recorder configured to minimize disk I/O overhead via buffered flushing.

Design Principles

Deterministic execution via CPU affinity.
Explicit thread priority control.
Selective recording for performance optimization.
Modular optional subsystems (EngineSync, DBSim).

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