0 Fork 0

mirror of https://github.com/MoHadiShibli/Control4Free.git synced 2026-10-06 18:00:33 +02:00

Files

T

MoHadiShibli baf36d648e 1.1.0: rumble and the light bar

A game talks to a virtual controller as it would to a real one, and the system
keeps what it asked for. scePadVirtualDeviceGetRemoteSetting reads it back in
the layout of a DualShock 4's output report: the two motors at [3] and [4], the
light bar at [5..7]. The layout was read on the console while games rumbled and
users signed in, and feedback.c is tested against those exact buffers.

The service reads it every 16 ms for each controller; games pulse rumble for
only tens of milliseconds, which a 100 ms poll missed.

- Rumble goes to the controller's owner as {"method":"v","params":[pad,large,
  small]}, once per change, and to whoever takes a controller over, so a page
  never keeps buzzing on old news. The page already drove an Android phone's
  vibration and a gamepad's actuators from it.
- The light bar goes into the status everyone sees. The PS4 sets player colours
  at a quarter strength, so the colour is brightened to full, keeping its hue;
  an unlit bar keeps the controller's own colour.
- Without the call, controllers work as before and it is logged once.

Also: the page says "Choose user on PS4", not "on TV", since not everyone plays
on a TV. The test stub takes C4F-TEST-FEEDBACK lines to set what the "game"
wants, and the test client can wait for messages the service pushes.

2026-10-06 01:05:32 +03:00

6.7 KiB

Raw Blame History

Protocol

The service listens on TCP port 4264 and speaks plain HTTP/1.1 and WebSocket (RFC 6455). This page is for anyone writing their own client or checking what the page does.

HTTP

Request	Answer
`GET /`, `GET /index.html`, `GET /?…`	The controller page, gzip-compressed, with a Content-Security-Policy.
`GET /manifest.webmanifest`	The web app manifest, for a home-screen shortcut.
`GET /icon-192.png`	The app icon.
`GET /ws` with `Upgrade: websocket`	The control socket, below.
`GET /api/status`, `POST /api/stop`	The launcher API, below.
Anything else	`404`.

Every request needs a Host header that is a literal IPv4 address or localhost, with or without a port; anything else gets 403. This keeps out domain names that resolve to the console (DNS rebinding).

The control socket

GET /ws upgrades to a WebSocket. The handshake is refused with 403 when it carries an Origin other than http://<the Host header> or null; no Origin at all is accepted. Messages are UTF-8 JSON text frames of at most 4096 bytes; a longer frame closes the connection. Fragmented messages and ping/pong control frames are handled.

Requests

{"id": 7, "method": "claim", "params": [0]}

method: a string.
params: an array of up to 16 integers; required, even if empty.
id: optional, an integer from 0 to 2^53−1. Requests with an id get a reply carrying the same id.
jsonrpc: "2.0" is allowed and ignored. Any other key, or anything that isn't this shape, is answered with an Invalid request error.

Controllers are numbered 0 to 3 in the protocol and 1 to 4 on screen.

Method	Params	Reply
`info`	`[]`	`{"version": "1.1.0", "protocol": 2, "pads": 4}`
`status`	`[]`	A status object, below.
`claim`	the controllers this connection wants, for example `[0]` or `[0, 2]`	A status object, once every controller in the claim exists.
`u`	input, below	None.
`leave`	`[pad]`	A status object.
`stop`	`[]`	None; the service stops and the connection closes.
`ping`	`[]`	`{}`

claim is the whole set this connection wants: controllers missing from it that it owned are removed, and free ones in it are created. A claim that needs a new controller is answered when the controller exists, usually within a second; the service keeps serving every other connection in the meantime. It's refused, changing nothing, if any controller in it belongs to another connection (409), if another controller is being created at that moment (409), or if controllers can't be created (503).

u sends the complete state of one controller this connection owns. Input for any other controller is ignored: input never claims a controller.

[pad, buttons, lx, ly, rx, ry, l2, r2, fingers, (id, x, y) × fingers]

Field	Range
`buttons`	a bit mask, below
`lx`, `ly`, `rx`, `ry`	0 to 255, 128 is centred; up and left are 0
`l2`, `r2`	0 to 255
`fingers`	0 to 2 touches on the touchpad
touch `id`	0 to 127, stable while the finger stays down
touch `x`, `y`	0 to 1919, 0 to 941

Button	Bit	Button	Bit
Share	`0x0001`	L2	`0x0100`
L3	`0x0002`	R2	`0x0200`
R3	`0x0004`	L1	`0x0400`
Options	`0x0008`	R1	`0x0800`
D-pad up	`0x0010`	Triangle	`0x1000`
D-pad right	`0x0020`	Circle	`0x2000`
D-pad down	`0x0040`	Cross	`0x4000`
D-pad left	`0x0080`	Square	`0x8000`
PS	`0x10000`	Touchpad click	`0x100000`

Send the state whenever it changes, and at least once a second while the controller is in use. After 3 seconds without input the controller goes neutral and shows as paused; after 15 it's removed. When a connection closes, its controllers' buttons are released at once, and they're removed 15 seconds later unless a connection claims them again; the page does so when it reconnects.

stop is refused with 409 while another connection owns a controller.

The status object

{
  "version": "1.1.0",
  "protocol": 2,
  "pads": [
    {"pad": 0, "name": "Controller 1", "enabled": true, "open": true, "connected": true, "clients": 1,
     "mine": true, "state": "ready", "uid": "1a2b3c4d", "color": [32, 96, 255], "reports": 5120, "error": 0}
  ]
}

Field	Meaning
`open`	The virtual controller exists.
`connected`	A connection owns it and is sending input.
`clients`	1 if a connection owns it, else 0.
`mine`	This connection owns it.
`state`	`free`, `connecting`, `select` (waiting for a user to be chosen on the PS4), `ready` (signed in), `paused` (no input lately, or nobody connected), or `error` (the console refused input).
`uid`	The signed-in user's ID in hex, or `unassigned-…` before sign-in.
`color`	The light bar's colour, brightened so its strongest channel is 255; the controller's own colour until one is set.
`reports`	Samples given to the console so far.
`error`	The console's error code for the last refused sample, or 0.

Messages from the service

{"method": "s", "params": <status>}: the status, whenever something changes and at least once a second.
{"method": "v", "params": [pad, large, small]}: rumble, 0 to 255 for each motor, sent to the controller's owner when it changes and when a connection takes the controller over. [pad, 0, 0] stops it.
{"method": "error", "params": {"message": "…"}}: a problem that isn't the reply to a request: a controller removed for sitting unused, a request that couldn't be parsed, or an error for a request sent without an id.

Errors in reply to a request:

{"id": 7, "error": {"code": 409, "message": "Controller is in use on another device"}}

Code	Meaning
`400`	The request or its values are invalid.
`404`	Unknown method: the page is newer than the service.
`409`	Someone else owns it, another controller is being created, or it isn't yours to `leave`.
`503`	Controllers can't be created now, the kernel log is busy, or the service is stopping.

The launcher API

For the app on the PS4. Both requests need the header X-Control4Free-Launcher: 1, and are refused with 403 if they carry an Origin, an Upgrade, a body or Transfer-Encoding. A browser only sends a custom header cross-origin after a CORS preflight, which the service never answers, so websites can't use these.

GET /api/status   →  {"application": "Control4Free", "api": 1, "version": "1.1.0", "controllers": 2, "stopping": false}
POST /api/stop    →  {"application": "Control4Free", "stopping": true}

/api/stop removes every controller, even ones in use, and the service exits a quarter of a second later.

6.7 KiB Raw Blame History Unescape Escape