##############
BetaBrite Sign
##############

We have an LED sign in the office!  Its protocol documentation is available either at
`<http://support.adaptivedisplays.com/Documentation/questions.php?questionid=149>`_
or a local mirror (not public since we lack redistribution rights!) is available in AFS
`<file:///afs/acm.jhu.edu/group/admins/scratch/Alpha%20Sign%20Communication%20Protocol%20(PN%2097088061).pdf>`_ .

Wiring
######

As shown on page 105 of the above, our sign uses a six-pin RJ connector.  It
should be cabled up as per the cable named 1088-9108 on page 103.

For the current, hackish, cabling harness, that means that the following
connections should be made.  Pin labels are as will be connected to a 

+-------------+-------+-------------------+
| white/orage | pin 5 |  Ground           | 
+-------------+-------+-------------------+
| blue        | pin 2 | Sign TX / Host RX |
+-------------+-------+-------------------+
| white/green | pin 3 | Sign RX / Host TX |
+-------------+-------+-------------------+

Basic Communication Examples
############################

First, you will want to set the baud rate and raw mode of the serial port.  The
sign supports both 7E2 and 8N1 serial streams, apparently, so pick your
favorite one of ::

  stty -F ${SERIAL_PORT_DEVICE} 9600 cs7 cstopb parenb -parodd clocal raw
  stty -F ${SERIAL_PORT_DEVICE} 9600 cs8 -cstopb -parenb clocal raw

You will probably want, as well, to set ::

  COMM_PREFIX="\0\0\0\0\0\001Z00\x02"
  COMM_SUFFIX="\x04"

which carries the synchronizing stream of nulls, the start of header character,
th esign type code (any sign), the broadcast address, and the start of text
character.

Set TEXT File
-------------

The sign is really quite amazing internally, but most of its time is spent
displaying one of 26 text messages, named 'A' to 'Z'.  To set a message, use the
"Write TEXT file" command (page 18, section 6.1.1), for example ::

  echo -ne ${COMM_PREFIX}'AQtesting 1 2 3'${COMM_SUFFIX} >${SERIAL_PORT_DEVICE}

will set text message 'Q' to be 'this is a test'.  Usually, our sign displays
message 'A', but that can be changed.

Use Special Commands
````````````````````

TEXT files can contain control characters (see appendix G) to do funny
things like display the date or time.  For example ::

  echo -ne ${COMM_PREFIX}'AQ\x0B9 \x19'${COMM_SUFFIX} >${SERIAL_PORT_DEVICE}

will set the TEXT file Q to display something like "FRI. 12:03 PM", which is
nicely informative.

Fonts (``0x1A``), character attributes (``0x1D``), spacings (``0x1E``),
speed (``0x15`` - ``0x19``), and color control (``0x1C``) are also available
using this mechanism.  This example specifies mode and mixes fonts and
colors:: 

  echo -ne ${COMM_PREFIX}'AA\x1B b\x1A1\x1C1\x0B9 \x1A7\x1C2\x13'${COMM_SUFFIX} >${SERIAL_PORT_DEVICE}

Use Modes
`````````

TEXT files can have "modes" set on them, which determines how they appear on
the display.  If no modes are specified, the so-called automode table is
used (see section 7.13.5).  Mode fields begin with an ESCape character
at the start of a text file ::

  echo -ne ${COMM_PREFIX}'AQ\x1b athis is a test'${COMM_SUFFIX} >${SERIAL_PORT_DEVICE}

will cause "this is a test" to scroll by.  See section 7.9.1 and 7.9.2 for
more on modes.

SMALL DOTS PICUTRE
------------------

Be sure that memory is configured correctly (see below).

One can then load in a SMALL DOTS PICTURE::

  echo -ne ${COMM_PREFIX}'I!050501010\x0D10101\x0D01010\x0D10101\x0D01010\x0D'${COMM_SUFFIX} >${SERIAL_PORT_DEVICE}

And call out to it::

  echo -ne ${COMM_PREFIX}'AA\x1B b\x14!'${COMM_SUFFIX} >${SERIAL_PORT_DEVICE}
  

Set Time of Day
---------------

Set the current time with ::

  echo -ne ${COMM_PREFIX}'E '`date +%H%M`${COMM_SUFFIX} >${SERIAL_PORT_DEVICE}

And day of week ::

  echo -ne ${COMM_PREFIX}'E&'$(((`date +%u` + 1) % 7))${COMM_SUFFIX} >${SERIAL_PORT_DEVICE}

And date ::

  echo -ne ${COMM_PREFIX}'E;'`date +%m%d%y`${COMM_SUFFIX} >${SERIAL_PORT_DEVICE}

Note that the sign is not a real-time clock (it will lose track of the date,
apparently) and is only capable of representing years 1994 through 2009.
``00`` corresponds to 2000, ``94`` to 1994, and ``09`` to 2009, but ``93``
to 2007, ``92`` to 2006, ``10`` to 1994 ... this seems to be a firmware
"feature" which renders the sign's understanding of the date pretty useless.

Reading Back
------------

A command like ``od -t x1 -w1 -v -a ${SERIAL_PORT_DEVICE}`` can be used to view
bytes as they come back from the sign.  This is useful for reading back messages
or configuration data.

To read back text file 'A', run (page 19)::

  echo -ne ${COMM_PREFIX}'BA'${COMM_SUFFIX} >${SERIAL_PORT_DEVICE}

You'll get back something like ::

  nul ... null soh 0 0 0 stx A A t e s t i n g sp 1 sp 2 sp 3 etx 0 4 7 B eot

which is seen to be a synchronization burst, an addres indicating response
(the first "0") from the broadcast address (the next two "0"s) containing a
message "AAtesting 1 2 3" with a trailing checksum (printed using upper-case
hex letters).

Other possibly interesting read-backs include (swap out ``BA`` above with the
contents of the parenthesis below):

* ``(F )`` (F space) -- the time of day

* ``(F")`` general information about the sign

* ``(F$)`` memory configuration

Memory Configuration
--------------------

The sign is authoritative for its own configuration, of course, but we have
set it up so that files ``A`` and ``Q`` are TEXT files of up to 0xFF bytes,
``!`` is a 5x5 8-color DOTS PICTURE, and the rest are unassigned.  We did so
by the following command::

  echo -ne ${COMM_PREFIX}'E$AAL00FFFF00QAL00FFFF00!DL05058000'${COMM_SUFFIX} >${SERIAL_PORT_DEVICE}