geutebruck/ACTION_MAPPING_STRUCTURE_GUIDE.md

Action Mapping Binary Structure - Complete Guide

Summary

Based on analysis of TestMKS_original.set vs TestMKS_added_mapping.set, this document explains how action mappings are stored and how to programmatically add thousands of them.

Binary Structure

Overall Format

MARKER SECTION:
├─ 'ules' (4 bytes) - Action mapping marker
├─ Length (4 bytes, little-endian) - Length of marker name/data section
└─ Marker Name/Data Section (variable length)
   ├─ Metadata bytes
   ├─ Properties (optional, multiple)
   │  └─ Each property: 01 <len> <.name> <value_marker> <value>
   └─ Additional metadata

ACTION SECTION (follows marker section):
├─ Action Entry 1
│  ├─ Entry number (01 for first, 02 for second, etc.)
│  ├─ Metadata: 05 00 00 00
│  ├─ Action data: 07 01 40 <len_u16_LE> <action_string>
│  └─ Additional metadata (varies)
├─ Action Entry 2
│  └─ (same structure)
└─ ...

NEXT MARKER:
└─ 05 'Rules' or next 'ules' marker

Example 1: Simple Mapping (No Parameters)

Hex Dump (offset 0x41433):

75 6C 65 73    - 'ules' marker
02 00 00 00    - Length: 2 bytes
00 01          - Marker data (2 bytes)

31 05 00 00 00 - Action entry #1 metadata
07 01 40       - Action marker
0B 00          - Length: 11 bytes (little-endian)
47 53 43 20 50 61 6E 4C 65 66 74  - "GSC PanLeft"
...

Example 2: Mapping with Parameters

Hex Dump (offset 0x3D90D):

75 6C 65 73    - 'ules' marker
40 00 00 00    - Length: 64 bytes
00 01          - Start of marker data

# Properties within marker data:
01             - Property marker
0B             - Name length: 11
2E 53 77 69 74 63 68 4D 6F 64 65  - ".SwitchMode"
00             - Value type: null

01             - Property marker
0C             - Name length: 12
2E 56 69 64 65 6F 4F 75 74 70 75 74  - ".VideoOutput"
00             - Value type: null

# Then actions follow...

Property Value Types

Marker	Type	Structure
0x01	Boolean	01 <value> where value is 00 or 01
0x04	Integer	04 <int32_LE> (4 bytes, little-endian)
0x00	Null	Just 00
0x07	String	07 <len> <string_bytes>

Action Entry Format

Each action entry consists of:

<entry_number> - 01, 02, 03, etc. (sequential)
05 00 00 00    - Metadata (always this sequence)
07 01 40       - Action marker (always this sequence)
<length>       - 2 bytes, little-endian (length of action string)
<action_name>  - UTF-8 encoded action name
04 02 40 21 00 00 00 00 - Additional metadata
04 02 40 40 <4 bytes>    - More metadata (varies)

Key Findings

1. File Reorganization

When you add a mapping using GeViSoft GUI:

• The entire .set file is reorganized
• All offsets change
• Mappings may be reordered
• Net result: +1 mapping but many bytes change

This means you cannot simply append to the end of the file!

2. Insertion Strategy

To programmatically add mappings:

Option A: Parse → Modify → Rebuild

1. Parse the entire .set file
2. Add new mapping to internal structure
3. Regenerate the entire file
4. Write back to disk

Option B: Use GeViSoft API (if available)

1. Use SetupClient API to modify configuration
2. Let GeViSoft handle file format

Option C: Template-Based (recommended for bulk)

1. Create template mappings in GUI
2. Export configuration
3. Use find/replace to duplicate with new IDs
4. Import back

3. Complexity Factors

• Offsets must be recalculated
• File structure is tightly packed
• No obvious "free space" to insert data
• Dependencies between sections unknown
• Checksum or validation may exist

Programmatic Approach

Step 1: Create Mapping Binary Data

def create_action_mapping(actions, parameters=None):
    """
    Generate binary data for an action mapping

    Args:
        actions: List of action strings
        parameters: Dict of parameter_name -> value (optional)

    Returns:
        bytes: Complete mapping binary data
    """
    import struct

    # Build marker name/data section
    marker_data = bytearray()
    marker_data.extend(b'\x00\x01')  # Base metadata

    # Add parameters if any
    if parameters:
        for name, value in parameters.items():
            # Property marker
            marker_data.append(0x01)
            # Name with leading dot
            name_with_dot = f".{name}"
            name_bytes = name_with_dot.encode('utf-8')
            marker_data.append(len(name_bytes))
            marker_data.extend(name_bytes)

            # Value
            if value is None:
                marker_data.append(0x00)
            elif isinstance(value, bool):
                marker_data.append(0x01)
                marker_data.append(0x01 if value else 0x00)
            elif isinstance(value, int):
                marker_data.append(0x04)
                marker_data.extend(struct.pack('<i', value))

    # Build complete marker section
    result = bytearray()
    result.extend(b'ules')  # Marker
    result.extend(struct.pack('<I', len(marker_data)))  # Length
    result.extend(marker_data)  # Data

    # Add actions
    for i, action in enumerate(actions, 1):
        # Entry number
        result.append(i)
        # Metadata
        result.extend(b'\x05\x00\x00\x00')
        # Action marker
        result.extend(b'\x07\x01\x40')
        # Action length and string
        action_bytes = action.encode('utf-8')
        result.extend(struct.pack('<H', len(action_bytes)))
        result.extend(action_bytes)
        # Additional metadata (simplified)
        result.extend(b'\x04\x02\x40\x21\x00\x00\x00\x00')
        result.extend(b'\x04\x02\x40\x40\x00\x10\x00\x00')

    return bytes(result)

Step 2: Insert into Configuration

The recommended approach is to:

1. Read entire configuration using existing parser
2. Add new mapping to internal structure
3. Regenerate file using configuration writer

Practical Recommendations

For Adding Thousands of Mappings

Best Approach:

1. Use C# SDK + Configuration API

   // Pseudo-code
   var config = parser.Parse(file);
   for (int i = 0; i < 1000; i++) {
       var mapping = new ActionMapping {
           Actions = new[] { $"Action_{i}" },
           Parameters = new Dictionary<string, object>()
       };
       config.AddMapping(mapping);
   }
   writer.Write(config, outputFile);
   

2. Batch Process via GUI Templates

   • Create 1 mapping template in GUI
   • Export configuration as JSON/XML (if supported)
   • Programmatically duplicate + modify
   • Import back

3. Direct Binary Manipulation (risky!)

   • Parse existing file completely
   • Understand all section dependencies
   • Insert mappings
   • Rebuild file with correct offsets

Next Steps

For your use case (adding thousands of mappings), I recommend:

1. Extend C# Parser to support WRITING (currently read-only)
2. Create AddActionMapping() method in ConfigurationService
3. Batch add via gRPC/REST API
4. Write back to .set file

Would you like me to:

• Create C# writer for .set files
• Build Python script for bulk mapping creation
• Extend the gRPC API to support CREATE operations
• Create a bulk import tool (CSV → action mappings)