# Chromium Auto-Start Configuration for Raspberry Pi

This directory contains scripts and configuration files to automatically start Chromium in fullscreen mode on boot for a Raspberry Pi device (reTerminal DM4).

## Files

- **`start-chromium.sh`** - Main startup script that launches Chromium with proper configuration
- **`chromium-kiosk.desktop`** - Autostart desktop entry file
- **`README.md`** - This documentation file

## Overview

This setup configures Chromium to:
- Start automatically on boot
- Open in fullscreen mode at `http://127.0.0.1:8080`
- Avoid keyring password prompts
- Prevent restore session notifications
- Properly fill the entire screen (fixes Wayland/X11 fullscreen issues)
- Support both fullscreen and kiosk modes (switchable via script)

## Installation

### Prerequisites

1. **SSH access** to the Raspberry Pi device
2. **Auto-login enabled** (required for autostart to work)
3. **Chromium installed**: `sudo apt-get install chromium`
4. **wmctrl installed**: `sudo apt-get install wmctrl` (for fullscreen forcing)

### Setup Steps

1. **Copy the startup script to the device:**
   ```bash
   scp start-chromium.sh pi@<device-ip>:/home/pi/start-chromium.sh
   ssh pi@<device-ip> "chmod +x /home/pi/start-chromium.sh"
   ```

2. **Create autostart directory and copy desktop file:**
   ```bash
   ssh pi@<device-ip> "mkdir -p ~/.config/autostart"
   scp chromium-kiosk.desktop pi@<device-ip>:/home/pi/.config/autostart/chromium-kiosk.desktop
   ```

3. **Install wmctrl (if not already installed):**
   ```bash
   ssh pi@<device-ip> "sudo apt-get update && sudo apt-get install -y wmctrl"
   ```

4. **Reboot to test:**
   ```bash
   ssh pi@<device-ip> "sudo reboot"
   ```

## Configuration

### Switching Between Fullscreen and Kiosk Mode

Edit `/home/pi/start-chromium.sh` on the device:

- **Fullscreen mode** (current): Uncomment the fullscreen line, comment out the kiosk line
- **Kiosk mode**: Comment out the fullscreen line, uncomment the kiosk line

### Changing the URL

Edit the `--app=http://127.0.0.1:8080` parameter in `start-chromium.sh` to point to your desired URL.

### Adjusting Delays

If Chromium doesn't start properly on boot, you may need to increase delays:
- Line 25: `sleep 5` - Delay before starting Chromium
- Line 32: `sleep 3` - Delay before forcing fullscreen

## Troubleshooting

### Chromium doesn't start on boot
- Verify auto-login is enabled: `sudo raspi-config` → Boot Options → Desktop Autologin
- Check if the script is executable: `chmod +x ~/start-chromium.sh`
- Check autostart file exists: `ls -la ~/.config/autostart/chromium-kiosk.desktop`

### Fullscreen doesn't work properly
- Ensure `wmctrl` is installed: `sudo apt-get install wmctrl`
- Check if X11 is being used (not Wayland): The script forces X11 with `--ozone-platform=x11`
- Manually test: `DISPLAY=:0 ~/start-chromium.sh`

### Keyring password prompt appears
- The script includes `--password-store=basic --use-mock-keychain` flags
- If it still appears, you may need to set an empty password for the keyring once

### Restore session notification appears
- The script includes `--disable-session-crashed-bubble --disable-restore-session-state` flags
- If it still appears, clear Chromium's session data: `rm -rf ~/.config/chromium/Session*`

## Manual Testing

Test the script without rebooting:
```bash
ssh pi@<device-ip> "pkill chromium && sleep 2 && DISPLAY=:0 ~/start-chromium.sh"
```

## Exiting Fullscreen/Kiosk Mode

- **Fullscreen mode**: Press `F11` to toggle fullscreen, or `Alt+F4` to close
- **Kiosk mode**: Use `Ctrl+Alt+T` to open terminal, then `pkill chromium`
- **From SSH**: `ssh pi@<device-ip> "pkill chromium"`

## Disabling Autostart

To temporarily disable autostart:
```bash
ssh pi@<device-ip> "mv ~/.config/autostart/chromium-kiosk.desktop ~/.config/autostart/chromium-kiosk.desktop.disabled"
```

To re-enable:
```bash
ssh pi@<device-ip> "mv ~/.config/autostart/chromium-kiosk.desktop.disabled ~/.config/autostart/chromium-kiosk.desktop"
```

## Chromium Flags Explained

- `--start-fullscreen` - Start in fullscreen mode
- `--kiosk` - Kiosk mode (no UI, harder to exit)
- `--noerrdialogs` - Suppress error dialogs
- `--disable-infobars` - Remove info bars
- `--disable-session-crashed-bubble` - Disable crash notifications
- `--disable-restore-session-state` - Don't restore previous session
- `--no-first-run` - Skip first-run dialogs
- `--password-store=basic` - Use unencrypted password store (no keyring)
- `--use-mock-keychain` - Avoid keychain prompts
- `--ozone-platform=x11` - Force X11 instead of Wayland (better fullscreen)
- `--app=<url>` - Run as app (no address bar, cleaner interface)

## Device Information

- **Device**: reTerminal DM4 (Raspberry Pi)
- **OS**: Raspberry Pi OS (Debian-based)
- **Tested on**: Linux raspberrypi 6.12.62+rpt-rpi-v8

## Notes

- The script waits for the desktop environment to be ready before starting Chromium
- It uses `wmctrl` to programmatically force fullscreen after Chromium starts
- X11 is forced instead of Wayland for better fullscreen compatibility
- The script runs in the background and maintains the Chromium process

## License

This configuration is provided as-is for use with the reTerminal DM4 project.