Client Libraries (Java, Python)

New for Psyclone AIOS v2.3 — published 20 November 2026 on Maven Central and PyPI.

Client libraries let a program outside a Psyclone system talk to it the way modules inside it do: it posts messages by post name and receives what the system sends back by trigger name. One library for Java, Kotlin and Android, one for Python — free, open source (BSD) and installed with one line.

Install

  • Java / Kotlin / Android (JVM 17+, Android 8+): implementation("com.cmlabs:psyclone-client:2.3.1") from Maven Central.
  • Python (3.8 or later, any operating system): pip install psyclone-client from PyPI. Pure Python with no dependencies.

Why not just REST?

Every Psyclone service also speaks plain HTTP, and for a request now and then that is all you need. The client libraries are for programs that stay connected: a phone streaming audio, a robot controller, a dashboard, a service in a larger Java or Python application. They give you

  • Push, not polling: the system sends to you the moment a trigger fires.
  • Two-way streams over WebSocket, TCP or UDP, with automatic reconnection and device identity that follows a phone from Wi-Fi to 4G.
  • The real message model: typed entries, binary data and attached messages, byte-identical with the C++ CMSDK, in the compact packed form (about three times less overhead) when bandwidth counts.
  • Request and reply on the same connection, with timeouts.

How it looks

// Kotlin
val psy = PsycloneClient.webSocket("wss://host:8443/phone", device = "phone-1")
psy.onTrigger("Playout") { msg -> play(msg.getData("audio")) }     // pushed by the system
psy.post("AudioFrame", DataMessage().setData("audio", opus))       // into the system
val answer = psy.request("Question", DataMessage().setString("Text", "hi"))

# Python
from psyclone_client import PsycloneClient, DataMessage
with PsycloneClient.udp("host", 18600, device="sensor-7") as psy:
    psy.on_trigger("Command", handle)
    psy.post("Reading", DataMessage().set_double("Value", 21.5))

The service on the Psyclone side is a few lines of psySpec — its posts say what incoming data becomes, its triggers say what goes back out — so the system, not the client, decides what can enter it. See Edge & Device Services.

Python inside Psyclone, too

Python code can also run inside a Psyclone system as modules (“cranks”). From version 2.3.1 those work with any installed Python 3.10 or later — the binary distributions are no longer tied to one Python version.

Read the docs


See also Edge & Device Services, PsyProbe 2.0, or return to the Psyclone AIOS overview.