Enhanced Multi-Protocol Diagnostic CLI

[amiable-dev]

Enhanced Multi-Protocol Diagnostic CLI

Overview

Extend the existing midi_diagnostic CLI tool to support all input protocols (MIDI, Gamepad, OSC future). Provides unified debugging interface with colored output, protocol-specific visualization, and export capabilities.

Motivation

• Debug gamepad support (Issue macOS BLE Gamepad Support: Xbox Controller not detected via gilrs #1) alongside MIDI
• Single tool for all protocol debugging
• Export captured events for generator (AI-Powered Multi-Protocol Message Generator #3)
• CLI-based (no GUI overhead)
• MCP-exposed logs for AI-assisted debugging

Approach

Enhance existing tool rather than build new GUI:

• Rename midi_diagnostic.rs → conductor_diagnostic.rs
• Add --protocol flag for selection
• Keep terminal-based for simplicity
• Add gamepad visualization (ASCII art)

Features

1. Protocol Selection

# Monitor all protocols
conductor-diagnostic --protocol all

# MIDI only (current behavior)
conductor-diagnostic --protocol midi

# Gamepad only
conductor-diagnostic --protocol gamepad

# Future: OSC
conductor-diagnostic --protocol osc

2. Enhanced Display

Current (MIDI only):

Note On:  note=60 velocity=100
Note Off: note=60 velocity=0
CC:       controller=7 value=64

New (Multi-protocol):

[MIDI] Note On:  note=60 velocity=100 (medium)
[GAMEPAD] Button: 128 (South/A) pressed
[GAMEPAD] Axis:   130 (RightStickX) value=200 (78%)

3. Gamepad Visualization

ASCII art representation of controller state:

┌─────────────────────────────────┐
│  Xbox Controller                │
├─────────────────────────────────┤
│                                 │
│   [LB]           [RB]          │
│    ●              ●            │
│                                 │
│  [◄]              [Y]          │
│   ●                ●            │
│  [▼]  [►]      [X]   [B]       │
│   ●    ●        ●     ●         │
│                                 │
│   Left Stick    Right Stick     │
│      ↑               →          │
│   (255,128)      (200,128)      │
│                                 │
└─────────────────────────────────┘

Recent Events:
[0.000s] Button 128 (South) pressed
[0.100s] Axis 130 (RightX) → 200
[0.150s] Button 128 (South) released

4. Export to Generator Format

# Record events for replay
conductor-diagnostic --protocol gamepad --record > test_sequence.json

# Compatible with conductor-generator (#3)
conductor-generator --replay test_sequence.json

5. Side-by-Side Monitoring

# Monitor MIDI + Gamepad simultaneously
conductor-diagnostic --protocol all

Output:
┌─────────────────┬─────────────────┐
│ MIDI Events     │ Gamepad Events  │
├─────────────────┼─────────────────┤
│ Note 60 On      │ Button 128 ▼   │
│ Velocity: 100   │ Axis 130: 200   │
│                 │                 │
└─────────────────┴─────────────────┘

Implementation

File Changes

Rename: conductor-daemon/src/bin/midi_diagnostic.rs → conductor_diagnostic.rs

Add:

enum Protocol {
    Midi,
    Gamepad,
    All,
}

struct DiagnosticDisplay {
    protocol: Protocol,
    show_visualization: bool,
    record_mode: bool,
}

// Gamepad visualization
fn render_controller_state(buttons: &[bool], axes: &[u8]) -> String {
    // ASCII art generation
}

Display Enhancement

• Colored output: MIDI (blue), Gamepad (yellow), OSC (green)
• Timestamps: Relative milliseconds since start
• Value interpretation: "velocity 100 (medium)", "axis 200 (78%)"
• Clear screen: Optional --clear flag for live updates

Integration with MCP (#2)

Export diagnostic logs as MCP resource:

conductor://diagnostics/latest
conductor://diagnostics/{session_id}

AI can analyze logs for issues:

User: "Why isn't my gamepad responding?"
AI: [Reads conductor://diagnostics/latest]
    "No gamepad events detected. Your controller may not be connected."

Timeline

Total: 2-3 hours

• Phase 1: Rename + protocol flag (30 min)
• Phase 2: Gamepad event display (1 hour)
• Phase 3: ASCII controller viz (1 hour)
• Phase 4: Export + testing (30 min)

Dependencies

# No new dependencies needed
colored = { workspace = true }  # Already in use
clap = { workspace = true }     # Already in use

Implementation Checklist

• Rename midi_diagnostic.rs → conductor_diagnostic.rs
• Add --protocol CLI flag
• Implement gamepad event display
• Create ASCII controller visualization
• Add colored output (protocol-specific)
• Implement --record mode (JSON export)
• Add --clear flag for live updates
• Test with MIDI device
• Test with virtual gamepad (from AI-Powered Multi-Protocol Message Generator #3)
• Update documentation

Blockers

None - can implement immediately

Blocked Issues

• macOS BLE Gamepad Support: Xbox Controller not detected via gilrs #1: Multi-backend gamepad support (diagnostic tool helps debug)

Future Enhancements (v3.2+)

• OSC protocol support
• Web-based UI (optional)
• Statistics (events/sec, min/max/avg values)
• Filtering (show only specific events)
• Diff mode (compare two recordings)

Labels

enhancement, diagnostics, cli, v3.1

[amiable-dev]

Status: Still Valid - Part of #5

This issue remains valid and is incorporated as a component of the crowdsourced pattern platform (#5).

Related to: #5 (Crowdsourced Pattern Platform - Phase 1)

Integration with #5

The enhanced diagnostic tool will:

1. ✅ Support all protocols (MIDI, Gamepad) - original scope
2. ✅ Export to capture format - feeds into conductor-capture (🚀 Crowdsourced Pattern Platform: Full Stack Implementation #5 Phase 1)
3. ✅ Colored output - original scope
4. ✅ ASCII controller visualization - original scope

Role in Crowdsourced Platform

The diagnostic tool becomes a key input for the capture system:

# Debug session
conductor-diagnostic --protocol gamepad

# When user finds interesting pattern, export for capture
conductor-diagnostic --protocol gamepad --record > interesting_pattern.json

# Upload to platform
conductor-capture --import interesting_pattern.json --upload

Implementation Priority

Timeline: Implement alongside conductor-capture (Phase 1 of #5)

• Diagnostic tool helps users verify what they're capturing
• Export format must match capture format
• Critical for debugging during platform development

Status

✅ Active - Implementing as part of #5 Phase 1