Pleneo API 用于 Solaro、Gio、Sonia、Neutrino 和 Uno 设备的第三方控制
Back to 索尼娅系列SOLARO 系列 | 第三方控制 API
1. 简介
该第三方控制协议适用于Solaro、Gio和Sonia系列产品。
2. 概述
对于以太网连接，用户应使用 TCP 端口 #10007 发送消息。服务器将使用相同的 TCP 连接响应该消息。必须每 60 秒通过此 TCP 连接发送一次保持活动消息，否则，服务器端将断开 TCP 连接，并且与该连接关联的所有订阅都将结束。
用户还可以选择使用 UDP 端口 #10008 来监听来自设备的订阅消息。用户可以选择在发出订阅命令时，特定参数是通过 TCP 单播还是 UDP 广播发送其更改。如果未指定，默认情况下参数将通过 TCP 单播通知。状态更新必须使用单独的 TCP 连接，并且即使用户选择对所有感兴趣的参数使用 UDP 广播，也必须通过此 TCP 连接持续发送保持活动消息。如果在任何情况下 TCP 连接断开，则必须重新配置设备中的所有订阅和组设置。
3.语法
第三方控制器字符串由人类可读的 ASCII 字符组成。每个字段由一个空格分隔，在字段之间使用多个空格将导致命令解析错误。发送回车符 ( <CR> ) 来标记消息的结束。方括号中的字段取决于命令。请参阅命令列表部分，了解所有命令的列表、其详细用法和示例。
| 命令 | 1 个空格 | [控制对象/组] | 1 个空格 | [数据] | <回车> |
CONTROL OBJECT是用户在软件中为各个参数指定的最多 32 个字符的字符串。它可以包含除双引号之外的任何可读 ASCII 字符。但是，第一个字符不能是美元符号 ($)，因为前面的“$”用于区分CONTROL OBJECT和CONTROL GROUP 。
控制组是使用CREATE命令创建的最多 32 个字符的字符串，用作组名。它还可以包含除双引号之外的任何可读 ASCII 字符。控制组的第一个字符始终以“$”开头，以表示它是组名。
对于CONTROL OBJECT/GROUP ，如果字符串中包含空格，则必须用双引号括起来。另外，请注意COMMAND和CONTROL OBJECT/GROUP都区分大小写。
DATA可以是：
›数字（正数、负数、浮点数、以 ASCII 表示的整数） ›字符串（必须始终放在双引号内，区分大小写） ›布尔值（TRUE 或 FALSE，区分大小写）
有关每个命令接受的数据类型的详细信息，请参阅命令列表部分。
4. 回应
无论正确与否，设备端都会响应第三方控制命令。如果没有收到响应，则可能表示连接存在问题。设备的所有响应消息都以回车符 (<CR>) 结尾。
如果发送了无效命令，最后遇到的错误代码将返回为： ERROR = <ERROR CODE><CR>
对于 GET 或 GETRAW 命令，响应将是：
<CONTROL OBJECT> = <DATA><CR>对于 REFRESH 命令，响应将是：
<CONTROL OBJECT> = <DATA><CONTROL OBJECT> = <DATA> … <CR>对于KEEPALIVE命令，设备端没有响应。
对于REBOOT命令，Neutrino系统中的行为与Solaro系统不同。
在 Neutrino 系统中，它将回复“ OK<CR> ”
在 Solaro 系统中，没有响应并且设备将重新启动对于所有其他命令，设备将返回：
确定<CR>
5.订阅
外部控制器可以订阅控制对象以获取有关订阅对象上的任何数据变化的通知。
要订阅/取消订阅控制对象，只需发送命令：
订阅 <控制对象> [“TCP”/”UDP”] <CR> 取消订阅 <控制对象> <CR>
然后，通知将根据命令中指定的方式通过 TCP 单播或 UDP 广播自动发送到外部控制系统。外部控制器收到的通知字符串将是：
#<控制对象>=<数据><CR>
该字符串类似于 GET 命令，前面添加了 # 字符，以区分显式读取或通知。
设备发出通知的间隔对于所有订阅的控制对象是全局的，可以通过以下方式配置：
INTERVAL <TIME（毫秒）> <CR>
6. 对照组
控制组允许用户使用单个命令同时控制多个参数。用户必须首先通过以下方式创建一个组：
创建<控制组> <CR>
创建群组后，各个控制对象可以通过以下方式加入或离开群组：
加入<控制组> <控制对象> <CR> 离开<控制组> <控制对象> <CR>
将参数添加到组时必须小心，以确保所有参数都是同一类型并支持相同的命令。
当一个组不再使用时，可以通过以下方式释放资源：
删除<控制组> <CR>
与订阅类似，控制组仅在活动连接期间持续存在。当连接丢失时，必须重新创建组。
7. 密码保护
如果设备受密码保护，则用户必须先解锁设备才能发送任何命令。身份验证仅在连接期间有效，因此如果发生 TCP 断开连接，用户必须再次解锁设备。
要解锁设备，请发送以下命令：
登录 <密码> <CR>
命令中使用的密码与软件中设置的密码相同。
8. 详细/简单模式
<未来实现 - 主要用于配置响应的详细信息量。这将有助于一些外部控制器更轻松地解析响应>
9. 控制对象设置
要设置控制对象字符串，您需要使用 Pleneo Designer 来设置您想要控制的 DSP 参数的控制对象名称。
在 Pleneo Designer 的项目设计模式下，您可以选择要创建第三方控制对象的 DSP 模块。双击模块以调出模块控制面板。在面板中，您可以按住 Ctrl 键并选择控制对象来选择要控制的参数。选择后，控制对象将突出显示。
右键单击突出显示的对象，然后在弹出菜单中选择“创建第三方控制对象名称”。将显示一个对话框。您可以输入一个唯一的（设备内唯一的）控制对象名称。此名称将用于您的第三方控制协议。
一旦定义了第三方控制对象名称，左上角就会显示一个小的红色指示器，表示此对象可以通过第三方控制进行控制。您还可以注意到，模块的左上角也会有一个指示器，表示其某些参数已定义第三方控制对象名称。
若要查询您项目中定义的所有第三方控制对象名称列表，您可以从顶部菜单栏中选择“项目”->“设备第三方控制元素”，以显示所有控制对象名称列表。您还可以将此列表导出到 Excel，作为第三方控制编程的参考。
10. 命令列表
设置 <控制对象/组> <数据 - 数字/字符串/布尔值>
| 示例 | 设置增益 1 -3.2 设置极性 1 TRUE 设置滤波器 1 “巴特沃斯” 设置$group1 -15.7 | 将“gain1”设置为-3.2 dB将“polarity1”设置为ON位置将“filter1”设置为Butterworth Filter将group1中的所有参数设置为-15.7dB |
SETRAW <控制对象/组> <数据 - 数字>
示例 SETRAW gain1 -3200 将“gain1”设置为 -3.2 dB
SETRAW 极性 1 1 将“极性 1”设置为 ON 位置
SETRAW filter1 1 将“filter1”设置为 Butterworth 滤波器
SETRAW $group1 1000 将group1中的所有参数设置为+1.0dB
获取<控制对象/组>
| 例子 | 获取 EQslope 获取 $group1 |
获取“EQslope”格式的值
获取 group1 中所有参数的格式化值
GETRAW <控制对象/组>
| 例子 | GETRAW EQslope GETRAW $group1 | 获取“EQslope”原始值获取组 1 中所有参数的原始值 |
INC <控制对象/组> <数据 - 数字>
例如 INC fader3 0.5 将“fader3”增加 0.5 dB
INC $group1 1 将 group1 中的所有参数增加 1dB
INCRAW <控制对象/组> <数据 - 数字>
| 例子 | INCRAW 推子3 500 INCRAW $组1 1000 | 将“fader3”增加 0.5 dB，将 group1 中的所有参数增加 1dB |
DEC <控制对象/组> <数据 - 数字>
| 例子 | DEC fader3 0.5 DEC $group1 1 | 将“fader3”降低 0.5 dB，将 group1 中的所有参数降低 1dB |
DECRAW <控制对象/组> <数据 - 编号>
| 例子 | DECRAW fader3 500 DECRAW $group1 1000 |
将“fader3”降低 0.5 dB
将组 1 中的所有参数降低 1dB
切换<控制对象/组>
| 例子 | 切换静音1 切换$group2 |
切换“静音1”状态
切换组 2 中的所有参数
PRESET <数据 - 数字/字符串>
| 例子 | PRESET 4 PRESET “预设名称” | 调用预设 #4调用名为“预设名称”的预设 |
订阅 <控制对象/组> <数据 - 字符串>*
| 例子 | 订阅 meter6 订阅 meter6 “TCP” 订阅 meter6 “UDP” | 通过 TCP 单播订阅“meter6”通过 TCP 单播订阅“meter6”通过 UDP 广播订阅“meter6” |
* <DATA - string> 是可选的，默认使用 TCP 单播
取消订阅 <控制对象/组>
示例 UNSUBSCRIBE meter6 取消订阅 “meter6”
保持活动
示例 KEEPALIVE 无操作。可由外部控制器使用，以保持 TCP 连接处于活动状态。
间隔 <数据 - 数字>
示例 INTERVAL 100 将订阅间隔设置为最小 100ms。
* 订阅数据可能会延迟超过指定的间隔
由于 CPU 使用率，但保证等待配置的
尝试发送订阅数据之前的间隔时间。
* 最小值为 100 毫秒。
笔记
在 Neutrino 系列处理器中，Interval 命令适用于单个 TCP 连接。这意味着您可以为不同的连接设置不同的 Interval。然而，在 Solaro 系列处理器中，此内部命令适用于全局。当您设置此 Interval 命令时，所有连接间隔都将更改。
登录<数据 - 字符串>
示例 LOGIN “密码” 使用“密码”登录外部控制
重启
示例 REBOOT 远程重启设备
刷新
示例 REFRESH 获取所有控件对象的格式化数据值
创建<控制组>
示例 CREATE group1 创建一个名为“group1”的组
这是唯一的例外，其中控制组在语法中不需要“$”符号，因为在创建组时会自动添加“$”符号。
删除<控制组>
示例 REMOVE $group1 删除名为“group1”的组
加入<控制组> <数据-字符串>
例如 JOIN $group1 “gain1” “gain1” 将加入 group1
离开<控制组> <数据-字符串>
例如 LEAVE $group2 “mute2” “mute2” 将离开 group2
11. 数据字符串
字符串值
滤波器类型 Butterworth、LR、Bessel
滤波器斜率 6db/Oct、12db/Oct、18db/Oct、24db/Oct、30db/Oct、36db/Oct、42db/Oct、48db/Oct
AFS 灵敏度 非常低、低、中、高、非常高
AFS 类型 动态，固定
控制斜坡类型 线性、对数、音频
12. 错误代码
错误代码描述
101无效命令
102糟糕的论点
103数据格式无效
104未找到控制对象
105参数未找到
106未找到数据值
107已达到最大订阅量
108密码错误
109尚未登录
110控制对象不支持命令
111组名无效
已达到最大控制组数112
113群组控制对象数量已达上限
114对象已在组中
115对象不在组中
116与组中其他对象发生冲突
117无效预设 #
118无效的预设名称
