« 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

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:

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

For example:

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:

Most commands do not have an expected reply.

General Commands

These commands allow you to read and update device settings.

name

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

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

Example: persona>persona|pixo

serial

Read the device's serial number

Example: serial>serial|abcdef-123456

echo

Echo any sent string, used for testing

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.

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.

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_password

Update the password of the wireless network to connect to.

Pixo devices with wireless functionality only

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

wifi_enabled

Enable or disable WiFi functionality.

Pixo devices with wireless functionality only

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

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

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

static

Set the targeted pixels to display a single static colour

Example: static|B

clear

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

Example:

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.

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.

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.

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.

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.

Example: cycle|1000|R|W|B

fade

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

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.

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.

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.

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.

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.

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.

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.

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.

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

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.

Face

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

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:

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

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

Examples:

Colour Code Reference

W K RD OD YD GD CD BD MD R O Y G C B M RL OL YL GL CL BL ML RP OP YP GP CP BP MP

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:

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

Further Reading