Control Chain Protocol
Contents
About
Control Chain is an open hardware assignment protocol developed to reflect the LV2 controls properties. In other words the Control Chain able you to control LV2 plugins control ports using a hardware device like Arduino.
Although the Control Chain has been created focused on MOD, it isn't a must to has it working with LV2 plugins. This can be done using, for example, an Arduino, connected via USB to your PC.
This page concentrates technical informations of Control Chain. If you are looking for startup guide to create new controllers, please refer to MOD Arduino Shield article, there you will find a tutorial and Arduino cases that will help you.
Physical interface
In theory, Control Chain does not requires a physical interface to deal with a host. But in practice is what happen and some of decisions about the protocol was taken looking at the physical interface limitations.
The MOD hardware uses the RS-485(TIA/EIA-485) electrical standard, over serial communication, accessible via RJ45 connector, which allows to connect external peripherals using ethernet cables. The communitication is full-duplex and the speed used is 1Mbps.
Probably the better way to prototype Control Chain controllers is using an Arduino. In this case the physical interface will be serial over USB.
Protocol
Control Chain uses a binary protocol which has your data encapsulation using SLIP (RFC 1055).
Message Structure
The below table shows the elementary structure of all messages.
| field | size |
|---|---|
| header | 5 |
| data | N |
| check | 1 |
The header contain the following informations: destination, origin, command and data size. The data field holds the data bytes related to coommand. And the check is the message verification byte. It's calculated XOR'ing all message bytes.
Expanding the fields:
| field | subfield | size |
|---|---|---|
| header | destination | 1 |
| origin | 1 | |
| command | 1 | |
| data size | 2 | |
| data | data 0 | 1 |
| data 1 | 1 | |
| ... | N | |
| check | 1 |
The destination and origin fields are addresses that says from where the message is going to and coming from, respectively. The value 0x00 stands for the host address and the devices addresses values must be between 0x80 and 0xFF, inclusively.
Commands
The valid commands are:
| value | description |
|---|---|
| 0x01 | handshaking |
| 0x02 | device descriptor |
| 0x03 | control assignment |
| 0x04 | data request |
| 0x05 | control unassignment |
| 0xFF | error report |
handshaking
device to host or host to device
| field | size | description |
|---|---|---|
| device URI | 1B_str | a string that identifies the device |
| channel | 1 | channel configured on device |
| protocol version (major) | 1 | major number version control |
| protocol version (minor) | 1 | minor number version control |
device descriptor
host to device
| field | size |
|---|---|
| [none] | 0 |
device to host
| field | size | subfield 1 | subfield 2 | subfield 3 | subfield 4 | description |
|---|---|---|---|---|---|---|
| device label | 1B_str | friendly device name | ||||
| actuators count | 1 | amount of actuators of the device | ||||
| actuators list | 1 | actuator 1 | id | actuator id | ||
| 1B_str | name | actuator name | ||||
| 1 | modes count | amount of supported assignment modes | ||||
| 1 | modes list | mode 1 | mask 1 | property mask 1 | ||
| 1 | mask 2 | property mask 2 | ||||
| 1B_str | label | mode label | ||||
| ... | ||||||
| 1 | slots | amount of controls that can be assigned to this actuator | ||||
| 1 | steps count | amount of values in the steps list | ||||
| 2 | steps list | value 1 | step value 1 | |||
| 2 | value 2 | step value 2 | ||||
| ... | ||||||
| ... |
control assignment
host to device
| field | size | subfield 1 | subfield 2 | description |
|---|---|---|---|---|
| actuator id | 1 | actuator identifier | ||
| assignment id | 1 | assignment identifier | ||
| port mask | 1 | LV2 control port properties | ||
| chosen mode | 1 | mask 1 | mask 1 of chosen mode | |
| 1 | mask 2 | mask 2 of chosen mode | ||
| label | 1B_str | control label | ||
| value | 4 | current control value | ||
| minimum | 4 | minimum control value | ||
| maximum | 4 | maximum control value | ||
| default | 4 | default control value | ||
| step | 2 | control step | ||
| unit render | 1B_str | control unit reder | ||
| scale points count | 1 | amount of control scale points | ||
| scale points list | 1B_str | scale point 1 | label | scale point label |
| 4 | value | scale point value | ||
| ... |
device to host
| field | size | description |
|---|---|---|
| response status | 2 | indicates whether assignment was well done |
data request
host to device
| field | size | description |
|---|---|---|
| sequence | 1 | sequential number used to detect non answered messages |
device to host
| field | size | subfield 1 | subfield 2 | description |
|---|---|---|---|---|
| assignments count | 1 | amount of assignments in the list | ||
| assignments list | 1 | assignment 1 | id | assignment identifier |
| 4 | value | current assignment value | ||
| ... |
control unassignment
host to device
| field | size | description |
|---|---|---|
| assignment id | 1 | assignment identifier |
device to host
| field | size |
|---|---|
| [none] | 0 |
error report
host to device or device to host
| field | size | description |
|---|---|---|
| error on command | 1 | indicates which command raise the error |
| error code | 1 | a number that represents the error |
| error message | 1B_str | string that describes the error |
Operation
Initially host is waiting for devices handshaking, once the first device sends the handshaking, the host must response back informing its device id. After that host must request the device descriptor and wait for device response or timeout. Since the device is identified on host, it should wait until the host send to it an assignment request.
The host start to polling the identified devices for data request as soon as an assignement is done. The polling period is determinated by the host considering the count of identified devices. In each polling devices cycle the host is responsible to reserve a short period of time to allow that new devices connect to it, this because devices can only send messages to host when it isn't sending any message.
The host can control when the devices will message it keeping its transmission line sending data.
