README
¶
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
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
demo
|
|
|
colorphase
Package colorphase defines the logic for the "colorphase" demo app.
|
Package colorphase defines the logic for the "colorphase" demo app. |
|
Package device provides basic device definition and management.
|
Package device provides basic device definition and management. |
|
Package discovery implements UDP multicast discovery functionality.
|
Package discovery implements UDP multicast discovery functionality. |
|
Package protocol contains PixelPusher wire definitions.
|
Package protocol contains PixelPusher wire definitions. |
|
pixelpusher
Package pixelpusher provides protocol constructs for the PixelPusher.
|
Package pixelpusher provides protocol constructs for the PixelPusher. |
|
streamfile
Package streamfile defines a file format to record and replay packet stream files.
|
Package streamfile defines a file format to record and replay packet stream files. |
|
support
|
|
|
byteslicereader
Package byteslicereader offers R a slice-backed Reader that offers zero-copy options.
|
Package byteslicereader offers R a slice-backed Reader that offers zero-copy options. |
|
fmtutil
Package fmtutil contains formatting helpers.
|
Package fmtutil contains formatting helpers. |
|
network
Package network contains generic network constants and utilities.
|
Package network contains generic network constants and utilities. |