PiPiece UI

Appearance

PiPiece Server ​

Swagger API Docs

Raspberry Pi management server with REST API.

API Documentation ​

Interactive API documentation is available via Swagger UI:

Local: http://localhost:3000/api-docsRaspberry Pi: http://pipiece.local:3000/api-docs

Available Endpoints ​

System Management ​

  • GET /api/system/status - Get system uptime and status
  • GET /api/system/metrics - Get load averages and current CPU temperature
  • POST /api/system/restart - Restart the Raspberry Pi
  • POST /api/system/shutdown - Shutdown the Raspberry Pi
  • POST /api/system/update - Update system packages (streams NDJSON output)

Camera ​

  • POST /api/camera/capture - Capture a single photo
  • POST /api/camera/long-exposure - Capture a long exposure photo
  • POST /api/camera/timelapse/start - Start a timelapse capture sequence
  • GET /api/camera/timelapse/status - Get current timelapse status
  • POST /api/camera/timelapse/stop - Stop active timelapse capture
  • GET /api/camera/stream - Stream live MJPEG video
  • GET /api/camera/settings/:type - Get last-used settings for preview or timelapse (falls back to defaults)

Camera Settings Examples ​

Request paths:

  • GET /api/camera/settings/preview
  • GET /api/camera/settings/timelapse

Example response (preview, saved values):

json
{
	"success": true,
	"type": "preview",
	"source": "saved",
	"settings": {
		"filename": "m42-preview",
		"width": 4056,
		"height": 3040,
		"gain": 1.2,
		"exposure": 1500,
		"redGain": 1.52,
		"blueGain": 1.6
	}
}

Example response (timelapse, defaults):

json
{
	"success": true,
	"type": "timelapse",
	"source": "defaults",
	"settings": {
		"interval": 2000,
		"duration": 60000,
		"prefix": "timelapse",
		"width": 4056,
		"height": 3040,
		"gain": 1,
		"exposure": 5,
		"redGain": 1.49,
		"blueGain": 1.55
	}
}

File Management ​

  • GET /api/files - List files/directories (supports path, sort, order query params)
  • POST /api/files/mkdir - Create a directory
  • PUT /api/files/rename - Rename a file or directory
  • DELETE /api/files - Delete a file or directory

Events ​

  • GET /api/events - Server-sent events stream with system uptime, load averages, CPU temperature, and camera status

Config ​

  • GET /api/config - Read current values from pipiece.env and active config paths
  • PUT /api/config - Write key/value config to pipiece.env and reload runtime environment

Other Server Routes ​

  • GET /api-docs - Swagger UI API documentation
  • GET /photos/* - Static access to photo files under the photos directory

Setup ​

Install Dependencies ​

bash
npm install

Configure Sudo Permissions ​

For system operations to work, configure sudo permissions for the user running Node.js:

bash
sudo visudo

Add the following line (replace username with your user):

username ALL=(ALL) NOPASSWD: /sbin/reboot, /sbin/shutdown, /usr/bin/apt

Start Server ​

bash
npm start

The server will run on port 3000.

Environment Configuration ​

At startup, the server loads environment variables from:

  • $HOME/pipiece/system.env

Runtime defaults applied when not set:

  • PHOTOS_DIR=/home/pi/photos
  • CONFIG_DIR=$HOME/pipiece/config

The config API reads/writes:

  • $CONFIG_DIR/pipiece.env
  • $CONFIG_DIR/preview.json (last-used preview capture settings)
  • $CONFIG_DIR/timelapse.json (last-used timelapse settings)

Updating config through PUT /api/config reloads values in the running process.

Development ​

The API uses Express.js and includes:

  • swagger-ui-express - Interactive API documentation
  • swagger-jsdoc - Generate OpenAPI specs from JSDoc comments
  • morgan - HTTP request logger
  • cookie-parser - Parse cookies

Testing ​

Use the included .http file with REST Client extension in VS Code, or access the Swagger UI for interactive testing.