ACAT JSON Configuration Guide

Version: 1.0
Last Updated: February 2026

Overview
Migration from XML
Configuration Files Reference
VS Code IntelliSense Setup
Troubleshooting
Best Practices

Overview

ACAT has modernized its configuration system by migrating from XML to JSON format. This change provides several benefits:

Benefits of JSON Configuration

🚀 Better Tooling: IntelliSense support in VS Code and other editors
✅ Validation: Real-time schema validation while editing
📝 Simpler Syntax: More readable and easier to edit than XML
🔧 Modern Standard: JSON is the industry standard for configuration
🛡️ Type Safety: Built-in validation with FluentValidation
📖 Self-Documenting: Schema provides inline documentation

Supported Configuration Types

ACAT supports five main JSON configuration types:

ActuatorSettings - Input device configurations (keyboard, camera, BCI, switches)
Theme - Color schemes and UI styling
PanelConfig - UI panel layouts (scanners, keyboards, menus)
Abbreviations - Text abbreviation expansions
Pronunciations - Custom word pronunciations for text-to-speech

Migration from XML

Using the ConfigMigrationTool

The ConfigMigrationTool is a command-line utility that automates the migration of XML configurations to JSON format.

Step 1: Locate Your Configuration Files

Your ACAT configuration files are typically located in:

User Configurations: %APPDATA%\ACAT\Config\
Default Configurations: C:\Program Files\ACAT\Install\Users\DefaultUser\

Step 2: Run the Migration Tool

Option A: Safe Migration (Recommended)

# Preview changes first
ConfigMigrationTool migrate --input "C:\Users\YourName\AppData\Roaming\ACAT\Config" --output "C:\Users\YourName\AppData\Roaming\ACAT\ConfigJSON" --dry-run

# Run actual migration with backup
ConfigMigrationTool migrate --input "C:\Users\YourName\AppData\Roaming\ACAT\Config" --output "C:\Users\YourName\AppData\Roaming\ACAT\ConfigJSON" --backup

# Validate the results
ConfigMigrationTool validate --input "C:\Users\YourName\AppData\Roaming\ACAT\ConfigJSON"

Option B: Quick Migration

ConfigMigrationTool migrate -i "C:\ACAT\Config" -o "C:\ACAT\ConfigJSON" --backup

Step 3: Review Migration Report

After migration, review the report for:

✓ Successfully Converted: Files that migrated without issues
⚠ Warnings: Validation issues (files still work but may need attention)
✗ Errors: Files that failed to convert

Step 4: Update ACAT to Use JSON

Replace your old XML configuration directory with the new JSON directory, or configure ACAT to use the new location.

Manual Migration

If you prefer to migrate manually:

Copy the appropriate example file from schemas/examples/
Open your old XML configuration
Transfer the settings to the JSON format
Save with .json extension
Validate using VS Code with IntelliSense

Configuration Files Reference

1. ActuatorSettings.json

Purpose: Configure input devices (switches) for ACAT control

Location: %APPDATA%\ACAT\Config\ActuatorSettings.json

Schema: schemas/json/actuator-settings.schema.json

Schema Reference

Property	Type	Required	Description
`actuatorSettings`	array	Yes	List of input device configurations
`actuatorSettings[].name`	string	Yes	Device name (e.g., "Keyboard", "Camera")
`actuatorSettings[].id`	string (GUID)	Yes	Unique identifier for the actuator
`actuatorSettings[].description`	string	No	User-friendly description with optional HTML
`actuatorSettings[].enabled`	boolean	Yes	Enable/disable this device
`actuatorSettings[].switchSettings`	array	Yes	Button/key mappings for this device
`switchSettings[].name`	string	Yes	Switch name (e.g., "Trigger")
`switchSettings[].source`	string	Yes	Input source (e.g., "F12", "LeftClick")
`switchSettings[].enabled`	boolean	Yes	Enable/disable this switch
`switchSettings[].actuate`	boolean	Yes	Whether this switch triggers actions
`switchSettings[].command`	string	Conditional	Command to execute (required if actuate=true)
`switchSettings[].minHoldTime`	string/number	No	Minimum hold time in milliseconds
`switchSettings[].beepFile`	string	No	Audio feedback file path

Example

{
  "$schema": "../json/actuator-settings.schema.json",
  "actuatorSettings": [
    {
      "name": "Keyboard",
      "id": "d91a1877-c92b-4d7e-9ab6-f01f30b12df9",
      "description": "Use the computer keyboard as a switch to control ACAT.",
      "enabled": true,
      "imageFileName": "KeyboardSwitch.jpg",
      "switchSettings": [
        {
          "name": "Trigger",
          "source": "F12",
          "description": "Main trigger key",
          "enabled": true,
          "actuate": true,
          "command": "@Trigger",
          "minHoldTime": "@MinActuationHoldTime",
          "beepFile": "beep.wav"
        }
      ]
    }
  ]
}

Variable References

ActuatorSettings supports variable references prefixed with @:

@Trigger - Default trigger command
@MinActuationHoldTime - System-defined minimum hold time
@CmdEnterKey - Enter key command

Common Commands

Command	Description
`@Trigger`	Primary selection/activation
`@CmdEnterKey`	Simulate Enter key
`@CmdTabKey`	Simulate Tab key
`@CmdUndo`	Undo last action

2. Theme.json

Purpose: Define color schemes and styling for ACAT UI

Location: %APPDATA%\ACAT\Config\Theme.json

Schema: schemas/json/theme.schema.json

Schema Reference

Property	Type	Required	Description
`description`	string	No	Theme description
`colorSchemes`	array	Yes	List of color schemes for different UI elements
`colorSchemes[].name`	string	Yes	Scheme name (e.g., "Scanner", "ScannerButton")
`colorSchemes[].background`	string	Yes	Background color (hex or color name)
`colorSchemes[].foreground`	string	No	Foreground/text color
`colorSchemes[].highlightBackground`	string	No	Highlighted state background
`colorSchemes[].highlightForeground`	string	No	Highlighted state foreground
`colorSchemes[].selectedBackground`	string	No	Selected state background
`colorSchemes[].selectedForeground`	string	No	Selected state foreground
`colorSchemes[].backgroundImage`	string	No	Path to background image file

Example

{
  "$schema": "../json/theme.schema.json",
  "description": "Default high contrast theme for ACAT",
  "colorSchemes": [
    {
      "name": "Scanner",
      "background": "#232433",
      "foreground": "White",
      "highlightBackground": "#ffaa00",
      "highlightForeground": "#232433"
    },
    {
      "name": "ScannerButton",
      "background": "#5865F2",
      "foreground": "White",
      "highlightBackground": "#ffaa00",
      "highlightForeground": "Black"
    }
  ]
}

Color Format

Colors can be specified in two formats:

Hex Codes: #RRGGBB or #AARRGGBB (e.g., #232433, #FF5865F2)
Color Names: Standard color names (e.g., White, Black, Red, Blue)

Essential Color Schemes

For proper ACAT functionality, include these schemes:

Scanner - Main scanner window
ScannerButton - Scanner buttons
ContextMenu - Context menus
DialogPanel - Dialog boxes
TalkWindow - Talk window interface

3. PanelConfig.json

Purpose: Define UI panel layouts for scanners, keyboards, menus

Location: %APPDATA%\ACAT\Config\Panels\[PanelName].json

Schema: schemas/json/panel-config.schema.json

Schema Reference

Property	Type	Required	Description
`widgetAttributes`	array	Yes	Widget definitions with properties
`widgetAttributes[].name`	string	Yes	Widget unique identifier
`widgetAttributes[].label`	string	No	Display text for button/label
`widgetAttributes[].command`	string	No	Command to execute on activation
`widgetAttributes[].font`	object	No	Font settings (family, size, bold, italic)
`animationSequences`	array	No	Scanning animation definitions
`layout`	object	Yes	Hierarchical widget layout

Example - Main Menu

{
  "$schema": "../json/panel-config.schema.json",
  "widgetAttributes": [
    {
      "name": "BtnSettings",
      "label": "Settings",
      "command": "@CmdSettings",
      "font": { "family": "Arial", "size": 16, "bold": true }
    },
    {
      "name": "BtnExit",
      "label": "Exit",
      "command": "@CmdExit",
      "font": { "family": "Arial", "size": 16, "bold": true }
    }
  ],
  "animationSequences": [
    {
      "name": "MainMenuScan",
      "steps": [
        { "widget": "BtnSettings", "highlightDuration": 1500 },
        { "widget": "BtnExit", "highlightDuration": 1500 }
      ]
    }
  ]
}

Widget Types

Common widget types in ACAT:

Button - Clickable button
Label - Static text display
Container - Layout container for other widgets
TextBox - Text input field

4. Abbreviations.json

Purpose: Define text abbreviation expansions

Location: %APPDATA%\ACAT\Config\Abbreviations.json

Schema: schemas/json/abbreviations.schema.json

Schema Reference

Property	Type	Required	Description
`abbreviations`	array	Yes	List of abbreviation definitions
`abbreviations[].word`	string	Yes	The abbreviation to replace (e.g., "btw")
`abbreviations[].replaceWith`	string	Yes	Full text expansion (e.g., "by the way")
`abbreviations[].mode`	string	Yes	Expansion mode: "Write", "Speak", or "None"

Example

{
  "$schema": "../json/abbreviations.schema.json",
  "abbreviations": [
    {
      "word": "btw",
      "replaceWith": "by the way",
      "mode": "Write"
    },
    {
      "word": "omg",
      "replaceWith": "oh my goodness",
      "mode": "Speak"
    }
  ]
}

Expansion Modes

Write: Replace abbreviation with full text in the document
Speak: Speak the full text via text-to-speech without writing
None: Disable expansion for this abbreviation

5. Pronunciations.json

Purpose: Define custom pronunciations for text-to-speech

Location: %APPDATA%\ACAT\Config\Pronunciations.json

Schema: schemas/json/pronunciations.schema.json

Schema Reference

Property	Type	Required	Description
`pronunciations`	array	Yes	List of pronunciation definitions
`pronunciations[].word`	string	Yes	Word to customize (e.g., "github")
`pronunciations[].pronunciation`	string	Yes	How to pronounce it (e.g., "git hub")

Example

{
  "$schema": "../json/pronunciations.schema.json",
  "pronunciations": [
    {
      "word": "github",
      "pronunciation": "git hub"
    },
    {
      "word": "ACAT",
      "pronunciation": "A cat"
    },
    {
      "word": "sql",
      "pronunciation": "sequel"
    }
  ]
}

Tips for Pronunciations

Use phonetic spelling to guide pronunciation
Break compound words with spaces (e.g., "git hub" instead of "github")
Use capital letters for emphasis (e.g., "A P I" for letter-by-letter)
Test with your TTS engine to verify

VS Code IntelliSense Setup

Visual Studio Code provides excellent support for JSON schemas, offering autocomplete and real-time validation.

Method 1: Using $schema Property (Recommended)

Add the $schema property at the top of your JSON file:

{
  "$schema": "../json/actuator-settings.schema.json",
  "actuatorSettings": [
    ...
  ]
}

Relative paths from typical locations:

User configs: ../../../path/to/acat/schemas/json/actuator-settings.schema.json
Or use the example files as templates (they already have the correct paths)

Method 2: Workspace Settings

Create .vscode/settings.json in your ACAT directory:

{
  "json.schemas": [
    {
      "fileMatch": ["**/ActuatorSettings.json"],
      "url": "./schemas/json/actuator-settings.schema.json"
    },
    {
      "fileMatch": ["**/Theme.json"],
      "url": "./schemas/json/theme.schema.json"
    },
    {
      "fileMatch": ["**/Abbreviations.json"],
      "url": "./schemas/json/abbreviations.schema.json"
    },
    {
      "fileMatch": ["**/Pronunciations.json"],
      "url": "./schemas/json/pronunciations.schema.json"
    },
    {
      "fileMatch": ["**/Panels/**/*.json"],
      "url": "./schemas/json/panel-config.schema.json"
    }
  ]
}

Method 3: User Settings (Global)

For system-wide IntelliSense, add to VS Code user settings:

Press Ctrl+Shift+P (Windows/Linux) or Cmd+Shift+P (Mac)
Type "Preferences: Open User Settings (JSON)"
Add the schema associations:

{
  "json.schemas": [
    {
      "fileMatch": ["**/ACAT/**/ActuatorSettings.json"],
      "url": "C:/path/to/acat/schemas/json/actuator-settings.schema.json"
    }
  ]
}

IntelliSense Features

Once configured, you'll get:

📝 Autocomplete: Press Ctrl+Space to see available properties
✅ Validation: Red squiggles indicate errors
📖 Hover Documentation: Hover over properties to see descriptions
🔍 Quick Info: See allowed values for enums
⚡ Snippets: Quickly insert common patterns

Troubleshooting

Configuration Validation Failed

Symptom: ACAT shows "Configuration validation failed" error

Common Causes:

Missing Required Fields

// ❌ Bad: Missing 'mode'
{ "word": "btw", "replaceWith": "by the way" }

// ✅ Good: All required fields present
{ "word": "btw", "replaceWith": "by the way", "mode": "Write" }

Invalid Enum Values

// ❌ Bad: Invalid mode
{ "mode": "WriteBoth" }

// ✅ Good: Valid mode
{ "mode": "Write" }

Malformed JSON

// ❌ Bad: Trailing comma
{
  "word": "btw",
  "replaceWith": "by the way",
  "mode": "Write",  // ← Remove this comma
}

Solution: Check the application logs for specific validation errors and fix the indicated issues.

Configuration File Not Found

Symptom: ACAT creates default configurations on startup

Causes:

Configuration file path is incorrect
File has wrong extension (should be .json)
File has no read permissions

Solution:

Verify file path: %APPDATA%\ACAT\Config\
Check file extension is .json not .json.txt
Ensure file is readable (right-click → Properties → Security)

JSON Parsing Error

Symptom: "JSON parsing error" or "Unexpected token"

Common Syntax Errors:

// ❌ Bad: Missing quotes around property names (not JSON)
{ word: "btw", replaceWith: "by the way" }

// ✅ Good: Property names in quotes
{ "word": "btw", "replaceWith": "by the way" }

// ❌ Bad: Single quotes (not valid JSON)
{ 'word': 'btw' }

// ✅ Good: Double quotes
{ "word": "btw" }

// ❌ Bad: Trailing comma in array
["item1", "item2",]

// ✅ Good: No trailing comma
["item1", "item2"]

Solution: Use a JSON validator or VS Code with IntelliSense to catch syntax errors.

IntelliSense Not Working

Symptom: No autocomplete or validation in VS Code

Solutions:

Check schema path: Ensure $schema property points to correct file
Install JSON Language Features: Already included in VS Code
Reload window: Press Ctrl+Shift+P → "Developer: Reload Window"
Check file extension: Must be .json not .txt

Migration Tool Warnings

Symptom: ConfigMigrationTool shows warnings after migration

Common Warnings:

"Enabled switches that actuate must have a command"
- Fix: Add "command": "@Trigger" to actuating switches
"Animations should have at least one step"
- Fix: Add animation steps or remove empty animation
"Color scheme names should be unique"
- Fix: Rename duplicate color scheme names

Note: Warnings don't prevent migration. Files are still converted and usable.

Configuration Changes Not Taking Effect

Symptom: Modified configuration doesn't change ACAT behavior

Solutions:

Restart ACAT: Configuration is loaded at startup
Check file location: ACAT may be loading from a different location
Verify JSON syntax: Syntax errors may cause fallback to defaults
Check logs: Application logs show which config file was loaded

Colors Not Displaying Correctly

Symptom: Theme colors appear wrong or default

Solutions:

Check color format:

// ✅ Valid formats
"background": "#232433"
"background": "White"
"background": "#FF232433"  // With alpha channel

// ❌ Invalid formats
"background": "232433"      // Missing #
"background": "#GGG"        // Invalid hex

Include both background and foreground:

{
  "name": "Scanner",
  "background": "#232433",
  "foreground": "White"  // Recommended
}

Verify scheme name matches usage:
- Check that scheme names like "Scanner", "ScannerButton" match the names referenced in code

Best Practices

1. Always Use Schema References

Include $schema property for IntelliSense support:

{
  "$schema": "../json/abbreviations.schema.json",
  ...
}

2. Use Comments for Documentation

JSON doesn't support comments, but VS Code's JSON parser does:

{
  // This is a configuration comment
  "abbreviations": [
    {
      "word": "btw",  // Common internet abbreviation
      "replaceWith": "by the way",
      "mode": "Write"
    }
  ]
}

3. Format for Readability

Use consistent indentation (2 or 4 spaces):

{
  "abbreviations": [
    {
      "word": "btw",
      "replaceWith": "by the way",
      "mode": "Write"
    }
  ]
}

VS Code can auto-format: Shift+Alt+F (Windows/Linux) or Shift+Option+F (Mac)

4. Backup Before Migration

Always create backups before migrating:

ConfigMigrationTool migrate -i "C:\ACAT\Config" -o "C:\ACAT\ConfigJSON" --backup

5. Validate After Changes

After making manual changes, validate:

ConfigMigrationTool validate -i "C:\ACAT\Config"

6. Use Example Files as Templates

Copy from schemas/examples/ instead of creating from scratch:

copy schemas\examples\abbreviations.example.json %APPDATA%\ACAT\Config\Abbreviations.json

7. Keep Variable References

Don't replace variable references with hard-coded values:

// ✅ Good: Keep variable reference
{
  "command": "@Trigger",
  "minHoldTime": "@MinActuationHoldTime"
}

// ❌ Bad: Hard-coded values
{
  "command": "Trigger",
  "minHoldTime": 100
}

8. Test in Stages

When making changes:

Make one change at a time
Restart ACAT to test
If it works, make the next change
If it fails, revert and investigate

Additional Resources

Schema Files

Location: schemas/json/
All schemas: actuator-settings.schema.json, theme.schema.json, panel-config.schema.json, abbreviations.schema.json, pronunciations.schema.json

Example Files

Location: schemas/examples/
Use as templates for creating new configurations

Migration Tool

Location: src/build/bin/ConfigMigrationTool.exe
Documentation: src/Applications/ConfigMigrationTool/ACAT.ConfigMigrationTool/README.md

Developer Documentation

See docs/JSON_CONFIGURATION_DEVELOPER_GUIDE.md for extending the system
See docs/JSON_CONFIGURATION_MIGRATION.md for technical migration details

Support

For issues or questions:

Check application logs in %APPDATA%\ACAT\Logs\
Review validation errors in ConfigMigrationTool output
Contact: ACAT@intel.com

FilesExpand file tree

JSON_CONFIGURATION_GUIDE.md

Latest commit

History

JSON_CONFIGURATION_GUIDE.md

File metadata and controls

ACAT JSON Configuration Guide

Table of Contents

Overview

Benefits of JSON Configuration

Supported Configuration Types

Migration from XML

Using the ConfigMigrationTool

Step 1: Locate Your Configuration Files

Step 2: Run the Migration Tool

Step 3: Review Migration Report

Step 4: Update ACAT to Use JSON

Manual Migration

Configuration Files Reference

1. ActuatorSettings.json

Schema Reference

Example

Variable References

Common Commands

2. Theme.json

Schema Reference

Example

Color Format

Essential Color Schemes

3. PanelConfig.json

Schema Reference

Example - Main Menu

Widget Types

4. Abbreviations.json

Schema Reference

Example

Expansion Modes

5. Pronunciations.json

Schema Reference

Example

Tips for Pronunciations

VS Code IntelliSense Setup

Method 1: Using $schema Property (Recommended)

Method 2: Workspace Settings

Method 3: User Settings (Global)

IntelliSense Features

Troubleshooting

Configuration Validation Failed

Configuration File Not Found

JSON Parsing Error

IntelliSense Not Working

Migration Tool Warnings

Configuration Changes Not Taking Effect

Colors Not Displaying Correctly

Best Practices

1. Always Use Schema References

2. Use Comments for Documentation

3. Format for Readability

4. Backup Before Migration

5. Validate After Changes

6. Use Example Files as Templates

7. Keep Variable References

8. Test in Stages

Additional Resources

Schema Files

Example Files

Migration Tool

Developer Documentation

Support

License