3.5 WebSocket

Clients send events to an environment and get its changes pushed over the WebSocket at ws://127.0.0.1:8080/ws, on the host and port of 3.3.4 Configuration. All messages are text frames.

3.5.1 Connecting#

A client first registers over HTTP with registerClientForWebSocket or observatory/registerClient of 3.4 HTTP API and gets an access key. Then it opens the WebSocket and sends as its first frame its client id, the key of the environment and the access key, separated by colons:

panel:env-1763035112345:ak-panel-1763035113001-4821

The runtime closes the connection with code 1003 and one of these reasons when the first frame is wrong:

ReasonWhen
First message must be textThe first frame is no text frame
Invalid auth formatThe frame does not have exactly three parts
Invalid credentialsThe access key is unknown, was used before, or belongs to another client or environment

The runtime sends no answer to a correct first frame. A client knows that it is connected when observatory/subscribeModel succeeds or when the first message arrives. Each access key works for one connection; a client that connects again registers again. The runtime sends a ping every 60 s and closes a connection that does not answer within 15 s.

The connections stay open when the environment is stopped and started again; the clients learn both through engineStatus. Two closes end them from the side of the runtime:

CodeReasonWhen
1000Environment droppedPOST /dropEnvironment dropped the environment of the connection
1001Runtime stoppedThe runtime itself ends

After either close the access key of the connection is gone. After a drop the environment is gone too, and a client that wants to go on needs a new environment.

3.5.2 Sending events#

A client sends an event as a JSON object:

{"environmentKey": "switch", "messageType": "dim", "payload": "{\"bright\": true}", "payloadFormat": "json"}
EntryMeaning
environmentKeyThe domain of the event, as in EVENT("switch", "dim"). Despite its name it is not the key of the environment
messageTypeThe name of the event
payloadThe payload as a string. Optional, empty by default
payloadFormatnone, json or kmodel, in any case. Optional

Without payloadFormat the runtime takes the format from the payload: empty is no payload, text that starts with { is JSON, text that starts with make object is KModel. The runtime reads the payload against the event type named like the event, as 3.1.7.4 Payloads describes. A payload in KModel is one make object of that type:

{"environmentKey": "switch", "messageType": "dim", "payload": "make object \"step\":\"dim\" { prop(\"bright\") -> \"true\" }"}

The event goes to the environment the connection belongs to. A frame that is no JSON object with environmentKey and messageType is ignored. Events sent before runEnvironment are dropped. Events sent after runEnvironment and before startEnvironment wait for the start. The runtime sends no answer to an event.

3.5.3 Pushed messages#

Every message the runtime pushes has the same frame:

{"environmentKey":"env-1763035112345","clientId":"panel","messageType":"objectChanged","payload":{}}

Here environmentKey is the key of the environment. payload is a JSON object that depends on messageType. The runtime pushes nothing when websocket.enabled is false.

MessageWho gets itWhen
objectChangedObservers of the object, model subscribersAn action block changed a property or relation of the object
objectDeletedObservers of the object, model subscribersAn action removed the object
stateChangeClients of observatory/registerClient for this state machine or *, model subscribersThe stack of a state machine changed, and in the first tick after the first start
stateMachineAttachedThe same clients as stateChange of the objectA state machine instance joined: at the first start for every instance, and at the end of a tick for each that joined in it
stateMachineDetachedThe same clients as stateChange of the objectA state machine instance left, at the end of the tick in which it ended
domainEventListeners of the domainAn event of the domain reached the bus
engineStatusEvery client connected to the environmentThe run starts or ends a wait of TickByTick, the environment was stopped, or a stopped environment was started

3.5.3.1 objectChanged#

{"environmentKey":"env-1763035112345","clientId":"panel","messageType":"objectChanged","payload":{"objectId":"bulb","revision":7,"value":{"__id__": "bulb", "__type__": "Bulb", "maxWatts": 40, "watts": 40, "lit": true}}}

value is the whole object after the action block: __id__ with its key, __type__ with its type, its properties in the order of the model, and its relations with the objects in them, again whole. Objects in a knows relation are written whole as well. A property without a value is left out. The message names the object whose own property or relation changed. A change of the bulb gives a message for bulb and none for lamp, which holds it.

A block that changes several objects gives one message per object, after the block.

3.5.3.2 objectDeleted#

{"environmentKey":"env-1763035112345","clientId":"panel","messageType":"objectDeleted","payload":{"objectId":"spare","revision":9}}

DROPOBJ("spare") gives objectDeleted for spare and every object it holds, and objectChanged for the lamp that held it. The messages of the changes come first.

3.5.3.3 stateChange#

{"environmentKey":"env-1763035112345","clientId":"panel","messageType":"stateChange","payload":{"modelElementId":"lamp","stack":["on","full"],"revision":8}}

modelElementId is the key of the object of the state machine. stack is its stack from the outside in; in a split it is the stacks of all branches one after the other. The order of the entries in payload is not fixed.

Inside a container state the stack names the states of the fragment with their qualified names, as 3.1.14.2 Qualified names describes. A lamp in the self test of 2.3.12 Pages reports "stack":["self test","self test/powered"]. A stack never ends on a container state.

3.5.3.4 domainEvent#

{"environmentKey":"env-1763035112345","clientId":"panel","messageType":"domainEvent","payload":{"domain":"switch","payload":{"event":"dim","payload":"{\"bright\": true}","payloadFormat":"json","source":"EXTERNAL_MESSAGE","timestamp":1763035114120,"ttlMs":5000}}}
EntryMeaning
eventThe name of the event
payloadThe payload as the sender wrote it, as a string
payloadFormatnone, json or kmodel
sourceEXTERNAL_MESSAGE for events from clients and from EventInjection, INTERNAL for events raised with the action EVENT
timestampWhen the runtime got or raised the event, in milliseconds since 1970
ttlMsThe time to live of the event

The order of the entries inside the inner payload is not fixed. A domainEvent has no revision.

3.5.3.5 engineStatus#

{"environmentKey":"env-1763035112345","clientId":"panel","messageType":"engineStatus","payload":{"paused":true,"waiting":true}}

The payload is the status of 3.2.5.3 Status, with halt while a breakpoint holds the run. An engineStatus has no revision.

A stop and a start after it are told with the member phase, stopped or running, the phase of the snapshot, next to the status at that moment; without TickByTick the status is {"paused":false,"waiting":false}:

{"environmentKey":"env-1763035112345","clientId":"panel","messageType":"engineStatus","payload":{"phase":"stopped","paused":false,"waiting":false}}
{"environmentKey":"env-1763035112345","clientId":"panel","messageType":"engineStatus","payload":{"phase":"running","paused":false,"waiting":false}}

The engineStatus messages of TickByTick have no phase. A stop while the run is paused says "paused":true and "waiting":true, and so does the start after it, because the run still waits. A client that reads only paused and waiting keeps working; it does not learn of the stop. The first start of an environment sends no engineStatus.

3.5.3.6 stateMachineAttached and stateMachineDetached#

{"environmentKey":"env-1763035112345","clientId":"panel","messageType":"stateMachineAttached","payload":{"modelElementId":"gen_Bulb_0","stateMachine":"blinking","revision":12}}
{"environmentKey":"env-1763035112345","clientId":"panel","messageType":"stateMachineDetached","payload":{"modelElementId":"bulb","stateMachine":"glowing","revision":15}}

modelElementId is the key of the object, the key that stateChange uses for the instance. stateMachine is the name of the attachable state machine the instance runs, and null for a state machine uploaded with attachedTo. So a client tells an instance, named by the object, from its definition, named by stateMachine. The order of the entries in payload is not fixed.

At the first start the runtime sends stateMachineAttached for every instance before the first tick, in the order in which they step. A start after a stop continues the run and announces nothing anew. During a run, an instance that joins is announced at the end of the tick it joined in, after the stateChange messages of that tick, and its first stateChange follows after its first step. An instance that leaves is announced at the end of the tick in which it ended, before the instances that join in the same tick; after it no stateChange comes for it. When EXCHANGE replaces an instance, stateMachineDetached with the old definition comes before stateMachineAttached with the new one, for the same object. objectDeleted of a removed object comes earlier, when the action removes it.

A client that does not know these messages can ignore them. It still gets stateChange for every instance, also for those that join during the run, but it does not learn when one leaves.

3.5.4 Revisions#

objectChanged, objectDeleted, stateChange, stateMachineAttached and stateMachineDetached carry a revision. Each environment counts its revisions from 1 on, one count for all five messages and all clients, in the order of the changes. The count goes on after a stop and a start; the two add no revision. A change of an object that cannot be written as JSON, because it reaches itself over its relations, uses up a revision and sends nothing.

3.5.5 Keeping a copy of the model#

A client that shows the whole model keeps a copy this way:

  1. Register with registerClientForWebSocket, connect, and call observatory/subscribeModel.
  2. Read observatory/model. Its revision is the last change it contains.
  3. Ignore pushed messages with a revision up to the one of the snapshot, and apply the later ones in order: replace the object for objectChanged, remove it for objectDeleted, replace the stack for stateChange, add the object with its definition to stateMachines for stateMachineAttached, and remove the object from stateMachines and activeStates for stateMachineDetached.
  4. When a revision is missing, read observatory/model again.

3.5.6 Delivery#

The runtime sends the messages of one client in the order they were made. A client that has more than one connection to the same environment gets each message on one of them. Messages for a client without a connection are dropped. After 10 s without a connection, the runtime also ends the registration of the client made with observatory/registerClient.

Source: this page on GitHub at commit 3b6029f, refreshed 16 November 2026. The whole reference as a PDF.