« Back to Guides

Pixo Device API #

Pixo LED controllers can be controlled by sending simple structured text commands to them. This guide details the available commands.

If you replace the default firmware, this API will be replaced as well!

Contents #

• Device Connections
• Device API
• General Commands
• Effect Commands
• Face Commands
• Command Colours
• Further Reading

Device Connections #

USB #

Device commands can be sent to Pixo devices over USB by opening a serial connection to the device. How to perform this is outside the scope of this document, however it is suggested that beginners use the Thonny editor.

UDP #

Sending messages to Pixo devices over UDP is not currently supported, but will be added in the future.

Device API #

Command Structure #

Commands are all structured in the same way:

1. the command string
2. an optional "target" separated from the command by @
3. a list of parameters, separated from the command and each other by |

Commands are specified in this guide like so:

• command with required target and required parameters: command@target|param1|param2
• command with optional target and optional parameters: command[@target][|param1][|param2]
• command with no target and one required parameter: command|param1[|param2]

Multiple commands may be sent at once by separating them with &.

For example:

• off@face&face@rest
• chase@outline|R|G|B|Y & static@star|Y & static@trunk|R

Command Responses #

Pixo devices can asynchronously "reply" to query commands, and can also emit "reply" messages unprompted if the device needs to log any alerts or status updates.

Response messages begin with >, then take the form of a normal command.

For example:

• Set the friendly name of a device:
  • Command: name|Office Shelves Backlight
  • Response: >name|Office Shelves Backlight
• Read the friendly name of a device:
  • Command: name
  • Response: >name|Office Shelves Backlight

Most commands do not have an expected reply.

General Commands #

These commands allow you to read and update device settings.

• name
• persona
• serial
• echo
• brightness
• brightness_raw
• wifi_ssid
• wifi_password
• wifi_enabled
• info

name #

Read the device's friendly name, or set it with the optional parameter. The friendly name is useful for identifying multiple connected devices.

• name[|name]
• >name|<string>

Example: name|Singing Tree 1 → >name|Singing Tree 1

persona #

Read the device's persona, or update the persona with the optional parameter.

If the persona is changed, the device will need to be rebooted for the update to be fully applied

• persona[|persona]
• >persona|<string>

Example: persona → >persona|pixo

serial #

Read the device's serial number

• serial
• >serial|<string>

Example: serial → >serial|abcdef-123456

echo #

Echo any sent string, used for testing

• echo[|string]
• >echo|<string>

brightness #

Set the global device brightness as a percentage. Parameter values between 0 and 100 inclusive are permitted. This percantage maps to a configured brightness range internally.

This command should be preferred in most cases, but for more control see brightness_raw.

• brightness|<percentage>
• >brightness|<percentage>

Example: brightness|37.5 → >brightness|37.5

brightness_raw #

Set the global brightness raw multiplier. The parameter value is a number between 0 and 1 inclusive. Values that are too low for the connected LEDs may not result in any light at all. Values that are too high may be unconfortably bright, or cause the LEDs to warm up slightly.

By default, the percentage range from 0 to 100 for the brightness command maps to the range 0.2 to 0.5 for the brightness_raw command.

The brightness command should be preferred in most cases.

• brightness_raw|<decimal>
• >brightness_raw|<decimal>

Example: brightness_raw|0.375 → >brightness_raw|0.375

wifi_ssid #

Update the WiFi SSID to connect to.

Pixo devices with wireless functionality only

• wifi_ssid|<ssid>
• >wifi_ssid|<ssid>

wifi_password #

Update the password of the wireless network to connect to.

Pixo devices with wireless functionality only

• wifi_password|<password>
• >wifi_password|<password length string of asterisks>

Example: wifi_password|christmastree → >wifi_password|*************

wifi_enabled #

Enable or disable WiFi functionality.

Pixo devices with wireless functionality only

• wifi_enabled|<true or false>
• >wifi_enabled|<true or false>

Example: wifi_enabled|false → >wifi_enabled|false

info #

Read all the common device settings and identity information at once. The Pixo Bridge sends this command after a device is connected to notify the Control App what was connected.

Note: the order of the response parameter values is not guaranteed

• info
• >info[|<parameters>] - the returned parameter values include zero or more of:
  • |n:<name> - the device name (see name command)
  • |p:<persona> - device persona (see persona command)
  • |sn:<serial>- serial number (see serial command)
  • |sw:<version> - software version identifier
  • |hw:<version> - hardware version identifier
  • |wifi_e:<true or false> - wifi enabled setting (see wifi_enabled command)
  • |wifi_s:<ssid> - wifi ssid (see wifi_ssid command)
  • |b:<brightness percent> - brightness as percentage (see brightness command)

Example: info → >info|n:Singing Tree|p:singing-tree|sn:pxtree-test-1234|b:45

Effect Commands #

These commands allow you to set, update, and clear lighting effects on parts or the entirety of a device.

Effect commands may optionally target a "submodel" of the device. If the commands to not include a target, then all the pixels in the device are affected, as if the command target were @all.

For example, the most common submodels to target in the Mini Tree are the following: star, lights, trunk.

Many effect commands take one or more "colours" as parameters. These may be codes representing preset colours or custom colours specified in the command. See: Command Colours

• off
• static
• clear
• breath
• burst
• chase
• chase_band
• cycle
• fade
• fill
• flicker
• pulse
• rainbow
• rainbow_cycle
• twinkle
• twinkle_fade
• wave
• wipe

off #

Set all targeted pixels to black. This is the same as sending the command static|K.

• off[@target]

static #

Set the targeted pixels to display a single static colour

• static|<colour>

Example: static|B

clear #

Remove any command effect from the target, if there is an effect.

• clear[@target]

Example:

• rainbow@all, then clear@all - set the Rainbow effect on all LEDs, then remove the Rainbow effect from all LEDs

breath #

Ramp up and down from black to a colour, and back to black. The specified list of colours is cycled through. Each colour is displayed for the specified time in milliseconds.

• breath|time_ms|...colour_list

Example: breath|1000|R|O|Y

burst #

Random bursts of colour are displayed at the specified rate in milliseconds. The bursts have the specified width in pixels, and decay over the specified time in milliseconds. The effect resembles simple fireworks.

• burst|rate_ms|decay_ms|width|...hsv_list

Example: burst|500|2000|width|W|R|Y

chase #

Display a repeating pattern of pixels which "moves along" by 1 pixel after the specified time in milliseconds.

• chase|time_ms|...hsv_list

Example: chase|250|R|W|B

chase_band #

Like chase, but with "bands" of colour rather than single pixels. Each band is the specified number of pixels wide.

• chase_band|time_ms|width|...hsv_list

Example: chase_band|500|5|G|R

cycle #

Cycle through a number of static colours, each colour is displayed for the specified time in milliseconds.

• cycle|time_ms|...hsv_list

Example: cycle|1000|R|W|B

fade #

Fade through the list of colours with the specified period in milliseconds.

• fade|time_ms|...hsv_list

Example: fade|2000|B|R

fill #

Fill the selected pixels with the foreground colour over the background colour over the specified time in milliseconds. This effect is like a one-off wipe.

• fill|time_ms|bg_colour|fg_colour

Example: fill|5000|K|R

flicker #

Each pixel displays a random colour in the range bounded by the two colour parameters. Each pixel changes after a random time within the specified time range. This effect can be used to look like flickering fire, candles, etc.

• flicker|mintime_ms|maxtime_ms|min_colour|max_colour

Example: flicker|100|1000|GD|GP

pulse #

A "pulse" moves along the pixels over the specified time in milliseconds over a black background. The specified colours is cycled through to colour the pulse.

• pulse|time_ms|width|...hsv_list

Example: pulse|1000|20|R|O|Y

rainbow #

Display rainbows with the specified length in pixels. Each pixel loops over the spectrum in the specified time in milliseconds.

• rainbow|time_ms|length

Example: rainbow|2000|20

rainbow_cycle #

A continuous rainbow is displayed on a loop of pixels. freq specifies the number of complete rainbows in the loop.

• rainbow_cycle|time_ms|freq

Example: rainbow_cycle|5000|1

twinkle #

A random selection of pixels is set to one of the foreground colours for the specified time in milliseconds. The number of randomly selected pixels is specified by the count parameter. If the count is 0, then 10% of the pixels will be selected. Those pixels not in the random selection are coloured with the background colour.

• twinkle|time_ms|count|bg_hsv|...hsv_list

Example: twinkle|500|0|G|Y|W

twinkle_fade #

Pixels are selected at random at the specified rate in milliseconds. Selected pixels are set to one of the specified colours, then fade to black over the fade duration specified in milliseconds.

• twinkle_fade|rate_ms|fade_ms|...hsv_list

Example: twinkle_fade|100|2000|B|C|M

wipe #

Fill the pixels with each colour sequentially over the specified duration in milliseconds. This effect is like like a repeating fill effect.

• wipe|time_ms|...hsv_list

Example: wipe|1000|R|W|B

Face Commands #

Some Pixo devices like the Mini Trees have a "face", which can be controlled to make the devices appear to sing along to music or other audio messages.

By default, the pixels in the face can only be controlled using face commands instead of the Effect commands above.

Certain devices or versions of firmware may include commands not listed here, but this set is common acroll all devices with faces.

Face commands use the @target part of the command message differently, as the pixels making up the face are implicitly defined.

All face commands use the colour white by default, though options to customise this will be added in the future.

• eyes
• mouth
• face

Eyes #

• eyes@open - set the eyes to "open"
• eyes@closed - set the eyes to "closed"
• eyes@blink - set the eyes to "closed" for a short time (around 100ms), then set to open
• eyes@off - turn all the eye pixels off

Mouth #

In addition to being simply "open" or "closed", the mouth can display one of a number of "phonemes". These can be used to control the mouth shape to make the device "sing along" to music.

See also the Extract Phonemes Bridge Websocket Command to easily generate a list of phonemes for common English words.

• mouth@off - turn the mouth off
• mouth@smile - an open smile, same as mouth@ai
• mouth@ai - set the mouth to the "AI" phoneme (same as mouth@smile)
• mouth@e - set the mouth to the "E" phoneme
• mouth@fv - set the mouth to the "FV" phoneme
• mouth@l - set the mouth to the "L" phoneme
• mouth@mbp - set the mouth to the "MBP" phoneme
• mouth@o - set the mouth to the "O" phoneme
• mouth@u - set the mouth to the "U" phoneme
• mouth@wq - set the mouth to the "WQ" phoneme
• mouth@etc - set the mouth to the "etc" phoneme
• mouth@rest - set the mouth to the "rest" phoneme - this is the default resting mouth shape

Face #

Face commands set both eyes and mouth in one simple command, though with a restricted set of options.

• face@off - eyes off, mouth off
• face@rest - eyes open, mouth rest
• face@smile - eyes open, mouth smile
• face@sleep - eyes closed, mouth rest

Command Colours #

Certain commands allow colours to be specified in their parameters. There are two ways of specifying a colour:

1. Colour Code
2. HSV Colour

Colour Codes #

Colour codes allow common colours to be easily specified with one or two character.

The core colours are as follows:

• W - white
• K - black
• R - red
• O - orange
• Y - yellow
• G - green
• C - cyan
• B - blue
• M - magenta

The core colour codes can be changed by appending one of the following modifier codes:

• D - dark - decreases the "value" of the colour as HSV
• L - light - increases the "saturation" of the colour as HSV
• P - pale - greatly increases the "saturation" of the colour as HSV

Note: K (black) and W (white) cannot be modified.

Examples:

• static@all|R - specify red as part of a static effect command
• flicker|100|1000|RD|YP - specify the colours "dark red" and "pale yellow" as the minimum and maximum colours in a flicker effect

Colour Code Reference #

HSV Colours #

HSV colours allow you to specify the Hue, Saturation, and Value of a colour to get colours not included in the colour Codes list.

HSV colours are specified in the form: (h,s,v), where:

• h - decimal between 0 and 1 inclusive - the hue "angle" (0 = red, 0.33 = green, 0.66 = blue, 1 = red)
• s - decimal between 0 and 1 inclusive - how saturated the colour is (0 = no colour, 1 = maximum colour)
• v - decimal between 0 and 1 inclusive - how light the colour is (0 = as dark as possible, 1 = as light as possible)

Example: static@all|(0.79,0.47,1) - a washed out purple as a parameter to the static effect command

• h = 0.79, ~284 degrees, between blue and red
• s = 0.47, about halfway between no colour and maximum colour
• v = 1, light

Further Reading #

• Websocket API Reference
• Mini Tree Hardware Overview