13. PsySpec XML Reference

How to read this chapter

This is the lookup chapter, extracted from the current parser code. Each element carries a badge:

• Shipped — parsed and functionally wired.
• Stub — parsed into internal structures but not (or only partially) acted on.
• Roadmap — documented/reserved syntax; no real parsing or behaviour yet.

Status summary

<psyspec> (root) Shipped

The root element of every spec. Besides port= (main system port, see System Guide), it now carries the global SSL client-verification policy:

Children: <include>, <variable>, <node>, <library>, <space>, <interface>, <service>, <psyprobe>, <whiteboard>, <catalog>, <module>, <stream>, plus the roadmap tags listed above.

<include> Shipped

<include file="system.xml" /> splices the referenced file's contents into the spec (like a C include) and reparses; errors in the expanded spec report line/column. file is required. Includes and variables are processed before anything else.

<variable> Shipped

<variable name="SystemID" value="2" /> defines a literal %SystemID% text substitution applied over the whole spec before XML parsing — usable in names, cranks, triggers, anywhere, as long as the result stays valid XML. Both name and value are required.

<node> Shipped

Child: <library name library path> — libraries loaded only on that node.

<library> Shipped

<library name="MyExamples" library="Examples" path="../libs" />. name is how cranks refer to it (MyExamples::Ping); library is the file name, resolved as Examples.dll (Windows) / libExamples.so (UNIX) — debug builds first try the ...Debug variants; path is an optional directory; node restricts to a node.

<space> Shipped

<space name="GUISpace" type="external" />. At the top level only type="external" is handled (creates a process-map entry waiting for an external program to connect). Regular spaces are created implicitly by the space= attribute on components (default Root). node restricts to a node. See Distributed Systems.

<interface> Shipped

<interface name="MyWebInterface" node="Node0" port="1234" protocol="HTTP"
           service="MyWebService" timeout="3000" default="yes" />

Child <authentication>: Stub — parsed by an empty function body; interface encryption attributes are likewise stubbed.

<service> Stub (partial)

Attributes: name, rootdir, subdir, timeout, node. The service is registered and a component is created for its subscription, so <trigger>/<post>/<crank> children parse — but custom services register a NULL receiver, so inbound requests are discarded. Built-in PsyProbe/Console services work. See Services & Interfaces.

<psyprobe> Shipped

Children: <alias name location default> (URL alias to a local directory with optional default file) and <post> (same attributes as a module post plus XML content, registered as a clickable manual post in PsyProbe).

Components: <module> / <whiteboard> / <catalog> / <stream>

All component tags share one parser; the tag name selects the type. <module type="external"> declares an external process component (connects via a space). <module count=N> tag-instancing is Roadmap. Common attributes:

Extra attributes for whiteboard/catalog/stream/service:

Component children

<parameter> Shipped

<parameter name=".." type="String|Integer|Float" value=".." interval=".." /> (type defaults to String). Rich value syntax:

All parameters are queryable, settable and tweakable at runtime (getParameterString/Int, setParameter, tweakParameter, resetParameter) — see Modules.

<context> (in a component) Shipped

<context name="SoB.Alive.Awake">...</context> groups child trigger/post/retrieve/query/crank/signal elements under a named context instead of the default Psyclone.Ready. See Contexts.

<trigger> Shipped

Subscribes the component to messages; a match dispatches its cranks. Valid if it has a name plus at least one of type, from, to; duplicate names are an error.

Trigger priority/history and the system= attribute are Roadmap — use context= to react to context changes.

<filter> (child of trigger) Shipped

<filter type="haskey" key="SomeKey" />                      <!-- entry exists (any type) -->
<filter type="equals" key="camera" value="front-left" />    <!-- string ==, exact, case-sensitive -->
<filter type="notequals" key="state" value="disabled" />    <!-- string != -->
<filter type="equalsnumeric" key="mode" value="3" />        <!-- float == -->
<filter type="notequalsnumeric" key="channel" value="0" />  <!-- float != -->
<filter type="greaterthan" key="temp" value="80" />         <!-- float > (≥ at the epsilon boundary) -->
<filter type="lessthan" key="pressure" value="2.5" />       <!-- float < (≤ at the epsilon boundary) -->

type is one of equals (exact, case-sensitive, no wildcards), notequals, equalsnumeric, notequalsnumeric, greaterthan, lessthan (all take key+value; numeric values are parsed as float64 with an epsilon compare, so exactly-equal values also pass greaterthan/lessthan) and haskey (key only, matches any entry type). The eighth filter operation, maxage, is written as a trigger attribute (milliseconds) rather than a <filter> child. Unrecognised types are silently ignored.

<retrieve> Shipped

On-demand fetch from a whiteboard/catalog when the owning trigger fires (see Whiteboards).

<query> Shipped

Free-form query to a catalog/component; catalogs dispatch on the Query/Operation fields. Attributes: name (required, unique), source (required), type (string), subdir, ext, binary (yes), maxcount, maxage (stored ×1000; unit under review), key, value, operation, and for remote queries host (DNS-resolved at parse time) + port.

<crank> Shipped

The processing function attached to triggers. Four forms:

<crank name="c1" function="lib::function" />            <!-- C/C++ library crank -->
<crank name="c2" language="python" script="file.py" />  <!-- external script file -->
<crank name="c3" language="python">inline code</crank>  <!-- inline script -->
<crank name="c4" />                                     <!-- external crank slot -->

A function without lib:: is an internal (built-in) crank. Duplicate crank names across components are rejected. Modules with no crank get the built-in passthrough (Internal::Simple) default crank. Java cranks are Roadmap.

<post> Shipped

Message posted when the owning trigger fires. Valid if it has a name and (type or context).

Message content comes from child XML elements; the older contentkey/content attribute form is no longer parsed. time="trigger" is Roadmap.

<signal> Shipped (minimal)

<signal name="Output" type="My.Signal.1" /> — both attributes required; no others are parsed. See Messaging & Signals.

<triggergroup> declarative join Shipped

Joins several triggers into one crank activation: member messages sharing the same tag are buffered on the node until the group completes, then delivered together as one set (wakeups ≈ joins, not one per member). Untagged messages group under the literal empty-string tag "" and never mix with real tags. This is the primitive for multi-modal fusion (audio + text + vision joined before a decision crank runs).

<module name="Simple" node="Node0">
  <triggergroup name="ts" count="2" maxage="2000">
    <trigger name="t1" type="bla1" />
    <trigger name="t2" type="bla2" />
    <trigger name="t3" type="bla3" optional="true" maxage="200" />
  </triggergroup>
  <crank name="c1" function="lib::function" />
  <post name="p1" type="bla4" to="WB/Stream/Cat" />
</module>

Child <trigger> elements accept all their normal attributes (they still route individually) plus:

SDK. A completed (or partial-fired) set arrives as one grouped activation. The crank calls waitForNewMessageGroup(ms, groupName), which returns a std::map<std::string, DataMessage*> keyed by trigger name — optional/absent members are simply not in the map (check with .count("t3")). getCurrentTriggerName() returns the group name. Messages are owned by the API for the activation and freed on the next waitForNewMessageGroup()/waitForNewMessage() call. Existing single-message cranks are untouched.

Stub grouping elements Stub

<triggers>, <retrieves>, <posts> and <signals> are recognised by the parser but their handling bodies are empty — they silently do nothing.

Roadmap-only elements Roadmap

<feed>, <supervisor>, <monitoring>, <performance> and <group> are logged and ignored; <phase> has no parsing code at all. None of these produce components or behaviour in the current build — do not rely on them.

Cross-cutting rules

• Config-node scoping: elements without node= run on the config node; with node= only on the named node.
• Expansion order: variables and includes are processed before all other parsing; the spec is reparsed after each expansion.
• Code escaping: inside the spec, message content and setup blobs must remain valid XML.