Camille at 10:43, 14 February 2024

2024-02-14T10:43:11Z

Camille: /* Change */

2023-11-03T10:38:55Z

Change

Show changes

Camille: Created

2023-09-29T09:04:02Z

Created

New page

This is the communication protocol used in all .CL libraries, and in some standalone products.

The protocol is based on JSON only.

=== Commands and answers ===
All exchanges are in the form : <code>{ "command" : ''data...'' }</code>.

The process/library is passive : it only answers when something is asked.

Answers will start with either :

* When the command is requesting some value (<code>get</code> or <code>change</code> for instance), the answer will start with the command containing the requested object.
* <code>"OK"</code> when the command is doing an action, with a string property containing the command. For instance: <code>{"OK":"set"}</code>
* <code>"ERROR"</code> if the command failed, with a string property containing the command. For instance: <code>{"ERROR":"load"}</code>

==== Basic commands ====

===== Get =====
<code>{ "get" : `object` }</code>

Get values. If <code>object</code> is NULL, get all parameters, and so show the possibilities.

Otherwise, return the requested object.

For instance, <code><nowiki>{"get":{"status":null}}</nowiki></code> returns <code><nowiki>{"get":{"status":{"preset_changed":false,"license_valid":true,"version":"1.1.19"}}}</nowiki></code>

===== Change =====
<code>{ "change" : null }</code>

Get all changes since last request from this port. This behaves like "get", but only providing changes. Each call reset the state for this connection to current.

For instance : <code>{"change":null}</code> returns <code><nowiki>{"change":{"vu":{"in":{"vu":{"pk":[-9.467268943786621,-10.68277359008789],"vu":[-20.523719787597656,-21.058277130126953]}}}}}</nowiki></code>

===== Set =====
<code>{ "set" : `object` }</code>

Set values. <code>object</code> can be any subpart, only those will be changed.

For instance: <code><nowiki>{"set":{"settings":{"general":{"operate":false}}}}</nowiki></code> returns <code>{"OK":"set"}</code>

==== Commands for undo/redo ====
If the process has undo/redo, you can use those.

===== Undo =====
<code>{ "undo" : `count` }</code>

Undo last(s) <code>count</code> preset change

===== Redo =====
<code>{ "redo" : `count` }</code>

Redo last(s) <code>count</code> preset change

==== Commands for presets ====
If the process has presets, you can use those.

===== Getting information =====
The <code>"status"</code> object has an extra <code>"preset_changed"</code> boolean value.

There are also :

* <code>"presetinfo"</code> object : contains the name, factory name, and dates of the onair preset.
* <code>"saved"</code> object : contains the on air preset's saved content (without current changes)
* <code>"factory"</code> object: contains the on air preset's factory preset
* <code>"presetlist"</code> array of <code>presetinfo</code> object for all presets
* <code>"factorylist"</code> array of string with factory preset names

===== Load =====
<code>{ "load" : "`presetname`" }</code>

Loads the preset with this name

===== Save =====
<code>{ "save" : "`presetname`" }</code>

Saves the preset. If NULL is given, save on air preset.

===== Delete =====
<code>{ "delete" : "`presetname`" }</code>

Deletes the preset. Can also be an array of preset names.

===== Factoryload =====
<code>{ "factoryload" : "`presetname`" }</code>

Creates a preset from factory and loads it.

===== Rename =====
<code>{ "rename" : { "preset" : "`presetname`", "name": "`newname`" } }</code>

Renames a preset.

===== Import =====
<code>{ "import" : { "preset" : "`presetname`", "content": `presetcontent` } }</code>

Imports a preset.

===== Export =====
<code>{ "export" : "`presetname`" }</code>

Exports a preset : get preset's content, so it can be imported later.

===== New =====
<code>{ "new" : { "name": "`presetname`", "factory": "`presetname`" } }</code>

Creates a new preset from a factory. Can use array for multiple.

==== Commands for extensions ====
Some process may have some extensions.

In this case, each extension provides a root object with its name, and then follow the same protocol.

NOTE: currently, undo/redo and presets does not work on extensions, you can only use basic commands (set,get,change).

=== Accessing JSON from HTTP server ===
When there is an HTTP server, you can access the JSON protocol in <code>/json</code>.

There are multiple ways to access a command and an object :

* Using the parameters in get/post/put, where the parameter name is the command <code>wget -O- --post-data 'load="Jazz"' <nowiki>http://localhost:8080/json</nowiki></code>
* Using the body as direct JSON request <code><nowiki>echo '{"get":{"presetlist":null}}' | http POST localhost:8080/json</nowiki></code>
* Using the path to construct a JSON request <code>http localhost:8080/json/get/presetlist</code>
* To get all JSON get/set possibilities <code>http localhost:8080/json/get</code>

The possible commands are:

* <code>get</code> or <code>set</code> with a full path, and value for set or <code>null</code> for get
* <code>load</code>, <code>factoryload</code> or save with the preset name
* <code>delete</code> with the preset name to delete <code>.../json/delete/presetname</code>
* <code>new</code> with the factory preset name to create a new preset <code>.../json/new/factoryname</code>
* <code>rename</code> with from preset name then to preset name <code>.../json/rename/from/to</code>
* <code>export</code> with from preset name <code>.../json/export/presetname</code>
* <code>undo</code>/<code>redo</code> with optional count <code>.../json/undo/2</code>

Here are some examples :

* Set <code><nowiki>http://localhost:8080/json/set/preset/agc/attack/15</nowiki></code> or <code><nowiki>http://localhost:8080/json?set={</nowiki>"preset":{"agc":{"attack":15}}}</code>
* Get <code><nowiki>http://localhost:8080/json/get/preset/agc</nowiki></code> or <code><nowiki>http://localhost:8080/json?get={</nowiki>"preset":{"agc":null}}</code>

<br />

← Older revision		Revision as of 10:43, 14 February 2024
Line 141:		Line 141:

	<br />		<br />
		+	[[Category:Cloud]]

Cloud JSON Protocol - Revision history

Camille at 10:43, 14 February 2024

Camille: /* Change */

Camille: Created