Using a wifi thermostat API


I love it when device manufacturers realize that they can do well by selling a device with documented interfaces, in the hopes that a nebulous community of hackers will invent cool new things for it. So I was pretty happy when the Radio Thermostat Company of America announced that they had an API available for their wifi thermostats (such as the 3M-50 at Home Depot or the CT-50 [amzn] at Amazon).

The API docs are currently available under a link on their “latest news” page.   The API describes a JSON interface to the thermostat, so you can retrieve or send information using http.  For example:

$ curl http://thermostat1/tstat
{"temp":67.50,"tmode":1,"fmode":0,"override":0,"hold":0,
"t_heat":62.00,"time""{"day":1,"hour":9,"minute":47},
"t_type_post":0}

We can get current temperature, set point, mode (heating, cooling, or off), humidity (on some models) etc. And it’s not just a read-only interface; you can set parameters like target temp, schedules, etc, as well as display some information on the screen (4 digits on the CT-30 [amzn] , alphanumeric on the CT-80 [amzn])

There’s a Windows tool out there called “Set Your Thermostat” which seems to have gotten the most press, and there’s a 3rd party iPhone app called Thermostapp which likely uses this API as well. So far all I’ve done with it at home is to query the devices every 5 minutes for setpoint and current temperature, so I can graph stuff out, like in the graph above.  At the end if this post is a basic & ugly perl script to gather that information from the thermostat; I process this a little with a bash script and use MRTG to graph it out.

I think there’s a lot more that could be done, such as:

  • Display of household electricity data, or thermostat run time, on the display
  • Use of indoor & outdoor temps to start heating/cooling in time to hit setpoint at desired time
  • Better graphing than MRTG can provide, maybe with Cacti or PCP.
  • Addition of X10 or similar occupancy sensors for automatic setback
  • Automatic coordination of two zones to minimize boiler firing cycles

Text display on a CT-80 [amzn]

I’ll leave you with my simple perl script to gather some basic data from a thermostat:

#!/usr/bin/perl

use LWP::UserAgent;
use MIME::Lite;
use MIME::Base64;
use Getopt::Std;
use JSON;
use strict;

use vars qw/ %opt /;

my $debug = 0;
my $host = "thermostat2";
my $tempurl = "http://$host/tstat";

my $ua = LWP::UserAgent->new;
my $req = HTTP::Request->new(GET => $tempurl);
my $res = $ua->request($req);

if (! $res->is_success) {
    exit;
}

my $scalar = from_json($res->content);

# target isn't there if not in heat mode
my $t_heat = 0;
$t_heat = $scalar->{ 't_heat' } if $scalar->{ 't_heat' };

print "Temp is " . $scalar->{ 'temp' } . "\n";
print "Target temp is " . $t_heat . "\n";
print "Mode is " . $scalar->{ 'tstate' } . "\n";

51 thoughts on “Using a wifi thermostat API

  1. Which one do you have?

    The CT-30/80 don’t have the best reviews on Amazon. I’d probably end up going with the CT-30, because then at least I won’t be out too much money is there are any problems.

    -Bryan

    • I have the 3M/Filtret 3M-50 which is basically the CT-30, and also the CT-80, which – full disclosure – I got gratis from the company a year or so ago for testing & review.

      One of the bad CT80 reviews is actually complaining about a different thermostat made by Rite Temp, and upset that Radio Thermostat didn’t help him with it – they may be similar thermostats and have the same parent company but still, you have to at least try to complain to the right people.

      The CT-30 got 4.5 stars average, so that’s not too bad.

      The screen on the 3M-50 / CT-30 isn’t the best, honestly; the touch screen is a little twitchy. The CT-80 is nicer, but yeah, it’s really on the pricey end. Both of them are a little fiddly to set up & install. Maybe I’ll do a full review of them at some point.

      I wish these had the style & build of my Lux thermostat, which looks and works well, with the addition of the WiFi interface, which is really neat.

  2. I wonder if the thermostats your way are compatible with those here — they should be, at least while now I have some Italian-brand (which I didn’t even know before getting them in, they are specialised in heater-related hardware, rather than more general electrical stuff that I’m most aware of), what I had beforehand, for over twenty years, was a Honeywell.

    I have been complaining with my mother about our current stupid (and wasteful!) thermostat setup for as long as we have had it. And honestly a munin plugin for the thermostats would be just too nerd not to have ;)

    I’m just honestly scared of custom duties of getting two of those my side of the pond.

  3. Pingback: Siri meets wifi thermostat | Eric's Blog

  4. That looks pretty cool, it’s nice to see something that is so hackable from the start. I need to replace the thermostat in my house to get some better control of the heating so I was looking into getting one. Unfortunately after contacting them I discovered they don’t currently have a European licensed WiFi module – so I shall have to wait or find something else for the UK market. So far I haven’t been very impressed with the options.

    • It is pretty cool, though I wish it were just a little more polished. A combination of my Lux TX9000TS touch screen thermostat’s aesthetic & build plus a wifi interface would make a really slick product. The actual thermostat on the wall is no great shakes, but that’s pretty much made up for by the handy network interface. I should do an actual review some time I suppose.

      (Hm maybe a display-less version for even cheaper would be cool, and just rely on the many connected devices everyone carries around by now…)

  5. I’d like to play around with this but I ran the script and saw no output. I replaced the hostname with my themostats name.

    • Hrm, does something as simple as:

      $ curl http://thermostatname/tstat

      work for you? I have a local nameserver to translate the name to an IP address; maybe substituting IP address for the name will do the trick?

      • Ya that works

        curl 192.168.1.6/tstat
        {“temp”:69.50,”tmode”:1,”fmode”:0,”override”:1,”hold”:1,”t_heat”:70.00,”tstate”:0,”fstate”:0,”time”:{“day”:2,”hour”:22,”minute”:40},”t_type_post”:0}

        I tried with the ip instead of the name.. same thing it runs with no error and no output. It should print the Temp, Target and Mode to the console right?

  6. ok I changed ot to:

    my $host = “192.168.1.6”;
    my $tempurl = “http://$host/tstat”;

    and it worked! Thanks! this is fun!

    • Yeah I’d considered DIY but for $99 … I figured what the heck. ;)

      I need to do a full review of it at some point; it has its rough spots but in general I’m pretty happy with it.

  7. Got mine installed and I have been polling data once a day on mine. Tried your script in my router running linux but hit this error. Could be limited on my routers openwrt linux running perl.

    Can’t locate LWP/UserAgent.pm in @INC (@INC contains: /usr/lib/perl5/5.10 .) at ./tstatperl line 3.
    BEGIN failed–compilation aborted at ./tstatperl line 3.
    root@OpenWrt:/home/julian#

    Here is what I am collecting if its any interest to anyone. I pole this using a crontab daily to get an idea of how much my a/c is running day to day. Again, Im running this through my Tplink router.

    # My first script
    date >> accompare
    curl http://192.168.0.196/tstat/datalog > dataloginfo
    cut -d: -f 1,6,7,8,13,14,15 dataloginfo >> accompare

    my output looks like this

    {“today”:{“hour”:0,”minute”:30}},”yesterday”:{“hour”:5,”minute”:10}}}
    Wed May 9 15:16:19 CDT 2012
    {“today”:{“hour”:0,”minute”:12}},”yesterday”:{“hour”:1,”minute”:9}}}
    Wed May 9 16:01:29 CDT 2012
    {“today”:{“hour”:0,”minute”:25}},”yesterday”:{“hour”:1,”minute”:9}}}
    Thu May 10 15:38:13 CDT 2012
    {“today”:{“hour”:0,”minute”:17}},”yesterday”:{“hour”:2,”minute”:52}}}
    Thu May 10 15:42:08 CDT 2012
    {“today”:{“hour”:0,”minute”:17}},”yesterday”:{“hour”:2,”minute”:52}}}
    Thu May 10 21:42:45 CDT 2012

    As you can tell, we had a cold front blow in.

  8. Thanks for the info on pachube. One problem I am running against is that I am running this perl on OpenWrt which doesnt seem to have any precompiled modules ready like JSON. Might have to look at building a miniATX or something small that will support a bigger linux install.

  9. I bought that thermostat but returned it 2 months later. It was a complete piece of crud in my opinion.

    I wrote an application that polled the tstat every 30 seconds. I don’t know if it was because of this “high” level of polling, but the tstat seemed to reboot a couple of times per day. I would also receive often enough, the wrong time or temperature (time was reset, or temperature = -1).

    Also, I was polling the schedule every 30 seconds, to stay updated in case someone would manually change it. It seems that if you temporarily override the temperature set by the schedule and that you pull the schedule, the override gets canceled and you are back to program. That is ridiculous.

    Anyway, I was very unsatisfied with that thermostat. And unfortunately, it seems like it’s the only one with an open API (not “cloud”-based) out there. It’s as if the 5year-old me was told that santa was monster who eats children. All hopes died.

    I guess it’s time to start designing my own thermostat with a couple of relays and a rPi.

    • I poll mine, but not that often, and it hasn’t had any sort of rebooting troubles, for what it’s worth.

      Did you try filing a bug w/ RTCOA about these issues? I do wish that it were just a bit nicer device.

      • I did file a bug report but not much came out of it. I returned the unit. I have a honeywell now. I can’t use the API though, it’s not open.

  10. Have 5 CT-50s (At $99 – love them) which I poll every 5 minutes via ASUS RT-16 router running DD-WRT.
    Router sends data to hosted MySQL database resulting in the ability to manipulate and chart data. http://vchr.net/chart.php?mDate=2014-03-10

    Capture data via:
    echo “#!/bin/sh
    err=1
    while [ \$err -gt 0 ];
    do
    results=\$(wget -q -O – \”http://192.168.2.101/tstat/\”)
    if \`echo \${results} | grep \”\-1\” 1>/dev/null 2>&1\`; then
    let \”err += 1\”;
    if [ \$err -gt 3 ]; then
    err=-1;
    results=\”none\”;
    fi
    else
    err=0;
    fi
    done;
    if [ \${#results} -lt 1 ]; then
    results=\”none\”;
    fi

  11. Do you know if the model LS60i and LS90 have the same API interface? It looks like they might be the same thermostats but with a new model number and company name?

    I got a Honeywell Wifi thermostat and you can’t even talk to the thing directly. It only takes commands from Honeywell’s servers so I want to take it back and get something I can interface with myself (without having to reverse engineer).

    • I don’t know for sure, but they certainly look the same. I imagine Radio Thermostat just OEMs these things, and others brand them – the one I got was ostensibly from “3M Filtrete.”

  12. Looks like there’s no authentication on this thermostat….. If I buy one and use it on a shared network, am I risking having other people control it? Can I control whether the APIs are turned on?

  13. I have been using one of these (CT 100) as part of a energy monitoring and control system in my house for a few years and have been reasonably happy with it – I had a very early one, and replaced it with the current model last year to deal with some networking flakiness. I have had some, reasonably helpful, correspondence with their tech people about the API in the past. HOWEVER, when I contacted them recently to clarify an API problem I had encountered while doing some preliminary work towards extending my system. I got the response: “Currently we do not support the API, and have very limited information on it. We are just technical support here for the thermostats, and do not have access to changing API responses. The most recent document available about the API is the one that you have. {dated March, 2012}”. People planning to use the thermostat in their own systems must now be aware that they are on their own, and that there is no guarantee that the API of a new device corresponds to the old documentation.

    • That sounds about right. There used to be a fairly active user forum at forums.radiothermostat.com, but it looks like that has been removed, or died, or something, around early 2013.

  14. aand it looks like I figured it out. Turning off hold every 2 minutes.

    */2 * * * * curl 192.168.1.245/tstat/hold -A foo -d {\”hold\”:0}

    lets see if this stops that night time mouse!

    • I did the same thing as well as placing proper entries back to proper temp in cron rather then wait for the system update. Also wrote another script that alerts my smartwatch when the mouse comes to call.

  15. Hi, I’m looking at the RadioThermostat products mostly because I found this article which seems to satisfy my needs.
    I wanted to make sure the thermostat is accessible on the LAN even if the cloud is down (ISP problem) so I contacted the technical support: they say both the router (of course) and the cloud have to be on 24/7.

    Could you please confirm this?

    Thank you in advance,
    regards

    Davide

  16. I have been trying to use the “Curl” commands to set temperature, the command says success, but the temperature will not change. Am I missing something, I’m using the commands from the API, directly from a PC. I’m trying to write an Android program, I have downloaded one from the play store and that is able to change settings.
    Thanks,
    Rob

      • Curiously I’m having a similar issue:

        curl http://thermostat/tstat
        {“temp”:73.00,”tmode”:1,”fmode”:0,”override”:0,”hold”:0,”t_heat”:73.00,…}

        curl -d ‘{“tmode”:1,”t_heat”:70}’ http://thermostat/tstat
        {“success”: 0}

        curl http://thermostat/tstat
        {“temp”:73.00,”tmode”:1,”fmode”:0,”override”:0,”hold”:0,”t_heat”:73.00,…}

        No change in the thermostat settings despite the success response. The Radio Thermostat people don’t offer support, and I unfortunately have no idea what could be wrong.

        It would be awesome if anyone with a similar problem has helpful feedback.

        • FYI, for the benefit of anyone else experiencing this issue, I’ve identified the problem. I found a third party application that could control my thermostat, proving that it wasn’t a problem with the thermostat, but an issue with the commands I was sending. I performed a packet capture of a valid fan state change request, which looked (as expected) like this:

          {"fmode":2}

          Then I compared to my curl request (which was copied verbatim from the Radio Thermostat API documentation). Although I typed the JSON as above, the packet capture showed that this was the data actually sent:

          '{fmode:2}'

          Looks like curl was interpreting my data in way I wasn’t expecting, and for some reason the thermostat return message didn’t reflect any issue. In any case, here’s the curl request that works as expected:

          curl -d "{\"fmode\":0}" http://thermostat/tstat

          Similar to my original request, but the inside quotes are escaped.

          • Note that wordpress changes/mangles the quotes in the message above – if you cut and paste the command above it doesn’t work, you need to use standard double quotes.

          • Nice, thanks. And thanks for putting up a place where I could post this. Considering all the info you have here, I’m happy to contribute some value.

          • WOWWWW!! Thank you! I would have never figured this out. The command returns success but nothing would happen. You just saved me a lot of headache and probably money buddy.
            :D :D :D

  17. Have the 3M50. I use Domoticz to send the API requests, working fine.
    changing shedule or other setting does not update the my.radiothermostat.com portal.
    because of that also my Android app is never updated. Anybody else experiencing this problem ?

    • Hi Richard, could you share the 3M50 / Domoticz script and maybe Instructions how to install script. I have both to check.

  18. Hi guys, Just found this thread and wanted to ask if anyone else is using both the CT50 and the CT80 series of Radio Thermostat units in a serious way. If so, I would like to share experiences and discoveries concerning the WiFi operation differences between the two. There are some documented differences in the published Radio Thermostat API, but many more that must be discovered the hard way. We have just begun using the CT80 and are struggling a bit. Please contact ‘fred.toewe at temp-aura.com’.

  19. This works in C#:

    var httpWebRequest = (HttpWebRequest)WebRequest.Create(“http://192.168.2.120/tstat”);
    httpWebRequest.ContentType = “application/json”;
    httpWebRequest.Method = “POST”;

    using (var streamWriter = new StreamWriter(httpWebRequest.GetRequestStream()))
    {
    string json = “{\”fmode\”:2}”;

    streamWriter.Write(json);
    streamWriter.Flush();
    streamWriter.Close();
    }

    var httpResponse = (HttpWebResponse)httpWebRequest.GetResponse();
    using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
    {
    var result = streamReader.ReadToEnd();
    Console.WriteLine(result);
    Console.ReadKey();
    }

  20. I am looking for an api programmable thermostat that can talk to additional sensors etc that I can program the AC Units various features including the fan separate from the compressor system. I have gone as far as I can with a NEST thermostat and its time to program a real one right that can do the several ideas I have for the way smart thermostats work. I would like to start with recommendations of models as well as the thermostats to use. I could easily boost sales of the thermostat hardware in my state using my software.

Leave a Reply to Eric Sandeen Cancel reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.