HID Controller Setup¶

ATLAS supports HID controllers (gamepads, joysticks) for hands-on map control in the DEF and BMS functional areas. The controller gateway publishes raw input over DDS, and the HMI maps axes and buttons to screen actions via JSON configuration.

Architecture¶

The system uses two processes:

This separation means any SDL2-compatible controller works — Xbox, PlayStation, Switch Pro, flight sticks, or third-party pads — without changing the HMI.

Supported Controllers¶

Any controller recognised by SDL2's SDL_GameController API works out of the box:

• Xbox Elite / Xbox Series — recommended, all features mapped
• Xbox 360 — wired and wireless (with adapter)
• PlayStation DualSense / DualShock 4 — via SDL2's mapping database
• Nintendo Switch Pro — via SDL2's mapping database
• Generic USB gamepads — if listed in SDL2's controller database

Quick Start¶

1. Connect the controller¶

Plug in a USB controller or pair a Bluetooth controller. Verify Linux sees it:

# List game controllers
ls /dev/input/js*

# Or check SDL2 directly
gva-gateway-joystick --verbose
# Output: SDL sees 1 joystick(s)
#   [0] gamepad  Xbox Elite Wireless Controller

2. Start the joystick gateway¶

# On the same DDS domain as the HMI (default: 0)
gva-gateway-joystick --domain=0

The gateway publishes three types of DDS samples:

Idle input generates zero DDS traffic — samples are only published on change.

3. Start the HMI¶

gva-hmi --domain=0

Navigate to the DEF screen (key 3). Trigger zoom and bumper threat-cycling work immediately with default bindings.

4. Verify with DDS discovery¶

astutedds-discovery-dump -d 0

Look for the gateway's participants and matched writer/reader pairs on the Displays_And_Controls__* topics.

Gateway Command-Line Options¶

gva-gateway-joystick [options]

JSON Configuration¶

Controller bindings are defined in the "controller" section of gva-hmi-config.json. The HMI reads this at startup — no recompilation needed.

Configuration File Location¶

The HMI searches for gva-hmi-config.json in order:

1. ./gva-hmi-config.json (current directory)
2. ./etc/gva-hmi-config.json
3. <app-dir>/etc/gva-hmi-config.json
4. /etc/gva/hmi/gva-hmi-config.json

Controller Section¶

{
    "controller": {
        "enabled": true,
        "resourceId": -1,
        "instanceId": -1,
        "deadzone": 0.15,
        "triggerZoomSpeed": 1.5,
        "tickIntervalMs": 30,
        "axisBindings": {
            "LEFT_STICK": { "action": "pan", "invertY": false },
            "RIGHT_STICK": { "action": "rotateTilt", "invertY": false },
            "DPAD": { "action": "pan", "invertY": false },
            "LEFT_TRIGGER": { "action": "zoomOut" },
            "RIGHT_TRIGGER": { "action": "zoomIn" }
        },
        "buttonBindings": {
            "BUTTON_A": "select",
            "BUTTON_B": "back",
            "BUTTON_X": "cycleMap",
            "BUTTON_Y": "toggleZoom",
            "LEFT_BUMPER": "prevThreat",
            "RIGHT_BUMPER": "nextThreat",
            "BACK": "resetView",
            "LEFT_STICK_BUTTON": "toggleTrackAll",
            "RIGHT_STICK_BUTTON": "resetNorth"
        }
    }
}

Global Settings¶

Axis Bindings¶

Axis bindings map analogue inputs (sticks, triggers) to continuous actions. The key is the role descriptor published by the gateway.

2D axis options:

Button Bindings¶

Button bindings map momentary presses to discrete actions. Only the press event is used — release is ignored.

Available Actions¶

Map / Radar Actions (DEF Screen)¶

Screen Navigation Actions¶

DEF Screen Controls¶

On the DEF (Defence) screen, the controller provides hands-on interaction with the radar view:

BMS Screen Controls¶

On the BMS screen, controller inputs are forwarded to the external BMS application (e.g. TALOS) via the Display Extension protocol:

DDS Topics¶

The joystick gateway publishes on three Displays_And_Controls_PSM topics, using the 2-arg constructor so QoS is resolved via PatternForTopic():

Each component is identified by a (resourceId, instanceId) pair, with a role descriptor string (e.g. "LEFT_TRIGGER", "RIGHT_BUMPER") published once at startup via C_Human_Interaction_Component_Specification.

Troubleshooting¶

Controller not detected¶

# Check if SDL2 sees the controller
gva-gateway-joystick --verbose
# If "no SDL_GameController-compatible device found":
#   - Check /dev/input/js* exists
#   - Ensure current user is in the 'input' group:
sudo usermod -aG input $USER
#   - Log out and back in for group change to take effect

Controller works in gateway but HMI doesn't respond¶

1. Verify both processes are on the same DDS domain:

   gva-gateway-joystick --domain=0
   gva-hmi --domain=0
   

2. Check DDS discovery:

   astutedds-discovery-dump -d 0
   

   Look for matched writer/reader pairs on the Displays_And_Controls__* topics.

3. Verify the "controller" section in gva-hmi-config.json has "enabled": true.

4. Check HMI logs for controller startup:

   QT_LOGGING_RULES="gva.hmi.hid_input.info=true" gva-hmi --domain=0
   

   You should see:

   gva.hmi.hid_input: created on domain 0 controller: enabled
   gva.hmi.hid_input: subscribed: Displays_And_Controls__Input_Control_1D
   

Trigger zoom is too fast or too slow¶

Adjust triggerZoomSpeed in the JSON config:

• Slower: 0.5 – 1.0
• Default: 1.5
• Faster: 2.0 – 3.0

Stick/trigger jitter at rest¶

Increase the deadzone value in the JSON config (default 0.15). A value of 0.2–0.25 eliminates most controller jitter.

Multiple controllers¶

When multiple controllers are connected, each needs its own gva-gateway-joystick instance with a unique --id:

# Controller 1 — map control (joystick index 0)
gva-gateway-joystick --domain=0 --id=100 --joystick=0

# Controller 2 — weapon system (joystick index 1)
gva-gateway-joystick --domain=0 --id=101 --joystick=1

Then set resourceId (and optionally instanceId) in the JSON config to the --id / --instance of the controller you want the HMI to use for map control:

"controller": {
    "resourceId": 100,
    "instanceId": -1
}

With resourceId set to 100, the HMI ignores all controller input from resource 101. Set instanceId to further narrow the match when multiple gateways share the same resource ID. MFD bezel input (from gva-gateway-hid) is always accepted regardless of these filters.