dcreemer / flipdot

PIL-based driver and simulator for the Alfa-Zeta Flip-Dot display

Flipdot Simulator and Driver

This program implements a Pillow (Python Imaging Library friendly fork) driver and simulator for the Flip-Dot XY5 Display from AlphaZeta.

The Flip-Dot Display

The XY5 Display can be thought of as a bitmaped screen. It consists of mechanical flipping "dots," laid out in an XY grid. The display is made up of a number of individual panels, where each panel is 7x28 pixels. Each panel has a controller, and the controllers may be daisy-chained. Controllers connect to driver computers via RS-485. On a single daisy-chain, each panel gets a unique numeric address (0, 1, 2, etc..).

The protocol to control a panel is not well-documented. Essentially each column of 7 pixels (in a 7x28 board) is a controlled by a single byte, using the lower seven bits. The packet header includes panel address information, as well as other meta-data. The protocol is outlined more in the reference code from Alfa-Zeta.

Driver

For developing interesting visualizations, it's much nice to treat a collection of panels as an 1-bit-per-pixel arbitrary XY image. This software implements that abstraction using the Python Imaging Library. Image data is rendered into an image, and then periodically that image is converted to Flip-Dot display protocol and sent to the panels. To make development easier, this software also implements a curses-based simulator of the display that communicated via UDP. Develop on a local computer, then try it out on a real display.

Usage

Install the required libraries with pip:

$ make init

(this just does pip install -r requirements.txt).

In one terminal window, run the display simulator:

$ make sim

In another, run the demo application, specifying UDP as the communications mechanism:

$ make demo

Samples

$ python sim.py

 -----------------------------------------------------------
|                                                           |
|                                                           |
|                                                           |
|             * *     * *   * * *       * *                 |
|             * *     * * * *   * *     * *                 |
|               * * * *   * *   * *     * *                 |
|                 * *     * *   * *     * *                 |
|                 * *     * *   * *                         |
|               * * * *     * * *       * *                 |
|                                                           |
|                                                           |
|                                                           |
|                                                           |
|                                                           |
 -----------------------------------------------------------

Here is a sample video:

(click the image to play it). It shows this software running a live Flip-Dot display, cycling through headlines derived from Flipboard.

Develop

See the demo.py file for examples, but in general, anything that can be written to a Python Imaging Library 1-bit image can be sent to the display. The code should be fine on Python 2.7.X and Python 3.6.X.

License

BSD 3-Clause. Note that the included font "VeraBd.ttf" is from here and subject to its own license.

flipdot's Issues

animations need to take display size into account

Animations currently assume a 28-dot width. This should be read from the display rather than hard-coded.

Doesn't work for 28x14 panels

This library is great and I appreciate you sharing it. But I'm getting some errors, which I'm pretty sure boil down to the fact that the library presumes each panel is 28x7, or at least that the height is exactly 7.

Unfortunately this isn't the case for my display, which is comprised of 18 panels, each 28x14 pixels. (These are AlfaZeta panels -- the XY5 comes in multiple sizes.) My configuration is 3 rows and 6 columns, such that the entire display is 28x3 = 84 pixels wide and 14x6 = 84 pixels high.

I know that the display.Display object allows you to specify arbitrary configurations so long as the panels (and the overall display?) are rectangular. But it looks like other aspects of the code require each panel's height to be 7. For example:

• sim.DisplaySim.update warns you if h is not 7, and contains the comment "note that h should always be 7".
• display.Display.to_bytes similarly warns you if h isn't 7.
• In that same to_bytes() function, I'm getting a ValueError from result.append(b) because my "byte" is out of range. In fact the value it's trying to append is 8192.

From your Readme file, I gather the essence of the problem is contained in your description of the underlying control protocol: "Essentially each column of 7 pixels (in a 7x28 board) is a controlled by a single byte, using the lower seven bits." Obviously you can't represent a 14-bit column in a single byte. Presumably for the 28w x 14h panels the protocol uses two bytes for each column, ignoring the highest bit of each.

Anyway, I'm not expecting you to update the library right away to enable the use of 28x14 panels. But I'd be grateful if:

1. You can confirm I'm on the right track here, and not screwing something else up.
2. You can provide any guidance (general and specific) on how one might modify the library to support 28x14 panels. (I could probably get there eventually, but alas I am an intermediate coder at best.)
3. If you do want to go ahead and update the library to support 28x14 panels, that would be amazing.