HTTP API Changes - v1beta1 - 2015-09-07

  • Added PUT /lights/states/ and PUT /lights/[selector]/state documentation
  • Added POST /lights/[selector]/cycle API which cycles lights within a selector through the specified states. Rather than needing client-side logic to figure out what state to send next, the API handles it for you, so you only need to send the same request again to transition to the next state in the cycle. You can supply from 2 to 5 state entries. The endpoint takes the following:
    • states - required, array of 2 to 5 hashes:
      • power - optional, on or off
      • color - optional
      • brightness - optional, 0.01.0, overrides any brightness value from color (if any)
      • duration - optional, defaults to 1.0, 0.03155760000.0 (100 years)
    • defaults - optional hash, applied to each entry in states
      • power - optional, on or off
      • color - optional
      • brightness - optional, 0.01.0, overrides any brightness value from color (if any)
      • duration - optional, defaults to 1.0, 0.03155760000.0 (100 years)

We’re open to feedback to these changes, and will be holding off adding these to the documentation for a week as we gather feedback from the community. Please let us know if the API does not function as expected, or is failing to meet a particular use case.

You now have an endpoint for applying states to multiple selectors, and an endpoint for cycling a single selector through multiple states. Is there any reason not to combine them, and be able to apply cycles to several selectors in a single API call?

Also, with a few more parameters, it seems like the “cycle” endpoint could be made to subsume the “pulse” and “breathe” endpoints, too.

To be honest I don’t get what you are trying to achieve here with the cycle endpoint. I have tested it and nothing happens.
I suspect it should cycle the lights set by the selector through the different states so for example if I set my defaults to duration 3000, power on and brightness 1 then set my states to colors, blue, green, red. This should have the bulbs in the selector change from blue to green to red over 3 second intervals.
This is what threw me “so you only need to send the same request to cycle between up to 5 different…” did you mean you only need to send the one request to cycle or send the same request each time you want to change to the new state. I assume it is one request.

States and state works well for me but cycle nothing.

What’s your use case for applying cycles to several selectors? I’ve had plans for adding the ability to compose selectors, but want to find out the use cases so I can design it appropriately.

Would also like to hear a use case for having cycle also do pulse and breathe. It I designed cycle for hooking up single press hardware buttons a lot easier for clients to implement.

As per above, it’s designed for simplifying client side logic so you don’t have to calculate which state the light should be in.

Duration is in seconds, so 3000 would be 50 minutes, which means you probably wouldn’t see any transition happen. This is how it would work with your example:

  • Light is white
  • Send request
  • Light turns on, transitions to blue, maximum brightness over 3 seconds
  • Send exact same request
  • Light transitions to green over 3 seconds
  • Send same request
  • Light transitions to red over 3 seconds
  • Send same request
  • Light transitions to blue over 3 seconds
  • etc

I’ll update the first post to clarify.

I read through your post more carefully, and now I realize that “cycle” doesn’t do what I thought it did. So my comments are irrelevant, since I misunderstood what it was. I see now that “cycle” goes from one state to the next on command. When I first read it late last night, I wasn’t paying enough attention, and I thought it just cycled endlessly between the given states. That made it look sort of like a version of “pulse” or “breathe” which could transition through up to 5 states instead of 2.

I apologize for my confusion on the matter!

Doh sorry I am used to working in milliseconds not seconds.

The buttons example makes sense, without that it made no sense to me, set up to 5 colours and from one button each time you press you get the next colour, stop when you are happy no need to remember which state is next. What about a pause option, still 5 states but add a 6th where you specify a pause interval that cycles the bulb(s) through all states each x seconds automatically, so still on the button theme. the pause interval could have x seconds and maybe a range value if exists means between x and y seconds pause for a random period in that range and move to the next state. makes the lights one colour or changing constantly
e.g press 1, red, 2nd green, 3rd blue, 4th yellow, 5th purple, 6th cycle between them automatically. Of course one of these the state could be off so a simple stand alone light swtich with a micro processor just calling this one command.

What would your use case be for a feature like that? Is it just so you can run your own sequences without having to make multiple API calls?

I’m not opposed to it, but that would fall under the sequencing/scripting feature that’s further down the roadmap rather than the Cycle endpoint.

That’s alright, I could’ve explained it a bit clearer :smile:

Are you able to share any of the roadmap? I’d be curious to know what features are coming to the HTTP API, and it might influence the design of my library, since I’ll want to expose the features of the HTTP API to the users of my library.

We’re working on the v1 release at the moment, which is going to be mostly the same except for:

  • response format will be improved and be more consistent
  • all selectors will return an collection of lights or results rather than one for consistency
  • deprecated endpoints will be removed
1 Like

Sorry to take so long I have been busy. as per what I said it felt a natural progression, change between static states using one button but just like christmas lights one of the states can be an automatic cycling between those static states. If however you are already planning something along those lines then great but if you only have one button then you would still need to keep a count of how many times it has been pushed so you may as well keep a track of the state yourself anyway.

You don’t need to track how many times the button has been pressed with the Cycle API as the API figures out the next state for you, so the only thing you need to implement with a button is for it to hit API, and the API does the rest.

You’re describing a custom effect that runs continuously, right? That would require firmware changes to be done efficiently but the complexity of the effect would be limited somewhat if done completely on the bulb.

Yes I understand how your endpoint works. The idea is to use the max 5 states you have allowed for and then an effect that runs continuously which I was thinking would be the states in the endpoint.

All I was thinking was we added an extra time element that is the change period to the next state, so we say from state one we wait x period and change to the new state slowly. It sounds like it isn’t possible.

As it stands this new endpoint is great due to it’s simplicity.