About External Control Systems

Wouldn’t it be great if you could control the HAL system not only from attached Digital Remotes, but also from a controller that is not even part of the HAL system? Perhaps this controller also connects to other components in the installation, providing the end users with integrated control over their environment from a single control panel. This is what external control systems are all about and the HAL system makes is easy for you to set up controls that are accessible to an external control system, test them, and put them into production.

The Halogen software lets you create - and make accessible to external control systems - any of the four control types that the HAL system supports: CommandHas no state. A Command control simply allows you to initiate an action. Unlike a Toggle, you cannot undo a Command. The most common usage of Command controls is to assert a preset., LevelGenerally associated with volume, Level controls have a continuous series of states that are represented by a slider., ToggleAllows the user to switch between two states — on or off. A common usage of a Toggle control is to mute/unmute audio. Another common usage is to activate/deactivate a preset., and SelectorAllows the end user to make a selection from a list. Uses for a Selector control might include selecting a music channel, a preset, a room combination, and so on.. Once you have created these controls, you can then link them to any linkable HAL control of the same type, using the same process that you use when linking any HAL system controls together.

This approach gives you a great deal of flexibility over what external control systems have access to and how they relate to the configuration and Digital Remote controls that are present. Think about it for a minute – with HAL and Halogen you can provide controls to an external system that can connect to anything that you can link to. Since control links can include any number of participants, this means that the external controls can work seamlessly with Digital Remote controls or independently of them. The choice is yours and you can provide as much or as little control as you’d like to the external system.

The first step in creating controls for external control systems is similar to configuring the controls for Digital Remotes. What parts of the HAL system do the end users need access to and what are the types of controls they need? For example, if you’d like to allow the end user to control the volume in a room, the external control system needs access to a level control that sets the volume.

Once you’ve decided on the controls that you need, you then open the External Controls dialog box and create the controls that you will link to the parameters that you want to control. Do this by clicking on the Control Systems drop down menu in the Processing Workspace toolbar and then select External Controls:

See Creating Controls for External Control Systems for details on how to do this for each type of control.

Once you have created controls in the Control Systems dialog, you can then link them to any other linkable control of the same type in your HAL configuration. The process is very similar to how you link controls together in other parts of the Halogen software, which is fully explained in Creating a Control Link. For external controls, the link icon appears both in the Control Systems dialog as well as the property dialog for the control. For example, you can create a link for a control system toggle by dragging the link icon from a toggle in the Control Systems dialog and dropping it on a Line Output Mute toggle link icon as shown here.

Alternatively, you can open the toggle’s property dialog, then drag and drop the link icon that appears next to the control. Either way, the result is the same.

Yes! Halogen views the controls that you create in the Control Systems dialog no differently than any other linkable control, which means that you can link them together however you wish.

Do you want a Digital Remote level control and an external level control to work together to control a volume level? No problem, just link all three together with simple drag and drop operations. Do you want a selector available on both a DR and an external control system panel? Again, no problem, just link them together. The external control system can even dynamically update the number of selections and their labels as the links change, just like DR selectors do.

Yes! In keeping with the spirit of testing a HAL configuration without requiring HAL hardware, the external control system support is built into Halogen. As soon as you create controls for your control system, you can test them by connecting your external control system to the Halogen control server, which runs as a part of Halogen when it is not connected to HAL. See Testing External Controls for details.

When Halogen is running and not connected to HAL, the control system server is available as a TCP/IP connection using your PC’s IP address at port 4996. Just connect your external control system to that address and port and you’re in business.

Once connected, the server will respond to any control messages it receives from the external control system and send messages to the external control systems as control values change. The operation of the Halogen control system server is no different than it is on HAL except there is no hardware present to physically control.

After you apply a configuration that contains external controls to a HAL device, its control server will respond to messages from any connected external control system and send control changes to those systems.

To start using your external control system with HAL, just connect it to HAL’s IP address using port 4996. To find your HAL’s available IP address, open the Connect Window in Halogen click on the IP> button to view a list of available IP addresses for the HAL.

For additional information or to add additional IP Addresses connect to HAL and view its properties dialog by double clicking on the HAL title bar. You can use the Link Local IP or any of the other IP addresses configured for this HAL.

See Working with DHCP, DNS, Static IP Addresses, and Gateways for information about how to set up and use HAL IP addresses.

The HAL system uses a TCP/IP ASCII text oriented messaging protocol for communications between the HAL control server and connected external control systems. One type of message the HAL can receive is a ‘get’ message for each type of control. To request a particular control’s value from the HAL, the control system sends a ‘get’ message for the control, which includes the type of control and the number for the control. The HAL will respond with the value.

Every control has a unique number assigned to it automatically in the Control Systems property dialog, but you can change it if you want to. Even if you change a control number, it must remain unique among all defined external controls. The good news is that Halogen always does this for you, but it’s something to be aware of as you change the control numbers.

The message protocol is fully defined in the External Control Message Protocol section, but here is an example. Suppose you’d like to have your external control system get the current value of a level control. In the Control System dialog shown below, there is a Level control that has a number of 1. To make the request, you send the following message to the HAL control server: <L&1>.

What does this mean? All HAL control system messages start with a ‘<’ character and end with a ‘>’ character. This lets the HAL control server know when to start and stop reading the message contained inside. The ‘L’ tells HAL that the control type is ‘Level’ and the 1 tells HAL that the control that you’re interested in is number 1. The ‘&’ character is a separator that divides the message into two parts, the first part being the control type (L) and the second part being the control number (1).

When the HAL control server receives this message, it looks up the current value for level control 1 and sends a message back to the external control system. This message contains the control type, its number, and the current value.

For example, if our level control was currently set to 80.1%, HAL would return the message <L&1&801>.

You are probably noticing that this message looks a lot like the ‘get’ message – just an extra &801 is added to the end. In this case, the final ‘&’ character separates the control number from the value, which is 801. Level values are always integers that range from 0 to 1000, corresponding to the range of 0.0 to 100.0%.

When an external control system is connected to the HAL control server, it can set a control to a new value by sending a ‘set’ message.

note: If you haven’t read the previous question and its answer, now would be a good time to do so – this section builds on it.

Suppose you want your external control system to set the HAL’s level control number 1 to a new value of 49.9%. To do this, send the message <L&1&499> to the HAL control server. This message asks the HAL to set the level control that has control number 1 to a value of 49.9%.

But wait, you say, that looks very similar to the message that HAL returned in the previous section when the control system requested the current value if level control number 1. You are absolutely right – when HAL receives a ‘get’ message, it responds with a ‘set’ message that contains the current value. As we’ve just seen, the external control system can send a ‘set’ message to tell HAL to set a control to a new value.

Perhaps you have an external level control defined and it is linked to both a level control in a level block and to a level control in a DR1. What happens when the end user changes the level by turning the knob on the DR1?

Because the three controls are linked together, HAL always keeps them set to the same value. That is, they track each other. So, if the end user changes the DR1 level to 75.0%, then all three level controls change to 75.0%. What does this mean for the external level control? When this control changes, the HAL control server sends a ‘set’ message informing the external control system of the change. In this case, the message would be <L&1&750>, assuming that this is level control number 1 as in the previous sections. In this message the L indicates that the control is a level control, the ‘1’ means that it is the control that is number 1, and the 750 is the value for the control. Level values range from 0 to 1000, corresponding to the range 0.0 to 100.0%.

When the external control system receives this message, it knows that level control number 1 now has a current value of 75.0% and can indicate this to the end user on the external control system’s user interface.

For details on how to use all four external control types, see Control Systems Tasks. For details about the external message protocol see External Control Message Protocol in the Reference section.

The examples in the previous sections have included information on how to use Level external controls, but here is a summary.

Once you have configured a Level control in the Halogen Control Systems dialog, you can have your external control system use it by sending ‘get level’ and ‘set level’ messages to the HAL control server and by receiving and processing ‘set level’ messages that the HAL control server sends.

To ask HAL to send the current value of a level, use a ‘get level’ message. For example, to get the current value of Level control number 8, send <L&8> to the HAL control server.

HAL responds to a ‘get level’ message with a ‘set level’ message. Suppose the current value of Level control number 8 is 31.4%. In this case HAL would respond to the ‘get level’ message for level number 8 with <L&8&314>. The last number in this response is the value of the level control, which can range from 0 to 1000 corresponding to 0.0 to 100.0%.

Whenever a Level external control changes, the HAL control server updates all connected external control systems by sending a ‘set level’ message that contains the new value.

To change a Level control from your external control system, send a ‘set level’ message to the HAL control server. For example, to set Level control number 8 to 78.9% send the message <L&8&789>.

Once you have configured a Command control in the Halogen Control Systems dialog you can have your external control system use it by sending ‘command’ messages to the HAL control server. Commands are simple one-time actions that are similar to pushing a button.

There is a single ‘command’ message that your external control system can send to the HAL control server to trigger the command. For example, if you have a Command control number 10 defined in the Halogen Control Systems dialog, your external control system could trigger it by sending a <C&10> message. In this case the ‘C’ means it is a Command message and the 10 is for control number 10.

Whenever an external Command control fires, the HAL control server sends a ‘command’ message to all connected external control systems.

Once you have configured a Toggle control in the Halogen Control Systems dialog, you can have your external control system use it by sending ‘get toggle’ and ‘set toggle’ messages to the HAL control server and by receiving and processing ‘set toggle’ messages that the HAL control server sends.

To ask HAL to send the current value of a toggle, use a ‘get toggle’ message. For example to get the current value of Toggle control number 4 send <T&4> to the HAL control server.

HAL responds to a ‘get toggle’ message with a ‘set toggle’ message. Suppose the current value of Toggle control number 4 is 1 (e.g., checked). In this case HAL would respond to the ‘get toggle’ message for toggle number 4 with <T&4&1>. The last number in this response is the value of the toggle control, which is either 0 (un-checked) or 1 (checked).

Whenever a Toggle external control changes, the HAL control server updates connected external control systems by sending a ‘set toggle’ message that contains the new value.

To change a Toggle control from your external control system, send a ‘set toggle’ message to the HAL control server. For example, to set Toggle control number 4 to 0 (un-checked) send the message <T&4&0>.

Once you have configured a Selector control in the Halogen Control Systems dialog, you can have your external control system use it by sending ‘get selector’ and ‘set selector’ messages to the HAL control server and by receiving and processing ‘set selector’ messages that the HAL control server sends.

To ask HAL to send the current value of a selector, use a ‘get selector’ message. For example to get the current value of Selector control number 7 send <S&7> to the HAL control server.

HAL responds to a ‘get selector’ message with a ‘set selector’ message. Suppose the current value of Selector control number 7 is 3, meaning that the current selection for the control is the fourth item in the list. In this case HAL would respond to the ‘get selector’ message for selector number 7 with <S&7&3>. The last number in this response is the value of the selector control, which is the current selection for the control. Selection values are numbered starting with 0 for the first item. Each subsequent item is the next higher number; that is the second item is selection value 1, the third item is selection value 2, etc.

Whenever a Selector external control changes, the HAL control server updates connected external control systems by sending a ‘set selector’ message that contains the new value.

The HAL system also provides messages for external control systems to request and be notified of the number of selections for a Selector control and also the display names for each selection. See “How can an external control system know changes to the number or names of selector items?” in the Advanced section below for more information about this.

To change a Selector control from your external control system, send a ‘set selector’ message to the HAL control server. For example, to set Selector control number 7 to the third selection item send the message <S&7&2>.

The Control Systems Reference section contains all of the details for the full External Control Message Protocol.

Yes, an external control can link to any linkable control in a HAL configuration. This includes read-only controls, for example a HAL1 Logic In toggle control. Of course because the Logic In control is read-only, the external control system cannot change the value of the link, but it can receive ‘set’ messages that inform it of the current value of the link. You could use this to set the state of an indicator on your control system user interface, for example.

Yes! You can have multiple external control systems connected to HAL at the same time. Each control system can exchange messages with the HAL control server. Whenever an external control changes in the HAL, the HAL control server sends ‘set’ messages to each connected external control system to inform them of the change. Similarly, when a Command external control fires, the HAL control server sends a ‘command’ message to each connected external control system to let them know of the event.

The HAL control server doesn’t echo a set or a command message back to the external control system if it is the source of the change. That is, if your external control system sends a ‘set’ command, the HAL control server sends the ‘set’ command to all other connected control system except yours. The only exception to this is if your ‘set’ message attempted to change a control to an invalid value, in which case HAL sends back a ‘set’ message containing the actual value that the control has in the HAL system. These Out of range sets msgs ... These would typically result if you attempted to change an external control linked to a read-only control or to set a value out of the allowed range.

When a HAL selector link activation changes, the HAL control server sends a ‘set’ message for the selector link to all connected external control systems. This message includes the control number for the external selector control and the current number of selections for that control. When the external control system receives this message, it knows that the link has changed. It can use this information to update its control panel.

In addition, when a link activation changes, the HAL control system also sends a set of ‘set selection name’ messages, one for each selection. This informs the external control system of the labels for each item in the selector – these are the same labels that would appear for the selections in a Digital Remote selector control.

For example, suppose an external selector control is defined and has a control number of 7. Let’s link this to a selector block that has four inputs. We’ll use the same scenario as we used in the Selector Control Link Example. In this example, which is a restaurant audio system, the selector includes four program choices: Jazz, Soft Rock, Classical, and Country.

When the external selector control is linked to the selector block, the number of selections is four and the selection names are “Jazz”, “Soft Rock”, “Classical”, and “Country”.

When this link is activated, the HAL control server sends five messages to the connected external control system related to selector control number 7:

<SL&7&4>

<SN&7&0&Jazz>

<SN&7&1&Soft Rock>

<SN&7&2&Classical>

<SN&7&3&Country>

The first message above is a ‘set selector link’ message informing the external control system that external selector control number 7 has four selections defined for it.

The other four messages are ‘set selection name’ messages, one for each of the selections. For example, the first one, <SN&7&0&Jazz>, informs the external control system that first selection for selector control number 7 has a label of ‘Jazz’. Selection items are numbered sequentially starting with 0, where 0 is the first selection, 1 is the second selection and so on.

When a HAL link activation changes, the HAL control server sends a ‘set’ message for each external control that participates in the link to all connected external control systems. This message includes the control number for the external control and the current value of that control. When the external control system receives this message, it knows that the link has changed. It can use this information to update its control panel.

Since external controls participate in links just like any other controls, when the link is not active, the controls in the link no longer track each other. For Command, Level and Toggle controls, nothing actually changes for external controls other than the fact that the link no longer operates. For these controls, deactivating a link results in the HAL control server sending no messages to the connected external control systems.

For Selector controls, however, deactivating the link it participates in does result in HAL sending a message. Just as in Digital Remote selectors, the number of selections is determined by the link that the selector is participating in. When the link is deactivated, there are no selections in the external selector control. As a result, the HAL control server sends a ‘set selection link’ message informing the external control systems that there are zero selections. For example, if the link that external selector control number 7 participates in becomes inactive, the HAL control server sends a <SL&7&0> message to all connected external control systems. This tells the external control systems that there are no selections available for selector control number 7.

The connection between an external control system and the HAL control server is a standard TCP/IP socket connection. In most cases, if something happens to break this connection – such as an Ethernet cable getting unplugged – both ends of the connection will know and respond appropriately. Most external control systems automatically take care of monitoring and responding to connection breaks.

For an added layer of monitoring, the HAL control server also provides a ping-pong message facility that lets the external control system determine whether or not its connection to the HAL is active or not. The way this works is simple: the external control system sends a ping message to HAL: <ping>. Whenever the HAL control server receives this message it sends back a <pong> message. The ping-pong messages have no other purpose or affect on the HAL system other than to let the external control system know that it is still connected and functioning.

No, Halogen/HAL limits the rate of sending level messages when you continuously change level controls in the Halogen application or on a Digital Remote.