Linux agent — Operation

systemd service

The agent runs as kiosk-browser.service. Auto-starts on VT7 at boot, with Restart=on-failure.

Heartbeat and RDS integration

• Heartbeat every 60 seconds: the agent registers as a Linux device and sends state.
• GPS / device info every 5 minutes (includes lat/lon, uptime, distro/version read from /etc/os-release, DMI hardware model).
• Log upload on every heartbeat — available in the panel: Devices → Actions → Logs.
• Remote config: on every heartbeat the agent receives the mode (Web/Playlist), home URL, allowlist, and passcode updated from the panel.
• Remote captures: when the panel requests one via Actions → Screenshot, the agent runs scrot on $DISPLAY=:0, compresses to JPEG (quality 70), and uploads the image signed with HMAC v2. Detail.

Geolocation (GPS + IP)

The agent reports location via two tiers, in order:

1. Local gpsd (127.0.0.1:2947) — if you have a GPS module plugged in (USB serial / NMEA) and gpsd.socket is active (the installer enables it), the agent reads the latest fix with mode ≥ 2 (2D / 3D).
2. IP geolocation — automatic fallback. Calls https://ipwho.is/ and caches the result 1 hour in memory; enough for a kiosk that doesn't move.

If both tiers fail, sends 0,0 and RDS treats it as "no fix" (doesn't overwrite the last good value).

Connecting a USB GPS

gpsd ships pre-installed with USBAUTO=true: plug in the receiver, no other action needed — the next gpsd read will return a fix as soon as the receiver gets signal.

Touchscreen support

Enabled out of the box on any panel that appears as a touch device to libinput:

• The embedded browser receives real TouchEvents instead of emulated mouse (Chromium flags --touch-events=enabled --enable-pinch in run.sh).
• Pinch-to-zoom works.
• The Settings hot-corner (5 taps in the top-left within 2 s) accepts TouchBegin in addition to mouse press.
• On-screen keyboard: the Settings dialog launches onboard automatically on open and closes it on close. You can configure the agent without a physical keyboard.

Web Kiosk mode

Launches the browser at a configurable URL with:

• Allowlist-based navigation — only allowed domains load; everything else redirects to the home URL.
• Floating Back, Reload, and Home buttons in the bottom-left corner.
• Blocks new tabs / windows — every link opens in the same view.

Playlist mode

Plays the slideshow of videos/images managed from the web panel.

• Files are downloaded automatically to local disk.
• CRC32 verification before marking a file as downloaded.
• Plays from local cache immediately on restart — no server connection needed to start.
• Fullscreen, edge-to-edge — no status bar or buttons.
• Automatically adapts to any resolution (SD, FHD, 4K) without restart.

Logs

Agent logs are persisted locally and uploaded to the server on every heartbeat. To view them:

• Locally: tail -f /tmp/kiosk.log via SSH.
• From the panel: Devices → device row → Actions → Logs.

Updates

Updates are done by re-running the same one-liner installer you used to install. When /opt/promobrowser/.git is detected, it does git fetch + reset --hard origin/main, re-applies system packages (idempotent via apt-get install -y), and rewrites the systemd unit. Then restart the service:

curl -fsSL https://rds.digitalsignagerds.com/install.sh | sudo bash
sudo systemctl restart kiosk-browser

The installer does not restart the service automatically — do it yourself with systemctl restart after updating.

Network configuration

The admin menu (5 taps in the top-left corner) includes a Network tab with:

Current status

Monospace panel at the top, auto-refreshes every 5 seconds. Shows, for each connected interface:

• Name and type (ethernet / wifi)
• NetworkManager connection profile name
• IP, mask, gateway, DNS

WiFi

• Scan again — refreshes the list of available networks (nmcli device wifi rescan).
• Table with SSID, signal %, and security type. The currently-in-use network appears with a green ✓.
• Connect — select a network from the table and press Connect. If encrypted, asks for a password. Calls nmcli device wifi connect.
• Forget current network — removes the profile of the currently active WiFi network (nmcli connection delete).

On boxes without a WiFi adapter (purely wired kiosks) the panel still appears and shows "No WiFi adapter detected" when pressing Scan/Connect.

Ethernet

• Selector DHCP (recommended) / Static.
• In Static mode the fields appear:
  • IP / CIDR — e.g. 192.168.1.50/24
  • Gateway — e.g. 192.168.1.1
  • DNS — one or more separated by commas
• Apply Ethernet config calls nmcli connection modify ipv4.method auto|manual … followed by a down/up of the profile to apply instantly.

The change may briefly drop your connection if you're SSH'd through the same cable. Kiosk services (heartbeat) recover automatically.

All network operations are logged to agent.log under the NETWORK category.

Common troubleshooting