Troubleshooting¶

This page covers common issues you might encounter when setting up or running CyberHUD, along with solutions and diagnostic steps.

Display Initialization Failures¶

If your display doesn't initialize or shows nothing:

Verify SPI is enabled on your Raspberry Pi:
```
ls /dev/spidev*
```
If no devices appear, enable SPI via raspi-config or by adding dtparam=spi=on to /boot/config.txt.
Confirm you're using the correct panel name:
```
cyberhudctl display modes
```

Check the daemon logs for initialization errors:

sudo journalctl -u cyberhudd.service -n 50

Try running in headless mode to isolate whether the issue is display-specific:
```
sudo ./cyberhudd -nodisplay
```

Input Not Working (Buttons/Joystick)¶

If buttons or joystick input is unresponsive:

Verify the correct panel is loaded — different displays use different input pins:
```
cyberhudctl display status
```
Check for GPIO pin conflicts:
```
cyberhudctl gpio pins
```
If using custom GPIO wiring, ensure your configuration file specifies the correct button/joystick pins (key1, key2, key3, up, down, left, right, press).

You can disable input entirely if not needed:

{
  "display": {
    "disable_input": true
  }
}

Optional Accessory Device Detection¶

If STEMMA/QWIIC devices aren't being detected:

Confirm I2C is enabled:
```
ls /dev/i2c*
```
Check which devices the daemon sees:
```
cyberhudctl stemma status
```
Verify the I2C bus path in your config matches your hardware. Multiple buses can be specified:
```
{
  "i2c": "/dev/i2c-1,/dev/i2c-3"
}
```
Adjust the scan interval if devices appear intermittently:
```
{
  "scan": "500ms"
}
```

Permission Errors¶

If you see permission denied errors:

The daemon typically needs root or appropriate group membership to access SPI, I2C, and GPIO:
```
sudo ./cyberhudd
```
For systemd service deployment, ensure the service user has the required group memberships (spi, i2c, gpio). See Systemd Integration for details.
Check socket permissions if cyberhudctl can't connect:
```
ls -la /run/cyberhudd/console.sock
```

GPIO Conflicts¶

If you suspect pin conflicts between the display driver and other software:

Run the pin conflict checker:
```
cyberhudctl gpio pins
```
Review the Pin Assignments for your display panel to identify which pins are in use.

If conflicts exist, use custom GPIO overrides to remap pins:

{
  "display": {
    "dc": "GPIO25",
    "rst": "GPIO27",
    "bl": "GPIO24"
  }
}

Checking Systemd Logs¶

When running as a systemd service, logs are available via journalctl:

# View the last 50 log entries
sudo journalctl -u cyberhudd.service -n 50

# Follow logs in real time
sudo journalctl -u cyberhudd.service -f

# Check service status
sudo systemctl status cyberhudd.service

Running Headless Mode¶

Headless mode starts the daemon without display initialization, which is useful for isolating display-related issues:

sudo ./cyberhudd -nodisplay

In headless mode the daemon will still:

Scan I2C buses for STEMMA devices
Monitor GPIO pins
Serve the console socket

You can verify core functionality works by querying the daemon:

cyberhudctl gpio status
cyberhudctl stemma status
cyberhudctl gpio pins

If headless mode works correctly, the issue is likely display-specific — check your panel selection and GPIO wiring.

Configuration Troubleshooting¶

Config File Not Being Read¶

Verify the path is correct and the file contains valid JSON:

# Validate JSON syntax
jq . /etc/cyberhudd.json

Ensure you're passing the config flag when starting the daemon:

sudo ./cyberhudd -config /etc/cyberhudd.json

CLI Flags Not Overriding Config¶

CLI flags should override config file values. Make sure you're using explicit flags alongside the config flag:

sudo ./cyberhudd -config /etc/cyberhudd.json -panel waveshare-2.2

Partial Overrides Not Working¶

When using a config file, only include fields you want to override. Omitted fields automatically keep their panel defaults — you don't need to set them to empty or zero:

{
  "display": {
    "panel": "waveshare-1.3hat",
    "dc": "GPIO22"
  }
}

This overrides only the DC pin. All other fields (rst, bl, offsets, etc.) remain at the panel's built-in defaults.

Next Steps¶

Review the full Configuration Schema for all available settings
Set up cyberhud to start at boot: Systemd Integration
Browse available Display Modes to customize your setup
Check the FAQ for answers to common questions

Need More Help?¶

Check the CLI Usage page for full command reference
Review Configuration for config file setup
Read the Pin Assignments for your specific display
Try headless mode to isolate display issues: sudo ./cyberhudd -nodisplay
Open an issue on GitHub with logs and hardware details