correl.github.io/_posts/2018-03-13-hue-wake-up.html

---
title: "How Does The Phillips Hue Wake-Up Feature Work?"
author: "Correl Roush"
---
<p>
I recently got myself a set of Phillips Hue White and Color Ambiance
lights. One of the features I was looking forward to in particular
(besides playing with all the color options) was setting a wake-up
alarm with the lights gradually brightening. This was pretty painless
to get set up using the phone app. I'm pretty happy with the result,
but there's certainly some things I wouldn't mind tweaking. For
example, the initial brightness of the bulbs (at the lowest setting)
still seems a bit bright, so I might want to delay the bedside lamps
and let the more distant lamp start fading in first. I also want to
see if I can fiddle it into transitioning between some colors to get
more of a sunrise effect (perhaps "rising" from the other side of the
room, with the light spreading towards the head of the bed).
</p>

<p>
Figuring out how the wake-up settings that the app installed on my
bridge seemed a good first step towards introducing my own
customizations.
</p>

<p>
Information on getting access to a Hue bridge to make REST API calls
to it can be found in the <a href="https://www.developers.meethue.com/documentation/getting-started">Hue API getting started guide</a>.
</p>

<div id="outline-container-orgcb557c8" class="outline-2">
<h2 id="orgcb557c8">My wake-up settings</h2>
<div class="outline-text-2" id="text-orgcb557c8">
<p>
My wake-up is scheduled for 7:00 to gradually brighten the lights with
a half-hour fade-in each weekday. I also toggled on the setting to
automatically turn the lights off at 9:00.
</p>

<div class="org-center">
<p>
<img src="/images/Screenshot_20180313-182434.png" alt="nil"/> <img src="/images/Screenshot_20180313-182438.png" alt="nil"/>
</p>
</div>
</div>
</div>

<div id="outline-container-orgb533fb6" class="outline-2">
<h2 id="orgb533fb6">Finding things on the bridge</h2>
<div class="outline-text-2" id="text-orgb533fb6">
<p>
The most natural starting point is to check the schedules. Right off
the bat, I find what I'm after:
</p>
</div>

<div id="outline-container-org0792257" class="outline-3">
<h3 id="org0792257">The schedule &#x2026;</h3>
<div class="outline-text-3" id="text-org0792257">
<div class="org-src-container">
<pre class="src src-http"><span style="color: #5fafd7;">GET</span> <span style="color: #ffd700;">http://bridge/api/${username}/schedules/1</span>
</pre>
</div>

<div class="org-src-container">
<pre class="src src-js">{
  <span style="color: #ff4ea3;">"name"</span>: <span style="color: #ff4ea3;">"Wake up"</span>,
  <span style="color: #ff4ea3;">"description"</span>: <span style="color: #ff4ea3;">"L_04_fidlv_start wake up"</span>,
  <span style="color: #ff4ea3;">"command"</span>: {
    <span style="color: #ff4ea3;">"address"</span>: <span style="color: #ff4ea3;">"/api/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/sensors/2/state"</span>,
    <span style="color: #ff4ea3;">"body"</span>: {
      <span style="color: #ff4ea3;">"flag"</span>: <span style="color: #5fafd7;">true</span>
    },
    <span style="color: #ff4ea3;">"method"</span>: <span style="color: #ff4ea3;">"PUT"</span>
  },
  <span style="color: #ff4ea3;">"localtime"</span>: <span style="color: #ff4ea3;">"W124/T06:30:00"</span>,
  <span style="color: #ff4ea3;">"time"</span>: <span style="color: #ff4ea3;">"W124/T10:30:00"</span>,
  <span style="color: #ff4ea3;">"created"</span>: <span style="color: #ff4ea3;">"2018-03-11T19:46:54"</span>,
  <span style="color: #ff4ea3;">"status"</span>: <span style="color: #ff4ea3;">"enabled"</span>,
  <span style="color: #ff4ea3;">"recycle"</span>: <span style="color: #5fafd7;">true</span>
}
</pre>
</div>

<p>
This is a recurring schedule item that runs every weekday at 6:30. We
can tell this by looking at the <code>localtime</code> field. From the
documentation on <a href="https://www.developers.meethue.com/documentation/datatypes-and-time-patterns#16_time_patterns">time patterns</a>, we can see that it's a recurring time
pattern specifying days of the week as a bitmask, and a time (6:30).
</p>

<table border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
<caption class="t-above"><span class="table-number">Table 1:</span> Unraveling the weekday portion</caption>

<colgroup>
<col  class="org-left" />
</colgroup>
<tbody>
<tr>
<td class="org-left"><code>0MTWTFSS</code></td>
</tr>

<tr>
<td class="org-left"><code>01111100</code> (124 in decimal)</td>
</tr>
</tbody>
</table>

<p>
Since this schedule is enabled, we can be assured that it will run,
and in doing so, will issue a <code>PUT</code> to a sensors endpoint, setting a
flag to true.
</p>
</div>
</div>

<div id="outline-container-orgc27ffad" class="outline-3">
<h3 id="orgc27ffad">&#x2026; triggers the sensor &#x2026;</h3>
<div class="outline-text-3" id="text-orgc27ffad">
<div class="org-src-container">
<pre class="src src-http"><span style="color: #5fafd7;">GET</span> <span style="color: #ffd700;">http://bridge/api/${username}/sensors/2</span>
</pre>
</div>

<div class="org-src-container">
<pre class="src src-js">{
  <span style="color: #ff4ea3;">"state"</span>: {
    <span style="color: #ff4ea3;">"flag"</span>: <span style="color: #5fafd7;">false</span>,
    <span style="color: #ff4ea3;">"lastupdated"</span>: <span style="color: #ff4ea3;">"2018-03-13T13:00:00"</span>
  },
  <span style="color: #ff4ea3;">"config"</span>: {
    <span style="color: #ff4ea3;">"on"</span>: <span style="color: #5fafd7;">true</span>,
    <span style="color: #ff4ea3;">"reachable"</span>: <span style="color: #5fafd7;">true</span>
  },
  <span style="color: #ff4ea3;">"name"</span>: <span style="color: #ff4ea3;">"Sensor for wakeup"</span>,
  <span style="color: #ff4ea3;">"type"</span>: <span style="color: #ff4ea3;">"CLIPGenericFlag"</span>,
  <span style="color: #ff4ea3;">"modelid"</span>: <span style="color: #ff4ea3;">"WAKEUP"</span>,
  <span style="color: #ff4ea3;">"manufacturername"</span>: <span style="color: #ff4ea3;">"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"</span>,
  <span style="color: #ff4ea3;">"swversion"</span>: <span style="color: #ff4ea3;">"A_1801260942"</span>,
  <span style="color: #ff4ea3;">"uniqueid"</span>: <span style="color: #ff4ea3;">"L_04_fidlv"</span>,
  <span style="color: #ff4ea3;">"recycle"</span>: <span style="color: #5fafd7;">true</span>
}
</pre>
</div>

<p>
The sensor is what's <i>really</i> setting things in motion. Here we've got
a <a href="https://www.developers.meethue.com/documentation/supported-sensors#clipSensors">generic CLIP flag sensor</a> that is triggered exclusively by our
schedule. Essentially, by updating the flag state, we trigger the
sensor.
</p>
</div>
</div>

<div id="outline-container-org44bbaad" class="outline-3">
<h3 id="org44bbaad">&#x2026; triggers a rule &#x2026;</h3>
<div class="outline-text-3" id="text-org44bbaad">
<div class="org-src-container">
<pre class="src src-http"><span style="color: #5fafd7;">GET</span> <span style="color: #ffd700;">http://bridge/api/${username}/rules/1</span>
</pre>
</div>

<div class="org-src-container">
<pre class="src src-js">{
  <span style="color: #ff4ea3;">"name"</span>: <span style="color: #ff4ea3;">"L_04_fidlv_Start"</span>,
  <span style="color: #ff4ea3;">"owner"</span>: <span style="color: #ff4ea3;">"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"</span>,
  <span style="color: #ff4ea3;">"created"</span>: <span style="color: #ff4ea3;">"2018-03-11T19:46:51"</span>,
  <span style="color: #ff4ea3;">"lasttriggered"</span>: <span style="color: #ff4ea3;">"2018-03-13T10:30:00"</span>,
  <span style="color: #ff4ea3;">"timestriggered"</span>: 2,
  <span style="color: #ff4ea3;">"status"</span>: <span style="color: #ff4ea3;">"enabled"</span>,
  <span style="color: #ff4ea3;">"recycle"</span>: <span style="color: #5fafd7;">true</span>,
  <span style="color: #ff4ea3;">"conditions"</span>: [
    {
      <span style="color: #ff4ea3;">"address"</span>: <span style="color: #ff4ea3;">"/sensors/2/state/flag"</span>,
      <span style="color: #ff4ea3;">"operator"</span>: <span style="color: #ff4ea3;">"eq"</span>,
      <span style="color: #ff4ea3;">"value"</span>: <span style="color: #ff4ea3;">"true"</span>
    }
  ],
  <span style="color: #ff4ea3;">"actions"</span>: [
    {
      <span style="color: #ff4ea3;">"address"</span>: <span style="color: #ff4ea3;">"/groups/1/action"</span>,
      <span style="color: #ff4ea3;">"method"</span>: <span style="color: #ff4ea3;">"PUT"</span>,
      <span style="color: #ff4ea3;">"body"</span>: {
        <span style="color: #ff4ea3;">"scene"</span>: <span style="color: #ff4ea3;">"7GJer2-5ahGIqz6"</span>
      }
    },
    {
      <span style="color: #ff4ea3;">"address"</span>: <span style="color: #ff4ea3;">"/schedules/2"</span>,
      <span style="color: #ff4ea3;">"method"</span>: <span style="color: #ff4ea3;">"PUT"</span>,
      <span style="color: #ff4ea3;">"body"</span>: {
        <span style="color: #ff4ea3;">"status"</span>: <span style="color: #ff4ea3;">"enabled"</span>
      }
    }
  ]
}
</pre>
</div>

<p>
Now things are happening. Looking at the conditions, we can see that
this rule triggers when the wakeup sensor updates, and its flag is set
to <code>true</code>. When that happens, the bridge will iterate through its
rules, find that the above condition has been met, and iterate through
each of the actions.
</p>
</div>
</div>

<div id="outline-container-orgb90f963" class="outline-3">
<h3 id="orgb90f963">&#x2026; which sets the scene &#x2026;</h3>
<div class="outline-text-3" id="text-orgb90f963">
<p>
The bedroom group (<code>/groups/1</code> in the rule's action list) is set to
the following scene, which turns on the lights at minimum brightness:
</p>

<div class="org-src-container">
<pre class="src src-http"><span style="color: #5fafd7;">GET</span> <span style="color: #ffd700;">http://bridge/api/${username}/scenes/7GJer2-5ahGIqz6</span>
</pre>
</div>

<div class="org-src-container">
<pre class="src src-js">{
  <span style="color: #ff4ea3;">"name"</span>: <span style="color: #ff4ea3;">"Wake Up init"</span>,
  <span style="color: #ff4ea3;">"lights"</span>: [
    <span style="color: #ff4ea3;">"2"</span>,
    <span style="color: #ff4ea3;">"3"</span>,
    <span style="color: #ff4ea3;">"5"</span>
  ],
  <span style="color: #ff4ea3;">"owner"</span>: <span style="color: #ff4ea3;">"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"</span>,
  <span style="color: #ff4ea3;">"recycle"</span>: <span style="color: #5fafd7;">true</span>,
  <span style="color: #ff4ea3;">"locked"</span>: <span style="color: #5fafd7;">true</span>,
  <span style="color: #ff4ea3;">"appdata"</span>: {},
  <span style="color: #ff4ea3;">"picture"</span>: <span style="color: #ff4ea3;">""</span>,
  <span style="color: #ff4ea3;">"lastupdated"</span>: <span style="color: #ff4ea3;">"2018-03-11T19:46:50"</span>,
  <span style="color: #ff4ea3;">"version"</span>: 2,
  <span style="color: #ff4ea3;">"lightstates"</span>: {
    <span style="color: #ff4ea3;">"2"</span>: {
      <span style="color: #ff4ea3;">"on"</span>: <span style="color: #5fafd7;">true</span>,
      <span style="color: #ff4ea3;">"bri"</span>: 1,
      <span style="color: #ff4ea3;">"ct"</span>: 447
    },
    <span style="color: #ff4ea3;">"3"</span>: {
      <span style="color: #ff4ea3;">"on"</span>: <span style="color: #5fafd7;">true</span>,
      <span style="color: #ff4ea3;">"bri"</span>: 1,
      <span style="color: #ff4ea3;">"ct"</span>: 447
    },
    <span style="color: #ff4ea3;">"5"</span>: {
      <span style="color: #ff4ea3;">"on"</span>: <span style="color: #5fafd7;">true</span>,
      <span style="color: #ff4ea3;">"bri"</span>: 1,
      <span style="color: #ff4ea3;">"ct"</span>: 447
    }
  }
}
</pre>
</div>
</div>
</div>

<div id="outline-container-org5ae0873" class="outline-3">
<h3 id="org5ae0873">&#x2026; and schedules the transition &#x2026;</h3>
<div class="outline-text-3" id="text-org5ae0873">
<p>
Another schedule (<code>/schedules/2</code> in the rule's action list) is enabled
by the rule.
</p>

<div class="org-src-container">
<pre class="src src-http"><span style="color: #5fafd7;">GET</span> <span style="color: #ffd700;">http://bridge/api/${username}/schedules/2</span>
</pre>
</div>

<div class="org-src-container">
<pre class="src src-js">{
  <span style="color: #ff4ea3;">"name"</span>: <span style="color: #ff4ea3;">"L_04_fidlv"</span>,
  <span style="color: #ff4ea3;">"description"</span>: <span style="color: #ff4ea3;">"L_04_fidlv_trigger end scene"</span>,
  <span style="color: #ff4ea3;">"command"</span>: {
    <span style="color: #ff4ea3;">"address"</span>: <span style="color: #ff4ea3;">"/api/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/groups/0/action"</span>,
    <span style="color: #ff4ea3;">"body"</span>: {
      <span style="color: #ff4ea3;">"scene"</span>: <span style="color: #ff4ea3;">"gXdkB1um68N1sZL"</span>
    },
    <span style="color: #ff4ea3;">"method"</span>: <span style="color: #ff4ea3;">"PUT"</span>
  },
  <span style="color: #ff4ea3;">"localtime"</span>: <span style="color: #ff4ea3;">"PT00:01:00"</span>,
  <span style="color: #ff4ea3;">"time"</span>: <span style="color: #ff4ea3;">"PT00:01:00"</span>,
  <span style="color: #ff4ea3;">"created"</span>: <span style="color: #ff4ea3;">"2018-03-11T19:46:51"</span>,
  <span style="color: #ff4ea3;">"status"</span>: <span style="color: #ff4ea3;">"disabled"</span>,
  <span style="color: #ff4ea3;">"autodelete"</span>: <span style="color: #5fafd7;">false</span>,
  <span style="color: #ff4ea3;">"starttime"</span>: <span style="color: #ff4ea3;">"2018-03-13T10:30:00"</span>,
  <span style="color: #ff4ea3;">"recycle"</span>: <span style="color: #5fafd7;">true</span>
}
</pre>
</div>

<p>
<i>This</i> schedule is a bit different from the one we saw before. It is
normally disabled, and it's time pattern (in <code>localtime</code>) is
different. The <code>PT</code> prefix specifies that this is a timer which
expires after the given amount of time has passed. In this case, it is
set to one minute (the first 60 seconds of our wake-up will be spent
in minimal lighting). Enabling this schedule starts up the timer. When
one minute is up, another scene will be set.
</p>

<p>
This one, strangely, is applied to group <code>0</code>, the meta-group including
all lights, but since the scene itself specifies to which lights it
applies, there's no real problem with it.
</p>
</div>
</div>

<div id="outline-container-org2ead4a1" class="outline-3">
<h3 id="org2ead4a1">&#x2026; to a fully lit room &#x2026;</h3>
<div class="outline-text-3" id="text-org2ead4a1">
<div class="org-src-container">
<pre class="src src-http"><span style="color: #5fafd7;">GET</span> <span style="color: #ffd700;">http://bridge/api/${username}/scenes/gXdkB1um68N1sZL</span>
</pre>
</div>

<div class="org-src-container">
<pre class="src src-js">{
  <span style="color: #ff4ea3;">"name"</span>: <span style="color: #ff4ea3;">"Wake Up end"</span>,
  <span style="color: #ff4ea3;">"lights"</span>: [
    <span style="color: #ff4ea3;">"2"</span>,
    <span style="color: #ff4ea3;">"3"</span>,
    <span style="color: #ff4ea3;">"5"</span>
  ],
  <span style="color: #ff4ea3;">"owner"</span>: <span style="color: #ff4ea3;">"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"</span>,
  <span style="color: #ff4ea3;">"recycle"</span>: <span style="color: #5fafd7;">true</span>,
  <span style="color: #ff4ea3;">"locked"</span>: <span style="color: #5fafd7;">true</span>,
  <span style="color: #ff4ea3;">"appdata"</span>: {},
  <span style="color: #ff4ea3;">"picture"</span>: <span style="color: #ff4ea3;">""</span>,
  <span style="color: #ff4ea3;">"lastupdated"</span>: <span style="color: #ff4ea3;">"2018-03-11T19:46:51"</span>,
  <span style="color: #ff4ea3;">"version"</span>: 2,
  <span style="color: #ff4ea3;">"lightstates"</span>: {
    <span style="color: #ff4ea3;">"2"</span>: {
      <span style="color: #ff4ea3;">"on"</span>: <span style="color: #5fafd7;">true</span>,
      <span style="color: #ff4ea3;">"bri"</span>: 254,
      <span style="color: #ff4ea3;">"ct"</span>: 447,
      <span style="color: #ff4ea3;">"transitiontime"</span>: 17400
    },
    <span style="color: #ff4ea3;">"3"</span>: {
      <span style="color: #ff4ea3;">"on"</span>: <span style="color: #5fafd7;">true</span>,
      <span style="color: #ff4ea3;">"bri"</span>: 254,
      <span style="color: #ff4ea3;">"ct"</span>: 447,
      <span style="color: #ff4ea3;">"transitiontime"</span>: 17400
    },
    <span style="color: #ff4ea3;">"5"</span>: {
      <span style="color: #ff4ea3;">"on"</span>: <span style="color: #5fafd7;">true</span>,
      <span style="color: #ff4ea3;">"bri"</span>: 254,
      <span style="color: #ff4ea3;">"ct"</span>: 447,
      <span style="color: #ff4ea3;">"transitiontime"</span>: 17400
    }
  }
}
</pre>
</div>

<p>
This scene transitions the lights to full brightness over the next 29
minutes (1740 seconds), per the specified <code>transitiontime</code> (which is
specified in deciseconds).
</p>
</div>
</div>

<div id="outline-container-orgb5c1bbc" class="outline-3">
<h3 id="orgb5c1bbc">&#x2026; which will be switched off later.</h3>
<div class="outline-text-3" id="text-orgb5c1bbc">
<p>
Finally, an additional rule takes care of turning the lights off and
the wake-up sensor at 9:00 (Two and a half hours after the initial
triggering of the sensor).
</p>

<div class="org-src-container">
<pre class="src src-http"><span style="color: #5fafd7;">GET</span> <span style="color: #ffd700;">http://bridge/api/${username}/rules/2</span>
</pre>
</div>

<div class="org-src-container">
<pre class="src src-js">{
  <span style="color: #ff4ea3;">"name"</span>: <span style="color: #ff4ea3;">"Wake up 1.end"</span>,
  <span style="color: #ff4ea3;">"owner"</span>: <span style="color: #ff4ea3;">"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"</span>,
  <span style="color: #ff4ea3;">"created"</span>: <span style="color: #ff4ea3;">"2018-03-11T19:46:51"</span>,
  <span style="color: #ff4ea3;">"lasttriggered"</span>: <span style="color: #ff4ea3;">"2018-03-13T13:00:00"</span>,
  <span style="color: #ff4ea3;">"timestriggered"</span>: 2,
  <span style="color: #ff4ea3;">"status"</span>: <span style="color: #ff4ea3;">"enabled"</span>,
  <span style="color: #ff4ea3;">"recycle"</span>: <span style="color: #5fafd7;">true</span>,
  <span style="color: #ff4ea3;">"conditions"</span>: [
    {
      <span style="color: #ff4ea3;">"address"</span>: <span style="color: #ff4ea3;">"/sensors/2/state/flag"</span>,
      <span style="color: #ff4ea3;">"operator"</span>: <span style="color: #ff4ea3;">"eq"</span>,
      <span style="color: #ff4ea3;">"value"</span>: <span style="color: #ff4ea3;">"true"</span>
    },
    {
      <span style="color: #ff4ea3;">"address"</span>: <span style="color: #ff4ea3;">"/sensors/2/state/flag"</span>,
      <span style="color: #ff4ea3;">"operator"</span>: <span style="color: #ff4ea3;">"ddx"</span>,
      <span style="color: #ff4ea3;">"value"</span>: <span style="color: #ff4ea3;">"PT02:30:00"</span>
    }
  ],
  <span style="color: #ff4ea3;">"actions"</span>: [
    {
      <span style="color: #ff4ea3;">"address"</span>: <span style="color: #ff4ea3;">"/groups/2/action"</span>,
      <span style="color: #ff4ea3;">"method"</span>: <span style="color: #ff4ea3;">"PUT"</span>,
      <span style="color: #ff4ea3;">"body"</span>: {
        <span style="color: #ff4ea3;">"on"</span>: <span style="color: #5fafd7;">false</span>
      }
    },
    {
      <span style="color: #ff4ea3;">"address"</span>: <span style="color: #ff4ea3;">"/sensors/2/state"</span>,
      <span style="color: #ff4ea3;">"method"</span>: <span style="color: #ff4ea3;">"PUT"</span>,
      <span style="color: #ff4ea3;">"body"</span>: {
        <span style="color: #ff4ea3;">"flag"</span>: <span style="color: #5fafd7;">false</span>
      }
    }
  ]
}
</pre>
</div>

<p>
Unlike the first rule, this one doesn't trigger immediately. It has an
additional condition on the sensor state flag using the special <code>ddx</code>
operator, which (given the timer specified) is true <b>two and a half
hours after</b> the flag has been set. As the schedule sets it at 6:30,
that means that this rule will trigger at 9:00, turn the lights off in
the bedroom, and set the sensor's flag to <code>false</code>.
</p>
</div>
</div>
</div>

<div id="outline-container-org37adedd" class="outline-2">
<h2 id="org37adedd">Where to go from here</h2>
<div class="outline-text-2" id="text-org37adedd">
<p>
The wake-up config in the phone app touched on pretty much every major
aspect of the Hue bridge API. Given the insight I now have into how it
works, I can start constructing my own schedules and transitions, and
playing with different ways of triggering them and even having them
trigger each other.
</p>

<p>
If I get around to building my rolling sunrise, I'll be sure to get a
post up on it :)
</p>
</div>
</div>