TCP Communication

PLESTY devices communicate with client applications over TCP/IP using ZeroMQ (ZMQ). This decouples the hardware interface from the control logic, allowing devices to run on dedicated machines while experiments control them over the network.

Architecture

The communication model follows a simple server-client pattern:

┌─────────────────┐          ZMQ          ┌─────────────────┐
│  Device Server  │ ◄──────────────────►  │  Device Client  │
│  (on lab PC)    │    tcp://host:5555    │  (experiment)   │
└─────────────────┘                       └─────────────────┘

• Server wraps a device instance and listens for incoming requests
• Client connects to the server and sends commands on behalf of the experiment

Server

The SDK provides build_server() to create a TCP server for any device:

from plesty.lib.service import build_server

server = build_server(
    device=my_device,
    fixed_threading=False,
    address="tcp://*:5555",
)

The server listens for ZMQ messages, dispatches them to the device's methods, and returns responses. The fixed_threading parameter controls whether each request gets a dedicated thread.

Client

The SDK provides build_client() to create a client that connects to a device server:

from plesty.lib.service import build_client

client = build_client(
    address="tcp://localhost:5555",
    timeout=5000,
    resources=None,
    client_id=None,
    connect_kwargs=None,
)

The client sends method calls and parameters to the server and receives responses. The timeout parameter (in milliseconds) controls how long to wait for a response.

Message protocol

Messages are serialized as JSON over ZMQ. Each message contains:

• Method — the device method to call (e.g., connect, identity, _write_)
• Parameters — key-value pairs for the method
• Response — the return value or error

The protocol is symmetric: the same message format works for both requests and responses.

Connection lifecycle

1. Server starts — binds to the specified TCP address and waits for connections
2. Client connects — opens a ZMQ socket to the server address
3. Communication — client sends requests, server dispatches to device methods
4. Disconnection — either side closes the socket

Error handling

If a device method raises an exception, the server serializes it and returns it to the client. The client raises a corresponding exception on the caller's side. Timeouts are handled by the client — if no response arrives within the configured timeout, a timeout exception is raised.

Next steps

• See how the quality tiers govern device reliability
• Learn to scaffold a device that uses this communication model