Pixotope API - Message Schema

Message structure

Every ZeroMQ message is split up into either 2 or 3 parts.

Topic

JSON like string without spaces or line breaks and in strict order

{"Type":"Set","Target":"Service","Name":"SettingName"}

Message

JSON

{"Value":"SettingValue"}

Attachment - Optional

Serialized data of arbitrary type.

94f4e323...

The Topic field is designed to be easily filterable no matter what your service is trying to do. Learn more about how to Subscribe to Topics

The Attachment field can be used by specific Call commands to, for example, send raw binary data over the Pixotope Network.

Easily test ZeroMQ messages using the Pixotope explorer - see Pixotope developer tools

Service names

"1 per machine" service	`[MachineName]-[ServiceName]` for example `"RenderMachine1-Engine"`
Singleton or wildcard service	`[ServiceName]` for example `"Store"`

Learn more about the available Pixotope Services

Parameter names

Type	Message type
Target	Name of a specific service this message targets OR "BROADCAST"
RespondTo	Name of a specific service to which the response should be targeted to
Source	Name of a specific service this message originates from
Name	Setting on a service (in case of a JSON by using the dot (.) notation) NOTE: if the name starts with “LOWPRIO_” and is an “Update” message with target “BROADCAST” it will be considered dispensable by DH2 and can be dropped if traffic exceeds available bandwidth.
Value	Value of a setting on a service NOTE: this value can be either a JSON or a single value

Message types

Get

Get state or non-state value from the service

Description

Command used to fetch the current value of a state or non-state value on a Service. Try to avoid continuous polling, instead subscribe to Update-messages and just listen to changes.

Template

Topic	`{"Type":"Get","Target":"Service1","Name":"SettingName","RespondTo":"Service2"}`
Message	`{}`

Example

Topic	`{"Type":"Get","Target":"Jakubs-PC_CTS","Name":"State.RED_Camera.Aperture","RespondTo":"Piotrs-PC_Director"}`
Message	`{}`

When Receiving

When you are receiving this someone is asking about the state or a non-state value.

Return the value via an Update-command targeted to them
If you don’t have this value, return "Value":"null" in the message
- optionally send a log message of type Warning (more on the Log command below).

Set

Request change of state or non-state values on the service

Description

Command used by a Service that attempts to change the state or a non-state value of another service. It is not guaranteed to have any effect and does not include information about the sender. You can set things inside the state struct or on specific exposed values.

Template

Topic	`{"Type":"Set","Target":"Service","Name":"SettingName"}`
Message	`{"Value":"SettingValue"}`

Example 1

Topic	`{"Type":"Set","Target":"Store","Name":"State.Cameras.IDXX.Name"}`
Message	`{"Value":"2.0"}`

Example 2

Topic	`{"Type":"Set","Target":"Jakubs-PC-CTS","Name":"State.RED_Camera"}`
Message	`{"Value":{"Aperture":"2.0"}}`

When Receiving

When someone sends this message they probably expect you to change your singleton state, part of it, or something else to the new value. If you do that (you are also free to refuse it), remember to send an Update command afterwards (more on Update below).

Reset

Request that service state returns to default

Description

Command used to reset the state of a Service to default.

Template

Topic	`{"Type":"Reset","Target":"Service"}`
Message	`{}`

Example

Topic	`{"Type":"Reset","Target":"Jakubs-PC-CTS"}`
Message	`{}`

When Receiving

When you are receiving this, there is likely some disconnection of the current context happening.

Reset or return to a "baseline" and/or a generic start state
- When setting this default state, remember to send an Update-message to notify listeners

Update

Returned on a Get request and when state or non-state variables change

Description

Used when the state of a Service changes. This command should be sent every time there is a change. Services decide whether they want to listen to these updates or not.

It is also sent as a response to a Get request. In this case the "RespondTo"-field of the Get request is used as the "Target" of the Update message.

Template

Topic	`{"Type":"Update","Target":"ServiceOrBroadcast","Source":"Service","Name":"SettingName"}`
Message	`{"Value":"SettingValue"}`

Example 1

Topic	`{"Type":"Update","Target":"BROADCAST","Source":"Jakubs-PC-CTS", "Name":"State.RED_Camera.Aperture"}`
Message	`{"Value":"2.0"}`

Example 2

Topic

{"Type":"Update","Target":"BROADCAST","Source":"Jakubs-PC-CTS", "Name":"World.PropertyChanged"}

Message

CODE

{
  "Value": {
    "Owner":"'PostProcessHandler_0",
    "ObjectSearchTag": "post_process_handler",
    "Path": "Settings.",
    "Name": "bOverride_SceneFringeIntensity",
    "PrettyName": "Override Scene Fringe Intensity",
    "Type": "bool",
    "AdjustmentStatus": "MODIFIED",
    "Value": "True"
  }
}

Example 3

Topic	`{"Type":"Update","Target":"PIOTRS-PC-Director","Source":"Jakubs-PC-Engine","Name":"Some.Key.That.Does.Not.Exist.But.Maybe.It.Could.Be.Zero.How.Can.You.Tell.It.Is.A.Mystery"}`
Message	`{"Value":null}`

When Receiving

When receiving this message, it means a value you had subscribed to has been updated or a value you have asked for has been retrieved.

It’s up to you if you want to do something with this or not, but if you don’t you probably want to unsubscribe in order to not waste network resources.

Identify

Constantly ticking heartbeat to see what services are connected and responsive

Description

Used by the central server to get information about connected Services, if you don’t respond you won't be considered connected (and won’t appear in Store’s ConnectedClients).

Template

Topic	`{"Type":"Identify","Target":"ServiceOrBroadcast","RespondTo":"Service"}`
Message	`{}`

Example 1

Topic	`{"Type":"Identify","Target":"Jakubs-PC-CTS","RespondTo":"Store"}`
Message	`{}`

Example 2

Topic	`{"Type":"Identify","Target":"BROADCAST","RespondTo":"Store"}`
Message	`{}`

When Receiving

When receiving this message you should respond with a Self command to the one asking, or other services won’t be able to find you (more on the Self command below).

Self

Service response to Identify

Description

Sent as an answer to the Identify-request OR directly when coming online to avoid having to wait for the next heartbeat before coming online.

Note: If you have a state, use the Startup command instead.

In this case "Role" is referring to the name of the service, for example "Engine".

Template

Topic	`{"Type":"Self","Target":"Service1","Source":"Service2","Role":"Director"}`
Message	`{}`

Example

Topic	`{"Type":"Self","Target":"Store","Source":"Piotrs-PC-Director","Role":"Director"}`
Message	`{}`

When Receiving

Only Store is expected to receive this message, if you should receive it (as a normal Service) you probably want to unsubscribe.

Startup

Sent on connection by a service that maintains a state triggering data fetching from "Store"

Description

Sent by any service that maintains a State when connecting to a network. This will make "Store" go through its memory, find the proper settings for the current Show that you should use and send that to you as a Set message.

Template

Topic	`{"Type":"Startup","Target":"BROADCAST","Source":"Service2","Role":"Director"}`
Message	`{}`

Example

Topic	`{"Type":"Startup","Target":"BROADCAST","Source":"Piotrs-PC-Director","Role":"Director"}`
Message	`{}`

When Receiving

Only "Store" is expected to receive this message, if you should receive it (as a normal Service) you probably want to unsubscribe.

Log

Logs over DH2

Description

Logging over the network. "Message" and "Code" are always strings. The Code field is optional and does not have to be included.

Template

Topic	`{"Type":"Log","Source":"Service","Verbosity":"Error/Warning/Log/Spam"}`
Message	`{"Message":"Description","Code":"UPPERCASE_CODE"}`

Example 1

Topic	`{"Type":"Log","Source":"Piotrs-PC-Director","Verbosity":"Error"}`
Message	`{"Message":"Director ran out of memory and crashed", "Code": "DIRECTOR_OUT_OF_MEMORY"}`

Example 2

Topic	`{"Type":"Log","Source":"Motive-1-CTS","Verbosity":"Log"}`
Message	`{"Message":"CTS is doing great and doesn’t need a code for this log message"}`

When Receiving

You’d only get this if you subscribed to logs from somewhere, and if you did you should have some idea of what you want to do with it.

Call

Service specific black box RPC function call. Every service can implement how many or few it desires.

Description

Every service can define custom endpoints for executing actions (not only getting data). These RPC-style function calls can then be triggered.

A "Method" is supposed to have named parameters and follow the PascalCase naming convention.

The "ID" is a unique identifier of this specific call.

Template

Topic	`{"Type":"Call","Target":"Service1","RespondTo":"Service2","Method":"MethodName","ID":"0x29A"}`
Message	`{"Params":{"ParamName":"ParamValue", ...}}`
Attachment	`OptionalSerializedData`

Example

Topic	`{"Type":"Call","Target":"Jakubs-PC-Engine","RespondTo":"Piotrs-PC-Director","Method":"GetProperty"}`
Message	`{"Params":{"ObjectSearch":"BP_Actor_0","PropertyPath":"Name"},"ID":"0x29A"}`
Attachment	`94f4e323...`

When Receiving

If the service doesn’t have any remote function calls implemented, this message can be ignored.

Otherwise, when receiving this message the service should parse the method and arguments and execute the corresponding code. Then the CallResult message should be sent as a response, targeted at the service defined in the "RespondTo" field of the original Call message, passing through the received "ID".

CallResult

Response to a Call

Description

Communicates a result of an RPC executed with a Call command. Depending on whether the original call succeeded or failed the message should contain the "Result" or "Failure" field. The "Result" field is always an object. The "Failure" field can be either a string or an object.

Template

Topic

{"Type":"CallResult","Target":"Service2","ExecutedOn":"Service1","Method":"MethodName","ID":"0x29A"}

Message (when the call succeeded)

{"Result":{}}

Message (when the call failed)

{"Failure":"Failure message."}

{"Failure":{}}

Example 1

Topic	`{"Type":"CallResult","Target":"Piotrs-PC-Director","ExecutedOn":"Jakubs-PC-Engine","Method":"GetProperty","ID":"0x29A"}`
Message	`{"Result":{"Property":{"Owner":"BP_Actor_0", "PropertyPath":"Name", "Type":"FString", "Value":"Tomasz Karolak"}}}`

Example 2

Topic	`{"Type":"CallResult","Target":"Piotrs-PC-Director","ExecutedOn":"Jakubs-PC-Engine","Method":"GetProperty","ID":"0x29A"}`
Message	`{"Failure":"Unknown method name."}`

Example 3

Topic	`{"Type":"CallResult","Target":"Piotrs-PC-Director","ExecutedOn":"Jakubs-PC-Engine","Method":"GetProperty","ID":"0x29A"}`
Message	`{"Failure":{Code:"NO_SUCH_PROPERTY","Message":"Property does not exist."}}`

Example 4

Topic	`{"Type":"CallResult","Target":"Piotrs-PC-Director","ExecutedOn":"Jakubs-PC-Engine", "Method":"GetProperty","ID":"0x29B"}`
Message	`{"Property":12345.67890}`

When Receiving

When receiving, it should be parsed by services interested in receiving back the results of an RPC they called.

Legend for examples

Service	example name of a Pixotope Service
ServiceOrBroadcast	example name of a Pixotope Service OR "BROADCAST"
SettingName	example name of a setting on a Pixotope Service
SettingValue	example value of a setting on a Pixotope Service