pxnode HTTP API

The node's identity. The one request that never needs the password.

Older firmware may leave out zone, bootloader and password: read them as "", "" and false.

{"uuid":"003000513431500d20343556","name":"Stage left","zone":"","manufacturer":"Kinora","model":"pxnode 4",
 "firmware":"0.1.8","api":1,"capabilities":["rgbw","fx","sync"],"mac":"00:80:e1:62:b2:52","slot":"B",
 "bootloader":"1.0.0","http":80,"password":false,"ip":"10.2.1.99","mode":"standalone","revision":479}

Health and live counters: what the node is doing now, and what went wrong since it started. Nothing here is saved; everything restarts at boot.

Node

Input

Rates, over the last second

Pixel output

Network errors, since start

Totals and settings storage

Zone sync

The pxsync object: how the node keeps in step with the other nodes of its zone (pxsync in /api/timing).

{"link":true,"uptime_s":3612,"reset_cause":"power-on","temperature_c":46.4,"cpu_load":36,"stack_free":17192,
 "input":"ok","input_age_ms":24,"artnet_source":"10.2.1.215","artsync":false,"blackout":false,
 "artnet_fps":468,"artnet_universes":12,"artnet_frame_rate":40,"artsync_fps":0,"pixel_fps":60,"dmx_in_fps":0,
 "dmx_out_fps":43,"network_fps":470,"artnet_ignored_fps":0,"frame_us":16666,"frame_rate_max":60,"render_us":702,
 "pixel_overruns":1,"net_rx_missed":0,"net_rx_errors":0,"pbuf_exhausted":0,"heap_exhausted":0,
 "totals":{"artnet_packets":1690245,"dmx_in_frames":0,"dmx_out_frames":155316,"pixel_frames":216720,"pixel_overruns":1},
 "config":{"saves":76,"erases":0,"free_bytes":43520},"sync":{"events":0,"last_age_ms":-1},
 "pxsync":{"enabled":true,"role":"alone","nodes":0,"peers":[],"more_peers":0}}

The Art-Net controllers sending to the node, up to 10, most recent first. When several send the same universe, the node takes the last packet received.

{"senders":[{"ip":"10.2.1.215","active":true,"last_seen_ms":12,"packets_per_s":480,"dropped_per_s":0,
  "broadcast":false,"artsync":true,"universes":[{"universe":0,"packets_per_s":40,"used":true,"shared":false}],
  "more_universes":false}]}

The nodes of the network this node has found, itself first, up to 32. Only nodes of its own zone are listed. Each entry has the fields of GET /api/node, plus mask, online (heard in the last 32 s) and last_seen_ms. A node that went silent stays listed, offline, until this node restarts. The list refreshes every 10 s.

{"nodes":[{"uuid":"003000513431500d20343556","name":"Stage left","zone":"","manufacturer":"Kinora",
  "model":"pxnode 4","firmware":"0.1.8","api":1,"capabilities":["rgbw","fx","sync"],"mac":"00:80:e1:62:b2:52",
  "slot":"B","bootloader":"1.0.0","http":80,"password":false,"ip":"10.2.1.99","mask":"255.255.255.0",
  "mode":"standalone","revision":479,"online":true,"last_seen_ms":0}]}

Searches the network now instead of waiting for the next refresh. Replies arrive within milliseconds: read /api/nodes a few hundred ms later. Answers {"ok":true}.

curl -X PUT -d '{"name":"Stage left"}' http://10.2.1.99/api/name

{"name":"Stage left","revision":480}

{"ip":"10.2.1.99","mask":"255.255.255.0","gateway":"10.2.1.1","zone":"","revision":479}

What drives the pixels.

curl -X PUT -d '{"mode":"artnet-shape","input_profile":"fx","input_address":101}' http://10.2.1.99/api/mode

{"mode":"artnet-shape","input_address":101,"input_profile":"fx","input_universe":0,"control_universe":28,
 "control_address":1,"ignore_broadcast":false,"revision":480}

The DMX output, fed from an Art-Net universe.

{"output_enabled":true,"output_universe":0,"revision":479}

The node's screen and keys.

{"brightness":100,"screensaver_s":10,"rotation":0,"lock":false,"revision":479}

{"frame_rate_max":60,"artsync":true,"effect_sync":true,"pxsync":true,"revision":479}

Sets, changes or removes the node's password (see Authentication). Changing it needs the current one. It protects the settings, not the show: Art-Net, DMX and the presets keep working.

The password is never read back, and GET /api/config leaves it out. Forgotten: on the node's screen, Menu, Factory reset, Network only (the address returns to 10.0.0.99).

curl -X PUT -d '{"password":"stage left"}' http://10.2.1.99/api/password

{"password":true,"revision":481}

The four pixel outputs at a glance.

{"outputs":[{"output":"A","color_mode":"rgb","pixels":340,"groups":2,"max_pixels":512},
  {"output":"B","color_mode":"rgb","pixels":340,"groups":2,"max_pixels":512},
  {"output":"C","color_mode":"rgb","pixels":340,"groups":2,"max_pixels":512},
  {"output":"D","color_mode":"rgb","pixels":340,"groups":2,"max_pixels":512}],"revision":479}

One output: its pixel type and its patch, up to 16 groups of pixels, each on an Art-Net universe and address.

Group

Writing a patch

• Element i of groups updates group i; its missing fields, and the groups past the end of the array, are unchanged. Send all 16 groups to set a whole patch.
• A group does not continue on the next universe: pixels past channel 512 stay black (170 RGB or 128 RGBW pixels fit from address 1).
• More pixels than max_pixels are accepted; the extra ones are not sent.
• The other outputs are not changed.

curl -X PUT -d '{"color_mode":"rgbw","groups":[{"pixels":128,"universe":4},{"pixels":128,"universe":5},{"pixels":0}]}' \
     http://10.2.1.99/api/outputs/B

{"output":"A","color_mode":"rgb","max_pixels":512,"groups":[
  {"pixels":170,"universe":0,"address":1,"order":"grb","flip":false,"brightness":255,"highlight":false},
  {"pixels":170,"universe":1,"address":1,"order":"grb","flip":false,"brightness":255,"highlight":false},
  {"pixels":0,"universe":0,"address":1,"order":"grb","flip":false,"brightness":255,"highlight":false}],
 "revision":479}

Same body and rules as the PUT, plus highlight, applied to the output at once and not saved: for live patching in an editor, each change sent as it is made. Answers with the output as previewed. A restart, or a PUT of the output, returns to the saved patch.

curl -X POST -d '{"groups":[{},{"highlight":true}]}' http://10.2.1.99/api/outputs/A/preview

In standalone mode the pixels show one of the node's presets: a colour, or an effect between two colours. Up to 12 presets; the first is always there and always a single colour.

Preset

Factory presets: Solid colour (white), Fire, Ocean, Rainbow, Starry night, Plasma.

{"active":0,"presets":[{"name":"Solid colour","profile":"rgb","dimmer":255,"color":"ffffff00"},
  {"name":"Fire","profile":"shape","dimmer":255,"bg":"46000000","fg":"ff820000","effect":"fire","speed":150,
   "scale":60,"fx_dimmer":255}],"revision":479}

The preset shown now, for show control: changed with a crossfade, not saved. After a restart the node shows its default. In a mode other than standalone, the choice is kept for when the node returns to it.

curl -X PUT -d '{"preset":2,"fade_ms":4000}' http://10.2.1.99/api/presets/active

{"preset":2,"name":"Ocean","fading":true,"saved":false,"previewing":false}

The default preset, shown when the node starts. Setting it saves it (one flash write, none if it already is the default) and does not change the preset shown now.

curl -X PUT -d '{"preset":3}' http://10.2.1.99/api/presets/default

{"preset":3,"name":"Rainbow"}

Shows a preset being edited instead of the preset shown, without saving it. {"preset": {...}} takes the fields of a preset; the ones left out come from the previous preview, or from the preset shown. The preview ends with {"stop": true}, when a preset is shown, or 10 s after the last preview: an editor resends it every few seconds while it stays open. Answers like GET /api/presets/active.

curl -X POST -d '{"preset":{"effect":"plasma","speed":200}}' http://10.2.1.99/api/presets/preview

Every output dark, pixels and DMX, whatever the input. Not saved: a restart releases it. Inputs are still read and effects keep running, so a release shows the outputs as they are now.

curl -X PUT -d '{"on":true,"fade_ms":3000}' http://10.2.1.99/api/blackout

{"on":true,"level":255,"fade_ms":3000}

The whole configuration in one document, to back up a node or copy it onto another. Its sections are those of their own routes: name, network, mode, dmx, display, timing, presets, and outputs (A to D, as /api/outputs/{X}). About 7 KB.

• GET: one revision at the top; read-only and preview fields are left out.
• PUT: up to 32 KB. Each section is checked like its own PUT, then everything is saved once and applied: all or nothing. A section left out keeps its settings, so a document with only mode and outputs changes only those. Members other than the sections are ignored.
• With revision, the import is refused (409) if the node was changed since. Leave it out to restore a backup.
• Answers {"ok":true,"revision":152}. An error names its section: "field":"outputs[1].groups[0].pixels". A new network address applies once the answer is sent.

{"api":1,"model":"pxnode 4","firmware":"0.1.8","revision":151,
 "name":{"name":"Stage left"},
 "network":{"ip":"10.2.1.99","mask":"255.255.255.0","gateway":"10.2.1.1","zone":""},
 "mode":{...},"dmx":{...},"display":{...},"timing":{...},"presets":{"active":0,"presets":[...]},
 "outputs":[{"output":"A","color_mode":"rgb","groups":[{"pixels":170,"universe":0,"address":1,...}]}]}

curl http://10.2.1.99/api/config > stage-left.json
curl -X PUT --data-binary @stage-left.json http://10.2.1.100/api/config

Shows an identify screen on the node and lights its identify LED, to find it on the rig. Answers {"ok":true}.

Restarts the node about 200 ms after answering {"ok":true}.

Restarts into recovery: the node stays at the same address and serves a page to install a firmware. The outputs stay dark until it restarts. Needs bootloader 1.0 or later (bootloader in /api/node); 409 unsupported otherwise.

Restores factory settings, then restarts. Without a body: everything, the name included (address 10.0.0.99/24, no zone, no password, DMX shape mode, default patch and presets). With {"sections": [...]}, only those parts:

curl -X POST -d '{"sections":["patch","presets"]}' http://10.2.1.99/api/actions/factory-reset

Installs a firmware. The body is the .pxfw file of a release, sent as is with its Content-Length. The node writes it next to the firmware it runs, checks it, answers {"ok":true,"slot":"A"} and restarts on it. During the write the outputs freeze for a few seconds.

If the new firmware fails to start three times, the node goes back to the previous one by itself. A file that is not a valid firmware for the node is refused with 400 firmware and a message, and nothing changes.

curl --data-binary @pxnode-2.0.0.pxfw -H 'Content-Type: application/octet-stream' http://10.2.1.99/api/firmware

{"ok":true,"slot":"A"}