APIC – Streams.json

Convert ICD CSV documents to simulation-ready code blocks.

Streams Configuration (streams.json)

APIC uses streams.json to define how data flows between LRUs, simulations, hardware drivers, and network interfaces. Each stream contains blocks and a driver configuration.

See How to Build an APIC System for Software Engineers for where defining the CoreEngine's external interfaces in streams.json fits into the overall system-engineering workflow.

JSON Structure

{
  "streams": {
    "[StreamName]": {
      "blocks": [ ... ],
      "driver": { ... }
    }
  }
}
  

Blocks list ("blocks" array)

{
  "raw": "LRU_Seeker.VideoFrame",
  "direction": "in",
  "framePerMS": 10,
  "rawcounterbyte": 4,
  "headerMarker": "534f_2A",
  "model": "modelName"
}
    

Field Reference

FieldDescription
rawBlock path: LRU.BlockName
direction"in" = input stream (read from device), "out" = output stream (write to device)
framePerMS Defines the stream rate. If specified as frames per millisecond, provide a numeric value only. If specified in Hertz, append the hz postfix (e.g., 100hz). Set to 0 to disable both transmission and reception.
Optional
rawcounterbyteDefines a position in bytes of block counter to automatically increment on send or receive
headerMarkerA unique identifier placed at the start of a data block to mark its beginning. an _ means ignore value
modelModel name to execute (invokes modelName::OnRun()) when block data is received. The model’s periodic scheduler is suspended during this mode.

Driver Types ("driver" block)

Sniffer Driver

Captures packets from network interfaces using SnifferDriver. Supports local, remote, or both directions, and optional pcap filters.

          "driver": {
            "name": "SnifferDriver",
            "active": true,
            "adapter": "\\Device\\NPF_Loopback",
            "filter": "udp",
            "remoteIP": "127.0.0.1",
            "remotePort": 0,
            "localIP": "127.0.0.1",
            "localPort": 3021,
            "source": "remote",
            "destination": "remote"
            //https://www.tcpdump.org/manpages/pcap-filter.7.html
          }
        

Field Reference

FieldDescription
adapterNetwork adapter name, list of avaliable names displayed on application startup
filterString Capture filter, (see ncap string filter for detailed specification )
remoteIPFilter messages only to / from remoteIP, can be empty string ""
remotePortFilter messages only to / from remotePort, can be zero 0
localIPFilter messages only to / from localIP, can be empty string ""
localPortFilter messages only to / from localPort, can be zero 0
source"remote" capture only from remote, "local" capture only from local, "both" capture from local and remote
destination"remote" capture only to remote, "local" capture only to local, "both" capture to local and remote
NI65xx Driver for NIDAQ

Interfaces with NI DAQ cards. Supports multiple ports, read/write configuration, raw types, and power-up states.

      "driver": {
        "name": "NI65xxDriver",
        "active": true,
        "CardType": "MX",
        "DeviceID": 1,
        "PortNum": 2,
        "PowerUpState": "low", //"high" , "TriState", "NA"
        "RawType": "U", //BI binary signed, BU binary unsigned, U unsigned, F analog float64
        "LinesPerPort": 16, //16, 32, 64 floats
        "Port0": "R",
        "Port1": "W",
        ...
        "PortX": "W"
      }
    

Field Reference

Field Type / Values Description
name string Driver name "NI65xxDriver".
active boolean (true / false) Enables or disables the driver.
CardType string (e.g. "MX") Defines the hardware card type used by the driver.
DeviceID integer Specifies the unique device ID of the card.
PortNum integer Number of ports available on the device.
PowerUpState enum ("low", "high", "TriState", "NA") Defines the output line state after power-up.
RawType enum ("BI", "BU", "U", "F") Specifies data representation:
BI = binary signed,
BU = binary unsigned,
U = unsigned integer,
F = 64-bit floating-point.
LinesPerPort integer (16, 32, or 64) Number of I/O lines per port.
Port0 enum ("R", "W") Defines port direction:
R = Read, W = Write.
Port1 enum ("R", "W") Defines port direction:
R = Read, W = Write.
PortX enum ("R", "W") Defines port direction:
R = Read, W = Write.
Socket Drivers UDP / TCP

Socket driver for UDP and TCP. Supports multiple IN/OUT blocks, optional header markers, and raw counter bytes.

      "driver": {
        "name": "UDPSocketDriver",
        "active": true,
        "remoteIP": "172.30.176.2",
        "remoteIPBind": "172.30.192.1",
        "remotePortBind": 8081,
        "remotePort": 8081,
        "localIP": "172.30.192.1",
        "localPort": 8081
      }
    
Field Type / Values Description
name string Driver name "UDPSocketDriver" for UDP, "TCPSocketDriver" for TCP.
active boolean (true / false) Enables or disables the UDP driver.
remoteIP IPv4 address Specifies the remote host IP address to send data to.
remoteIPBind IPv4 address Only for TPC. Local interface IP used to bind the outgoing UDP socket for remote communication.
remotePort integer (1–65535) UDP port number on the remote host to which data is sent.
remotePortBind integer (1–65535) Only for TPC. Local UDP port used to bind the socket when sending to a remote host.
localIP IPv4 address Specifies the local IP address on which the driver listens for incoming UDP packets.
localPort integer (1–65535) Local UDP port on which the driver listens or sends data.
XDMA Driver

High-speed FPGA streaming. Supports video frames, frame sync, metadata, and static/dynamic streaming modes.

      "driver": {
        "name": "XDMADriver",
        "DeviceGuid": "{74c7e4a9-6d5d-4a70-bc0d-20691dff9e9d}",
        "userBaseAddress": "0x00020000",
        "DDR_BASE": "0x88000000",
        "DeviceIndex": 0,
        "FrameWidth": 640,
        "FrameHeight": 512,
        "BPP": 2,
        "FrameRateUs": 200000,
        "FrameSyncDelayMs": 10,
        "AddMetadata": "Yes",
        //StreamingMode=Static/Dynamic",
        "StreamingMode": "Static",
        //SyncSource=Internal/External/Sim
        "SyncSource": "External"
      }
    
Field Type / Values Description
name string Driver name "XDMADriver".
DeviceGuid GUID string Unique identifier of the XDMA PCIe device used for DMA operations.
userBaseAddress hex string Base address in user memory space for XDMA control or buffer mapping.
DDR_BASE hex string Base physical address of DDR memory used for frame data transfer.
DeviceIndex integer Index of the XDMA device (used when multiple devices are present).
FrameWidth integer (pixels) Width of the image frame in pixels.
FrameHeight integer (pixels) Height of the image frame in pixels.
BPP integer (bytes per pixel) Bits-per-pixel or bytes-per-pixel for image format (e.g., 2 = 16-bit).
FrameRateUs integer (microseconds) Frame interval in microseconds (e.g., 200000 = 5 FPS).
FrameSyncDelayMs integer (milliseconds) Delay applied before frame synchronization signal is sent or processed.
AddMetadata string ("Yes" / "No") Whether to append metadata to each transferred frame.
StreamingMode string ("Static" / "Dynamic") Defines data transfer mode: static (fixed memory) or dynamic (continuous stream).
SyncSource string ("Internal" / "External" / "Sim") Specifies synchronization signal source for frame timing.
CIG IDriver

CIGI protocol driver.

      "driver": {
        "name": "CIGIDriver",
        "remoteIP": "127.0.0.1",
        "remotePort": 8015,
        "localIP": "",
        "localPort": 8014
      }
    
Field Type / Values Description
name string Driver name "CIGIDriver" for UDP, "TCPSocketDriver" for TCP.
active boolean (true / false) Enables or disables the UDP driver.
remoteIP IPv4 address Specifies the remote host IP address to send data to.
remoteIPBind IPv4 address Local interface IP used to bind the outgoing UDP socket for remote communication.
remotePort integer (1–65535) UDP port number on the remote host to which data is sent.
remotePortBind integer (1–65535) Local UDP port used to bind the socket when sending to a remote host.
localIP IPv4 address Specifies the local IP address on which the driver listens for incoming UDP packets.
localPort integer (1–65535) Local UDP port on which the driver listens or sends data.
Serial Driver

Serial port driver for telemetry, commands, and sensors. Configurable COM port, baud rate, parity, stop bits, flow control, USB latency, buffer sizes, and overlapping mode.

      "driver": {
        "name": "SerialDriver",
        "comPort": "\\\\.\\com5",
        "baudRate": 921600,
        "parity": 0,
        "stopBits": 1,
        "byteSize": 8,
        "latency": 1, //-1 report port latency, 0 use default latency, >0 set latency in ms
        "flowcontrol": "none", //"software", "hardware", "none"
        "totalTimeoutConstant": 0,
        "overlapping": "yes",
        "InBufferSize": "auto",
        "OutBufferSize": "auto"
      }
    }
    
Field Type / Values Description
name string Driver name "SerialDriver".
file string Optional. Specifies the filename to read / write from instead of serial port. when specified the comPort is ignored.
comPort string Specifies the serial port name or path (e.g., \\\\.\\com5). If the value contains ?, the driver ignores the rest of the string and instead enumerates the serial ports currently available on the system, connecting to one of them automatically — see the note below.
baudRate integer Communication speed in bits per second (e.g., 921600).
parity integer (0–4) Parity mode: 0=None, 1=Odd, 2=Even, 3=Mark, 4=Space.
stopBits integer (1 / 2) Number of stop bits per frame (typically 1 or 2).
byteSize integer Number of data bits per character (usually 8).
latency integer -1 = report the port's current latency without changing it, 0 = use the driver/OS default latency, >0 = set the USB latency timer to that many milliseconds. See "Understanding latency" below.
flowcontrol "none" / "hardware" / "software" Selects how the link paces data to avoid buffer overrun. See "Understanding flowcontrol" below.
totalTimeoutConstant integer (ms) Timeout in milliseconds for read/write operations. 0 disables the fixed timeout component.
overlapping "yes" / "no" Enables asynchronous (overlapped) I/O on the port. Recommended "yes" for high-throughput / high-baud-rate links so reads and writes don't block the driver thread.
InBufferSize integer / "auto" Input buffer size in bytes or "auto" for system default.
OutBufferSize integer / "auto" Output buffer size in bytes or "auto" for system default.
Wildcard comPort (auto-detect): a value containing ? (e.g. "?") tells the driver to enumerate the serial ports available on the host system at startup and pick one automatically, rather than opening a specific device path. The rest of the string is not used to target a port — everything else in the driver block (baud rate, parity, flow control, etc.) still applies once a port is selected. This is useful for setups where the OS-assigned COM number for a USB-serial adapter isn't fixed across reboots or machines.

Understanding flowcontrol

Flow control decides how the two ends of the link tell each other to pause sending when a receive buffer is filling up, so bytes aren't silently dropped.

  • "none" — No pacing at all; the sender never slows down for the receiver. Simplest and lowest-overhead option. Fine for low/moderate baud rates or protocols that fit comfortably within the driver's buffers (short framed messages, telemetry that isn't continuously bursty). At sustained high baud rates with a slow-to-drain receiver, "none" risks buffer overrun and dropped bytes.
  • "hardware" — Uses the RTS/CTS signal lines: the receiving side de-asserts CTS to tell the sender to pause, and re-asserts it once buffer space is free. Signaling happens on dedicated wires, so it never touches the data stream, works with binary protocols, and reacts almost instantly. Use this whenever the cable/adapter wires RTS/CTS and you're running high sustained baud rates or long bursts of data (e.g. firmware/log streaming) — it's the safest option for high-throughput links.
  • "software" — Uses in-band XON/XOFF control characters to pause/resume the stream. Only appropriate for plain ASCII/text protocols: because it reserves two byte values inside the data itself, it will corrupt any binary protocol where those byte values occur naturally as payload data. Mostly relevant for legacy modem/terminal links; avoid it for ICD binary messages.

Default recommendation: use "none" for framed binary protocols at moderate baud rates, switch to "hardware" if you see overruns at high baud rates and the wiring supports RTS/CTS, and reserve "software" for legacy text-only links.

Understanding latency

Most COM ports used with APIC are USB-to-serial adapters (FTDI, CP210x, CH340, etc.). Their driver briefly buffers incoming bytes for a fixed window — the "latency timer" — before handing them to the application, trading a little delay for fewer, larger USB transfers. On Windows this default is commonly 16 ms, which is negligible for logging but can add noticeable, variable delay to time-critical command/response or control-loop traffic.

  • latency: -1 — Query only: reports the port's currently configured latency without changing it. Useful for diagnostics.
  • latency: 0 — Leave the driver/OS default latency in place. Good enough for low baud rates (9600–57600) or non-time-critical bulk/log streams, where minimizing USB overhead matters more than shaving a few milliseconds.
  • latency: >0 (e.g. 1) — Explicitly sets the latency timer to that many milliseconds. Use a low value like 1 ms for high baud rates (typically ≥115200, as in the 921600 example above) driving real-time telemetry, command/response, or hardware-in-the-loop links where deterministic, low-jitter byte delivery matters more than USB bus efficiency. This increases USB polling frequency and CPU/bus overhead slightly, so don't set it unnecessarily low on links that aren't timing-sensitive.
UEI Serial Driver

Serial port driver using UEI solutions. Configurable COM port, baud rate, parity, stop bits, buffer sizes, and overlapping mode.

      "driver": {
        "name": "UEISerialDriver",
        "ip": "192.168.100.102",
        //Serial standard settings
        "comPort": "\\\\.\\COM10",
        "baudRate": 921600,
        "parity": 0,
        "stopBits": 1,
        "byteSize": 8,
        "totalTimeoutConstant": 10,
        "InBufferSize": "auto",
        "OutBufferSize": "4096"
      }
    }
    
Field Type / Values Description
name string Driver name "UEISerialDriver".
ip string Specifties the UEI box IP address.
Same as standard serial port settings
FFMpeg video streaming driver

Video streaming driver using FFMpeg solution. Configurable video camera streaming properties

      "driver": {
        "name": "FFMPegDriver",
        "cameraName": "Lenovo FHD Webcam",
        "format": "yuvj422p",
        "fps": 30,
        "width": 640,
        "height": 480,
        "bufferSizeMB": 10
      }
    }
    
Field Type / Values Description
name string Driver name "FFMPegDriver".
cameraName string the Camera name to stream from. if this value is missing or empty a list of all avaliable connected devices will be shown on startup.
format string Pixel format of the video stream. Must be supported by both the camera and the driver pipeline.
fps string Target frames per second for image acquisition.
width string Frame width in pixels.
height string Frame height in pixels.
bufferSizeMB string Specifies the size of the driver buffer (in megabytes) used to temporarily store incoming frames that have not yet been read or processed by the application.
GenICam video streaming driver

Video streaming driver using FFMpeg solution. Configurable video camera streaming properties

      "driver": {
        "name": "GenICamDriver",
        "cameraName": "Lenovo FHD Webcam",
        "format": "yuvj422p",
        "externalSync": {
          "line": "Line4",
          "activation": "RisingEdge"
        },
        "fps": 30,
        "width": 640,
        "height": 480,
        "numOfPreAllocatedBuffers": 16,
        "waitForFrameTimeout_us": 0,
      }
    }
    
Field Type / Values Description
name string Driver name "GenICamDriver".
cameraName string the Camera name to stream from. if this value is missing or empty a list of all avaliable connected devices will be shown on startup.
format string Pixel format of the video stream. Must be supported by both the camera and the driver pipeline.
externalSync object External synchronization configuration for hardware trigger input.
externalSync.line string (e.g. LineX) Physical input line used for external trigger synchronization.
externalSync.activation string (RisingEdge | FallingEdge) Trigger activation edge used to capture frames.
fps string Target frames per second for image acquisition. this will override the external sync properties.
width string Frame width in pixels.
height string Frame height in pixels.
numOfPreAllocatedBuffers integer Number of frame buffers pre-allocated by the driver to handle continuous streaming without frame drops.
waitForFrameTimeout_us integer (microseconds) Timeout duration, in microseconds, to wait for a frame before aborting the acquisition attempt.
value of 0 indicates no timeout and the implementation switch to event driven async mode.
Shmem Driver

Shared memory interface for inter-process communication. Supports configurable filename and size.

        "driver": {
            "name": "ShmemDriver",
            "filename": "sharememFilename",
            "size": 2048
        }
    

Field Reference

Field Type / Values Description
name string Driver name "ShmemDriver".
filename string Unique name or path of the shared memory segment (e.g. "sharememFilename").
size integer (bytes) Total shared memory size in bytes (e.g. 2048).
INET Driver

HTTP/SFTP stream. Supports protocol, IP, port, URLs, and custom headers.

      "driver": {
        "name": "INETDriver",
        "protocol": "http", //sftp / http
        //"IP": "192.168.1.103",
        "IP": "127.0.0.1",
        "port": 30000,
        "URL": "/api/v0/{1}",
        "header": {
          "Content-Type": "application/json",
          "Accept": "text/json",
          "Accept-Language": "en-US",
          "Cache-Control": "no-cache"
        }
      }
    }
    

Field Reference

Field Type / Values Description
name string Driver name "INETDriver".
protocol enum: http, sftp Specifies the communication protocol used for network transfers.
IP string Target server IP address (e.g. 127.0.0.1).
port integer TCP port number for the connection (e.g. 30000).
URL string Relative URL or API endpoint, may include indexed placeholders (e.g. /api/v0/{1}).
header object Defines custom HTTP headers sent with each request.

Header Fields

Header Example Description
Content-Type application/json Defines the data format of the request body.
Accept text/json Indicates the expected format of the response data.
Accept-Language en-US Preferred response language.
Cache-Control no-cache Specifies caching behavior for network requests.
Note: The INETDriver provides a unified interface for network-based data exchange. It supports both HTTP and SFTP protocols and allows defining dynamic endpoints using placeholders within the URL.
GDP90 Driver

The GDL90 driver implements standard protocal for aviation entities display.

      "driver": {
          "name": "GDL90Driver",
          "active": true,
          "remoteIP": "127.0.0.1",
          "remotePort": 4000,
          "localIP": "",
          "localPort": 4001
      }
    }
    

Field Reference

Field Type / Values Description
name string Driver name "GDL90Driver".
active boolean (true / false) Enables or disables the UDP driver.
remoteIP IPv4 address Specifies the remote host IP address to send data to.
remotePort integer (1–65535) UDP port number on the remote host to which data is sent.
localIP IPv4 address Specifies the local IP address on which the driver listens for incoming UDP packets.
localPort integer (1–65535) Local UDP port on which the driver listens or sends data.
Note: The GDL90Driver protocol is a communication standard used to exchange aviation data, particularly Automatic Dependent Surveillance-Broadcast (ADS-B) information, between airborne and ground-based systems

Tips & Best Practices