Using clean energy preferentially via WattTime

Tutorials & Examples Solutions
1

I recently came across a service called WattTime (https://www.watttime.org/); in short, they have built a technology that estimates the ‘cleanliness’ of the marginal power generation in your geographical area, and they provide an API that can be used to get this “relative realtime marginal emissions intensity”.
(their service seems to have some international references, but it seems to be pretty USA-and-Canada-centric based on what I have seen on their site. YMMV). Their free API option basically provides you an integer between 0 and 100, where 0 is “cleanest energy you could get” and 100 is “dirtiest energy you could get”. They do have paid API options where historical values, or ‘real, meaningful’ emissions values in lbs/MWh are available.

I came up with a simple method to get this value into my openHAB instance that others may find useful. Personally, I plan to display this value (or a color inferring this value) in my laundry room as an aid to help my family decide if we should run the washer or dryer at a given time, or perhaps wait till later. Likely this summer I will consider using it modify Ecobee thermostat setpoints.
(I am certain this method can be improved upon, but I threw it together quickly and it seems to work OK so far…)

The WattTime API itself is well-documented here:
https://www.watttime.org/api-documentation/
… but in the interest of providing a very high level overview, I’ll summarize the steps you’ll need to do to get this working below:

INITIAL SETUP

  • Register a username and password - I found this was pretty easily done with Postman. You need to self-register and specify your own username and password.
  • Login and obtain a token via HTTP GET request - also pretty easily done with Postman. This token is good for a limited amount of time.
  • Execute an HTTP request to identify your “balancing authority” based on your GPS coordinates – essentially, a ‘prefix’ representing your geographical area.

Once you have the token request working, and you know your ‘ba’ prefix, you should be ready to set up ongoing openHAB ‘stuff’ to extract your real-time emissions intensity.

ONGOING OPENHAB STUFF

  • Frequent login for token extraction - the ‘bearer token’ you get on any given HTTP login request expires after a while. I simply set up an HTTP Thing to execute the proper HTTP GET request with Basic Authentication on a frequent basis. My HTTP Thing looks like this:
UID: http:url:xxxxx
label: API - WattTime Bearer Token
thingTypeUID: http:url
configuration:
  authMode: BASIC
  ignoreSSLErrors: false
  baseURL: https://api2.watttime.org/v2/login
  password: yourPassHere
  delay: 0
  stateMethod: GET
  refresh: 300
  commandMethod: GET
  timeout: 3000
  username: yourUserHere
  bufferSize: 2048
channels:
  - id: token
    channelTypeUID: http:string
    label: token
    description: ""
    configuration: {}

A valid response looks like this:

{
    "token": "fyJhbGciOiJS... super long string here..."
}

… so it is pretty trivial to create a Channel and Item of type String and use JSONPATH transformation to parse out the token value and put it into that Item. (for continuity’s sake, the item name I used, seen below, is APIWattTimeBearerToken_token)

  • Periodic emissions index request
    We can set up a Rule to extract the emissions index of interest, using the ba prefix and the Bearer token. Here’s what my rule code looks like, I used Javascript/ECMA:
var logger = Java.type('org.slf4j.LoggerFactory').getLogger('org.openhab.rule.' + ctx.ruleUID);
strToken = itemRegistry.getItem("APIWattTimeBearerToken_token").getState().toString();
//logger.info(strToken)

var client = java.net.http.HttpClient.newBuilder().build();
var request = java.net.http.HttpRequest.newBuilder()
  .GET()
  // update the 'ba' prefix below based on your region
  .uri(java.net.URI.create( "https://api2.watttime.org/v2/index?ba=XXXXXX"))
  .header("Authorization", "Bearer " + strToken)
  .header("Content-Type", "application/json")
  .build();
  var response = client.send(request, java.net.http.HttpResponse.BodyHandlers.ofString());

  var obj = JSON.parse(response.body());

  var eScore = itemRegistry.getItem("XXXXXX_CleanEnergyScore");
  events.sendCommand(eScore, obj.percent);

I set up a cron schedule to run this rule every few minutes. The API limits you to no more than 10 calls/second, I believe, so you should not have any problem running into API request caps.

And you should now have a frequent update of how clean your marginal watt of power usage will be!

cleanEnergyScore
cleanEnergyScore1916×951 56.9 KB

I hope this helps some folks! Please let me know if anything needs clarification.

3 Likes