Skip to content

API Reference

Jump to bottom
th3drk0ne edited this page Feb 25, 2026 · 3 revisions

SindenPS Web Dashboard – API Reference

This document describes the HTTP APIs exposed by the Flask backend (app.py) and how they are used by the web frontend (index.html).

The application provides a local web dashboard for managing the Sinden Lightgun services, configuration, profiles, backups, logs, and software updates.

Overview

  • Backend: Python 3 + Flask
  • Frontend: Single-page HTML/CSS/JavaScript (served statically)
  • Transport: JSON over HTTP
  • Auth: None (assumes trusted local network / device)
  • Base URL: http://<host>

All API endpoints are prefixed with /api/ unless otherwise stated.

Health & Status

GET /healthz

Simple health check endpoint.

Response

{ "ok": true }

Service Management APIs

These endpoints control and inspect systemd services related to the lightgun.

GET /api/services

Returns the current status of managed services.

Response

{
  "lightgun.service": "active",
  "lightgun-monitor.service": "inactive"
}

Used by the UI to:

  • Display service status
  • Drive the online/offline mode indicator

POST /api/service/<service>/<action>

Start, stop, or restart a service.

  • service: lightgun.service | lightgun-monitor.service
  • action: start | stop | restart

Response

{
  "success": true,
  "status": "active"
}

GET /api/logs/<service>

Returns systemctl status output for the given service.

Response

{ "logs": "<systemd output>" }

Platform Detection

GET /api/platform

Reports the currently active platform mode.

  • Determined from /run/lightgun/sinden_mode
  • Falls back to ps2 if unavailable

Response

{ "ok": true, "platform": "ps2" }

Used by the frontend to:

  • Switch UI theme (PS1 red / PS2 blue)
  • Display the correct mode icon

System Power Actions

POST /api/system/<action>

Performs a system power action via systemctl.

  • action: reboot | shutdown

Response

{ "ok": true }

Note: The response may not be delivered if the system shuts down immediately.

Sinden Log Access

GET /api/sinden-log

Returns the contents of the Sinden Lightgun runtime log file.

Response

{ "logs": "<log file contents>" }

Displayed in the Lightgun Log tab.

Configuration APIs

These endpoints manage the XML configuration files for PS1 and PS2 modes.

GET /api/config?platform=<ps1|ps2>&profile=<name>

Loads the active or profile configuration.

Query Parameters

  • platform (optional): ps1 or ps2
  • profile (optional): profile name (loads from profiles/ instead of live file)

Response

{
  "ok": true,
  "platform": "ps2",
  "path": "/path/to/LightgunMono.exe.config",
  "player1": [ { "key": "SerialPort", "value": "..." } ],
  "player2": [ { "key": "SerialPort", "value": "..." } ],
  "player1Groups": [ { "name": "Device & Ports", "items": [...] } ],
  "player2Groups": [ { "name": "Device & Ports", "items": [...] } ],
  "source": "live",
  "profile": ""
}

The grouped data is used to render structured forms in the UI.

POST /api/config/save

Saves configuration changes in-place, strictly preserving XML layout, comments, and order.

Request Body

{
  "platform": "ps2",
  "player1": [ { "key": "SerialPort", "value": "..." } ],
  "player2": [ { "key": "SerialPort", "value": "..." } ]
}

Response

{
  "ok": true,
  "platform": "ps2",
  "path": "...",
  "backup": ".../backups/LightgunMono.exe.config.TIMESTAMP.bak"
}

A byte-for-byte backup is created automatically before changes are applied.

Profile Management APIs

Profiles are stored as full copies of configuration files.

GET /api/config/profiles?platform=<ps1|ps2>

Lists available profiles.

Response

{
  "ok": true,
  "platform": "ps2",
  "profiles": [
    { "name": "default", "path": "...", "mtime": 1700000000 }
  ]
}

POST /api/config/profile/save

Saves the current live configuration as a named profile.

Request Body

{ "platform": "ps2", "name": "myprofile", "overwrite": false }

POST /api/config/profile/load

Overwrites the live configuration with the selected profile.

A safety backup of the live file is created automatically.

POST /api/config/profile/delete

Deletes a saved profile.

Backup & Restore APIs

GET /api/config/backups?platform=<ps1|ps2>

Lists automatic and manual backups.

Response

{
  "ok": true,
  "platform": "ps2",
  "backups": [
    { "name": "LightgunMono.exe.config.20240225-101010.bak", "mtime": 1700000000, "size": 12345 }
  ]
}

POST /api/config/backup/restore

Restores a selected backup file to the live configuration.

Request Body

{ "platform": "ps2", "filename": "LightgunMono.exe.config.20240225-101010.bak" }

A safety backup of the current live config is created before restore.

Software Update APIs

These endpoints wrap a privileged update script.

GET /api/update/status

Returns the current update state and installed channel.

GET /api/update/check?channel=<name>

Prepares the selected update channel.

Supported channels:

  • latest
  • previous
  • beta
  • psiloc
  • ubuntu

POST /api/update/apply

Runs the update script for the selected channel.

Request Body

{ "channel": "latest" }

GET /api/update/logs

Returns update logs (from file or in-memory buffer).

Static Assets

The following paths serve static assets used by the UI:

  • /logo.png
  • /ps1.png
  • /ps2.png
  • /load.png
  • /offline.png
  • /favicon.ico

Frontend Integration Notes

  • All UI actions use fetch() with JSON payloads
  • Polling is used for:
    • Service status
    • Logs
    • Platform/mode detection
  • No client-side routing; visibility is controlled by tab switching

Security Notes

  • APIs execute privileged system actions (systemctl, file writes)
  • Intended for local, trusted environments only
  • Should not be exposed directly to untrusted networks

License / Ownership

Internal project – SindenPS dashboard tooling.

Clone this wiki locally