geutebruck/ACTION_PARAMETERS_ANALYSIS.md

# GeViServer Action Parameters Analysis

## Summary
Analyzed 67 action mappings from GeViServer revealing **29 unique action types** with **115 total action instances**.

## Action Categories & Parameters

### 1. PTZ Camera Control
Actions for controlling pan/tilt/zoom cameras.

**Common Parameters:**
- `Caption`: string - Descriptive label
- `PTZ head`: string - Camera ID (e.g., "101027")
- `GCoreServer`: string - Server routing (e.g., "gscope-cdu-3", "G-Core")
- `Speed`: string - Movement speed (e.g., "128", "255")

**Actions:**
- `PanLeft`, `PanRight`, `PanStop`
- `TiltUp`, `TiltDown`, `TiltStop`
- `ZoomIn`, `ZoomOut`, `ZoomStop`
- `FocusFar`, `FocusNear`, `FocusStop`
- `IrisOpen`, `IrisClose`, `IrisStop`

**Example:**
```json
{
  "action": "FocusFar",
  "parameters": {
    "Caption": "Gsc FocusFar 128",
    "Speed": "128",
    "PTZ head": "101027",
    "GCoreServer": "gscope-cdu-3"
  }
}
```

### 2. Preset Positions
Actions for saving and recalling camera positions.

**Parameters:**
- `Caption`: string
- `PTZ head`: string (optional)
- `GCoreServer`: string (optional)

**Actions:**
- `PrePosSave`, `PrePosCallUp`, `PrePosClear` - Preset positions
- `DefaultPosSave`, `DefaultPosCallUp`, `DefaultPosClear` - Default positions

**Example:**
```json
{
  "action": "DefaultPosSave",
  "parameters": {
    "Caption": "GNG SaveDafaultPostion_101027",
    "PTZ head": "101027",
    "GCoreServer": "gscope-cdu-3"
  }
}
```

### 3. System Messages
Actions for system errors, warnings, and info messages.

**Parameters:**
- `Caption`: string - Display message
- `Source`: string - Message source code (e.g., "5", "7")
- `Message`: string - Message code (e.g., "0", "20", "23")
- `Description`: string - Full message text

**Actions:**
- `SystemError` - Error messages
- `SystemWarning` - Warning messages
- `SystemInfo` - Information messages

**Example:**
```json
{
  "action": "SystemError",
  "parameters": {
    "Caption": "GSC error: \"GeViIO Client: start of interface failed\"",
    "Source": "5",
    "Message": "0",
    "Description": "GeViIO Client: start of interface failed"
  }
}
```

### 4. Digital Outputs
Actions for controlling digital output contacts.

**Parameters:**
- `Caption`: string
- `Contact`: string - Contact number ("1", "2", "3", etc.)
- `State`: string - "1" (close) or "0" (open)

**Actions:**
- `SetDigitalOutput`

**Example:**
```json
{
  "action": "SetDigitalOutput",
  "parameters": {
    "Caption": "Set digital output (1,close)",
    "Contact": "1",
    "State": "1"
  }
}
```

### 5. Video Viewer
Actions for controlling video display.

**Parameters:**
- `Caption`: string

**Actions:**
- `ViewerConnectLive` - Connect to live video
- `ViewerClear` - Clear viewer

**Example:**
```json
{
  "action": "ViewerConnectLive",
  "parameters": {
    "Caption": "VC live"
  }
}
```

### 6. Cross-Switching
Actions for video matrix switching.

**Parameters:**
- `Caption`: string
- `SwitchMode`: string (e.g., "3")
- `VideoInput`: string (e.g., "0")
- `VideoOutput`: string (e.g., "0")

**Actions:**
- `CrossSwitch OpCon -> Matrix`

**Example:**
```json
{
  "action": "CrossSwitch OpCon -> Matrix",
  "parameters": {
    "Caption": "CrossSwitch OpCon -> Matrix",
    "SwitchMode": "3",
    "VideoInput": "0",
    "VideoOutput": "0"
  }
}
```

### 7. Custom Actions
General-purpose custom actions.

**Parameters:**
- `Caption`: string
- `Int`: string - Integer parameter
- `String`: string - String parameter

**Actions:**
- `CustomAction`

**Example:**
```json
{
  "action": "CustomAction",
  "parameters": {
    "Caption": "GscCustomAction:GscDiagnostics still running.",
    "Int": "0",
    "String": "GscDiagnostics still running."
  }
}
```

## Complete Action Type List

1. CrossSwitch OpCon -> Matrix
2. CustomAction
3. DefaultPosCallUp
4. DefaultPosClear
5. DefaultPosSave
6. FocusFar
7. FocusNear
8. FocusStop
9. IrisClose
10. IrisOpen
11. IrisStop
12. PanLeft
13. PanRight
14. PanStop
15. PrePosCallUp
16. PrePosClear
17. PrePosSave
18. SetDigitalOutput
19. SystemError
20. SystemInfo
21. SystemWarning
22. TiltDown
23. TiltStop
24. TiltUp
25. ViewerClear
26. ViewerConnectLive
27. ZoomIn
28. ZoomOut
29. ZoomStop

## Implementation Notes

### Parameter Types
All parameters are currently stored as strings in the API, but represent different semantic types:
- **Numeric IDs**: PTZ head, Contact, Source, Message
- **Numeric Values**: Speed, SwitchMode, VideoInput, VideoOutput, State
- **Text**: Caption, Description, String, GCoreServer

### Optional vs Required Parameters
- `Caption` appears in almost all actions (recommended but optional)
- PTZ-specific parameters (`PTZ head`, `GCoreServer`, `Speed`) only apply to PTZ actions
- Action-specific parameters are required for their respective action types

### UI Considerations
For editing these parameters, the UI should:
1. Display different fields based on selected action type
2. Provide input validation (numeric ranges, required fields)
3. Offer dropdowns for known values (server names, contact numbers, states)
4. Show helpful tooltips explaining each parameter

## Next Steps

To implement full parameter support in the Flutter app:

1. ✅ **Data Models** - Update models to store parameter objects
2. **Local Storage** - Update Hive models for offline storage
3. **UI Components** - Create dynamic parameter input forms
4. **Action Catalog** - Build a registry of action types with their parameter schemas
5. **Validation** - Implement parameter validation per action type
6. **Testing** - Verify parameter sync with GeViServer