Venstar had a short description of the API posted on their web site (8 pages), but it needs a little further explanation. Another issue is that Venstars have been at API V4 for several years now, but the documentation reads V3. Fortunately I haven’t noticed any major differences between what the doc says and what I actually see on the network.
You can get a good idea of the 5 available queries (root, info, sensors, runtimes and alerts) by entering the IP address of the Venstar followed by the query. As an example, for a Venstar at 192.168.2.148, if I type “192.168.2.148/query/info” into the web browser’s url window I will get a JSON-formatted response that looks pretty much like what section 3.1.1 of their documentation shows. The control function is quite different and I know of no way to just type the url to issue a control command.
Fortunately, Perl provides good capabilities to both issue the commands and handle the responses. As an example, the following Perl code will issue a proper query and place the response into $resp.
my $ua = new LWP::UserAgent;
my $req = new HTTP::Request ‘GET’,’http://192.168.2.148/query/info’;
my $resp = $ua -> request($req);
To issue a control, the Perl code is somewhat different.
my $ua = new LWP::UserAgent;
my $req = new HTTP::Request ‘POST’,’http://192.168.2.148/control’;
$req->header(‘content-type’ => ‘application/x-www-form-urlencoded’);
my $query = “heattemp=” . $heattemp . “&” . “cooltemp=” . $cooltemp;
$req->content($query);
my $resp = $ua -> request($req);
In the case of the control, there isn’t much of a response to handle. For the queries, handling the response becomes critical. Perl does have a JSON parser but after looking at the text of the responses I decided it would be easier to handle them without using it. I first remove any header (luckily fixed length), then remove all the brackets, braces and quotes from the response. I then use commas and colons to split the remaining message into elements of an array(for the runtimes) or a hash(for the info). I have posted complete samples of the Perl code to handle the info and the runtimes.
RUNTIMES
The response that needs a fair amount of explanation is the one I cared about the most – the query/runtimes. Venstar’s documentation on the runtimes mentions the content-length is 56 but only shows 8 – well, it shows 9 but the last one is an either/or. What they don’t say is that each response includes all the daily runtimes for the previous 6 days plus a 7th runtime for today, and 7 times 8 makes up the 56. The runtimes for the 6 previous days are based on a 24-hour period that ended at midnight. If you look at the runtimes on Skyport you’ll see the previous 6 days (along with the previous week’s runtimes) plus whatever the runtime is for that day, and if you use your browser to look at the response itself you’ll see where those numbers came from. In the packet itself the days are ordered in chronological order, with the current (incomplete) day being last. Further complicating this is that for the first 6 days of operation there are fewer than the 6 + 1 days.
If you’ve been successful at retrieving the runtimes every day for the previous 6 days, the only new runtime you care about is the 6th one out of the 7. You don’t care about 1 through 5 because you’ve already seen them, and the 7th/last one is always for an incomplete day. As each day passes the runtimes for a particular day advance in the response until they drop off the leading edge.