Commands are sent over a TCP connection. The connection may remain open, or it may be opened and closed as needed. The default TCP port is port # 11000. To test, start a Telnet session on a computer connected to the same network as the A2Z-Link and connect to port 11000. This command is typically:
telnet ip-address-of-a2zlink 11000
Then enter:
vr[ENTER]
A version # should be returned such as:
3.0.0.127
Connections need to be authorized. In Setup on the Network tab users may be set up. A user with rights Admin or Normal will have access. Guests will not have access. The connection IP is authorized with the following command:
au,user,pass
If the user is authorized, the command returns "ok". After authorization, commands may be given from the source IP address. To de-authorize a connect use the command:
lo
This will remove the source IP address from the this list of authorized IP addresses.
Controlling Devices
The A2Z-Link abstracts Z-Wave devices so there is no need to understand the intricacy of the Z-Wave protocol. When devices are added, the A2Z-Link creates virtual devices that represent the functionality of the target device. For example. if a simple Z-Wave lamp module is added, it will be viewed on the Device Management web page like:
This virtual device represents the lighting control functionality of the device and shows it can be turned On,Off, and Dimmed. These devices are controlled with their reference #. A reference # is a unique ID assigned to the device and cannot be changed. Other properties of the device may be changed as needed, such as the location and name. The reference # is listed in the second column as can be seen above.
Devices are controllable by setting their value or label. Each device holds a collection of name/value pairs that represent the available control points. Control points can be a single value, such as 0 for Off, or a value range such as 1-98 for a dim level. In the web interface on the device management page you can click on the name of a device to bring up its properties. Click on the "Status/Graphics" tab to see the available pairs. From here you can determine how to control the device. You can also issue a command to get the pairs if your control system can deal with that.
Commands are available to retrieve the control information if your control system can support this.
Here is an example of the status pairs for a dimmable light. It can be seen that the possible control values are 0 for Off, 99 for On, 255 for on last level, and 1-98 for the dim level.
Commands are issued as simple text strings terminated with a carriage return and linefeed.
Commands are not case sensitive.
Parameters in [] are optional.
The following commands are available for device control:
| Command | Format |
Description |
Example |
| Control a device by value |
cv,ref,value | Controls a device by settings its value. All devices have a collection of name/value pairs that represent controllable parts of the device, such as On=99 and Off=0. The value is used for control. |
Turn on a light where the reference # is 2356 and the ON value is 99: cv,2356,99 |
| Control a device by label |
cl,ref,label | Controls a device using the control label. All devices have a collection of name/value pairs that represent controllable parts of the device, such as On=99, and Off=0. The actual label is used for control. |
Turn on a light where the reference # is 2356 and the ON label is On: cl,2356,On |
Retrieving control information
For advanced systems that can dynamically create a user interface, the control information can be obtained. A request may contain a single device reference #, of, if omitted, control information for all devices is returned.
| Command | Format |
Description |
Example |
| Get control information |
gc,[ref] | Returns control information for a given device, all all devices if the reference # is omitted. The return format is: ref,label=value,label=value,... If the device supports a control point that accepts a range of values, such as dimming light, the control pair will be returned as: PREFIX (value)SUFFIX=FROM->TO The PREFIX is a label that appears before the value and the SUFFIX is a label that appears after the value. The PREFIX and SUFFIX are listed on the "Status/Graphics" tab in the device properties and can be changed if needed. Note: If a label contains a "," it will be escaped and returned as "\,". |
For example, a dimming device with ref 3755 may have its PREFIX set to "Dim" and its
SUFFIX set to "%", and the valid values are 1-98, the return would be: 3755,On=99,Off=0,Dim (value)%=1->98 |