Auber API

Connecting to the API

Applications can communicate with the API using the UDP protocol. The sample Visual Basic 6 source code (Sample.vbp) demonstrates how this can be accomplished. A developer can connect to the API using any development environment that allows Windows socket communications using UDP. The reason UDP was used versus ActiveX or similar protocols is because UDP will allow for monitoring/controlling over the Intranet or Internet. There are thousands of examples on the Internet on the subject of UDP. The MSDN library also has examples for Visual Basic and C++. Using Visual Basic, it is possible to open a connection and send a read or write request using less than ten lines of code.

Demo Application
Visual Basic 6 source code is provided that demonstrates all read and write requests.

Requests
The communications is divided into two categories: 1. Read Request. A developer would use this to read a value from the controller. 2. Write Request. A developer would use this to write a value to the controller. The requests are simple but must be formatted properly for the API to understand them. Each message starts with an STX (start of text character) and ends with an ETX (end of text character). This makes message parsing easy because it is known that a full message is contained between the two characters. The requests also contain the IP endpoint of the machine making the request. An IP endpoint is the IP address of the machine and the port that is listening for information. An example of an IP endpoint is 128.0.2.54,8001. Every request will indicate that it either wants to read a value or write a value. Finally, requests that write values also need to indicate the value to be written. All of these items are separated by pipes (|). Again, this is for ease of parsing.

Read Request
(Reading a value from the controller) The read request packet format is: <STX><this IP endpoint><separator><Read Instruction><Separator><Command><ETX> STX = ASCII character 02 ETX = ASCII character 03 Separator = | (pipe) Read Instruction = R Command = A command from the Valid Commands table Sample Read Request: localhost,8001|1|R|SV This sample request tells the API to Read the SV from the controller and send the value back to the application listening on the local machine (localhost) on port 8001.

Write Request
(Writing a value to the controller) The write request packet format is: <STX><this IP endpoint><separator><Write Instruction><Separator><Command><Separator><Set value><ETX> STX = ASCII character 02 ETX = ASCII character 03 Seperator = | (pipe) Write Instruction = W Command = A command from the Valid Commands table Set value = A value that falls in the valid range of the Valid Commands table Sample Write Request: localhost,8001|1|W|SV|225 This sample request tells the API to set SV to 225. The API will set the value and then send a message back to the local machine (localhost) on port 8001 indicating the new value. The developer can write safety checks to make sure the value was set properly and act accordingly.

Valid Commands and Ranges

SV ALM1 ALM2 HY1 HY2 HY AT I P D T SN DP PSL PSH ALP PB OPA OUTL OUTH COOL BAUD ADDR FILT AM LOCK -250 to 2500 -1999 to 9999 -1999 to 9999 0 to 9999 0 to 9999 0 to 20 0 to 3 0 to 9999 1 to 9999 0 to 2000 0 to 125 0 to 37 0 to 3 -1999 to 9999 -1999 to 9999 0 to 17 -1999 to 4000 0 to 2 0 to 110 0 to 110 0 to 15 4800 0 to 100 0 to 20 0 to 2 0 to 9999

Applications that connect to the API using UDP should use localhost for the loopback address rather than 127.0.0.1. In certain situations, you may need to open up the ports on your router. The API uses port 8000 by default, and the sample application uses port 8001. Every time a request (Read/Write) is sent to the controller via the API, a response is generated and sent back to the application. Responses containing an explanation point (!) indicate that there is an error. An example of this would be trying to set a value outside of the ranges listed in the Valid Commands and Ranges table. The controller can not handle more than 1 request per second. Because every request is followed by a response, it is possible to validate every request. An example of this would be setting the SV to a value and then checking the SV value in the response. Because the developer has full control over reading and writing values, tasks such as ramping, alarms, and notifications can be accomplished with little effort.