gopushpixels

gopushpixels is an MIT-licensed high-performance Go support library for PixelPusher hardware.

gopushpixels is not an official package. This package was initially built in order to help a friend with their light show display, and refined and made public to offer Go support for this awesome device.

This package is conscious of memory and CPU usage, and is designed to run on a Raspberry Pi. Many packet parsing options are zero-copy and/or support buffer reuse.

This powers PixelProxy, software which has been observed driving 15,000+ pixels at 40 FPS on a single Raspberry Pi without coming close to hitting any hardware constraints.

Capabilities

gopushpixels is a set of Go packages offering a fully-featured PixelPusher interface, which can:

• Passively discover devices and maintain a registry of active devices.
• Automatically generate stubs to interact with discovered devices.
• Generate, manipulate, and capture pixel buffers.
• Efficiently route pixel data to devices by group/controller or ID.
• Offers a man-in-the-middle proxy capability, which can:
  • Intercept, inspect, record, and modify PixelPusher data.
  • Advertise as fake PixelPusher devices, to interface with generation software.
• Collect operational metrics using Prometheus client integration.
• Support for several hardware devices, configurations, layouts, and software versions.
• Facilities to record and replay pixel data.
• A low-overhead file format to store pixel data:
  • Data can be associated with local or physical devices.
  • Smaller files can be merged together.
  • Optional compression support.
• Perform both generation and parsing of PixelPusher's protocol, allowing simulation of PixelPusher devices.

Packages

gopushpixels includes a set of core packages, which expose basic device interoperability and functionality. These packages attempt to minimize external dependencies:

• device, an abstraction of a PixelPusher device and constructs to manage, track, and interact with them.
• discovery, utility classes to interact with the device's discovery announcements.
• protocol, an expression of the PixelPusher's discovery, command, and data network protocols, and utilities to read and write to them.
• support, auxiliary capabilities used by the other packages.

Features

gopushpixels also includes some feature packages. These provide non-core functionality for devices that may be useful.

• proxy, a system to enable man-in-the-moddle operations on devices, creating local devices for each remote device which capture received data before forwarding it to the remote device.
• replay, which exposes the ability to record and replay packet streams, as well as a streamfile, a versatile packet file format designed to accommodate large amounts of pixel data efficiently.

Some higher-level libraries are instrumented with Prometheus metrics. This is a low-overhead instrumentation, and using Prometheus is entirely optional.

License

gopushpixels is licensed under an MIT license. For more information, see LICENSE.

History

gopushpixels is an open-source version of a rapidly-developed application called PixelProxy. PixelProxy is a full stack capable of:

• Masquerading proxy devices for observed physical PixelPusher devices.
• Recording observed pixels in a Google protobuf-based file format capable of compression and composing files by merging file fragments.
• HTTP-enabled control interface to manage files, record, playback, view latest-state snapshot visualizations, view device state, and view logs.
• HTML/JS/CSS embedding for single-binary deployment.
• Prometheus-instrumented structs and http/pprof helpers for effective introspection and profiling.

PixelProxy was used to enable LED replay by the team that built the Baltimore Light City Octopus sculpture.

Contributing

If you'd like to contribute a patch, please open an issue or submit a pull request.

Submitted code must pass pre-commit-go checks. These impose basic formatting and correctness checks. Prior to developing code, please install the pcg tool and Git hook:

go get -u github.com/maruel/pre-commit-go/cmd/... && pcg

Prior to submitting a pull request, please validate that it passes by executing the Git hook and/or explicitly running pcg in the root of the repository:

pcg

Resources

Most of this library was obtained by examining PixelPusher wire protocols and examining code from the following libraries:

• Java (canonical): https://github.com/robot-head/PixelPusher-java
• Python: https://github.com/cagerton/pixelpie
• Node: https://github.com/TheThingSystem/node-pixelpusher
• C++: https://github.com/q-depot/Cinder-PixelPusher
• PixelPusher Server: https://github.com/hzeller/pixelpusher-server

TODO

• It is a background task of mine to implement unit tests for important features in this package suite. gopushpixels uses the Ginkgo BDD-style testing framework, enabled by Gomega matchers.