nearxos/reterminal-dm4
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
80614cb4007b52ad89e097e15e49855a56162a97
reterminal-dm4/chromium-setup/README.md

5.1 KiB
Raw Blame History

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:

    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:

    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):

    ssh pi@<device-ip> "sudo apt-get update && sudo apt-get install -y wmctrl"

  4. Reboot to test:

    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:

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:

ssh pi@<device-ip> "mv ~/.config/autostart/chromium-kiosk.desktop ~/.config/autostart/chromium-kiosk.desktop.disabled"

To re-enable:

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.