Skip to main content
Skip table of contents

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.

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.

Implement custom RPC or Log messages

Use PascalCase for methods and parameter naming

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.