Format of the light instructions

[jimbobbennett]

Commands are sent by IoT Central containing plain text to dictate the color.

The following formats will be supported:

One set of colors

Single hex string

A single 6 character string containing RGB values as 2 digit hex strings - first 2 characters for red, second 2 for green, third 2 for blue.

Example - light all lights in purple:

FF00FF

JSON with a single value

A JSON object with a single value, 'color' that contains a hex string (as above)

Example - light all lights in purple:

{
  "color" : "FF00FF"
}

This means light all lights in purple.

JSON with an array

A JSON object with at least a single value, 'colors' that contains an array of hex strings.

These will be applied in order to the available lights, so array item [0] will be applied to the light at index [0], array item [1] will be applied to the light at index [1], and so on.

If there are more values than lights, the values will be applied to the length of the lights and the rest will be ignored.

If there are more lights than values, the default behavior is to repeat the sequence until all lights are lit.

The JSON can also have an optional bool value 'repeat' that determines if the sequence should be repeated if there are less value than lights. true, the default means repeat the value, false means don't repeat.

Example 1 - Repeated sequence of red then green, lighting all lights:

{
  "colors" : [
      "FF0000",
      "00FF00"
    ]
}

Example 2 - Non-repeated sequence of red then green, only lighting the first 2 lights:

{
  "repeat" : false,
  "colors" : [
      "FF0000",
      "00FF00"
    ]
}

Multiple sets of colors

Multiple sets of colors can be used to dictate a sequence of colors to be applied over time, to give an animation to the lights. These can be defined as a series of color values and a single value for the 'frame rate', so how often the values should change, or as a series of color values against a time interval. There will also be a flag to say if the sequence should loop, which will default to true.

Regular frame rate

This is defined as a JSON document with a field for the frame rate, and an array of frames. Each frame is a JSON object as defined for a single set of colors, so can be a single value or an array of values, with the repeat rule followed. The frame rate is in seconds (can be a decimal) and defines how often the lights should change.

Every frame_rate milliseconds, the lights will move to the next color or colors in the sequence. Once the sequence has finished, if the loop flag is set to false the lights stop changing after the last frame, otherwise the frames are repeated. To turn the lights off when not looping, set the last frame to 000000.

Example 1 - change all the lights every second to red then green:

{
  "frame_rate" : 1,
  "colors" : [
    { "color" : "FF0000" },
    { "color" : "00FF00" }
  ]
}

Example 2 - change the lights every half a second to alternating colors, then turn the lights off:

{
  "frame_rate" : 0.5,
  "loop" : false,
  "colors" : [
    { "colors" : ["FF0000", "00FF00", "0000FF"] },
    { "colors" : ["0000FF", "FF0000", "00FF00"] },
  ]
}

Timed frames

For timed frames, the frame rate is not used, instead an extra field called frame_time is added to the colors to give a frame time. A timer will wait for the frame time in seconds (can be a decimal), then apply the next color.

Example 1 - hold red for 1 second, then green for half a second and blue for half a second:

{
  "colors" : [
    { "frame_time" : 1, "color" : "FF0000" },
    { "frame_time" : 0.5, "color" : "00FF00" }    
  ]
}