Control Chain Protocol

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	6
data	N

The header contain the following informations: destination, origin, command,data size and check. The data field holds the data bytes related to command.

Expanding the fields:

field	subfield	size
header	destination	1
	origin	1
	command	1
	data size	2
	check	1
data	data 0	1
	data 1	1
	...	N

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. The check is the byte message verification. It's calculated XOR'ing all message bytes.

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

Devices can only send the handshaking to host when the host isn't sending data. New devices doesn't has any origin address yet thus the origin, in the header message field, must contain the 0x00 value. Once that host received the handshaking it will generate an address to new device, this address value must be between 0x80 and 0xFF, inclusively, and must be informed to device using the destination field. The data field of original message must be give back to device untouched.

The channel field is used to differentiate devices of the same type, i.e. same device URI. Each device can choose its own way to select the channel.

The protocol version always must be verified by the host. In the case of device has newer protocol implementation, the host have to raise an error report message to device, and the device, by its side, can optionally, if possible, pop up the received error to user. And finally that device has to stop sending handshaking. The host have to support backwards compatibility.

device to host or host to device data field

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 in the destination field. After that host can 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 or send other requests, 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.