This API is conceptually similar to the property publish/subscribe Javascript APIs available to web cllients, but does not require a browser envoronment and websocket support. Instead, it's based on a raw TCP socket (e.g. a "telnet" connection).

The API is implemented by a user script named TCPProtocol, which you must install and configure on your blocks server in order to use it. A fully working example of how to use this API from a Unity application can be found here.

This API provides direct access to all properties in Blocks using the same property paths as used inside Blocks itself (e.g., in a button binding). Properties can be set or subscribed to, so you'll be notified when the property's value changes.

Once the TCPProtocol script has been installed ane configured, you should be able to connect to port 3041 on your Blocks server and send a command. Try it out using a telnet client like this:

telnet 10.1.0.10 3041

Replace the IP address above with the correct IP address of your Blocks server. Commands are specified using JSON syntax. To set a value of a property, type the following into your telnet session:

{ "type": "set", "path": "Artnet.aurora.Red.value", "value": 0.2}

To add a value to a property (pass a negative value to subtract):

{ "type": "add", "path": "Artnet.aurora.Red.value", "value": 0.2}

Valid message types are "set", "add" "subscribe" (for subscription) and "unsubscribe" (to end a subscription). Multiple commands can be sent together by wrapping them in a JSON array. For example, to subscribe to two properties, do this:

[{ "type": "subscribe", "path": "Artnet.aurora.Red.value"},{ "type": "subscribe", "path": "Artnet.aurora.Green.value"}]

The entire command must be entered as a single string, with a newline ONLY at the end. Do not put newlines inside the string. The maximum length of such a string is 4096 characters. Split commands into multiple strings to send more.

Since a plain TCP connection provides no security, a white/black-list mechanism is provided, allowing you to explicitly state which properties that may (or may not) be set through this API/protocol. This mechanism does not currently limit which properties can be subscribed to. Specify this as a JSON file located at script/files/TCPProtocol.json, containing data as described here. If no configuration file is provided, this protocol provides unfettered access to ALL properties (which will be indicated by a log message).