Once you have connected to either the Halogen or HAL external control server, you can communicate with it using simple, text-based messages. This section defines this message protocol.
All messages consist of ASCII text and a single message always starts with a ‘<’ character and ends with a ‘>’ character. Inside the start and end characters is the message body, which always includes at least a message type followed by a control number. Each part of the message body is separated from another part by an ‘&’ character. Messages can also have additional parts depending on the type of message. The table below shows the format for each specific message type.
When sending messages to the Halogen/HAL Control Server, it:
- Allows white space anywhere in the message, which includes space, tab, carriage return, and line feed characters
- Ignores all characters outside of a message (that is, before the start character and after the end character)
- Ignores the case of alpha characters – you can use upper or lower case in any combination
Halogen’s External Control Systems dialog defines the unique control number for each control, which is always ‘n’ in the message table below. For example, suppose you have defined a Level control in the Halogen External Control Systems dialog as follows:
In this instance, the control number is 5, and that is what you use in the ‘set level’ and ‘get level’ messages when developing external control systems. In this case the ‘get level’ message for this control is <L&5>.
Details of external control messages
In the following tables, normal characters are literal while bold characters are variable and defined in the description.
All Controls
| Message Format | Description | How Used | Example |
|---|---|---|---|
| <?> |
Get all values message. |
Send this to HAL to request the current values of all controls. |
<?> - request the current values of all controls in the configuration. |
Level Controls
| Message Format | Description | How Used | Example |
|---|---|---|---|
| <?&L> |
Get all level control values message. The includes value, enable, and label for every level control. |
Send this to HAL to request all values associated with all level controls. | <?&L> - request the current level value, enable, and label of all Level external controls. |
| <?&L&n> |
Get level value, enable and label message, where: n is the control number. |
Send this to HAL to request all values associated with the level control with the specified control number. | <?&L&1> - request the current value, enable, and label of Level external control number 1. |
| <L&n> |
Get level message, where: n is the control number. |
Send this to HAL to request the current value of a Level external control. |
<L&1> - request the current value of Level external control number 1. |
| <L&n&v> |
Set level message, where: n is the control number. v is the control value. The range for v is 0 to 1000, corresponding to 0 to 100.0%. |
Send this to HAL to set a Level external control to a new value. HAL sends this:
|
<L&1&456> - set the value of Level external control number 1 to 45.6%. |
|
<L&n&+v> <L&n&-v> |
Increment/Decrement level message, where: n is the control number. + indicates increment. - indicates decrement. v is the amount to increment or decrement the current control value. The range for v is 0 to 1000, corresponding to 0 to 100.0%. note: When an increment or decrement message would result in setting the level control to a value outside of the allowed range of 0 to 100%, the HAL sets the level to the limit value. |
Send this to HAL to increment or decrement a Level external control. |
<L&1&+105> - increment the value of Level external control number 1 by 10.5%. <L&2&-234> - decrement the value of Level external control number 2 by 23.4%. |
| <LA&n> |
Get label message, where: n is the control number. |
Send this to HAL to request the current label value of a Level external control. | <LA&1> - request the current label value of Level external control number 1. |
| <LA&n&string> |
Set label message, where: n is the control number. string is the label for the control. |
Send this to HAL to set the label for a Level external control to a new value. HAL sends this:
|
<LA&1&Volume> - set the label value for Level control number 1 to "Volume". |
| <LE&n> |
Get enable message, where: n is the control number. |
Send this to HAL to request the current enable value of a Level external control. | <LE&4> - request the current enable value of Level external control number 4. |
| <LE&n&v> |
Set enable message, where: n is the control number. v is the enable value. The values for v are 0 (disabled) or 1 (enabled). |
Send this to HAL to set the enable for a Level external control to a new value. HAL sends this:
|
<LA&4&0> - set the enable value for Level control number 4 to 0 (disabled). |
Toggle Controls
| Message Format | Description | How Used | Example |
|---|---|---|---|
| <?&T> |
Get all toggle control values message. The includes value, enable, and label for every toggle control. |
Send this to HAL to request all values associated with all toggle controls. | <?&T> - request the current toggle value, enable, and label of all Toggle external controls. |
| <?&T&n> |
Get toggle value, enable and label message, where: n is the control number. |
Send this to HAL to request all values associated with the toggle control with the specified control number. | <?&T&1> - request the current value, enable, and label of Toggle external control number 1. |
| <T&n> |
Get toggle message, where: n is the control number. |
Send this to HAL to request the current value of a Toggle external control. |
<T&23> - request the current value of Toggle external control number 23. |
| <T&n&v> |
Set toggle message, where: n is the control number. v is the control value. The values for v are 0 (un-checked) or 1 (checked). |
Send this to HAL to set a Toggle external control to a new value. HAL sends this:
|
<T&23&1> - set the value of Toggle external control number 23 to 1 (checked). |
| <TA&n> |
Get label message, where: n is the control number. |
Send this to HAL to request the current label value of a Toggle external control. | <TA&1> - request the current label value of Toggle external control number 1. |
| <TA&n&string> |
Set label message, where: n is the control number. string is the label for the control. |
Send this to HAL to set the label for a Toggle external control to a new value. HAL sends this:
|
<TA&1&Mute> - set the label value for Toggle control number 1 to "Mute". |
| <TE&n> |
Get enable message, where: n is the control number. |
Send this to HAL to request the current enable value of a Toggle external control. | <TE&4> - request the current enable value of Toggle external control number 4. |
| <TE&n&v> |
Set enable message, where: n is the control number. v is the enable value. The values for v are 0 (disabled) or 1 (enabled). |
Send this to HAL to set the enable for a Toggle external control to a new value. HAL sends this:
|
<TA&4&0> - set the enable value for Toggle control number 4 to 0 (disabled). |
Selector Controls
| Message Format | Description | How Used | Example |
|---|---|---|---|
| <?&S> |
Get all selector control values message. The includes selector count, value, enable, label and item names for every selector control. |
Send this to HAL to request all values associated with allselector controls. | <?&S> - request the current selector count, value, enable, label and item names of all Selector external controls. |
| <?&S&n> |
Get selector count, value, enable, label and item names message, where: n is the control number. |
Send this to HAL to request all values associated with the selector control with the specified control number. | <?&S&1> - request the current selector count, value, enable, label and item names of Selector external control number 1. |
| <S&n> |
Get selection message, where: n is the control number. |
Send this to HAL to request the current value of a Select external control. | <S&6> - request the current value of Select external control number 6. |
| <S&n&v> |
Set selection message, where: n is the control number. v is the control value. The range for v is 0 to one less than the number of selections. |
Send this to HAL to set a Select external control to a new value. HAL sends this:
|
<S&6&3> - set the value of Select external control number 6 to 3 (the fourth item in the set of selections). |
| <SL&n> |
Get selection link message, where: n is the control number. |
Send this to HAL to request the current number of selections for Select external control. | <SL&7> - get the number of selections for Select external control number 7. |
| <SL&n&x> |
Set selection link message, where: n is the control number. x is the number of selections. 0 indicates that no selections are available – i.e. the selector link is inactive. |
It is not meaningful to send this message to HAL because an external control system cannot change a selection link. HAL sends this:
|
<SL&7&4> - set the number of selections for Select external control number 7 to 4. |
| <SN&n&i> |
Get selection name message, where:
|
Send this to HAL to request the current value of a selection name for a particular selection item of a Select external control. |
<SN&12&2> - get the current selection name for selection item 2 of Select control number 12. Selection item 2 is the third item in the set of selections. |
| <SN&n&v&string> |
Set selection name message, where: n is the control number. v is the control value. The range for v is 0 to one less than the number of selections. string is the current display name for selection v. |
It is not meaningful to send this message to HAL because an external control system cannot change a selection name. HAL sends this:
|
<SN&12&2&Jazz> - set the current selection name for selection item 2 of Select control number 12 to “Jazz”. Selection item 2 is the third item in the set of selections. |
| <SA&n> |
Get label message, where: n is the control number. |
Send this to HAL to request the current label value of a Selector external control. | <SA&1> - request the current label value of Selector external control number 1. |
| <SA&n&string> |
Set label message, where: n is the control number. string is the label for the control. |
Send this to HAL to set the label for a Selector external control to a new value. HAL sends this:
|
<SA&1&Program> - set the label value for Selector control number 1 to "Program". |
| <SE&n> |
Get enable message, where: n is the control number. |
Send this to HAL to request the current enable value of a Level external control. | <SE&4> - request the current enable value of Selector external control number 4. |
| <SE&n&v> |
Set enable message, where: n is the control number. v is the enable value. The values for v are 0 (disabled) or 1 (enabled). |
Send this to HAL to set the enable for a Selector external control to a new value. HAL sends this:
|
<SA&4&0> - set the enable value for Selector control number 4 to 0 (disabled). |
Command Controls
| Message Format | Description | How Used | Example |
|---|---|---|---|
| <?&C> |
Get all command control labels message. |
Send this to HAL to request label value associated with all command controls. | <?&C> - request the current label of all Command external controls. |
| <?&C&n> |
Get the label message, where: n is the control number. note: Equivalent to the <CA&n> message described below. |
Send this to HAL to request the current label value of a Command external control with the specified control number. | <?&C&1> - request the current label of Command external control number 1. |
| <C&n> |
Command message, where: n is the control number. |
Send this to HAL to fire a Command external control. HAL sends this whenever a Command external control fires. |
<C&4> - Fire Command control number 4. |
| <CA&n> |
Get label message, where: n is the control number. |
Send this to HAL to request the current label value of a Command external control. | <CA&1> - request the current label value of Command external control number 1. |
| <CA&n&string> |
Set label message, where: n is the control number. string is the label for the control. |
Send this to HAL to set the label for a Command external control to a new value. HAL sends this:
|
<CA&1&Flatten> - set the label value for Command control number 1 to "Flatten". |
| <CE&n> |
Get enable message, where: n is the control number. |
Send this to HAL to request the current enable value of a Command external control. | <CE&4> - request the current enable value of Command external control number 4. |
| <CE&n&v> |
Set enable message, where: n is the control number. v is the enable value. The values for v are 0 (disabled) or 1 (enabled). |
Send this to HAL to set the enable for a Command external control to a new value. HAL sends this:
|
<CA&4&0> - set the enable value for Command control number 4 to 0 (disabled). |
Communications Monitoring
| Message Format | Description | How Used | Example |
|---|---|---|---|
| <PING> | Ping message | Send this to HAL to request a pong message. | <PING> |
| <PONG> | Pong message |
It is not meaningful to send this message to HAL. HAL sends this whenever it receives a ping message from an external control system. |
<PONG> |