# MageDok 7" Touchscreen Display Setup

Issue #369: Display setup for MageDok 7" IPS touchscreen on Jetson Orin Nano.

## Hardware Setup

### Connections
- **Video**: DisplayPort → HDMI cable from Orin DP 1.2 connector to MageDok HDMI input
- **Touch**: USB 3.0 cable from Orin USB-A to MageDok USB-C connector
- **Audio**: HDMI carries embedded audio from DisplayPort (no separate audio cable needed)

### Display Specs
- **Resolution**: 1024×600 @ 60Hz
- **Panel Type**: 7" IPS (In-Plane Switching) - wide viewing angles
- **Sunlight Readable**: Yes, with high brightness
- **Built-in Speakers**: Yes (via HDMI audio)

## Installation Steps

### 1. Kernel and Display Driver Configuration

```bash
# Update display mode database (if needed)
sudo apt-get update && sudo apt-get install -y xrandr x11-utils edid-decode

# Verify X11 is running
echo $DISPLAY  # Should show :0 or :1

# Check connected displays
xrandr --query
```

**Expected output**: HDMI-1 connected at 1024x600 resolution

### 2. Install udev Rules for Touch Input

```bash
# Copy udev rules
sudo cp jetson/ros2_ws/src/saltybot_bringup/udev/90-magedok-touch.rules \
    /etc/udev/rules.d/

# Reload udev
sudo udevadm control --reload-rules
sudo udevadm trigger

# Verify touch device
ls -l /dev/magedok-touch
# Or check input devices
cat /proc/bus/input/devices | grep -i "eGTouch\|EETI"
```

### 3. X11 Display Configuration

```bash
# Backup original X11 config
sudo cp /etc/X11/xorg.conf /etc/X11/xorg.conf.backup

# Apply MageDok X11 config
sudo cp jetson/ros2_ws/src/saltybot_bringup/config/xorg-magedok.conf \
    /etc/X11/xorg.conf

# Restart X11 (or reboot)
sudo systemctl restart gdm3  # or startx if using console
```

### 4. PulseAudio Audio Routing

```bash
# Check current audio sinks
pactl list sinks | grep Name

# Find HDMI sink (typically contains "hdmi" in name)
pactl set-default-sink <hdmi-sink-name>

# Verify routing
pactl get-default-sink

# Optional: Set volume
pactl set-sink-volume <sink-name> 70%
```

### 5. ROS2 Launch Configuration

```bash
# Build the saltybot_bringup package
cd jetson/ros2_ws
colcon build --packages-select saltybot_bringup

# Source workspace
source install/setup.bash

# Launch display setup
ros2 launch saltybot_bringup magedok_display.launch.py
```

### 6. Enable Auto-Start on Boot

```bash
# Copy systemd service
sudo cp jetson/ros2_ws/src/saltybot_bringup/systemd/magedok-display.service \
    /etc/systemd/system/

# Enable service
sudo systemctl daemon-reload
sudo systemctl enable magedok-display.service

# Start service
sudo systemctl start magedok-display.service

# Check status
sudo systemctl status magedok-display.service
sudo journalctl -u magedok-display -f  # Follow logs
```

## Verification

### Display Resolution
```bash
# Check actual resolution
xdotool getactivewindow getwindowgeometry

# Verify with xrandr
xrandr | grep "1024x600"
```

**Expected**: `1024x600_60.00 +0+0` or similar

### Touch Input
```bash
# List input devices
xinput list

# Should show "MageDok Touch" or "eGTouch Controller"
# Test touch by clicking on display - cursor should move
```

### Audio
```bash
# Test HDMI audio
speaker-test -c 2 -l 1 -s 1 -t sine

# Verify volume level
pactl list sinks | grep -A 10 RUNNING
```

## Troubleshooting

### Display Not Detected

```bash
# Check EDID data
edid-decode /sys/class/drm/card0-HDMI-A-1/edid

# Force resolution
xrandr --output HDMI-1 --mode 1024x600 --rate 60

# Check kernel logs
dmesg | grep -i "drm\|HDMI\|dp"
```

### Touch Not Working

```bash
# Check USB connection
lsusb | grep -i "eGTouch\|EETI"

# Verify udev rules applied
cat /etc/udev/rules.d/90-magedok-touch.rules

# Test touch device directly
evtest /dev/magedok-touch  # Or /dev/input/eventX
```

### Audio Not Routing

```bash
# Check PulseAudio daemon
pulseaudio --version
systemctl status pulseaudio

# Restart PulseAudio
systemctl --user restart pulseaudio

# Monitor audio stream
pactl list sink-inputs
```

### Display Disconnection (Headless Fallback)

The system should continue operating normally with display disconnected:
- ROS2 services remain accessible via network
- Robot commands via `/cmd_vel` continue working
- Data logging and telemetry unaffected
- Dashboard accessible via SSH/webui from other machine

## Testing Checklist

- [ ] Display shows 1024×600 resolution
- [ ] Touch input registers in xinput (test by moving cursor)
- [ ] Audio plays through display speakers
- [ ] System boots without login prompt (if using auto-start)
- [ ] All ROS2 nodes launch correctly with display
- [ ] System operates normally when display is disconnected
- [ ] `/magedok/touch_status` topic shows true (ROS2 verify script)
- [ ] `/magedok/audio_status` topic shows HDMI sink (ROS2 audio router)

## Related Issues

- **#368**: Salty Face UI (depends on this display setup)
- **#370**: Animated expression UI
- **#371**: Deaf/accessibility mode with touch keyboard

## References

- MageDok 7" Specs: [HDMI, 1024×600, USB Touch, Built-in Speakers]
- Jetson Orin Nano DisplayPort Output: Requires active adapter (no DP Alt Mode on USB-C)
- PulseAudio: HDMI audio sink routing via ALSA
- X11/Xrandr: Display mode configuration
