v0.5 Deprecated -p and CTRL-characters. We now offer embedding within colons(:)

Added builtin icons and -l to list them.

README.md

@@ -6,8 +6,7 @@ Upload tool for an led name tag with USB-HID interface
 ## Warning
 
 There are many different versions of LED Badges on the market.
-Some even look identical, but are not.
+This one uses an USB-HID interface, while others use USB-Serial (see references below).
-This one uses an USB-HID interface, while many others use USB-Serial.
 
 The type supported by this project has an array of 44 x 11 LEDs and
 identifies itself on the USB as
@@ -24,41 +23,52 @@ Required dependencies on Debian/Ubuntu Systems:
 
 #### Examples:
 
+Sudo may or may not be needed for accessing the USB device, depending on your system.
+
     sudo python3 ./led-badge-11x44.py "Hello World!"
 
 loads the text 'Hello World!' as the first message, and scrolls it from right to left (default scroll mode=0) and speed 4 (default). After an upload the device shows the first message once and returns to the charging screen if still connected to USB. Either pull the plug or press the small button next to the USB connector.
 
-Sudo may or may not be needed, depending on your system.
+    sudo python3 ./led-badge-11x44.py -m 6 -s 8 "Hello" "World!"
 
-    sudo python3 ./led-badge-11x44.py -m 6 -s 8 Hello World!
+loads the text 'Hello' as message one and 'World!' as message two. Compare the difference in quoting to the previous example. Up to 8 messages can be uploaded. This example uses mode 6, which drops the words with a nice little animation vertically into the display area. Speed is set to maximum here, for smoothness.
 
-loads the text 'Hello' as message one and 'World!' as message two. Note the diffrence in quoting. Up to 8 messages can be uploaded. This example uses mode 6, which is dromps the words with a nice little animation vertically into the display area. Speed is set to maximum here, so that the animation is very smooth. Per default you will only see 'Hello'.
+Per default you will only see 'Hello'.  To see all messages, press the small button next to the USB connector multiple times, until you briefly see 'M1-8'. Now the display loops through all uploaded messages.
-To see all messages, press the small button next to the USB connector multiple times, until you briefly see 'M1-8'. Now the display loops through all uploaded messages.
 
-    sudo python3 ./led-badge-11x44.py -m 5 gfx/fablabnbg_logo_44x11.png
+    sudo python3 ./led-badge-11x44.py -m 5 :gfx/fablabnbg_logo_44x11.png:
 
-loads a fullscreen still image. (Or displays the pathname, if the image was not found. That is a hack. Sorry)
+loads a fullscreen still image. Avoid whitespace between colons and name.
 
-    sudo python3 ./led-badge-11x44.py -p gfx/heart.png -p gfx/fablab_logo_16x11.png  "I^Amy^Bfablab^B"
+    sudo python3 ./led-badge-11x44.py "I:HEART2:my:gfx/fablab_logo_16x11.png:fablab:1:"
 
-preloads two images, a heart and a crude fablab logo as images 1 and two. The images can then be embedded in a message by using control characters. To enter the ^A control character on the shell, press CTRL-V followed by CTRL-A.
+uses one builtin and one loaded image. The heart is builtin, and the fablab-logo is loaded from file. The fablab logo is used twice, once before the word 'fablab' and again behind through the reference ':1:' (which references the first loaded image).
 
 ![LED Mini Board](photos/love_my_fablab.jpg)
 
+    sudo python3 ./led-badge-11x44.py sudo ./led-badge-11x44.py -s7 -m0,1 :bicycle: :bicycle_r:
+
+shows a bicycle crossing the display in left-to-right and right-to-left (as a second message). If you select the 'M1-8' mode, the bike permanently runs back and forth the display. You may add a short message to one or both, to make it appear the bike is pulling the text around.
+
+    python3 ./led-badge-11x44.py --list-names
+
+prints the list of builtin icon names, including :happy: :happy2: :heart: :HEART: :heart2: :HEART2: :fablab: :bicycle: :bicycle_r: :owncloud: ::
+
     python3 ./led-badge-11x44.py --help
 
 prints some condensed help:
 
 <pre>
-Usage: led-badge-11x44.py [-h] [-s SPEED] [-m MODE] [-p FILE]
+Usage: led-badge-11x44.py [-h] [-s SPEED] [-m MODE] [-p FILE] [-l]
-                          MSG_OR_FILENAME [MSG_OR_FILENAME ...]
+                          MESSAGE [MESSAGE ...]
 
-Upload messages or graphics to a 44x11 led badge via USB HID. Version 0.4 from
+Upload messages or graphics to a 44x11 led badge via USB HID. Version 0.5 from
 https://github.com/jnweiger/led-badge-44x11 -- see there for more examples and
 for updates.
 
 positional arguments:
-  MSG_OR_FILENAME       Up to 8 message texts or image file names
+  MESSAGE               Up to 8 message texts with embedded builtin icons or
+                        loaded images within colons(:) -- See -l for a list of
+                        builtins
 
 optional arguments:
   -h, --help            show this help message and exit
@@ -70,17 +80,17 @@ optional arguments:
                         curtain(7); laser(8)
   -p FILE, --preload FILE
                         Load bitmap images. Use ^A, ^B, ^C, ... in text
-                        messages to make them visible
+                        messages to make them visible. Deprecated, embed
-
+                        within ':' instead
-Example combining image and text (enter the ^A character as CTRL-V CTRL-A):
+  -l, --list, --list-names, --listnames
-sudo ./led-badge-11x44.py -p gfx/heart.png I^Ayou
+                        list named icons to be embedded in messages and exit
-
 
+Example combining image and text: sudo ./led-badge-11x44.py "I:HEART2:you"
 </pre>
 
 
 
-## References (all USB-Serial)
+## Related References (for USB-Serial devices)
  * https://github.com/Caerbannog/led-mini-board
  * http://zunkworks.com/projects/programmablelednamebadges/
  * https://github.com/DirkReiners/LEDBadgeProgrammer

led-badge-11x44.py

@@ -16,12 +16,14 @@
 # v0.2, 2019-03-07, jw  support for loading bitmaps added.
 # v0.3              jw  option -p to preload graphics for inline use in text.
 # v0.4, 2019-03-08, jw  Warning about unused images added. Examples added to the README.
+# v0.5,             jw  Deprecated -p and CTRL-characters. We now use embedding within colons(:)
+#                       Added builtin icons and -l to list them.
 
 import sys, os, re, time, argparse
 from array import array
 import usb.core
 
-__version = "0.4"
+__version = "0.5"
 
 font_11x44 = (
   # 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'
@@ -156,7 +158,7 @@ bitmap_preloaded = [ ([],0) ]
 bitmaps_preloaded_unused = False
 
 bitmap_named = {
-  'happy':    (array('B', (0x00, 0x3c, 0x42, 0xa5, 0x81, 0xa5, 0x99, 0x42, 0x3c, 0x00, 0x00)), 1, '\x1d'),
+  'happy':    (array('B', (0x00, 0x00, 0x3c, 0x42, 0xa5, 0x81, 0xa5, 0x99, 0x42, 0x3c, 0x00)), 1, '\x1d'),
   'happy2':   (array('B', (0x00, 0x08, 0x14, 0x08, 0x01, 0x00, 0x00, 0x61, 0x30, 0x1c, 0x07,
                            0x00, 0x20, 0x50, 0x20, 0x00, 0x80, 0x80, 0x86, 0x0c, 0x38, 0xe0)), 2, '\x1c'),
   'heart':    (array('B', (0x00, 0x00, 0x6c, 0x92, 0x82, 0x82, 0x44, 0x28, 0x10, 0x00, 0x00)), 1, '\x1b'),
@@ -170,13 +172,16 @@ bitmap_named = {
   'bicycle':  (array('B', (0x01, 0x02, 0x00, 0x01, 0x07, 0x09, 0x12, 0x12, 0x10, 0x08, 0x07,
                            0x00, 0x87, 0x81, 0x5f, 0x22, 0x94, 0x49, 0x5f, 0x49, 0x80, 0x00,
                            0x00, 0x80, 0x00, 0x80, 0x70, 0xc8, 0x24, 0xe4, 0x04, 0x88, 0x70)), 3, '\x16'),
+  'bicycle_r':(array('B', (0x00, 0x00, 0x00, 0x00, 0x07, 0x09, 0x12, 0x13, 0x10, 0x08, 0x07,
+                           0x00, 0xf0, 0x40, 0xfd, 0x22, 0x94, 0x49, 0xfd, 0x49, 0x80, 0x00,
+                           0x40, 0xa0, 0x80, 0x40, 0x70, 0xc8, 0x24, 0x24, 0x04, 0x88, 0x70)), 3, '\x15'),
   'owncloud': (array('B', (0x00, 0x01, 0x02, 0x03, 0x06, 0x0c, 0x1a, 0x13, 0x11, 0x19, 0x0f,
                            0x78, 0xcc, 0x87, 0xfc, 0x42, 0x81, 0x81, 0x81, 0x81, 0x43, 0xbd,
-                           0x00, 0x00, 0x00, 0x80, 0x80, 0xe0, 0x30, 0x10, 0x28, 0x28, 0xd0)), 3, '\x15'),
+                           0x00, 0x00, 0x00, 0x80, 0x80, 0xe0, 0x30, 0x10, 0x28, 0x28, 0xd0)), 3, '\x14'),
 }
 bitmap_builtin = {}
 for i in bitmap_named:
-  bitmap_builtin[bitmap_named[i][0]] = bitmap_named[i]
+  bitmap_builtin[bitmap_named[i][2]] = bitmap_named[i]
 
 def bitmap_char(ch):
   """ Returns a tuple of 11 bytes,
@@ -185,7 +190,7 @@ def bitmap_char(ch):
   """
   if ord(ch) < 32:
     if ch in bitmap_builtin:
-      return bitmap_builtin[ch]
+      return bitmap_builtin[ch][:2]
 
     global bitmaps_preloaded_unused
     bitmaps_preloaded_unused = False
@@ -199,13 +204,17 @@ def bitmap_text(text):
   """ returns a tuple of (buffer, length_in_byte_columns_aka_chars)
       We preprocess the text string for substitution patterns
       "::" is replaced with a single ":"
+      ":1: is replaced with CTRL-A referencing the first preloaded or loaded image.
       ":happy:" is replaced with a reference to a builtin smiley glyph
       ":heart:" is replaced with a reference to a builtin heart glyph
       ":gfx/logo.png:" preloads the file gfx/logo.png and is replaced the corresponding control char.
   """
   def colonrepl(m):
     name = m.group(1)
-    if name == '': return ':'
+    if name == '':
+       return ':'
+    if name.isdecimal():
+      return chr(int(name))
     if '.' in name:
       bitmap_preloaded.append(bitmap_img(name))
       return chr(len(bitmap_preloaded)-1)
@@ -282,11 +291,12 @@ def header(lengths, speeds, modes):
   return h
 
 
-parser = argparse.ArgumentParser(description='Upload messages or graphics to a 44x11 led badge via USB HID. Version %s from https://github.com/jnweiger/led-badge-44x11 -- see there for more examples and for updates.' % __version, epilog="Example combining image and text (enter the ^A character as CTRL-V CTRL-A): sudo %s -p gfx/heart.png I^Ayou" % sys.argv[0])
+parser = argparse.ArgumentParser(description='Upload messages or graphics to a 44x11 led badge via USB HID. Version %s from https://github.com/jnweiger/led-badge-44x11 -- see there for more examples and for updates.' % __version, epilog='Example combining image and text: sudo %s "I:HEART2:you"' % sys.argv[0])
 parser.add_argument('-s', '--speed', default='4', help="Scroll speed. Up to 8 comma-seperated values (range 1..8)")
 parser.add_argument('-m', '--mode',  default='0', help="Up to 8 mode values: Scroll-left(0) -right(1) -up(2) -down(3); still-centered(4) -left(5); drop-down(6); curtain(7); laser(8)")
-parser.add_argument('-p', '--preload',  metavar='FILE', action='append', help="Load bitmap images. Use ^A, ^B, ^C, ... in text messages to make them visible")
+parser.add_argument('-p', '--preload',  metavar='FILE', action='append', help="Load bitmap images. Use ^A, ^B, ^C, ... in text messages to make them visible. Deprecated, embed within ':' instead")
-parser.add_argument('message', metavar='MSG_OR_FILENAME', nargs='+', help="Up to 8 message texts or image file names")
+parser.add_argument('-l', '--list-names', action='version', help="list named icons to be embedded in messages and exit", version=':'+':  :'.join(bitmap_named.keys())+':  ::  or e.g. :path/to/some_icon.png:')
+parser.add_argument('message', metavar='MESSAGE', nargs='+', help="Up to 8 message texts with embedded builtin icons or loaded images within colons(:) -- See -l for a list of builtins")
 args = parser.parse_args()
 
 dev = usb.core.find(idVendor=0x0416, idProduct=0x5020)