Communication Protocol¶

The control server contains the following http endpoints:

The control server also accepts websocket connections and informs connected clients of certain events when they take place. This includes updates on reservation statuses and notifications when devices become available for reservation.

While the workers contain http endpoints, these are not called directly by clients:

The majority of worker communication is done through a websocket.

Exposing Device States¶

During a devices reservation, its state determines its behavior and how it can communicate with the client. Device states inherit from icefarm.worker.device.state.core.AbstractState and can be made available to clients by decorating the class with icefarm.worker.device.state.reservable.reservable. States can receive arguments from the client upon initialization.

@reservable("example state", "message")
class ExampleState(AbstractState):
    def __init__(state, message)
        super().__init__(state)
        print(f"Message from client!: {message}")

Initial Reservation Handshake¶

When a client is created, it starts a websocket connection to the control server. This allows the control server to send events to the client. Once a client wants to use devices, it uses the /reserve or /reserveserials endpoint on the control server. The control server determines which devices the client will be given and figures out what worker servers the devices are located on. In the background, it sends a request to the each relevant worker /reserve endpoint to initialize the device. When a worker receives a reservation request, it determines which AbstractState to create using the kind argument. The args argument are passed into the AbstractState during initialization.

The control server then responds with a map of device serials to worker urls.

After the client receives a response from the control server, it creates a websocket connection to each of the provided workers. When a worker is done initializing a device for the client, it sends a initialized event containing the devices serial through the websocket to the client.

Handling Client Events¶

The client uses its EventServer to receive data from workers and the control server through websockets. This functions like a webserver and has a similar interface to most python web libraries. The client can register methods:

class ExampleEventHandler(AbstractEventHandler):
    @register("results", "data")
    def printResults(self, data)
        print(data)

{
    "serial": "example pico2ice serial",
    "contents": [
        {
            "event": "results",
            "data": "hello!"
        }
    ]
}

Sending Worker Commands¶

The workers AbstractStates can expose methods to the client. This is done using the AbstractState.register decorator. Calls are handled through the worker's websocket and file transfers are supported.

class ExampleState(AbstractState):
    ...
    @AbstractState.register("getdata", "data")
    def receiveData(self, data)
        print(f"Got data from client: {data}")

{
    "serial": "example pico2ice serial id",
    "event": "getdata",
    "contents": {
        "data": "Hello!"
    }
}