PlasmaTrim-combiner

Server/library to combine the display of information and animations on a set of plasmatrims.

Given a set (works with one) of connected plasmatrims forming a grid, you can:

• allocate a rectangular region of the grid to a widget (for instance, digit, or simple unary bar).
• set the widget displayed value
• set the animation used by the widget (fixed single color, or various patterns)

Building

make

This will produce ptrim-combiner.

Starting

ptrim-combiner -p <port>

This will start the server, listening on TCP and stdin for commands. Where available, you can use the rlwrap program to get basic history and command editing.

Typing 'help' will give you the list of available commands.

If you are running on a raspberry pi, or are experienced freeze (caused by lost USB messages), run with DISABLE_READ=1 in your environment.

Sample session

In the console where ptrim-combiner is started. Don't type //-starting line, those are comments explaining what is going on.

// get available device serial numbers
devices
BE0032BE BE0032BF // that's the server output 

// Setting color on one device
// Syntax is color <COLOR> <INTENSITY> <DEVICES>
// COLOR can be 3,6,24 or 48 hex values.
// intensity is in 0-255
// devices is a space-separated list of device serial or index
// set first device to white on all leds, max intensity
color FFF 255 BE0032BE
// set all leds to red on first device, with lower intensity
color FF0000 127 BE0032BE
// set per-led color on first device (48-byte color hex)
color FF00FFFF00FFFF00FFFF00FFFF0FF00FFFF00FF0FFFF00FF 127 1

// Creating widgets
// Display the list of available widgets.
wlist
// Create a simple bar widget "a" using the first 5 leds of the first device
wcreate a Unary 0 0 0 4
// Create an other bar widget "b" using the two next leds
wcreate b Unary 0 0 5 6
// Create an other bar widget, spawning the last led of the two plasmatrims
wcreate c Unary 0 1 7 7

// Setting widget value
// Set the value of widget a (from 0 to 5)
wset a 3

// Animation
// General syntax is:
//   wanim <widget> <animname> <frequency> <parameters>...
// widget is the target widget name
// animname is the name of the animation (use anims to list them
// frequency is animation speed in Hz. 0 means only run one step of the
//   animation
// parameters are animation-dependant
//
// Singleshot animation (freq = 0) to set color used by widget a to red
wanim a Color 0 1 F00
// Color will stay if you call set again
wset a 4
// Set widget b to blue
wanim b Color 0 1 00F
// Set a wave animation on widget 1 at 20Hz.
wanim a Wave 20
// set wave animation to 100Hz
wfreq a 100

Concepts

• Device: One plasmatrim device.
• Color: RGB color value for 1 or multiple leds. For one led, color can be 1, 3, or 6 hex-bytes long (like F, 80, F0F, FF00FF).
• Region: A rectangular group of led possibly spawming multiple devices.
• Widget: Associated to a region, knows how to display some data.
• Animation: led animation associated to a widget, not interfering with the widget data
• Layer: Widget data sets a per-led layer value (0=OFF, 1=ON). Then animation data fills all layers with color data.
• Singleshot: An animation that only sets the layer state once. Enabled when animation frequency is set to 0.

Command reference

Type "help\n" at the prompt. Each command ends with '\n'. Most commands do not cause any reply from the server. A server reply ends with '\n\n'.

Widget reference

Unary firstDev lastDev firstLed lastLed

Simple 'bar' widget that displays data in 'unary' base, ie the value is the number of leds in the on state. The arguments are the widget boundaries. So widget value is between 0 and (1 + lastDev-fistDev) * (1+ lastLed - firstLed).

Digit firstDev=0 firstLed=0 rotate=false swapx=false swapy=false

A single digit from 0 to 9 displayed using 5x5 leds. Use rotate, swapx, swapy to rotate and mirror the displayed digit depending on your plasmatrims orientation.

Animation reference

Color FREQ LAYER COLORS...

Use in singleshot mode only.

• LAYER: the layer number(s) to set (0=Off, 1=On)
• COLORS: a (space-separated) color list of any size. Will be applied to each led of the layer in order, wrapping the list over when needed Color can also be 'x,y:COLOR' to set only one led

Wave FREQ key=value

Relative animation (initial led value is important) with many parameters: min/max led value, per-step led change, and change transform. The following parameters can be set:

• model: Use given template(waveRGB, alternate, revRGB, revR, revG, revB)
• initDir: rDiff,gDiff,bDiff change to apply to each component at each step
• minV: r,g,b minimum value(hex no spaces). Apply dirchange algorithm when reached, per pixel
• maxV: r,g,b maximum value(hex no spaces). Apply dirchange algorithm when reached, per pixel.
• matrix: a0,...a10 3x3 matrix, applyed to current dir upon dirchange to get new dir
• dirChange: override matrix and use given function instead(alternate, alternate2)
• target: LAYER layer id as target for this animation

Examples (run wstop a to stop anim between tests):

// Default wave, 100Hz
wanim a Wave 100
// Run it faster (default initDir is 1,0,-1))
wanim a Wave 100 initDir=4,0,-4
// Use the alternate model
wanim a Wave 100 model=alternate
// Use the waveRGB, but with red in range 00-80 (instead of 00-FF
wanim a Wave 100 model=waveRGB maxV=80,FF,FF
// Basic wave, but dephase initial position to get a different result
wanim a Color 0 1 00F 0F0 F00
wanim a Wave 100
// Another wave, white, alternating intensity
wanim a Color 0 1 1 0
wanim a Wave 100 model=revRGB
// fade in-out red, then green, then blue
wanim a Wave 100 model=alternate
// blink between white and black every 1s
wanim a Color 0 1 0
wanim a Wave 1 initDir=FF,FF,FF matrix=-1,0,0,0,-1,0,0,0,-1
// while it runs, switch to "alternate leds" mode
wanim a Color 0 1 00 FF

Propagate key=value

Propagation animation, at each step values are kept unchanged but moved around.

Arguments:

• target: target layer
• dir: x,y direction of the pattern
• pos: x,y start coordinates of the pattern
• pattern: pattern to use (left,right,up,down,line,s)

Example:

wcreate a Unary 0 0 0 7
wset a 8
// Light one led up
wanim a Color 0 1 FFF 000 000 000 000 000 000 000
// Move it around one direction
wanim a Propagate 1 pattern=s
// ...and then an other
wanim a Propagate 1 pattern=s dir=-1,0 pos=1,1
// while it runs, change just one led and see it propagate
wanim a Color 0 1 0,0:00F

License and Credit

Licensed under the terms of the Gnu Public License version 3.

Reusing pieces from PlasmaTrim-CLI, https://github.com/cocide/PlasmaTrim-CLI, GPLv3.

Using PlasmaTrim-CLI's sligltly patched HID API from Signal 11: http:// www.signal11.us/oss/hidapi/