An AMX controller needs a TCP/IP client to communicate with the HAL. This client exchanges string messages with the HAL using the External Control Message Protocol. The example program included in the AMX Support Package provides a reference implementation of such a client. Let’s take a look at it.
Open the Main.axs source file in NetLinx Studio. Find the dvIPClient and dvHAL device addresses in the DEFINE_DEVICE section of the program. There you will see:
dvIPClient = 0:2:1
dvHAL = 0:FIRST_LOCAL_PORT:0
Device addresses in AMX are comprised of a device number, a port number and a system number. The dvIPClient definition is the device address of the TCP/IP client. The dvHAL definition is the device address of the HAL itself. Their device number is 0 indicating that their ports reside on the NetLinx master controller.
Find the DEFINE_CONSTANT section of the program. There you will see four TCP/IP client-related constants:
sRemoteIP = '10.0.0.6 '
nRemotePort = 4996
nLocalPort = FIRST_LOCAL_PORT
nTCP = 1
The sRemoteIP constant is the IP address of the Control Systems server. This server could be running on a HAL or it could be running on your PC when Halogen is open and not connected to a HAL. We'll assume you will test your control system using Halogen, so change this IP address to match the IP address of your PC for now. The transport protocol is always TCP and the remote port is always 4996 to match the TCP port that the Halogen/HAL Control Server listens on.
The nLocalPort constant is the local port on the controller that identifies a client connection. A NetLinx controller’s available local ports start at FIRST_LOCAL_PORT. Since this program supports no more than one connection at a time the same local port can be used every time the controller tries to open a connection. If you want more simultaneous connections you will need to define more local ports like: FIRST_LOCAL_PORT + 1, FIRST_LOCAL_PORT + 2, etc.
Find the DEFINE_START section of the program. It contains the controller’s first attempt to open a client connection upon startup.
ip_client_open(nLocalPort, sRemoteIP, nRemotePort, nTCP)
Connection retries happen in the Mainline when the client is disconnected. The Mainline is located in the DEFINE_PROGRAM section of the program. The code in the Mainline executes whenever the controller is idle (not processing an event handler).
Find the DATA_EVENT handler in the program. This is the event handler for any data the client receives from the HAL.
DATA_EVENT[dvHAL] { ONLINE: { … bConnected = 1 … } OFFLINE: { bConnected = 0 ip_client_close(nLocalPort) } STRING: { … } … }
The ONLINE event is triggered when an ip_client_open call succeeds in connecting to the HAL. The OFFLINE event is raised when the connection to the HAL is dropped. A variable named bConnected keeps track of the client’s connected state. This variable sends feedback to a connection status indicator on the touch panel.
The ONLINE event is handled by requesting the live values of various controls from the HAL. This initial query ensures that the values displayed on the touch panel reflect the current state of the HAL.
Any actual data that the client receives from the HAL gets processed in the STRING event handler. This handler contains code to parse HAL control values that are sent back in response to a query from the IP client, or that arrive unsolicited because some other client changed or requested them. Refer to the button and level event handlers later on in this guide for code to build and send HAL control values.