Communication Protocol

The SpiNNaker partition server uses a simple JSON-based protocol over TCP to communicate with clients. The protocol has no security features what-so-ever, just like SpiNNaker hardware, and it is assumed that the server is operated within the same trusted network as the boards it manages.

By default, the server listens on TCP port number 22244. The client and server communicate by sending and receiving newline (\n) delimited JSON objects (i.e. lines of the form {...}). Clients may send commands to the server to which return values are sent by the server. The server may also asynchronously send notifications to the client, if requested by the client.

As soon as a client connects to the server it should send a version() command and ensure the server version is compatible with the client.

Sending Commands

Commands map exactly to Python function calls. A command has a name and arguments and returns a value. To send a command, a client must sent a JSON object the following keys, followed by a newline:

A string. The name of the command to be executed.
An array. A list of positional arguments for the command.
An object. A list of keyword arguments for the command.

For example, if a client sent the following to the server:

{"command": "create_job", "args": [4, 2], "kwargs": {"owner": "me"}}\n

This would be interpreted as a function call like:

create_job(4, 2, owner="me")


In all examples, \n means a newline character (ASCII 10), not the \ and n characters.

The server will then respond with a JSON object with a single key, “return”, whose value is the value returned by the command. For example:

{"return": 42}\n

Commands are processed and return values sent in FIFO order. No blocking commands are implemented by the server and the server will make a best-effort attempt to respond to all commands as quickly as possible. If any command is malformed or causes an error for any reason, the client is immediately disconnected.

Receiving Asynchronous Notifications

If the client requests to be notified of certain events (using a command, as described above), the server may send a JSON object to the client which does not contain the key “return”. Notifications may be sent at any time, once requested, including between a function being called and the return value being sent. The exact format of the notification depends on its type. An example notification may look like the following:

{"jobs_changed": [42, 10, 3]}\n

Available Commands