A connected home with Honeywell
Honeywell has been successfully providing best of breed solutions in a large variety of sectors for many years. It has notably addressed the consumer home sector and more recently, the connected home, by providing the market with connected and smart devices (thermostats, wireless doorbells, light timers, etc.) In order to encourage the implementations of smart home applications, Honeywell also started exposing the features of some of its devices through APIs and more specifically, its Total Connect Comfort thermostats (TCC), which we wrapped into a connector that you can use from within your scriptr.io scripts.
The Honeywell TCC API is not public. To gain access please contact Honeywell directly.
Overview of scriptr.io’s Honeywell TCC connector
Using the connector is very easy: all it takes it to obtain an access token for your end users, require a script and start sending instructions, as you will see it in the following.
Obtain an end user access token
First step is to obtain an OAuth access token from Honeywell for one of your end users who owns a thermostat that we’ll manipulate using the connector. This is simply done by invoking the “https://api.scriptrapps.io/honeywell/oauth2/grantAccess” script of the Honeywell connector, passing your scriptr.io authentication token and a username as parameters, as in the below example:
curl -X POST -F username=john.doe@mail.com -H 'Authorization: bearer YOUR_TOKEN' 'https://api.scriptrapps.io/honeywell/oauth2/grantAccess'
This redirects you to Honeywell’s login page. Enter your end user’s credentials using the login form and grant the required authorization to the connector.
Once done, Honeywell sends an access token that is automatically associated to your end user’s username and stored by the Honeywell connector in scriptr.io’s persistent storage.
Manipulate your thermostats
Now that you have an access token, you just need to require the “honeywell/user” module to start sending instructions to the user’s Honeywell devices. From this module, you create an instance of User, passing the end user’s username.
var userModule = require("honeywell/user");
var user = new userModule.User({username:"john.doe@mail.com"});
Get all devices at a given location
With the “user” instance obtained above, you can do many things, such as get information about a given location (e.g. “home” or “office”). A “location” is a place where the end user has installed one or more Honeywell devices. In the following, we assume that our user (john.doe@mail.com) has installed a thermostat in his office (the location name given by the user is “office”):
var location = user.getLocation({locationName:"office", allData:true});
The above returns an instance of Location that you can use to list all the Honeywell devices (or a specific device) it contains:
var devices = location.listDevices();
The invocation of “listDevices()” returns a list of Device instances.
Specify the cooling temperature
Let’s assume we need to manipulate the first device (a thermostat) by setting the cooling temperature to 72 Fahrenheit degrees. All we need to do is instruct the Device instance about it, by passing the required configuration:
var device = devices[0];
// configuration
var coolSetPoint = {
value: 72,
status: "Temporary",
nextTime: new Date().toISOString()
};
// instruct the thermostat to apply the given configuration
device.changeCoolingSetPoint(coolSetPoint);
Isn’t this simple? The connector offers you many more features, such as turning the fan on or off, setting the heat temperature, scheduling the thermostat or defining alerts.
Now that you know more about the Honeywell TCC connector, we’ll see how to leverage it to remotely control TCC devices using email.
Controlling your Honeywell TCC devices by email
Many IoT devices are not smart enough to take their own decisions and thus, simply process instructions that are sent to them by complex logic running on the cloud or more simply, by end users through mobile apps for instance. All of these options and their combinations are tackled by Scriptr.io using its powerful scripts. End users are however not limited to using graphical interfaces: they can also resort to voice or even to simpler text-based interfaces such as email for example.
In the coming paragraphs, we’ll explore how to send instructions to a thermostat using email. While this might not be the first thing you would think of, email has some advantages such as being non intrusive (it doesn’t require from you to install an application on your phone) and being message based, which doesn’t require a permanent connection and can scale easily.
Note1:The below code shows how to read instructions from a Gmail mailbox, using scriptr.io’s Gmail connector and to forward them to a Honeywell thermostat, using our Honeywell TCC connector.
Note2: We assume that emails that contain instructions should have the sentence “thermostat control” as subject. In addition, instructions should have the following format: -deviceId,feature,value-. Example: -35359,heat,69- (set heat temperature to 69 degrees); -35359,fan,auto- (set fan mode to “auto”).
Check for emails that contain instructions
First, we need to require the “user” module of our Gmail connector, then use it to create an instance of a Gmail user. In our specific case, the Gmail user is a thermostat for which we created a mailbox:
var gmailUserModule = require("google/user");
var gmailUser = new gmailUserModule.User({username: "office.thermostat@gmail.com"});
We then use the “gmailUser” object to obtain an instance of the Gmail class that wraps Gmail’s APIs:
var gmail = gmailUser.getMailManager({email : "office.thermostat@gmail.com"});
Next step is to ask our “gmail” object for the list of all unread emails that have “thermostat control” as subject. Note that this does not return the body of the corresponding messages:
var filter = gmail.createFilter();
filter.setQuery(filter.subject("thermostat control")).AND(filter.isUnread());
var instructions = gmail.listMessages(filter);
Let’s read the first message in the list and instruct Gmail to mark it as read:
var dto = {
id: instructions[0].id,
format: gmail.format.minimal,
markAsRead: true
};
var message = gmail.getMessage(dto);
Parse the emails’ body and send corresponding instructions to the thermostat
Let’s parse the body of the received email according to the convention defined earlier (-deviceId,feature,value-):
var start = instructions.indexOf("-") + 1;
var end = instructions.lastIndexOf("-");
var instructionExcerpt = instructions.substring(start, end);
var splitI = instructionExcerpt.split(",");
var instruction = {
id: splitI[0],
feature: splitI[1],
value: splitI[2]
};
Next, we create an instance of a device, as we have already done it in the “Overview of scriptr.io’s Honeywell TCC connector” paragraph:
var userModule = require("honeywell/user");
var user = new userModule.User({username:"john.doe@mail.com"});
var location = user.getLocation({locationName:"office", allData:true});
var device = location.getDevice({deviceId: instruction.id, allData:false}); // use the instruction object above to pass the device id
In order to determine what method to invoke on our “device” object, we need to check the feature that was sent in the message. To make it simpler, we’ll assume we’re only handling “heat” and “cool” instructions:
var setPoint = {
value: instruction.value,
status: "Temporary",
nextTime: new Date().toISOString()
};
switch (instruction.feature) {
case "heat": device.changeHeatingSetPoint(setPoint);break;
case "cool": device.changeCoolingSetPoint(setPoint);break;
}
That’s all we need to do. You can now communicate through emails with your Honeywell TCC devices 🙂
Other IoT App ideas;
- Connect to more than one smart home device and create more complex rules, door open & lights on = temp up/down depending on current temp
- Control several brand of thermostats, scriptr.io has connectors for NEST too and easy to add others
- Use the scriptr.io graphical blockly to create integrations and rules without code
