General API Information:¶

Terminology:¶

pixel: A single RGB capable LED. The term is used independently of the actual protocol being used to communicate with the LED. A single LED in a Neopixel strip, and a single LED in a DotStar strip are considered to be a pixel under this definition.

strip: One or more pixels connected in series. The term is used independently of the protocol used. Both Neopixels and DotStars are considered strips

strip_id: A unique string that represents an initialized strip. Can be supplied by the user, or generated by default from pin names.

Request Body:¶

All POST requests should send a response body containing a valid JSON encoded string.

Response Body:¶

All requests will be responded to with a response body containing a valid JSON encoded string. The success field will have a boolean value indicating success of the operation. Other fields are included as needed by specific endpoints.

Valid Color Formats:¶

For all endpoints that take argument(s) representing colors there are two valid value formats:

str containing hex notation prepended with “0x” example: "0x00ff00"
list containing 3 or 4 ints 0-255 representing RGB color values. example: [255, 0, 255]

Authentication (Optional)¶

To enable token based authentication add a value HTTP_RGB_BEARER_AUTH inside of your settings.toml file. The value should be a token string. If this configuration is present then all HTTP endpoints will require this token to be passed in the Authentication header.

Example settings.toml config:

HTTP_RGB_BEARER_AUTH="cIgw2mX7Ditmxu2i8kD0EaeARLbsKnPmAwbxDc7gWDk"

Example Request Auth Header:

Authorization: Bearer cIgw2mX7Ditmxu2i8kD0EaeARLbsKnPmAwbxDc7gWDk

Un-authorized requests will be returned 401 Unauthorized responses.

HTTP API Endpoints:¶

Initialize Neopixels:¶

URL: /init/neopixels/

Method(s): POST

Details: Initialize a strip of Neopixels with 1 or more pixels on it.

Required Args:¶

pin:: str | The pin name that the strip is connected to as it appears on the board object.
pixel_count:: int | The number of LEDs in the strip.

Optional Args:¶

parameter id:: str | The ID to be used to refer to the initialized strip with requests in the future.
parameter kwargs:: dict | Dictionary of keyword arguments to pass along to the Neopixel class constructor. Commonly used kwargs include: brightness, bpp, auto_write. See Neopixel library for comprehensive list.

Return Object Fields:¶

success:

bool | Whether the strip was initialized successfully.

strip_id:

str | The strip_id that was assigned to the strip if it was successfully initialized. This will be the value of the id argument if it was passed, or a default strip_id generated from the pins used if id was not passed.

Example Request Data Body:

{
  "pin" : "NEOPIXEL",
  "pixel_count": 1,
  "kwargs":{
    "brightness": 0.01,
    "bpp": 3,
    "auto_write": true
  }
}

Example Successful Response(s):

{
  "success": true,
  "strip_id": "NEOPIXEL"
}

Example Error Response(s):

{
  "success": false,
  "error": "Invalid Pin: NOT_NEOPIXEL"
}

Initialize Dotstars:¶

URL: /init/dotstars/

Method(s): POST

Details: Initialize a strip of DotStars with 1 or more pixels on it.

Required Args:¶

data_pin:: str | The data pin name that the strip is connected to as it appears on the board object.
clock_pin:: str | The clock pin name that the strip is connected to as it appears on the board object.
pixel_count:: int | The number of LEDs in the strip.

Optional Args:¶

parameter id:: str | The ID to be used to refer to the initialized strip with requests in the future.
parameter kwargs:: dict | Dictionary of keyword arguments to pass along to the DotStar class constructor. Commonly used kwargs include: brightness, bpp, auto_write. See Neopixel library for comprehensive list.

Return Object Fields:¶

success:: bool | Whether the strip was initialized successfully.
strip_id:: str | The strip_id that was assigned to the strip if it was successfully initialized. This will be the value of the id argument if it was passed, or a default strip_id generated from the pins used if id was not passed.

Example Request Data Body:

{
  "clock_pin" : "D9",
  "data_pin" : "MOSI",
  "pixel_count": 30,
  "kwargs":{
    "brightness": 0.1,
    "auto_write": true
  }
}

Example Successful Response(s):

{
  "success": true,
  "strip_id": "D9MOSI"
}

Example Error Response(s):

{
  "success": false,
  "error": "Invalid Pin: MOSI"
}

GET or SET Pixels:¶

URL: /pixels/<strip_id>/

Method(s): GET, POST

Details: Get or set the color of pixels within a strip. If the pixels are being set and the strip is currently in animation mode, it will be switched back to pixels mode.

Path Arguments:¶

strip_id:: str | The strip_id that was assigned when the strip was initialized.

Required Args for POST:¶

pixels:: Union[dict, list] | A dictionary with pixel indexes as keys and colors as values. Or a list containing color values where index within the list will map to index within the strip.

Optional Args:¶

blank_pixels:: bool | Whether to clear the pixels to blank before setting the given new colors.

Return Object Fields:¶

success:: bool | Whether the operation was completed successfully.

Example Request Data Body:

{
  "blank_pixels": true,
  "pixels": {
    "12": "0xff0000",
    "13": "0x00ff00"
    "17": "0xff00ff"
  }
}

Example Successful Response(s):

{
  "success": true
}

Example Error Response(s):

{
  "success": false,
  "error": "Pixels must be list or dictionary"
}

Write:¶

URL: /write/<strip_id>/

Method(s): POST

Details: Call write() on the specified strip. Generally only needed if auto_write is False on: the strip. This will write any pending color change operations to the strip.

Path Arguments:¶

strip_id:: str | The strip_id that was assigned when the strip was initialized.

Return Object Fields:¶

success:: bool | Whether the operation was completed successfully.

Example Successful Response(s):

{
  "success": true
}

Example Error Response(s):

{
  "success": false,
  "error": "Strip D9 is not initialized"
}

Fill:¶

URL: /fill/<strip_id>/

Method(s): POST

Details: Fill the specified strip with the given color

Path Arguments:¶

strip_id:: str | The strip_id that was assigned when the strip was initialized.

Required Args for POST:¶

color:: str | The color to fill the strip with

Return Object Fields:¶

success:: bool | Whether the operation was completed successfully.

Example Request Data Body:

{
"color": "0x0000ff"
}

Example Successful Response(s):

{
  "success": true
}

Example Error Response(s):

{
  "success": false,
  "error": "Strip D9 is not initialized"
}

Get or Set Brightness:¶

URL: /brightness/<strip_id>/

Method(s): GET, POST

Details: Get or Set the brightness value for a strip.

Path Arguments:¶

strip_id:: str | The strip_id that was assigned when the strip was initialized.

Required Args for POST:¶

brightness:: float | The brightness level to set on the strip between 0.0 - 1.0

Return Object Fields:¶

success:: bool | Whether the operation was completed successfully.

Example POST Request Data Body:

{
"brightness": 0.1
}

Example Successful Response from GET:

{
  "success": true,
  "brightness": 0.1
}

Example Successful Response from POST:

{
  "success": true
}

Example Error Response(s):

{
  "success": false,
  "error": "Strip D9 is not initialized"
}

Get or Set Auto Write:¶

URL: /auto_write/<strip_id>/

Method(s): GET, POST

Details: Get or Set the auto_write value for a strip.

Path Arguments:¶

strip_id:: str | The strip_id that was assigned when the strip was initialized.

Required Args for POST:¶

auto_write:: bool | Whether auto_write is enabled

Return Object Fields:¶

success:: bool | Whether the operation was completed successfully.

Example POST Request Data Body:

{
"auto_write": true
}

Example Successful Response from GET:

{
  "success": true,
  "auto_write": false
}

Example Successful Response from POST:

{
  "success": true
}

Example Error Response(s):

{
  "success": false,
  "error": "Strip D9 is not initialized"
}

Initialize Animation:¶

URL: /init/animation/

Method(s): POST

Details: Initialize an animation on the specified strip. Animations are dynmically imported. Sending a request to this endpoint will result in the animation being imported.

Required Args:¶

strip_id:: str | The strip_id that was assigned when the strip was initialized.
animation_id:: str | The unique ID that will be used to refer to this animation in future requests.
animation:: str | The animation type to initialize. See ANIMATION_CLASSES.keys() for possible types.
kwargs:: dict | Dictionary of keyword arguments to pass along to the Animation class constructor. Different animations support different arguments. Some commonly used kwargs are color and speed. See the LED_Animation library documentation for more comprehensive information.

Return Object Fields:¶

success:

bool | Whether the animation was initialized successfully.

animation_id:

str | The animation_id that was assigned to the animation if it was successfully initialized.

Example Request Data Body:

{
  "strip_id" : "NEOPIXEL",
  "animation_id": "blink_builtin",
  "animation": "blink",
  "kwargs":{
    "speed": 0.25,
    "color" : "0x0000ff"
  }
}

Example Successful Response(s):

{
  "success": true,
  "animation_id": "blink_builtin"
}

Example Error Response(s):

{
  "success": false,
  "error": "Invalid animation: BlinkyDiscoParty"
}

Start Animation:¶

URL: /start/animation/<animation_id>/

Method(s): POST

Details: Start running an animation. If the strip was in pixels mode it will be changed to animation mode.

Path Args:¶

animation_id:: str | The animation_id of the already initialized animation to start.

Return Object Fields:¶

success:

bool | Whether the animation was started successfully.

Example Successful Response(s):

{
  "success": true
}

Example Error Response(s):

{
  "success": false,
  "error": "Animation builtin_comet is not initialized"
}

Set animation property:¶

URL: /animation/<animation_id>/setprop

Method(s): POST

Details: Set a property on the specified initialized animation. See LED_Animation docs for comprehensive info: about which properties are supported by which aniatmions and their effects.

Required Args:¶

name:: str | The name of the property to get or set.
value:: Any | The value to set to the property.

Return Object Fields:¶

success:

bool | Whether the animation property was set successfully.

Example Request Data Body:

{
"name": "speed",
"value": 0.1
}

Example Successful Response(s):

{
  "success": true
}

Example Error Response(s):

{
  "success": false,
  "error": "Invalid property highlight"
}