Hanover FlipDot Display RS485 Driver

Node.js driver for the Hanover Flip-Dot Display. Designed to be used with USB-RS485 dongle.

For a usage demo, see the emulated web app controller I made for my display to show at a local art trail. Source link.

See my blog post and YouTube video for a technical run down: https://engineer.john-whittington.co.uk/2017/11/adventures-flippy-flip-dot-display/

Features

• Figlet ascii art based text renderer, including font selection, offset and inversion.
• Automatic scrolling text.
• Automatic queueing of data and frame management.
• Matrix based data input ([x][y]).

Installation & Usage

As a module:

npm install flipdot-display # see below sections on integration

As a CLI application:

npm install -g flipdot-display
flipdot --help # send text bin (args are optional)
flipdot-clock --help # send clock bin (args are optional)

Debug

DEBUG=* node examples/test.js

Important Notes

• The address of your display (defualt 0x05 - arbitary but matches mine) must be correct otherise the display will not display the data. Find the correct address through trial and error or by taking the back off and reading the potentiometer (RHS) position
• The number of columns and rows (default 56x7) must be correct for your display otherwise the message length will be incorrect - the Hanover display may not acknowledge or display the incorrect message length.

Methodology

The Hanover Flip-Dot display expects ascii chars representing the hexadecimal bytes; bytes being every 8 rows of dots. For example, an eight row column:

. = 1 => 0xF5 => ['F', '5'] => [0x46, 0x35]
| = 0
. = 1
| = 0
. = 1
. = 1
. = 1
. = 1

Along with a header (containing display resolution and address) and footer (containing CRC).

My module is designed around a 2d array (or matrix) of rows and columns. One can create this using FlipDot.matrix. The matrix is then converted to an array of column bytes using FlipDot.matrixToBytes. This byte array can then be buffered for the next send (or queued if multiple frames are desired) using FlipDot.load. Finally, the buffered data is encoded, packaged and sent using FlipDot.send.

This process is largely automated in FlipDot.writeText, FlipDot.writeFrames, FlipDot.writeParagraph and FlipDot.writeMatrix, with only a call to FlipDot.send required.

See the 'examples/' folder for code usage but broadly:

const FlipDot = require('flipdot-display');

const flippy = new FlipDot('/dev/ttyUSB0',5,7,56);

flippy.once('open', function() {
  flippy.writeText('Hello World');
  flippy.send();
});

Acknowledgements

• ks156 Python driver - Explained the bizare protocol expected by the Hanover display and saved a lot of work!
• @j_whittington - JBR Engineering - 2017
• 

JSDoc Class

FlipDot ⇐ EventEmitter.

FlipDot is a Hanover FlipDot display connected via USB RS485

Kind: global class
Extends: EventEmitter.
Emits: FlipDot#event:sent All data sent, FlipDot#event:free Queue'd data emptied

• FlipDot ⇐ EventEmitter.
  • new FlipDot(port, addr, rows, columns, callback)
  • .write(data)
  • .writeDrain(data)
  • .matrix(rows, col, fill) ⇒ matrix
  • .matrixToBytes(matrix) ⇒ array
  • .writeMatrix(matrix, load) ⇒ array
  • .writeFrames(frames, refresh)
  • .writeText(text, fontOpt, offset, invert, load) ⇒ array
  • .writeParagraph(paragraph, fontOpt, offset, invert, refresh)
  • .clear()
  • .fill(value)
  • .asciiToByte(chars) ⇒ int
  • .byteToAscii(byte) ⇒ array
  • .encode(matrix) ⇒ array
  • .decode(data) ⇒ array
  • .load(data, queue)
  • .send(data, callback)
  • .close(callback)

new FlipDot(port, addr, rows, columns, callback)

Param	Type	Description
port	string	Serial port of RS485.
addr	int	Address of FlipDot display, set with pot internal to display.
rows	int	Number of rows on display.
columns	int	Number of columns on display.
callback	function	Function to call when port is open.

flipDot.write(data)

Write data to the serial object.

Kind: instance method of FlipDot

Param	Type	Description
data	buffer	Binary data.

flipDot.writeDrain(data)

Write to serial object and wait to drain.

Kind: instance method of FlipDot

Param	Type	Description
data	buffer	Binary data.

flipDot.matrix(rows, col, fill) ⇒ matrix

Return matrix (2d array), default size of display (matrix[rows][columns])

Kind: instance method of FlipDot
Returns: matrix - 2d array [rows][col].

Param	Type	Description
rows	int	Number of rows (default size of display).
col	int	Number of columns (default size of display).
fill	int	Value to initialise array.

flipDot.matrixToBytes(matrix) ⇒ array

Convert matrix to array of bytes, bytes constructed from rows in each column.

Kind: instance method of FlipDot
Returns: array - Array of column bytes.

Param	Type	Description
matrix	matrix	2d array returned from this.matrix.

flipDot.writeMatrix(matrix, load) ⇒ array

Load matrix, ready to send on next call.

Kind: instance method of FlipDot
Returns: array - Array of column bytes.

Param	Type	Description
matrix	matrix	2d array returned from this.matrix.
load	bool	Whether to load the data or just return encoded.

flipDot.writeFrames(frames, refresh)

Queue data frames to display in order.

Kind: instance method of FlipDot

Param	Type	Description
frames	array	Array of display data in byte format.
refresh	int	Refresh rate of frames (ms).

flipDot.writeText(text, fontOpt, offset, invert, load) ⇒ array

Write text string to display in ascii art format, using figlet module.

Kind: instance method of FlipDot
Returns: array - Array of column bytes.

Param	Type	Description
text	string	Text to display.
fontOpt	object	figlet options { font: , horizontalLayout: , verticalLayout: }.
offset	array	Text offset cordinates [x,y].
invert	bool	Invert text.
load	bool	Whether to load for next send or just return encoded data.

flipDot.writeParagraph(paragraph, fontOpt, offset, invert, refresh)

Write lines of text to display in ascii art format, using figlet module. Same inputs as writeText but sends each line as a frame.

Kind: instance method of FlipDot

Param	Type	Description
paragraph	string	Lines of text to display; '\n' line break.
fontOpt	object	figlet options { font: , horizontalLayout: , verticalLayout: }.
offset	array	Text offset cordinates [x,y].
invert	bool	Invert text.
refresh	int	Period to display each frame.

flipDot.clear()

Clear display (write 0x00 and stop queue).

Kind: instance method of FlipDot

flipDot.fill(value)

Fill display with value.

Kind: instance method of FlipDot

Param	Type	Description
value	int	hex value to fill.

flipDot.asciiToByte(chars) ⇒ int

Convert Hanover two ascii charactor format hex value to byte.

Kind: instance method of FlipDot
Returns: int - Byte.

Param	Type	Description
chars	array	Chars representing hex value, eg: ['0','F'].

flipDot.byteToAscii(byte) ⇒ array

Convert byte to two ascii chars representing hex value.

Kind: instance method of FlipDot
Returns: array - Two ascii chars of hex value.

Param	Type	Description
byte	int	Byte to convert.

flipDot.encode(matrix) ⇒ array

Encode data for Hanover display; the display reads two ascii chars per byte, representing the visual hex representation of the byte - this means the data packet doubles in size.

Kind: instance method of FlipDot
Returns: array - Hanover encoded data (two ascii chars representing visual form of each byte).

Param	Type	Description
matrix	array	Array of column bytes.

Example

// returns ['0', '5']
FlipDot.encode(0x05);

flipDot.decode(data) ⇒ array

Decode Hanover display data (two ascii chars per byte) back to bytes.

Kind: instance method of FlipDot
Returns: array - Bytes (will be half size of passed).

Param	Type	Description
data	array	Hanover display data of ascii chars representing visual form of hex byte.

Example

// returns 0x0F
FlipDot.asciiToBye(['0', 'F']);

flipDot.load(data, queue)

Load or queue data for next call to send. Does the encoding of data.

Kind: instance method of FlipDot

Param	Type	Description
data	array	Array of column bytes.
queue	bool	Whether to queue or write data.

flipDot.send(data, callback)

Send data to display over RS485 and load next from queue if available. This should be called without parameters after a write or load function. Will start task to empty queue if queued data, which will pop frames at this.refresh period.

Kind: instance method of FlipDot

Param	Type	Description
data	data	Optional: data to send.
callback	function	Function to call once data is sent and drained.

Example

FlipDot.writeText('Hello World');
FlipDot.send();

flipDot.close(callback)

Close the serial port ready to clear object

Kind: instance method of FlipDot

Param	Type	Description
callback	function	to call when port closed