How do I use Python to control the IO over WebSockets on my BB-400


The BB-400 can be used with many different programming languages. This FAQ explains how the Python programming language can be used to obtain and set the IO line status over WebSockets on the BB-400.


Install Visual Studio Code available here:
Download and install Python on your PC:
Attach your BB-400 to the same network as the development PC using the Uplink Ethernet port or a WiFi connection.

If your version of Visual Studio Code does not have Python installed, then please refer to the following link: FAQ How do I set up visual studio code with Python.

Obtain the IP address of the BB-400 and the port number of the Websocket server

The Websocket server port number can be obtained from the Brainboxes Web admin IO page.
Here you can see that the Websocket server is running on port 8989:


Sample Python Program for BB-400

In this example we are going to connect to the Websocket server on the BB-400 and print out the IO line status every time there is a change in state.

Copy the following code into your sample program on VS Code and make sure to update the IP address and port number to match the settings on the BB-400.

'''In this example we are going to connect to the Websocket server on the BB-400 and print out the IO line status every time there is a change in state.
The default port number of the Websocket server is 8989.'''

import websocket, json, datetime

# status dictionary contains string values for 0 and 1
status = {
        0: "off",
        1: "on"

# this function is called when the websocket connection is opened
def on_open(ws):
    # set all the outputs to zero on startup
    json_data = [0,0,0,0,0,0,0,0]

    print("Connected to WebSocket server setting all outputs off/open/0")

    # send the data as json string to the websocket server  to set the output lines status

# this function is called when any error occurs when the websocket connection is open
def on_error(ws, error):
    print("Error occurred: "+ error)

# invoked after websocket connection is closed
# websocket connection can be closed using keyboard interrupt (Ctrl+C)
def on_close(ws):
    print("##### closed websocket connection #####")

def on_message(ws, message):
    '''The BB-400 sends a message everytime the state of the IO changes
        ws {object} -- the websocket connection object
        message {JSON} -- the JSON message sent by the BB-400 looks like
                                "inputs": [1,1,1,1,1,1,1,1],
                                "outputs": [0,0,0,0,0,0,0,0]

    # the response from the BB-400 is in JSON format
    # converting it to a Python object
    response = json.loads(message)
    # extract only the 'outputs' section of the response
    io_status = response["outputs"]
    # print the outputs in  readable format
    print("nn------"+"%d %B %Y %I:%M:%S %p ")+"-------n")
    print("Light: "+str(status[io_status[0]]))
    print("Modem: " + str(status[io_status[1]]))
    print("Motor: " + str(status[io_status[2]]))
    print("Pump: " + str(status[io_status[3]]))
    print("Sensor: " + str(status[io_status[4]]))
    print("Fan: " + str(status[io_status[5]]))
    print("Printer: " + str(status[io_status[6]]))
    print("Buzzer: " + str(status[io_status[7]]))

# the starting point of the program
if __name__ == "__main__":
    # The ip of the BB-400 and the port the websocket server is on
    ws_end_point = "ws://"
    print("Opening Connection to BB-400 WebSocket Server on "+ws_end_point)

    # create a websocket connection to the websocket server on the BB-400
    # initialise the functions to be called when open, close, error and message received events occur
    ws = websocket.WebSocketApp(ws_end_point,
                                on_open= on_open,
                                on_message = on_message,
                                on_error = on_error,
                                on_close = on_close)

    # The websocket connection can be exited using Keyboard interrupt (Ctrl+C)
    print("nPress Ctrl+C to exit the program")

    # to keep the connection open

This example is based on Python version 3.6.

If you need to install missing header files, use the following command in the terminal window. To go to the terminal window View > Terminal. The terminal window opens at the bottom of the editor:

  • pip3 install websocket-client


To run the program right-click on the editor and select ‘Run Python File in Terminal’.

A terminal opens up at the bottom of the editor. The program is executed and the output is displayed in the terminal.

As soon as the websocket connection is opened, the websocket server sends the IO line status. The program prints out the output status, resets the IO line status and then waits for further response from the websocket server:


The web admin IO page of the BB-400 shows the status of all the outputs. It is possible to change an output status by clicking on the output:


Within the python terminal, the new status of the outputs are received by the python program.
Every time the status of the IO lines on the BB-400 changes, the websocket server sends the updated IO line status, and our python program prints it out:


To stop the process, disconnect the websocket connection and stop the program by pressing Ctrl+C.