This page takes you from a source checkout to a running Psyclone system in a few minutes. Everything here uses the shipped Examples project — the same code you will later copy to start your own modules.

1. Build

Follow Compiling and linking with the CMSDK library for the full build instructions. The short version:

Linux/macOS: run make (release) or make debug in the distribution's top directory. Remember make clean when switching between release and debug builds — shared-memory struct layouts must match across all binaries in a system (see Going Deeper for why this matters).
Windows: open the solution file (e.g. Psyclone.vs2015.sln) in the top directory and build Debug or Release.

The build produces the Psyclone executable plus at least two shared libraries in bin/<arch> (win32, win64, linux32, linux64):

Examples — all module cranks from the Examples project (extend or recreate this to make your own modules), and
PsySystem — the system components (whiteboards, catalogs) which you can copy into your own library and modify to create new component types.

2. Smoke test

The quickest possible check needs no configuration at all. From the bin/<arch> directory the build just produced (where the Psyclone executable sits next to the Examples library), run:

./Psyclone psytest

This auto-generates a PsySpec with modules, whiteboards and catalogs from the Examples library and runs a self-test on a single node. psytest=N spawns N nodes on the local machine and spreads the test modules across them. The full test architecture is in Examples/psytest.xml and Examples/src/PsyTest.cpp.

3. Your first real system: ping-pong

The smallest interesting system is two modules batting messages back and forth. This is the complete PsySpec (Examples/pingpong.xml):

<psySpec>
    <library name="Examples" library="Examples" /> <!-- auto path and name per OS (xx.dll or libxx.so) -->
    <module name="Ping">
        <trigger name="Ready" type="Psyclone.Ready" />
        <trigger name="Ball" type="ball.1" maxage="2000" />
        <crank name="Ping" function="Examples::Ping" />
        <post name="Ball" type="ball.2" />
    </module>
    <module name="Pong">
        <trigger name="Ball" type="ball.2" maxage="2000" />
        <crank name="Pong" function="Examples::Ping" />
        <post name="Ball" type="ball.1" />
        <post name="Done" type="Psyclone.Shutdown" />
    </module>
</psySpec>

Reading it top to bottom:

<library> loads the Examples DLL / shared object. Its name= is the logical name the rest of the spec refers to (<crank function="Examples::Ping">), while library= is the file stem on disk; the platform prefix/extension are added automatically (Examples.dll / libExamples.so), and an optional path= attribute points at the directory. Here both attributes happen to be Examples, but they need not match.
Module Ping is woken up by the system-generated Psyclone.Ready message, and thereafter by any message of type ball.1. Each time it fires its crank — the C++ function Ping in the Examples library — and its <post> entries allow it to post messages of type ball.2.
Module Pong subscribes to ball.2 and posts ball.1 back. When it decides the game is over it posts Psyclone.Shutdown, which stops the whole system.

The crank code behind it lives in Examples/src/Examples.cpp. The essential shape of every crank is:

int8 Pong(PsyAPI* api) {
    const char* triggerName;
    DataMessage* inMsg;
    while (api->shouldContinue()) {
        if ((inMsg = api->waitForNewMessage(100, triggerName))) {
            // ... process inMsg (owned by the system; do not delete) ...
            api->postOutputMessage("Ball");
        }
    }
    return 0;
}

shouldContinue() asks the system whether the crank should keep running, waitForNewMessage() blocks (here up to 100 ms) for the next trigger, and postOutputMessage() posts through the named <post> entry in the PsySpec — the crank never needs to know the destination or the message type. See Writing a Module (Crank) for the full story.

Run it from the Examples directory:

./Psyclone spec=pingpong.xml

You will see the Ping module logging its message-per-microsecond statistics, then the system shutting itself down. Use port=<port> to run on something other than the default port 10000.

4. Watch it live: PsyProbe

Every Psyclone node serves a web-based monitoring interface, PsyProbe, using the CMSDK's built-in HTTP server (cmlabs::NetworkManager). While a system is running, open:

http://localhost:10000

(or whatever host/port the node runs on). PsyProbe shows the nodes, spaces, modules, whiteboards and catalogs of the running system, lets you inspect message traffic, filter whiteboard contents by type patterns (My.Namespace.*), and post messages manually — invaluable for verifying that your triggers and posts are wired the way you think they are. The ping-pong system is over too quickly to watch; try ./Psyclone spec=psyprobe.xml (a steadily-active system built precisely for browsing in PsyProbe, see Examples/psyprobe.xml and Examples Index) and browse while it runs.

5. Where next

Understand why it works: Core Concepts
Write your own crank: Writing a Module (Crank)
Wire it your way: Writing a PsySpec
Browse all shipped examples: Examples Index