What is CMSDK?

CMSDK is a cross-platform C++ base library, and the SDK for the Psyclone AIOS platform. It plays two roles at once:

1. A portable C++ foundation. It abstracts the operating system (Windows, Linux, macOS) behind one identical set of objects and functions: threading and synchronisation, process handling, sockets and networking, shared memory, dynamic libraries, timers, wait queues, binary message containers, a fully functional HTTP/WebSocket server, maths and stats classes, 64-bit integer time with microsecond resolution, a request client/server/gateway fabric, a system-wide logging/verbose system and a large library of text and file utilities. You can use any of this in a plain C++ program without ever touching Psyclone — see Using the CMSDK library.
2. The Psyclone SDK. Psyclone is a general-purpose platform for deploying many cooperating processes with powerful publish–subscribe message and stream communications. Every component you write for Psyclone — a vision module, a planner, a robot driver — is written against CMSDK, chiefly through two objects: cmlabs::PsySpace (the process-side runtime you attach to) and cmlabs::PsyAPI (the handle each component uses to talk to the system).

CMSDK is open source — licensing details are on the index page. For more about the Psyclone platform see https://cmlabs.com/psyclone.

The mental model

A running Psyclone system is a small distributed world with a few kinds of inhabitants:

• Node — one Psyclone runtime on one machine, identified by a port (10000 by default). Multiple nodes on multiple machines can be joined into one system (see Distributed Systems).
• Space — an operating-system process attached to a node. All inter-process state lives in named shared-memory segments (see cmlabs::MemoryManager), so a space can crash without corrupting the others — crash isolation is a design goal, not an afterthought.
• Module / component — a named unit of processing declared in the PsySpec. A module does its work in one or more cranks: plain C/C++ functions of the form int8 MyCrank(PsyAPI* api) that are run when the module is triggered.
• Message — a cmlabs::DataMessage: a flat, binary, self-contained container with typed user entries (string, int, float, time, binary, nested message, arrays and maps of these). Because a message is one flat allocation, it can be copied verbatim into shared memory or sent over a socket without any serialisation step.
• Trigger — a subscription. Every message carries a dot-delimited type (e.g. robot.sensor.video); a module declares which types wake it up.
• Context — a named, hierarchical, system-wide state (e.g. Battery.Low). Modules can be context-driven: their triggers are only live while their declared context is active. Contexts let you switch whole groups of modules on and off with a single post.
• Whiteboard — a message store. Where the node itself only routes messages, a whiteboard keeps them (indexed by time and optionally by user-defined keys), so modules can retrieve past messages when they become relevant — for example after a context switch.
• Catalog — a component that fronts larger data with a query mechanism: files (FileCatalog), a persistent key/blob store (DataCatalog) or recorded message streams for later playback (ReplayCatalog). See Whiteboards & Catalogs.

How these inhabitants combine — in particular how contexts, triggers and cranks interact so that the same message can fire different cranks in different contexts — is worked through with a figure in Core Concepts.

Code vs. wiring: the PsySpec

The single most important design idea to internalise is the separation between what a module does (its crank code, compiled into a DLL / shared object) and how it is wired (the PsySpec, an XML file loaded at startup).

Crank code gets input and produces output, but it does not know where the input came from or where the output goes. That is defined entirely in the PsySpec: subscriptions, signals, retrieves, queries, posts, parameters. You can re-route a module's input from a live camera to a recorded message stream — or move the module to another machine — by editing XML, without recompiling anything. The PsySpec is the scaffolding that attaches modules, whiteboards and catalogs to each other. See Writing a PsySpec.

Where to go next

• Getting Started — build the library, run your first system, watch it in PsyProbe (the built-in web monitor).
• Core Concepts — pub/sub, triggers, contexts, signals and the message lifecycle in depth.
• Writing a Module (Crank) — the PsyAPI handle, one-shot vs continuous cranks, concurrency rules.
• Writing a PsySpec — the XML reference by example.
• Whiteboards & Catalogs — storing and retrieving messages and data.
• Distributed Systems — multiple nodes, external spaces and process placement.
• Going Deeper — shared memory, threading, the request fabric, HTTP server, time and SSL.
• Examples Index — the shipped examples, one line each.