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 for the data itself defines.
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
If your service needs persisting non-state (not per show)
Get, Update
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. You can also connect to a Datahub on a remote machine, it should not matter whether that Datahub is in Secondary or Primary mode, your service will appear to live locally on that machine.
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]"
You are of course free to make longer or shorter subscriptions, but keep in mind that the network becomes less effective the shorter filters you use (more data then needs to be sent to your service, that you might not need), Datahub will block subscriptions shorter than 10 characters.
Implement response for Identify request
Services should subscribe (and properly respond) to the topic {"Type":"Identify","Target":"BROADCAST" to be discovered by Datahub and other services on the network.
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. If you only are exposing data not bound to your state, you do not need to worry about Reset.
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. You only need to support this if you implement a State.
Implement sending Update message
As Datahub is entirely sub/pub based, you also need to notify everyone when your state or other exposed data 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