alphasign API

The alphasign package is a Python API for the Alpha Communications Protocol. This is the protocol used by many LED signs, including the popular Betabrite. This package provides a simple and powerful way to program those signs with Python.

Here is a simple example for controlling a Betabrite Prism via USB:

import time
import alphasign


def main():
  sign = alphasign.USB(alphasign.devices.USB_BETABRITE_PRISM)
  sign.connect()
  sign.clear_memory()

  # create logical objects to work with
  counter_str = alphasign.String(size=14, label="1")
  counter_txt = alphasign.Text("counter value: %s%s" % (alphasign.colors.RED,
                                                        counter_str.call()),
                               label="A",
                               mode=alphasign.modes.HOLD)

  # allocate memory for these objects on the sign
  sign.allocate((counter_str, counter_txt))

  # tell sign to only display the counter text
  sign.set_run_sequence((counter_txt,))

  # write objects
  for obj in (counter_str, counter_txt):
    sign.write(obj)

  # (strictly) monotonically increasing counter
  counter_value = 0
  while True:
    counter_str.data = counter_value
    sign.write(counter_str)
    counter_value += 1
    time.sleep(1)


if __name__ == "__main__":
  main()

The full API is documented with examples in the pages below:

Character sets

Character constants can be used to change the font style in TEXT (alphasign.text.Text) and STRING (alphasign.string.String) files.

Character sets

The following character set constants are defined:

  • FIVE_HIGH_STD
  • FIVE_STROKE
  • SEVEN_HIGH_STD
  • SEVEN_STROKE
  • SEVEN_HIGH_FANCY
  • TEN_HIGH_STD
  • SEVEN_SHADOW
  • FULL_HEIGHT_FANCY
  • FULL_HEIGHT_STD
  • SEVEN_SHADOW_FANCY
  • FIVE_WIDE
  • SEVEN_WIDE
  • SEVEN_FANCY_WIDE
  • WIDE_STROKE_FIVE

The following character sets are available only on Alpha 2.0 and 3.0 protocols:

  • FIVE_HIGH_CUST
  • SEVEN_HIGH_CUST
  • TEN_HIGH_CUST
  • FIFTEEN_HIGH_CUST

Character attributes

The following character attribute constants are defined:

  • WIDE_ON
  • WIDE_OFF
  • DOUBLE_WIDE_ON
  • DOUBLE_WIDE_OFF
  • DOUBLE_HIGH_ON
  • DOUBLE_HIGH_OFF
  • TRUE_DESCENDERS_ON
  • TRUE_DESCENDERS_OFF
  • FIXED_WIDTH_ON
  • FIXED_WIDTH_OFF
  • FANCY_ON
  • FANCY_OFF
  • AUXILIARY_PORT_ON – Series 4000 & 7000 signs only.
  • AUXILIARY_PORT_OFF
  • SHADOW_CHARACTERS_ON – Betabrite model 1036 and AlphaPriemere 9000 signs only.
  • SHADOW_CHARACTERS_OFF

Character spacing

The following character spacing constants are defined:

  • PROPORTIONAL – default
  • FIXED_WIDTH – fixed width left justified

Examples

Make a text file using the FIVE_WIDE charset:

msg = alphasign.Text("%sthis is wide" % alphasign.charsets.FIVE_WIDE,
                     label="A")

Colors

The following constants are defined to change TEXT (alphasign.text.Text) colors:

  • RED
  • GREEN
  • AMBER
  • DIM_RED
  • DIM_GREEN
  • BROWN
  • ORANGE
  • YELLOW
  • RAINBOW_1
  • RAINBOW_2
  • COLOR_MIX
  • AUTOCOLOR
alphasign.colors.rgb(rgb)

Create color constant for use in TEXT and STRING files.

Parameters:rgb – 6-character hex string in form RRGGBB.
alphasign.colors.shadow_rgb(rgb)

Create shadow color constant for use in TEXT and STRING files.

Parameters:rgb – 6-character hex string in form RRGGBB.

Examples

Make a text file with red text:

msg = alphasign.Text("%sthis text is red" % alphasign.colors.RED, label="A")

Make a text file with purple text (#CC66FF):

msg = alphasign.Text("%sthis text should be in purple" %
                     alphasign.colors.rgb("CC66FF"), label="A")

Make a bi-color text file (red primary with a green shadow):

msg = alphasign.Text("%s%sred and green" %
                     (alphasign.colors.rgb("FF0000"),
                      alphasign.colors.rgb("00FF00")), label="A")

Counters

Date access

class alphasign.date.Date

Class for setting and accessing the date.

call_date(format=0)

Call date for insertion into a TEXT file.

Parameters:format – integer from 0 to 9: 0 - MM/DD/YY; 1 - DD/MM/YY; 2 - MM-DD-YY; 3 - DD-MM-YY; 4 - MM.DD.YY; 5 - DD.MM.YY; 6 - MM DD YY; 7 - DD MM YY; 8 - MMM.DD, YYYY; 9 - Day of week
Returns:formatted string to use in a TEXT
Return type:string
set(year=None, month=None, day=None)

Sets the date in the memory of the sign. This must be done each day to keep the clock ‘up to date’, because the sign will not automatically advance the day.

If the date is not specified in the arguments, today’s date will be used.

Parameters:
  • year – (optional) two-digit year (98, 99, 00, ...)
  • month – (optional) integer month (1, 2, ..., 12)
  • day – (optional) integer day (1, ..., 31)
Return type:

alphasign.packet.Packet object
set_day(day=None)

Set the day of the week on the sign.

If the argument is omitted, today’s day will be used.

Parameters:day – (optional) integer between 1 (Sunday) and 7 (Saturday)
Return type:alphasign.packet.Packet object

Devices

Device constants are used during instantiation of interface classes (such as alphasign.interfaces.local.USB) to describe particular sign devices.

The following constants are defined in this module:

  • USB_BETABRITE_PRISM = (0x8765, 0x1234)

Examples

Connect to a BetaBrite Prism sign using USB:

sign = alphasign.USB(alphasign.devices.USB_BETABRITE_PRISM)
sign.connect()
...

Extended characters

Extended characters can be inserted into STRING or TEXT files.

The following extended character constants are defined:

  • UP_ARROW
  • DOWN_ARROW
  • LEFT_ARROW
  • RIGHT_ARROW
  • PACMAN
  • SAIL_BOAT
  • BALL
  • TELEPHONE
  • HEART
  • CAR
  • HANDICAP
  • RHINO
  • MUG
  • SATELLITE_DISH
  • COPYRIGHT_SYMBOL
  • MALE_SYMBOL
  • FEMALE_SYMBOL
  • BOTTLE
  • DISKETTE
  • PRINTER
  • MUSICAL_NOTE
  • INFINITY_SYMBOL

Display modes

This module defines available modes for use with TEXT files (alphasign.text.Text).

The following display modes are defined:

  • ROTATE
  • HOLD
  • ROLL_UP
  • ROLL_DOWN
  • ROLL_LEFT
  • ROLL_RIGHT
  • WIPE_UP
  • WIPE_DOWN
  • WIPE_LEFT
  • WIPE_RIGHT
  • SCROLL
  • AUTOMODE
  • ROLL_IN
  • ROLL_OUT
  • WIPE_IN
  • WIPE_OUT
  • COMPRESSED_ROTATE (works only on certain sign models)
  • EXPLODE (Alpha 3.0 protocol only)
  • CLOCK (Alpha 3.0 protocol only)

The following special modes are defined:

  • TWINKLE
  • SPARKLE
  • SNOW
  • INTERLOCK
  • SWITCH
  • SLIDE (only Betabrite 1036)
  • SPRAY
  • STARBURST
  • WELCOME
  • SLOT_MACHINE
  • NEWS_FLASH (only Betabrite 1036)
  • TRUMPET_ANIMATION (only Betabrite (1036)
  • CYCLE_COLORS (only AlphaEclipse 3600)

Special graphics are modes which display graphics before the message. The following special graphics are defined:

  • THANK_YOU
  • NO_SMOKING
  • DONT_DRINK_DRIVE
  • RUNNING_ANIMAL
  • FISH_ANIMATION
  • FIREWORKS
  • TURBO_CAR
  • BALLOON_ANIMATION
  • CHERRY_BOMB

Examples

Make a text file stationary on the sign:

msg = alphasign.Text("hello world", label="A", mode=alphasign.modes.HOLD)

To change the mode for an already created text file, do:

msg.mode = alphasign.modes.ROLL_IN

Packet

class alphasign.packet.Packet(contents)

Container for data to be sent to a sign device.

Packet objects are created by other classes and should not usually be instantiated directly.

Display positions

This module defines positions for use in TEXT files.

The following position constants are defined:

  • MIDDLE_LINE
  • TOP_LINE
  • BOTTOM_LINE
  • FILL
  • LEFT
  • RIGHT

LEFT and RIGHT only work on Alpha 3.0 protocol signs.

Conditions and exceptions for these positions are described in Section 7.10 of the Alpha Sign Communications Protocol document.

Speeds

The following constants are defined to change speeds in TEXT (alphasign.text.Text) files:

  • SPEED_1 (slowest)
  • SPEED_2
  • SPEED_3
  • SPEED_4
  • SPEED_5 (fastest)

Examples

Make a text file with fast text:

msg = alphasign.Text("%sthis text is fast" % alphasign.speeds.SPEED_5,
                     label="A",
                     mode=alphasign.modes.ROTATE)

STRING files

class alphasign.string.String(data=None, label=None, size=None)

Class representing a STRING file.

Variables:
  • data – string contained within object
  • label – label of string object
Parameters:
  • data – initial string to insert into object
  • label – file label (default: “1”)
  • size – maximum size of string data in bytes (default: 32)
call()

Call a STRING.

This is for inserting a STRING file into a TEXT file.

Returns:control code and specified string label
Return type:string

TEXT files

class alphasign.text.Text(data=None, label=None, size=None, position=None, mode=None, priority=False)

Class representing a TEXT file.

This class is aliased as alphasign.Text in alphasign.__init__.

Parameters:
  • data – initial string to insert into object
  • label – file label (default: “A”)
  • size – amount of bytes to allocate for object on sign (default: 64)
  • position – constant from alphasign.positions
  • mode – constant from alphasign.modes
  • priority – set this text to be displayed instead of all other TEXT files. Set to True with an empty message to clear a priority TEXT.

Time access

class alphasign.time.Time

Class for setting and accessing the time.

call()

Call time for insertion into a TEXT file.

Returns:formatted string to use in a TEXT
Return type:string
set(hour=None, minute=None)

Sets the hour and minute of the internal clock on the sign.

If the time is not specified in the arguments, the time now will be used.

Parameters:
  • hour – hour in 24-hour format (18 instead of 6 for 6PM)
  • minute – minute (0 - 59)
Return type:

alphasign.packet.Packet object
set_format(format=1)

Sets the time format on the sign.

Parameters:format – 1 - 24-hour (military) time; 0 - 12-hour (standard AM/PM) format
Return type:alphasign.packet.Packet object

Interfaces

class alphasign.interfaces.base.BaseInterface

Base interface from which all other interfaces inherit.

This class contains utility methods for fundamental sign features.

allocate(files)

Allocate a set of files on the device.

Parameters:files – list of file objects (alphasign.text.Text, alphasign.string.String, ...)
Return type:None
beep(frequency=0, duration=0.1, repeat=0)

Make the sign beep.

Parameters:
  • frequency – frequency integer (not in Hz), 0 - 254
  • duration – beep duration, 0.1 - 1.5
  • repeat – number of times to repeat, 0 - 15
Return type:

None
clear_memory()

Clear the sign’s memory.

Return type:None
set_run_sequence(files, locked=False)

Set the run sequence on the device.

This determines the order in which the files are displayed on the device, if at all. This is useful when handling multiple TEXT files.

Parameters:
Return type:

None
soft_reset()

Perform a soft reset on the sign.

This is non-destructive and does not clear the sign’s memory.

Return type:None
class alphasign.interfaces.local.DebugInterface

Dummy interface used only for debugging.

This does nothing except print the contents of written packets.

connect()
disconnect()
write(packet)
class alphasign.interfaces.local.Serial(device='/dev/ttyS0')

Connect to a sign through a local serial device.

This class uses pySerial.

Parameters:device (string) – character device (default: /dev/ttyS0)
connect()

Establish connection to the device.

disconnect()

Disconnect from the device.

write(packet)

Write packet to the serial interface.

Parameters:packet (alphasign.packet.Packet) – packet to write
class alphasign.interfaces.local.USB(usb_id)

Connect to a sign using USB.

This class uses PyUSB.

Parameters:usb_id – tuple of (vendor id, product id) identifying the USB device
connect(reset=True)
Parameters:reset – send a USB RESET command to the sign. This seems to cause problems in VMware.
Raises:usb.USBError – on USB-related errors
disconnect()
write(packet)

Indices and tables