You are here: Using External Control Systems with HAL > Integrating Stardraw Control Systems > Understanding the Example HAL1 Driver > Part 1 - Communicating with the Halogen/HAL Control Server

Part 1 - Communicating with the Halogen/HAL Control Server

Sending Messages to Halogen/HAL

Sending a message to the Halogen/HAL Control Server is very easy. The HAL1 driver is built upon a class, TcpInPortInstance, which Stardraw provides for basic communications with TCP/IP based devices. The TcpInPortInstance class provides a method, WriteLine(string), that sends the string argument to the connected TCP/IP device, in this case Halogen or a HAL1. The example HAL1 driver includes a set of utility methods that each create a HAL external control message and use WriteLine to send it to Halogen/HAL. There is a method for each type of message that the driver can send to Halogen/HAL (except for the <ping> message, which we don’t use in the example driver). These are:

Method	External Control Message
Level
`setLevel(uint controlID, int value)`	‘set level’
`requestLevel(uint controlID)`	‘get level’
Toggle
`setToggle(uint controlID, int value)`	‘set toggle’
`requestToggle(uint controlID)`	‘get toggle’
Command
`executeCommand(uint controlID)`	‘set command’
Select
`setSelection(uint controlID, int value)`	‘set selection’
`requestSelection(uint controlID)`	‘get selection’
`requestSelectionLink(uint controlID)`	‘get selection link’
`requestSelectionName(uint controlID, int selectionNumber)`	‘get selection name’

See Appendix A for the complete definition of the HAL external control messages and their formats.

To see how these methods work, look at the first one in the list, setLevel():


/// <summary>
/// Send a set level message
/// </summary>
/// <param name="controlNumber">The HAL control system number for the control</param> 
/// <param name="value">The level value to set</param> 
private void setLevel(uint controlNumber, int value)
{
  string cmd = string.Format("<L&{0}&{1}>", 
                             controlNumber, value);
  WriteLine(cmd);

  Logger.Debug("Level - set command sent: " + cmd);
}

This method first creates a message string, cmd, formatted according to the HAL external message protocol using the supplied parameters for the control number and value. For example, if the driver called the method like this:

setLevel(6, 800);

the method would send the HAL external control message <L&6&800> to the Halogen/HAL Control Server, telling it to set level control number 6 to a value of 800 (80.0%). You will also notice that setLevel() also logs a debug string to the Stardraw Logger, which appears in the Debug window when running the Stardraw application under the debugger.

Receiving and Processing Messages from Halogen/HAL

Receiving and processing messages that Halogen or HAL sends to the Stardraw driver is somewhat more difficult. This is because the driver not only receives messages, but it must also decode them and let the Stardraw application know about the information contained within them.

The methods that the example driver uses for this are:

The driver overrides Stardraw’s TcpInPortInstance.OnByteIn() method, which runs whenever the connected Halogen/HAL Control Server sends a message byte to the Stardraw application. OnByteIn() handles each character as it is received and when it has recorded a complete message, it passes it off to the processMessage() method.

The processMessage() method decodes the message and calls one of three other methods depending upon the type of message it decodes:

setValue() for ‘set toggle’, ‘set selector’, and ‘set level’ messages;
setSelectionLink() for ‘set selection link’ messages
setSelectionName() for ‘set selection name’ messages.

These three ‘set’ messages update the state of the internal driver properties and variables according to their areas of responsibilities. The setValue() method updates all of the Level, Toggle, and Selector values while setSelectionLink() updates the number of selections in each selector and setSelectionName() updates of the name for a selection item in a selector. In the next section you will see how this relates to the properties and events that the driver exposes to the Stardraw application.