Skip to content

Client Libraries

Cresco ships three external client SDKs for driving a mesh from outside the OSGi runtime:

All three connect to a running Cresco agent that hosts the wsapi plugin over a secure WebSocket (wss://host:8282) and drive the fabric — controlling agents, deploying plugins, submitting pipelines, streaming the data plane, and tailing logs.

The shared model

Every interaction follows the same shape regardless of language:

  1. Connect once. Construct a client with the target host, port, and the wsapi service key, then connect(). The client opens a single authenticated control connection to the global controller's wsapi endpoint. Identity (region, agent, plugin) is read from the negotiated TLS peer certificate.

  2. Use submodule handles. The connected client exposes a fixed set of submodules, each grouping a family of operations:

    Submodule Purpose
    api Local and global identity lookups (region/agent/plugin names).
    admin Node lifecycle on a target agent (stop/restart controller, restart framework, kill JVM).
    agents Per-agent operations: plugin add/remove/list/status, uploads, logs, CEP.
    globalcontroller Mesh-wide inventory and application ops: regions, agents, resources, pipelines, repositories, metric/capability inventories.
    messaging Low-level MsgEvent routing (RPC and fire-and-forget) to controllers, agents, and plugins.

  3. Open streams as needed. Data-plane and log-streamer channels are separate WebSocket connections opened on demand (get_dataplane(...), get_logstreamer(...)). They are tracked by name on the client, delivered to a callback, and auto-reconnect if the socket drops.

  4. Close. close() tears down the control connection and every managed stream.

RPC vs. fire-and-forget

Messaging calls carry an is_rpc flag. When true, the call blocks for the single reply and returns it; when false, the message is sent without waiting. The wsapi protocol is one-outstanding-RPC-per-connection with no correlation id, so each RPC completes before the next is issued.

Feature parity

Standardized clients

The Python, Java, and C++ clients are kept feature- and name-identical: the same submodules (api, admin, agents, globalcontroller, messaging), the same method names (snake_case in all three languages), the same behavior, and the same worked examples. Anything you can do in one client, you can do in the others with the same call.

Parity is enforced by test: the clients ship a self-contained suite that asserts they emit identical wire messages for identical API calls, verified against the same generated golden corpus. A green run proves the clients produce byte-for-byte equivalent results.

The only differences are the ones each platform forces:

Python (pycrescolib) Java (clientlib) C++ (cppcrescolib)
Concurrency asyncio under a blocking surface background reader threads single cooperative loop()
Structured returns dict / list Map / List / JSON ArduinoJson::JsonDocument
Target server / desktop server / desktop / JVM ESP32-S3 edge node

SSL verification

Cresco agents present self-signed certificates by default, so client SSL certificate verification is disabled by default. All three clients accept a verify_ssl constructor flag to enable it when the mesh is fronted by a trusted certificate authority.

Where to go next