Web API for hvac built on AWS

The HVAC API is used as a virtual representation of the physical HVAC devices. It serves as a bridge between the physical hvac controller and other devices, software, and APIs. The API has methods and resources for adding new hvac devices, getting the state of an hvac device, updating the state, and others.

State

So how does the API represent a controller for heating and air conditioning? It uses json formatted state objects sent in HTTP requests. The state includes the following parameters:

• heater (T/F):  A boolean indicating whether the heater is on or off.
• ac (T/F): A boolean indicating whether the ac is on or off.
• fan (T/F): A boolean indicating whether the fan is on or off.
• area (String): A string indicating the area in the home that the hvac controller is responsible for. Ex) “Upstairs”
• update_period (Number): How often (in seconds) the physical device should query the api to update its state.
• off_time (Number): How long the ac has been off.
• min_off_time (Number): Prevents the ac from turning on/off too quickly.
• uuid (String): A unique ID representing the hvac controller.

API

You can test the api here: api.zachbrogan.com/hvac

/hvac

GET: Returns an array of the state of all hvac controllers in json format
Response body:

[
 {
 "ac": false,
 "fan": true,
 "area": "new",
 "heater": true,
 "update_period": 10,
 "uuid": "2f3f04053b824a5491b4aa09975277f9",
 "min_off_time": 0,
 "off_time": 6190
 },
 {
 "ac": false,
 "fan": false,
 "area": "string",
 "heater": false,
 "update_period": 30,
 "uuid": "e74b80748033408bacc9939bc4ab8069",
 "off_time": 0,
 "min_off_time": 10
 }
]

POST: Creates a new hvac controller and returns the new device state in json format
Request body:

{
 "area": "Upstairs"
}

Response body:

{
 "uuid": "b9ca242bf4c84ac7b3c9a1d5d406e9b5",
 "area": "Upstairs",
 "heater": false,
 "ac": false,
 "fan": false,
 "off_time": 0,
 "min_off_time": 10,
 "update_period": 30
}

/hvac/<id>

(replace <id> with the uuid of the hvac controller)

GET: Returns the state of a specific hvac controller

Response body:

{
 "ac": false,
 "fan": false,
 "area": "Upstairs",
 "heater": false,
 "update_period": 30,
 "uuid": "b9ca242bf4c84ac7b3c9a1d5d406e9b5",
 "off_time": 0,
 "min_off_time": 10
}

PUT: Updates the parameters of a specific hvac controller

Request body (at least one parameter):

{
 "ac": true,
 "fan": true,
 "area": "Downstairs",
 "heater": false,
 "update_period": 10,
 "off_time": 10,
 "min_off_time": 30
}

Response body:

{
 "message": "Hvac updated"
}

DELETE: Delete a specific hvac controller

Response body:

{
 "message": "Hvac deleted."
}

In addition to the methods listed above, I also included an OPTIONS method for each resource so CORS support can be enabled. This makes it possible for web apps on a different domain to utilize the API more fully.

Deployment

The API could be implemented on any server really, but I found the AWS serverless ecosystem to be convenient for deployment. The hvac api is created using Amazon API Gateway + Lambda + Dynamodb. To make deployment even easier, I used a software tool called handel.

The code for the API is located here: https://github.com/zbrogz/hvacAPI, which include 3 important files:

1. handel.yml: The handel file, which specifies which AWS resources to create and link together. This includes api gateway and dynamodb.
2. swagger.yml: The swagger file, which outlines the API structure for API gateway. It also references the lambda function that is called for each resource method.
3. state.py: The lambda function, implemented in python. It makes the connections between api calls and the dynamoDB hvac controller state database.

Deployment instructions are included in the readme on github for HVAC API.