If the WebSocket server needs a passphrase to connect to, clients need to supply it encoded as a hex string in the Sec-WebSocket-Protocol header. Using JavaScript, you can add it to an array as a second parameter when creating a WebSocket instance, following the connection URL:

const socket = new WebSocket('ws://<IP address or FQDN>:4321', ['<your passphrase>']);

When connecting to the WebSocket server, the connecting client receives a list of currently registered blocks (including their display name, the current powered state, the output signal strength and the assigned group's id, if any), as well as block groups.

{
    "type": "block_list",
    "data": [
        {
            "blockId": "00000000-0000-0000-0000-000000000000",
            "name": "Example",
            "power": 15,
            "powered": false,
            "groupId": "00000000-0000-0000-0000-000000000000"
        },
        // ...
    ]
}

{
    "type": "block_groups",
    "data": [
        {
            "groupId": "00000000-0000-0000-0000-000000000000",
            "name": "Example Group",
            "blockIds": [
                //...
            ]
        },
        // ...
    ]
}

If any block or group is updated, their data will broadcast to every connected client.

{
    "type": "block_updated",
    "data": {
        "blockId": "00000000-0000-0000-0000-000000000000",
        "name": "Example",
        "power": 15,
        "powered": false,
        "groupId": "00000000-0000-0000-0000-000000000000"
    }
}

{
    "type": "group_updated",
    "data": 
        "groupId": "00000000-0000-0000-0000-000000000000",
        "name": "Example Group",
        "blockIds": [
            //...
        ]
    }
}

Block Management

Set a block's powered state:

{
    "type": "block_state",
    "data": {
        "blockId": "00000000-0000-0000-0000-000000000000",
        "powered": false // Can be either true or false
    }
}

Set a block's output signal strength:

{
    "type": "block_power",
    "data": {
        "blockId": "00000000-0000-0000-0000-000000000000",
        "power": 7 // Can be anything between 0 and 15
    }
}

Set the display name of a block:

{
    "type": "rename_block",
    "data": {
        "blockId": "00000000-0000-0000-0000-000000000000",
        "name": "My Example Block"
    }
}

Delete a block from the Web UI:

{
    "type": "unregister_block",
    "data": {
        "blockId": "00000000-0000-0000-0000-000000000000"
    }
}

Add or remove a block to/from a group:

{
    "type": "change_group",
    "data": {
        "blockId": "00000000-0000-0000-0000-000000000000",
        "groupId": "00000000-0000-0000-0000-000000000000"
    }
}

Move a block to a different position in a group:

This only affects a block if it has been assigned to a group.

{
    "type": "move_block",
    "data": {
        "blockId": "00000000-0000-0000-0000-000000000000",
        "newIndex": "2"
    }
}

Group Management

Create a new group:

{
    "type": "create_group",
    "data": {
        "name": "My awesome group"
    }
}

Rename a group:

{
    "type": "create_group",
    "data": {
        "groupId": "00000000-0000-0000-0000-000000000000",
        "name": "My awesome (renamed) group"
    }
}

Delete a group:

{
    "type": "delete_group",
    "data": {
        "groupId": "00000000-0000-0000-0000-000000000000"
    }
}

Move a group to a new position in the list of all groups:

{
    "type": "move_group",
    "data": {
        "groupId": "00000000-0000-0000-0000-000000000000",
        "newIndex": 2
    }
}