CMLabs · Psyclone AIOS

# 2. Quick Start

Get Psyclone running in minutes: install or build it, run the classic ping-pong example, and take your first look at the live system in PsyProbe.

## Obtain Psyclone

Psyclone ships as source code in the Psyclone distribution, dual-licensed LGPL / commercial (see Introduction § Licensing). Obtain the distribution from CMLabs. After unpacking (or checking out) you get a tree containing:

Directory | What it is
--- | ---
`Psyclone/` | The engine — builds the `Psyclone` executable (Windows: `Psyclone.exe`).
`CMSDK/` | The base library your crank libraries compile and link against.
`html/` | The PsyProbe web root (also contains this guide).
example specs | PsySpec XML files such as the ping-pong example used below.

Two placement rules to know before your first run: Psyclone serves PsyProbe from the `html/` tree, so run it from a directory that contains `html/` (or point it elsewhere with `html=<dir>`); and your crank libraries (`.dll`/`.so`) are looked up in the current directory — put them where you start Psyclone.

## The system at a glance

Every Psyclone system follows the same five steps, whatever its size:

1. Write a PsySpec — one XML file declaring the components (modules, whiteboards, catalogs) and the dataflow between them.
2. Start Psyclone with `spec=<file>`. Psyclone reads the PsySpec, loads any crank libraries, and creates every component.
3. The system boots: when everything is ready, Psyclone posts the `Psyclone.Ready` message and prints `SYSTEM READY`.
4. Components run: triggers match incoming messages, cranks process them, posts publish results — until something posts `Psyclone.Shutdown`.
5. Watch it live in PsyProbe by pointing a browser at the main port (default `http://localhost:10000/`).

## Running Psyclone

### Windows

    <path>\Psyclone.exe spec=<PsySpec XML file>

### UNIX / Linux

    <path>/Psyclone spec=<PsySpec XML file>

The PsySpec file holds the full system specification. Two convenience command-line parameters are available in addition:

Parameter | Meaning | Default
--- | --- | ---
`port=<n>` | Main network port (inter-system communication and the PsyProbe URL) | 10000
`html=<dir>` | Path to the PsyProbe HTML directory | `./html`

Beyond these, any `key=value` argument on the command line overrides a PsySpec variable of the same name — the command line wins over the spec's `<variable>` default.

### Satellite mode

To use a computer as an extra node in a distributed system, start Psyclone with no parameters (optionally `port=<n>`). It idles until a master system's PsySpec claims it with a `<node>` entry — see Distributed Systems.

## Building from source

The source tree contains five projects:

Project | What it is
--- | ---
CMSDK | Core library; all OS-dependent base code (threads, networking, shared memory, timing…).
Psyclone | The main executable; links CMSDK.
System | Whiteboards, Catalogs and other built-ins in a single DLL/SO; links CMSDK only; loaded when the PsySpec uses them.
Examples | Example modules in a single DLL/SO.
External Modules | Third-party programs that link CMSDK and connect to a running Psyclone from inside their own executable.

### Windows (Visual Studio)

Open `Psyclone.vs2015.sln` and build Debug or Release. For the SSL-enabled variant build Release SSL / Debug SSL, which expect OpenSSL headers and libraries at `..\..\_libs\OpenSSL\openssl-1.0.2g-vs2015\include{,64}` and `lib{,64}`.

### Linux (make)

You need a C++ compiler and `make`; add OpenSSL development headers for the SSL variants, and Python development headers plus SWIG for the Python link. Run `make` in the source root:

    make            # release
    make debug      # debug
    make ssl        # SSL-enabled (needs libssl / libcrypto dev packages)
    make ssldebug

Expected result: the `Psyclone` binary in the build output directory.

### Python module support

Python crank support is built separately: on Windows build the Python2Link / Python3Link DLL projects (the SWIG-generated CMSDKPY2/CMSDKPY3 bindings expect Python installs at `C:\Python27`, `C:\Python27-32`, `C:\Python35`, `C:\Python35-32`; other versions by editing the project files). On Linux run `make python2` / `make python3` (optionally `debug`); expected settings are `PYTHON2INCLUDE=-I/usr/include/python2.7`, `PYTHON3INCLUDE=-I/usr/include/python3.4m` and the matching `-lpython` libs — edit `CMSDK/Makefile.sys` for other locations.

Note. The reference build was VS2015 / OpenSSL 1.0.2g / Python 3.5; build with your current toolchain — a modern C++ compiler, current OpenSSL, and Python 3. Python 2 is end-of-life — treat it as legacy.
Warning. Recent Psyclone builds verify SSL certificates by default (`SSL_VERIFY_PEER` plus hostname checks). Self-signed certificates that "just worked" with older builds now fail unless you explicitly set `allowselfsigned="yes"` or point `cafile`/`capath` at your own CA — see the System Guide's security chapter.

## Your first system: ping-pong

The canonical first PsySpec defines two modules that bat a message back and forth using the built-in `Ping` crank — no user code required:

    <psySpec>
      <module name="Ping">
        <trigger name="Ready" type="Psyclone.Ready" />
        <trigger name="Ball" type="ball.1" />
        <crank name="Ping" function="Ping" />
        <post name="Ball" type="ball.2" />
      </module>
      <module name="Pong">
        <trigger name="Ball" type="ball.2" />
        <crank name="Pong" function="Ping" />
        <post name="Ball" type="ball.1" />
        <post name="Done" type="Psyclone.Shutdown" />
      </module>
    </psySpec>

Run it:

    Psyclone spec=pingpong.xml

What happens: at start-up Psyclone posts `Psyclone.Ready`, which triggers Ping; Ping posts a `ball.2` message, which triggers Pong; Pong posts `ball.1` back — and so on for 100,000 messages, after which Pong posts `Psyclone.Shutdown`. The 100,000-message count is baked into the built-in `Ping` crank code — it is not set anywhere in the XML. Every 10,000 messages the crank logs throughput statistics (average message time/age in µs). The console shows the start-up configuration, `SYSTEM READY`, the statistics batches, and finally `SYSTEM SHUTDOWN`.

Note the two attributes on `<crank name="Pong" function="Ping"/>`: `name` is your label for this crank instance, while `function` selects which crank code runs — here both modules run the same built-in `Ping` function under different names.

Smoke test. Before moving on, confirm the run actually worked: you should see `SYSTEM READY` in the console followed by the periodic throughput lines. If either is missing, see When things go wrong below.

### Ping-pong dataflow

Ping-pong: `Psyclone.Ready` starts the rally; the ball bounces as `ball.2`/`ball.1` until Pong posts `Psyclone.Shutdown`.
Tip. Notice that the modules never mention each other — each just posts and subscribes to message types. That decoupling is the core of the Psyclone mental model, explained in Core Concepts.

## First look at PsyProbe

While a system runs, point any browser at the main port — by default `http://localhost:10000/` — for a dynamic, live-updating view of all nodes, spaces and components. The overview page shows the current time and uptime, the node list with activity levels, and expandable sections for System Info, Nodes, Catalogs (including whiteboard stored messages) and Modules with per-component performance, activity and subscription tabs. Try the ping-pong system: open the Pong module's Activity tab and watch the last ten in/out messages tick past. PsyProbe is covered in depth in chapter 12.

Note. Ping-pong at full speed posts messages faster than you can read; PsyProbe samples the activity view, so don't worry if counters jump.

## When things go wrong (first run)

The five most common first-run failures:

Symptom | Cause & fix
--- | ---
Spec parse error at start-up | Bad XML in the PsySpec — the log prints the file, line and column of the problem; fix the XML there.
Crank library not found | A crank uses `function="Lib::Fn"` but the `.so`/`.dll` is not in the current directory / library path. Put it next to where you start Psyclone, or set the library path.
Port already in use | Another process (or another Psyclone) holds the main port. Start with a different `port=<n>`.
PsyProbe page blank or 404 | You are not running from a directory containing the `html/` tree. Start Psyclone there, or pass `html=<dir>`.
`SYSTEM READY` never appears | A module's crank blocked at start-up, or a required node/space did not come up. Raise the verbosity level and check the log.

For deeper diagnosis — log levels, tracing dataflow, common crank bugs — see the System Guide's Debugging chapter.

PreviousIntroduction NextCore Concepts