Difference between revisions of "Control Chain Protocol"

From MOD Wiki
Jump to navigation Jump to search
Line 1: Line 1:
 +
<div style="background-color: #FF2A2A; border:2px solid #FF0000; color: black; font-weight: bold; text-align: center; padding: 2px;">This page is in a work in progress, the informations here can be modified any time. Please, do not edit it yet, check the discussion section if you'd like to contribute with.</div>
 +
 +
 
== About ==
 
== About ==
  
−
The '''Control Chain''' is a communication interface that enables eletronic devices to interact with MOD devices. It is basically an eletronic signal standard with an open communication protocol.
+
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.
 +
 
 +
{| class="wikitable"
 +
! 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:
 +
 
 +
{| class="wikitable"
 +
! field
 +
! subfield
 +
! size
 +
|-
 +
| rowspan="4" | header
 +
| destination
 +
| 1
 +
|-
 +
| origin
 +
| 1
 +
|-
 +
| command
 +
| 1
 +
|-
 +
| data size
 +
| 2
 +
|-
 +
| rowspan="3" | 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:
 +
 
 +
{| class="wikitable"
 +
! 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''
 +
 
 +
{| class="wikitable"
 +
! 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''
 +
 
 +
{| class="wikitable"
 +
! field
 +
! size
 +
|-
 +
| [none]
 +
| 0
 +
|}
 +
 
 +
''device to host''
 +
 
 +
{| class="wikitable"
 +
! style="font-weight: bold;" | field
 +
! style="font-weight: bold;" | size
 +
! style="font-weight: bold;" | subfield 1
 +
! style="font-weight: bold;" | subfield 2
 +
! style="font-weight: bold;" | subfield 3
 +
! style="font-weight: bold;" | subfield 4
 +
! style="font-weight: bold;" | description
 +
|-
 +
| device label
 +
| 1B_str
 +
|
 +
|
 +
|
 +
|
 +
| friendly device name
 +
|-
 +
| actuators count
 +
| 1
 +
|
 +
|
 +
|
 +
|
 +
| amount of actuators of the device
 +
|-
 +
| rowspan="13" | actuators list
 +
| 1
 +
| rowspan="12" | actuator 1
 +
| id
 +
|
 +
|
 +
| actuator id
 +
|-
 +
| 1B_str
 +
| name
 +
|
 +
|
 +
| actuator name
 +
|-
 +
| 1
 +
| modes count
 +
|
 +
|
 +
| amount of supported assignment modes
 +
|-
 +
| 1
 +
| rowspan="4" | modes list
 +
| rowspan="3" | 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
 +
| rowspan="3" | steps list
 +
| value 1
 +
|
 +
| step value 1
 +
|-
 +
| 2
 +
| value 2
 +
|
 +
| step value 2
 +
|-
 +
|
 +
| ...
 +
|
 +
|
 +
|-
 +
|
 +
| ...
 +
|
 +
|
 +
|
 +
|
 +
|}
 +
 
 +
==== control assignment ====
 +
 
 +
''host to device''
  
−
The electrical signal is based on the [http://en.wikipedia.org/wiki/RS-422 RS422] (TIA/EIA-422) standard enabling a point to point multi-drop communication, with reliable differential signaling.
+
{| class="wikitable"
 +
! style="font-weight: bold;" | field
 +
! style="font-weight: bold;" | size
 +
! style="font-weight: bold;" | subfield 1
 +
! style="font-weight: bold;" | subfield 2
 +
! style="font-weight: bold;" | description
 +
|-
 +
| actuator id
 +
| 1
 +
|
 +
|
 +
| actuator identifier
 +
|-
 +
| assignment id
 +
| 1
 +
|
 +
|
 +
| assignment identifier
 +
|-
 +
| port mask
 +
| 1
 +
|
 +
|
 +
| LV2 control port properties
 +
|-
 +
| rowspan="2" | 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
 +
|-
 +
| rowspan="3" | scale points list
 +
| 1B_str
 +
| rowspan="2" | scale point 1
 +
| label
 +
| scale point label
 +
|-
 +
| 4
 +
| value
 +
| scale point value
 +
|-
 +
|
 +
| ...
 +
|
 +
|
 +
|}
  
−
The communication protocol was developed supporting [http://en.wikipedia.org/wiki/LV2 LV2] features, our standard for audio processing. The protocol enables multiple devices addressing and real time parameters variations.
 
  
−
It allows up to eight devices in a chain, each device controlling up to 255 effect parameters.
+
''device to host''
  
−
The control chain uses standards ethernet cables and RJ45 connectors.
+
{| class="wikitable"
 +
! field
 +
! size
 +
! description
 +
|-
 +
| response status
 +
| 2
 +
| indicates whether assignment was well done
 +
|}
  
−
It's an open protocol and it is actually used by our peripherals, the footswitch extensor, the expression pedal and our MOD Arduino Shield. It's a way to interface with MOD, for controlling effect parameters, with any kind of dedicated eletronic device.
+
==== data request ====
  
−
It will be fully documented so developers can implement their own devices.
+
''host to device''
−
[[File:MOD-Peripherals-Footswitch-Expression-Pedal.jpg |1000px|thumb|center|Multiple peripherals connected to MOD via Control Chain]]
 
  
−
== MOD Arduino Shield ==
+
{| class="wikitable"
−
[[File:MODArduinoShield-Sensors-Case.jpg|600x200px|thumb|right|MOD Arduino Shield with case examples]]
+
! field
 +
! size
 +
! description
 +
|-
 +
| sequence
 +
| 1
 +
| sequential number used to detect non answered messages
 +
|}
  
−
The MOD Arduino Shield was designed to help developers and hackers who wants to create their own effects controllers for MOD.
 
  
−
The main idea is that, with little effort, anyone can design and assemble the eletronics of any sensor, integrate with Arduino and then with MOD.
+
''device to host''
  
−
Copy and paste some lines of code, solder some components on the breadboard, and easily have your own controller of MOD effects.  
+
{| class="wikitable"
 +
! style="font-weight: bold;" | field
 +
! style="font-weight: bold;" | size
 +
! style="font-weight: bold;" | subfield 1
 +
! style="font-weight: bold;" | subfield 2
 +
! style="font-weight: bold;" | description
 +
|-
 +
| assignments count
 +
| 1
 +
|
 +
|
 +
| amount of assignments in the list
 +
|-
 +
| rowspan="3" | assignments list
 +
| 1
 +
| rowspan="2" | assignment 1
 +
| id
 +
| assignment identifier
 +
|-
 +
| 4
 +
| value
 +
| current assignment value
 +
|-
 +
|
 +
| ...
 +
|
 +
|
 +
|}
  
−
The complete documentation will be available.
+
==== control unassignment ====
  
−
Main article: [http://wiki.portalmod.com/wiki/MOD_Arduino_Shield MOD Arduino Shield]
+
''host to device''
−
=== MOD Arduino Cases ===
 
  
−
* '''Accelerometer'''
+
{| class="wikitable"
−
Control any effect parameter using an accelerometer. Control up to six parameters using the six degrees of freedom, three axis acceleration and three axis rotation.
+
! field
 +
! size
 +
! description
 +
|-
 +
| assignment id
 +
| 1
 +
| assignment identifier
 +
|}
  
−
Main article: [http://wiki.portalmod.com/wiki/Arduino_Case:_Accelerometer Arduino Case: Accelerometer]
+
''device to host''
  
−
* '''Distance'''
+
{| class="wikitable"
−
Control any effect parameter using an ultrasound distance sensor.
+
! field
 +
! size
 +
|-
 +
| [none]
 +
| 0
 +
|}
  
−
Main article: [http://wiki.portalmod.com/wiki/Arduino_Case:_Distance_Sensor Arduino Case: Distance Sensor]
+
==== error report ====
  
−
* '''Expression Pedal'''
+
''host to device or device to host''
−
Control any effect parameter using an expression pedal. Not only the usual wah-wah pedal - you can control tune, frequency, gain just like if you were changing a potenciometer value. Cames with an extra button for bypass, trigger or toggle effects/parameters.
 
  
−
Main article: [http://wiki.portalmod.com/wiki/Arduino_Case:_Expression_Pedal Arduino Case: Expression Pedal]
+
{| class="wikitable"
 +
! 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
 +
|}
  
−
* '''Footswitch'''
+
== Operation ==
−
Control and switch parameteres using a footswitch. Expand your MOD by adding four extra footswitches.
 
  
−
Main article: [http://wiki.portalmod.com/wiki/Arduino_Case:_Footswitch Arduino Case: Footswitch]
+
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.
  
−
* '''Light Sensor'''
+
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.
−
Control any effect parameter using a light sensor. The change of light will change the sound.
 
  
−
Main article: [http://wiki.portalmod.com/wiki/Arduino_Case:_Light_Sensor Arduino Case: Light Sensor]
+
The host can control when the devices will message it keeping its transmission line sending data.

Revision as of 21:35, 22 October 2014

This page is in a work in progress, the informations here can be modified any time. Please, do not edit it yet, check the discussion section if you'd like to contribute with.


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.

Retrieved from "http://wiki.mod.audio/index.php?title=Control_Chain_Protocol&oldid=397"