How to create your own Pixotope service

Creating your own Pixotope service allows you to

• make the Pixotope Store persist your data for you (on a "per show" basis)

• define your own data and functions that can be accessed by anyone using the API

A Pixotope Service can be written in any programming language, but needs to use ZeroMQ and support a few specific commands.

You can expose any number of values or functions to the network and they will be callable by anyone, but you are free to block improper calls and filter if you like. The service is its own single source of truth.

TLDR

To create a service you should support at least the following commands

• Identify - coming in from the network

• If your service needs persistent data "per show" (service state)

  • Get, Set, Reset, Update, Startup

Check out the "libdatahub" example in Pixotope API - Examples

Set up ZeroMQ

Checkout ZeroMQ’s Get started page - https://zeromq.org/get-started/

Specify network settings

• The subscriber binds to (listening)

  • Port 16201

• The publisher binds to (sending)

  • Port 16202

You connect to a Data hub running locally on your machine. That Data hub makes sure all messages are (if subscribed to) sent everywhere to all machines. The ports are hard coded on every machine, so your service does not need to do any network discovery.

Data hub PX_Datahub.exe, which is auto started by Pixotope, is expected to run on your machine.

Specify a service name

Specify a name for your service depending on if you create a

• "1 per machine" service

• OR a Singleton or wildcard service

Learn more about Service names

Subscribe to topics

Services are expected to subscribe (listen) to the following messages

• Identify

• If the service has a state or other fields

  • Get

  • Set

  • Reset

• If the service supports RPC Calls

  • Call

The subscription string is a JSON like string which is case sensitive and has to follow these rules

• No spaces or line breaks

• Strict order (see below)

The subscription string for each of these looks like this:

• {"Type":"Identify","Target":"[Your service name]"

• {"Type":"Get","Target":"[Your service name]","Name":"[SettingName]"

• {"Type":"Set","Target":"[Your service name]","Name":"[SettingName]"

• {"Type":"Reset","Target":"[Your service name]"

• {"Type":"Call","Target":"[Your service name]"

Implement response for Identify request

Services should subscribe (and properly respond) to the topic {"Type":"Identify","Target":"BROADCAST" to be discovered by Data hub and other services on the network.

Learn more about the Pixotope API - Message Scheme and the available message types

Create a service state (per show)

If your service is maintaining "per show" data, you will want to create a singleton state in your service, called "State".

Use PascalCase for parameter naming

In your Service "State" you are not allowed to keep multiple keys with the same name in the same level in a JSON object, neither exactly nor with different case (this should really be common sense).

Implement responses for Get, Set, Reset requests

Anyone on the network might ask for your service state (State) or any subtree of it for any reason, and ask you to change it. For this you have to implement responses to Get, Set, Reset requests.

Implement sending Startup message

Send a Startup message when connecting to a network. This will make Pixotope Store go through its memory, find the service state for the current show that you should use and send that to you as a Set message.

Implement sending Update message

You also need to notify everyone when this state changes, for example when you received a request to change it. For this you have to implement sending Update messages.

Learn more about the Pixotope API - Message Scheme and the available message types

Implement custom RPC or Log messages

Use PascalCase for methods and parameter naming