Websocket API Documentation? And wiring questions

Hello! I’ve connected to the websocket port and am struggling a bit to get info/send commands. I’m wondering if there’s a written out documentation of the possible messages to the websocket API - the only thing I can currently find is the video. I currently am sending {listPrograms:true} through a react front end, but I get a long arraybuffer that consists of individual numbers back, with no pattern names.

I’m also wondering if serial resistors are necessary from the pixelblaze output expanders to the data inputs of ws2812b/2813s.

When using multiple output expanders, (to run e.g. 14 strips from a pixelblaze) how should they be wired?

Hi! Here’s the lightweight websocket docs:

No, you don’t need serial resistors.

To use multiple expanders, just connect DAT from PB to all the expanders’ serial inputs (and power them + establish a common ground).

1 Like

If you have any questions after checking out the docs let us know!

You may also want to check out Firestorm (JavaScript) and pixelblaze-client (Python) which have code that can work with the protocol and handle parsing the pattern list.

1 Like

Thanks for the replies! Im writing a react front end so I’ll look at Firestorm.

I’m getting it where I can successfully getVars, set variables like brightness and colors in patterns from my front end. The only issue I’m having now is the listPrograms call- I get an arraybuffer that looks like this.
image and can’t parse it.
JSON.stringifying the whole arraybuffer definitely doesnt work as in the example in the git (https://github.com/simap/pixelblaze_websocket_example/blob/master/nodejs/getVars.js)

I’ve also tried

String.fromCharCode.apply(null, new Uint16Array(message.data));

which gives a similar error, image

Also, when I’m in editing mode on the pixelblaze ui, it seems like my websocket listener is getting spammed with messages, without doing any calls and without doing any changes in the PB editor - any idea whats going on there?

Yeah, that is expected for the pattern list reply. Check out the section “V2 Pattern List Response” in the websocket docs:

Pixelblaze uses a combination of text and binary websocket frames. The live preview pixels also stream on binary frames, which is probably what you are getting spammed with. Check the type of your websocket event data, e.g. typeof evt.data === "string" for text/json frames, otherwise it is a binary frame and usually provided in an ArrayBuffer. You can tell the browser that you prefer ArrayBuffer with this:

websocket.binaryType = "arraybuffer";

All Pixelblaze websocket binary frames have a simple 2 byte header that indicates its type, and some bit flags to indicate beginning and end frames of payloads that have been split across many websocket frames. The rest of the binary frame is the payload (or chunk of the payload). Due to memory limitations, the entire list of patterns can’t be sent all at once and doesn’t use JSON.

Pixelblaze ensures that a given pattern list frame is composed of one or more complete items, so each frame’s worth can be parsed without having to worry about a record being split across frames.

Firestorm has some code that handles these, feel free to copy from it:

It checks the type, flags, and slices the remaining bytes and converts those to text which is then converted to text, parsed, and added to the list until the end frame.

You can use the parsing code from Firestorm, though converting your payload to text will likely be different in the browser than in NodeJS. This line:

let text = Buffer.from(data).toString('utf8')

Can be replaced by something like this:

function readAsUtf8(buf, cb) {
  var blob = new Blob([new Uint8Array(buf)]);
  var fileReader = new FileReader();
  fileReader.onload = function(e) {
readAsUtf8(data, function(text) {
  //parse here

You can alternatively use the more elegant TextDecoder if you don’t care about old browsers or IE.

var text = new TextDecoder().decode(data)
1 Like

Thanks, I got it working with TextDecoder. Probably will be back later once I have my own pixelblaze and have a more complicated/permanent setup with more questions.

1 Like