pijector

README

Pijector

Pijector is yet another piece of Kiosk software designed for Raspberry Pi. It uses the Chrome Devtools Protocol (via the rod library) to control a Chromium instance as a Kiosk display.

Usage

You will need to launch a Chromium instance in debug mode as a prerequisite. For example:

$ chromium-browser \
    --incognito \
    --kiosk \
    --no-first-run \
    --remote-debugging-port=9222 \
    --user-data-dir=$(mktemp -d) \
    -- \
        "about:blank"

DevTools listening on ws://127.0.0.1:9222/devtools/browser/b2d22b3a-dd60-4aa8-86fc-fa494d90e1dc

For testing and development purposes, you may use bin/start-screen.sh.

Then, configure the Pijector server to control the chromium(s) you started. This will require a bit of YAML.

---
listen: 0.0.0.0:9292
default_url: https://en.wikipedia.org/wiki/Special:Random
screens:
  - name: Test Screen 1
    address: localhost:9223

Then run the server, given the above config as pijector-dev.yml:

$ pijector server --help
NAME:
   pijector server - Run the pijector server

USAGE:
   pijector server [command options] [arguments...]

OPTIONS:
   --config value, -c value  Path to server configuration file.
   --help, -h                show help (default: false)
$ pijector server -c pijector-dev.yml
DEBU[0000] Loaded config: {Listen:0.0.0.0:9292 DefaultURL:https://en.wikipedia.org/wiki/Special:Random Screens:[{Name:Test Screen 1 Address:localhost:9223}]}
INFO[0000] attached to screen                            address="localhost:9223"
INFO[0000] server listening on 0.0.0.0:9292

As soon as the Pijector server starts, it will attempt to take control of the Chromium instance, navigate it to the pijector default page, and bring it to the foreground.

Controlling the Pijector

Pijector exposes a simple admin user interface at /admin on its bound address (localhost:9292/admin by default).

API

The Pijector API is quite simple. The admin interface uses it to discover and control screens, and other Pijectors may use it to control screens on remote Pijectors (see below).

• GET /api/v1/screen will return an object describing the screens controlled by the Pijector instance.

  For example:

  {
    "screens": [
      {
        "url": "/api/v1/screen/91d21a4b-452d-43f7-a6bd-53797114242d",
        "id": "91d21a4b-452d-43f7-a6bd-53797114242d",
        "name": "Left Shoulder",
        "snap": "/api/v1/screen/91d21a4b-452d-43f7-a6bd-53797114242d/snap?2021-05-24T17:31:46Z",
        "display": {
          "title": "Aidan Roark - Wikipedia",
          "url": "https://en.wikipedia.org/wiki/Aidan_Roark"
        }
      },
      {
        "url": "/api/v1/screen/3b941997-b50f-4798-83ba-675c697dad61",
        "id": "3b941997-b50f-4798-83ba-675c697dad61",
        "name": "Remote Screen",
        "snap": "/api/v1/screen/3b941997-b50f-4798-83ba-675c697dad61/snap?2021-05-24T17:31:46Z",
        "display": {
          "title": "1945 All-Big Ten Conference football team - Wikipedia",
          "url": "https://en.wikipedia.org/wiki/1945_All-Big_Ten_Conference_football_team"
        }
      }
    ]
  }
  

• GET /api/v1/screen/$SCREENID will return details about the screen's current display.

  For example:

  {
    "url": "/api/v1/screen/91d21a4b-452d-43f7-a6bd-53797114242d",
    "id": "91d21a4b-452d-43f7-a6bd-53797114242d",
    "name": "Left Shoulder",
    "snap": "/api/v1/screen/91d21a4b-452d-43f7-a6bd-53797114242d/snap?2021-05-24T17:31:46Z",
    "display": {
      "title": "Aidan Roark - Wikipedia",
      "url": "https://en.wikipedia.org/wiki/Aidan_Roark"
    }
  }
  

• GET /api/v1/screen/$SCREENID/stat is an alias for /api/v1/screen/$SCREENID

• GET /api/v1/screen/$SCREENID/show?target=$TARGETURL will instruct the screen to display the provided $TARGETURL. On success, it will wait for the page to be displayed, and then return a /stat payload (as above) with the new details.

• GET /api/v1/screen/$SCREENID/snap will return a full-resolution PNG screenshot of the screen's current display.

Aggregating Screens

Since the Chromium / Google Chrome debugger refuses to bind to non-local (127.0.0.1, etc) addresses, a Pijector server will not be able to directly control a Chromium screen on another host. However, Pijector can use the API on another Pijector instance to virtually attach screens from other Pijector instances. This means that at least one Pijector server must be running on each Pijector host, but they can all be aggregated for control on a single server.

Pijector will know what you mean if you configure the address of a screen to contain a screen API URL. For example:

---
listen: 0.0.0.0:9292
default_url: https://en.wikipedia.org/wiki/Special:Random
screens:
  - name: Local Screen
    address: localhost:9223
  - name: Remote Screen
    address: http://other.host:9292/api/v1/screen/3b941997-b50f-4798-83ba-675c697dad61

Documentation

Overview

Package pijector uses the Chromium devtools protocol to control a Chromium instance in debugging mode.

Index

• Variables
• func DefaultTransport() http.RoundTripper
• type RemoteOption
  • func WithClientTimeout(ttl time.Duration) RemoteOption
  • func WithPassword(password string) RemoteOption
  • func WithRoundTripper(rt http.RoundTripper) RemoteOption
• type Screen
  • func AttachLocal(name, addr string) (Screen, error)
  • func AttachRemote(name, u string, opts ...RemoteOption) (Screen, error)
• type ScreenStatus

Variables

var (
	// Version of Pijector. Overridden at build time.
	Version = "development"
)

Functions

func DefaultTransport

func DefaultTransport() http.RoundTripper

DefaultTransport for HTTP requests to the Pijector API. Useful for wrapping the transport from outside the library.

Types

type RemoteOption

type RemoteOption func(*remoteInitOpt)

func WithClientTimeout

func WithClientTimeout(ttl time.Duration) RemoteOption

WithClientTimeout while connecting to the Pijector API.

func WithPassword

func WithPassword(password string) RemoteOption

WithPassword to authenticate to remote Pijector API.

func WithRoundTripper

func WithRoundTripper(rt http.RoundTripper) RemoteOption

WithRoundTripper for HTTP requests to the Pijector API.

type Screen

type Screen interface {
	// ID of the Screen, which is unique across Pijector instances.
	ID() string
	// Name of the Screen. Intended to be human-friendly. If name is not set when
	// the Screen is created, it will return ID().
	Name() string
	// Show a url on the Screen.
	Show(u string) error
	// Snap a screenshot of the Screen's current display.
	Snap() (io.ReadCloser, error)
	// Stat of the Screen.
	Stat() (ScreenStatus, error)
}

Screen represents a single Pijector display.

func AttachLocal

func AttachLocal(name, addr string) (Screen, error)

AttachLocal attaches a local Chromium instance via CDP at the provided addr, and identifies it in Pijector with the provided human-friendly name.

func AttachRemote

func AttachRemote(name, u string, opts ...RemoteOption) (Screen, error)

type ScreenStatus

type ScreenStatus struct {
	Title string `json:"title,omitempty"`
	URL   string `json:"url"`
}

ScreenStatus contains information about a Screen's current display.