From 83fefd2404fb2ae81bded05030fb75269334113f Mon Sep 17 00:00:00 2001 From: Ben Sartori <149951068+bensartori@users.noreply.github.com> Date: Sat, 11 May 2024 14:10:16 +0200 Subject: [PATCH 1/4] Some documentation improvements --- README.md | 13 +++++++++++-- lednamebadge.py | 1 + photos/bitmap_data_descr.puml | 28 +++++++++++++++------------- 3 files changed, 27 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 38eaf7a..7f1acfc 100644 --- a/README.md +++ b/README.md @@ -66,6 +66,13 @@ To reuse the venv again at a later point: sudo dnf install hidapi python3-hidapi python3-pillow python3-pyusb +### Manual link the HID API lib for some Linuxes + +For some distributions there is a discrepancy between the where pyhidapi searches for the lib and where the package +hidapi places it. A simple solution is to link the libraray to the needed place, e.g. + + ln -s /usr/lib/libhidapi-hidraw.so.0 /usr/local/lib/ + ### Required dependencies on Mac Systems sudo easy_install pip @@ -146,7 +153,7 @@ prints the list of builtin icon names, including :happy: :happy2: :heart: :HEART prints some condensed help: 
-usage: led-badge-11x44.py [-h] [-t TYPE] [-s SPEED] [-B BRIGHTNESS] [-m MODE] [-b BLINK] [-a ANTS] [-l] MESSAGE [MESSAGE ...]
+usage: led-badge-11x44.py [-h] [-t TYPE] [-H HID] [-s SPEED] [-B BRIGHTNESS] [-m MODE] [-b BLINK] [-a ANTS] [-l] MESSAGE [MESSAGE ...]
 
 Upload messages or graphics to a 11x44 led badge via USB HID.
 Version 0.12 from https://github.com/jnweiger/led-name-badge-ls32
@@ -158,6 +165,7 @@ positional arguments:
 options:
   -h, --help            show this help message and exit
   -t TYPE, --type TYPE  Type of display: supported values are 12x48 or (default) 11x44. Rename the program to led-badge-12x48, to switch the default.
+  -H HID, --hid HID'    Set to 1 to ensure connect via HID API, program will then not fallback to usb.core library
   -s SPEED, --speed SPEED
                         Scroll speed (Range 1..8). Up to 8 comma-separated values
   -B BRIGHTNESS, --brightness BRIGHTNESS
@@ -175,9 +183,10 @@ Example combining image and text:
 
 There are some options defining the default type:
 - use lednamebadge.py directly: default type is 11x44
-- rename lednamebadge.py to something with '12' and use that: default type is 12x48
+- rename lednamebadge.py to something with '12' (e.g. badge12.py) and use that: default type is 12x48
 - use led-badge-11x44.py: default type is 11x44
 - use led-badge-12x48.py: default type is 12x48
+
 For all these options you can override the default type with -t
 
 ### Animations
diff --git a/lednamebadge.py b/lednamebadge.py
index f65c71e..81fd593 100755
--- a/lednamebadge.py
+++ b/lednamebadge.py
@@ -551,6 +551,7 @@ or
                 print("No led tag with vendorID 0x0416 and productID 0x5020 found.")
                 print("Connect the led tag and run this tool as root.")
                 sys.exit(1)
+
             for i in range(int(len(buf)/64)):
                 # sendbuf must contain "report ID" as first byte. "0" does the job here.
                 sendbuf=array('B',[0])
diff --git a/photos/bitmap_data_descr.puml b/photos/bitmap_data_descr.puml
index 7268993..ccd55c6 100644
--- a/photos/bitmap_data_descr.puml
+++ b/photos/bitmap_data_descr.puml
@@ -1,9 +1,11 @@
+' Using .. for three dots / ellipsis, els it would be a dotted line
+
 @startuml bitmap_data_onebyte
 salt
 title One byte
 {#
  { most significant bit 7
- leftmost pixel } | bit 6 | ... | bit 1 | { least significant bit 0
+ leftmost pixel } | bit 6 | .. | bit 1 | { least significant bit 0
  rightmost pixel }
 }
 @enduml
@@ -12,17 +14,17 @@ title One byte
 salt
 title One scene
 {#
- byte 0 == 8 pixel | byte 11 == 8 pixel | byte 22 == 8 pixel | ...
- byte 1 ...        | byte 12 ...        | byte 23 ...        | ...
- byte 2 ...        | byte 13 ...        | byte 24 ...        | ...
- byte 3 ...        | byte 14 ...        | byte 25 ...        | ...
- byte 4 ...        | byte 15 ...        | byte 26 ...        | ...
- byte 5 ...        | byte 16 ...        | byte 27 ...        | ...
- byte 6 ...        | byte 17 ...        | byte 28 ...        | ...
- byte 7 ...        | byte 18 ...        | byte 29 ...        | ...
- byte 8 ...        | byte 19 ...        | byte 30 ...        | ...
- byte 9 ...        | byte 20 ...        | byte 31 ...        | ...
- byte 10 ...       | byte 21 ...        | byte 32 ...        | ...
+ byte 0 == 8 pixel | byte 11 == 8 pixel | byte 22 == 8 pixel | ..
+ byte 1 ...        | byte 12 ...        | byte 23 ...        | ..
+ byte 2 ...        | byte 13 ...        | byte 24 ...        | ..
+ byte 3 ...        | byte 14 ...        | byte 25 ...        | ..
+ byte 4 ...        | byte 15 ...        | byte 26 ...        | ..
+ byte 5 ...        | byte 16 ...        | byte 27 ...        | ..
+ byte 6 ...        | byte 17 ...        | byte 28 ...        | ..
+ byte 7 ...        | byte 18 ...        | byte 29 ...        | ..
+ byte 8 ...        | byte 19 ...        | byte 30 ...        | ..
+ byte 9 ...        | byte 20 ...        | byte 31 ...        | ..
+ byte 10 ...       | byte 21 ...        | byte 32 ...        | ..
 }
 @enduml
 
@@ -30,6 +32,6 @@ title One scene
 salt
 title Complete bitmap data
 {#
- scene 0 == x bytes | ... | scene n == z bytes
+ scene 0 == x bytes | .. | scene n == z bytes
 }
 @enduml

From 21d5665a42429b105dbd089500ec31cec36fcb12 Mon Sep 17 00:00:00 2001
From: Ben Sartori <149951068+bensartori@users.noreply.github.com>
Date: Sun, 26 May 2024 15:37:40 +0200
Subject: [PATCH 2/4] Some documentation improvements regarding issue #29

---
 README.md | 89 ++++++++++++++++++++++++++++++++++---------------------
 1 file changed, 55 insertions(+), 34 deletions(-)

diff --git a/README.md b/README.md
index 7f1acfc..330c60c 100644
--- a/README.md
+++ b/README.md
@@ -68,8 +68,9 @@ To reuse the venv again at a later point:
 
 ### Manual link the HID API lib for some Linuxes
 
-For some distributions there is a discrepancy between the where pyhidapi searches for the lib and where the package
-hidapi places it. A simple solution is to link the libraray to the needed place, e.g.
+For some distributions there is a discrepancy in where pyhidapi searches for the
+lib and where the package hidapi places it. A simple solution is to link the
+library to the needed place, e.g.
 
     ln -s /usr/lib/libhidapi-hidraw.so.0 /usr/local/lib/
 
@@ -80,63 +81,83 @@ hidapi places it. A simple solution is to link the libraray to the needed place,
     pip install pillow
     ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" < /dev/null 2> /dev/null
     brew install hidapi
-  or
-    Try with `pip3 install pyhidapi`
 
-### Required dependencies on Windows 10
+or Try with
 
-    Download win/inf-wizard.exe to your desktop. Right click 'Run as Administrator'
-       -> Click 0x0416 0x5020 LS32 Custm HID
-       -> Next -> Next -> Documents LS32_Sustm_HID.inf -> Save (we don't need that file)
-       -> Install Now... -> Driver Install Complete -> OK
+    pip3 install pyhidapi
 
-    Download python from python.org
-      [x] install Launcher for all Users
-      [x] Add Python 3.7 to PATH
-       -> Click the 'Install Now ...' text message.
+### Required dependencies on Windows 7/10
 
-    Run cmd.exe as Administrator, enter:
-      pip install pyusb
-      pip install pillow
+For Windows, we need to set up the libusb API for the LED badge device.
+The way described here, uses [libusb-win32](https://github.com/mcuee/libusb-win32/wiki)
+in a quite low level way and in a quite old version:
 
-### Required dependencies on Windows 7
+- Please use version 1.2.6.0 of 'usblib-win32`. It's still available on the
+  [old project repo on SourceForge](https://sourceforge.net/projects/libusb-win32/files/libusb-win32-releases/1.2.6.0/)
+- Then
+	- Extract `bin/inf-wizard.exe` from the downloaded zip file. Right click and `Run as Administrator`
+	- `Next` -> Select `0x0416 0x5020 LS32 Custm HID` (or similar with the same IDs)
+	- `Next` -> `Next` -> Save as dialog `LS32_Sustm_HID.inf` -> `Save` (just to proceed, we don't need that file)
+	- `Install Now...` -> Driver Install Complete -> `OK`
 
-    Download win/win32-bin-1.2.6.0.zip to your desktop. Extract.
-    Find the inf-wizard.exe in the bin folder. Right click 'Run as Administrator'
-    Then continue as with windows 10 above.
+There are other - meanwhile recommended, but untested here - ways to install and setup
+newer versions of `libus-win32`: use
+[Zadig](https://zadig.akeo.ie/) (it is also available from the old libusb-win32 repo on
+[GitHub repo](https://github.com/mcuee/libusb-win32/releases) of newer releases)
+or [libusbK](https://libusbk.sourceforge.net/UsbK3/index.html)
 
+Of course, Python is needed:
+
+- Download latest python from [python.org](https://www.python.org/downloads/),
+or specific versions from [here](https://www.python.org/downloads/windows/)
+	- Checkmark the following options
+		- `[x]` install Launcher for all Users
+		- `[x]` Add Python X.Y to PATH
+	- Click the `Install Now ...` text message.
+
+Install needed the Python packages.
+
+- Run cmd.exe as Administrator, enter:
+
+		pip install pyusb
+        pip install pillow
 
 #### Examples:
 
-Sudo may or may not be needed for accessing the USB device, depending on your system.
+To run these examples on linux, you might have to prepend `sudo` for accessing
+the USB device. On Windows, maybe you have to run the `cmd`, where you enter the
+commands, with `Run as administrator`, which is similar to the `sudo`on linux.
+
+On systems with Python 2 *and* 3 installed, you might want to use Python 3
+explicitely by using `python3` instead of `python`.
 
-    sudo python3 ./led-badge-11x44.py "Hello World!"
+    python ./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 python3 ./led-badge-11x44.py -m 6 -s 8 "Hello" "World!"
+    python ./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.
 
-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.
+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.
 
-    sudo python3 ./led-badge-11x44.py -m 5 :gfx/fablabnbg_logo_44x11.png:
+    python ./led-badge-11x44.py -m 5 :gfx/fablabnbg_logo_44x11.png:
 
 loads a fullscreen still image. Avoid whitespace between colons and name. If you receive a message `ImportError: cannot import name '_imaging'`, then try to update the corresponding package: `sudo pip install -U Pillow`
 
-    sudo python3 ./led-badge-11x44.py "I:HEART2:my:gfx/fablab_logo_16x11.png:fablab:1:"
+    python ./led-badge-11x44.py "I:HEART2:my:gfx/fablab_logo_16x11.png:fablab:1:"
 
 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 -s7 -m0,1 :bicycle: :bicycle_r:
+    python ./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.
 
 ![LED Mini Board](photos/bicycle.gif)
 
-    sudo python3 ./led-badge-11-x44.py -b0,1 -s1 -m5 "  :heart2:    :HEART2:" "  :HEART2:"
+    python ./led-badge-11-x44.py -b0,1 -s1 -m5 "  :heart2:    :HEART2:" "  :HEART2:"
 
 shows a simple animation of a slowly beating heart on the first message, and a blinking heart on the second message.
 
@@ -144,11 +165,11 @@ shows a simple animation of a slowly beating heart on the first message, and a b
 
 ![M2 ishm](photos/m2ishm.gif)
 
-    python3 ./led-badge-11x44.py --list-names
+    python ./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
+    python ./led-badge-11x44.py --help
 
 prints some condensed help:
 
@@ -216,13 +237,13 @@ Your own content has to be a byte array with the bitmap data for all scenes. Of
 
 See the following graphic for better understanding:
 
-![bitmap_data_onebyte.png](photos%2Fbitmap_data_onebyte.png)
+![bitmap_data_onebyte.png](photos/bitmap_data_onebyte.png)
 
-![bitmap_data_onescene.png](photos%2Fbitmap_data_onescene.png)
+![bitmap_data_onescene.png](photos/bitmap_data_onescene.png)
 
 For a 12x48 device there have to be 12 bytes for each byte-column instead of 11, of course.
 
-![bitmap_data_all.png](photos%2Fbitmap_data_all.png)
+![bitmap_data_all.png](photos/bitmap_data_all.png)
 
 Example:
 
@@ -262,7 +283,7 @@ scene_c_bitmap = creator.bitmap("gfx/starfield/starfield_020.png")
 ```
 
 The resulting bitmaps are tuples with the byte array and the length each. These lengths can be used in header() directly
-and the byte arrays can be concatenated to the header. Examle:
+and the byte arrays can be concatenated to the header. Example:
 
 ```python
 from lednamebadge import * 

From f43e76e612d7487dd7f075e4806fb1f788e16fc2 Mon Sep 17 00:00:00 2001
From: Ben Sartori <149951068+bensartori@users.noreply.github.com>
Date: Tue, 4 Jun 2024 07:21:37 +0200
Subject: [PATCH 3/4] Whitespace correction

---
 README.md | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/README.md b/README.md
index 330c60c..581b9e3 100644
--- a/README.md
+++ b/README.md
@@ -95,10 +95,10 @@ in a quite low level way and in a quite old version:
 - Please use version 1.2.6.0 of 'usblib-win32`. It's still available on the
   [old project repo on SourceForge](https://sourceforge.net/projects/libusb-win32/files/libusb-win32-releases/1.2.6.0/)
 - Then
-	- Extract `bin/inf-wizard.exe` from the downloaded zip file. Right click and `Run as Administrator`
-	- `Next` -> Select `0x0416 0x5020 LS32 Custm HID` (or similar with the same IDs)
-	- `Next` -> `Next` -> Save as dialog `LS32_Sustm_HID.inf` -> `Save` (just to proceed, we don't need that file)
-	- `Install Now...` -> Driver Install Complete -> `OK`
+    - Extract `bin/inf-wizard.exe` from the downloaded zip file. Right click and `Run as Administrator`
+    - `Next` -> Select `0x0416 0x5020 LS32 Custm HID` (or similar with the same IDs)
+    - `Next` -> `Next` -> Save as dialog `LS32_Sustm_HID.inf` -> `Save` (just to proceed, we don't need that file)
+    - `Install Now...` -> Driver Install Complete -> `OK`
 
 There are other - meanwhile recommended, but untested here - ways to install and setup
 newer versions of `libus-win32`: use
@@ -110,16 +110,16 @@ Of course, Python is needed:
 
 - Download latest python from [python.org](https://www.python.org/downloads/),
 or specific versions from [here](https://www.python.org/downloads/windows/)
-	- Checkmark the following options
-		- `[x]` install Launcher for all Users
-		- `[x]` Add Python X.Y to PATH
-	- Click the `Install Now ...` text message.
+    - Checkmark the following options
+        - `[x]` install Launcher for all Users
+        - `[x]` Add Python X.Y to PATH
+    - Click the `Install Now ...` text message.
 
 Install needed the Python packages.
 
 - Run cmd.exe as Administrator, enter:
 
-		pip install pyusb
+        pip install pyusb
         pip install pillow
 
 #### Examples:

From d5d977bbdd6f654f33f9ff9ce6c175643c4cfeb5 Mon Sep 17 00:00:00 2001
From: Ben Sartori <149951068+bensartori@users.noreply.github.com>
Date: Tue, 4 Jun 2024 07:49:12 +0200
Subject: [PATCH 4/4] Some documentation improvements regarding common
 installation hints.

---
 README.md | 29 +++++++++++++++++------------
 1 file changed, 17 insertions(+), 12 deletions(-)

diff --git a/README.md b/README.md
index 581b9e3..64cde53 100644
--- a/README.md
+++ b/README.md
@@ -47,20 +47,23 @@ access to the badge via USB.
  
 Using a venv will allow to use pip to install dependencies without the danger
 that the installed modules will interfere with the system installed ones.
+On some systems (esp. those with Python 2 *and* 3 installed), you have to
+address Python 3 explicitly by using the commands `python3` / `pip3` instead
+of `python` / `pip`.
 
     sudo apt install python3-venv
-    python3 -m venv ledtag
+    python -m venv ledtag
     source ledtag/bin/activate
     pip install pyhidapi pyusb pillow
     # this should now work:
-    # python3 led-badge-11x44.py -m 6 -s 8 "Hello" "World!"
+    # python led-badge-11x44.py -m 6 -s 8 "Hello" "World!"
 
 if the udev rules are installed, you should be able to access the badge without sudo / root privileges.
 
 To reuse the venv again at a later point:
 
     source ledtag/bin/activate
-    python3 led-badge-11x44.py …
+    python led-badge-11x44.py …
 
 ### Required dependencies on Fedora Systems
 
@@ -76,16 +79,15 @@ library to the needed place, e.g.
 
 ### Required dependencies on Mac Systems
 
+On some systems (esp. those with Python 2 *and* 3 installed), you have to
+address Python 3 explicitly by using the command `pip3` instead of `pip`.
+
     sudo easy_install pip
     pip install pyhidapi
     pip install pillow
     ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" < /dev/null 2> /dev/null
     brew install hidapi
 
-or Try with
-
-    pip3 install pyhidapi
-
 ### Required dependencies on Windows 7/10
 
 For Windows, we need to set up the libusb API for the LED badge device.
@@ -115,7 +117,9 @@ or specific versions from [here](https://www.python.org/downloads/windows/)
         - `[x]` Add Python X.Y to PATH
     - Click the `Install Now ...` text message.
 
-Install needed the Python packages.
+Install needed the Python packages. On some systems (esp. those with Python 2
+*and* 3 installed), you have to address Python 3 explicitly by using the
+command `pip3` instead of `pip`.
 
 - Run cmd.exe as Administrator, enter:
 
@@ -125,11 +129,12 @@ Install needed the Python packages.
 #### Examples:
 
 To run these examples on linux, you might have to prepend `sudo` for accessing
-the USB device. On Windows, maybe you have to run the `cmd`, where you enter the
-commands, with `Run as administrator`, which is similar to the `sudo`on linux.
+the USB device or install a udev rule as stated above. On Windows, maybe you
+have to run the `cmd`, where you enter the commands, with `Run as administrator`,
+which is similar to the `sudo`on linux.
 
-On systems with Python 2 *and* 3 installed, you might want to use Python 3
-explicitely by using `python3` instead of `python`.
+On some systems (esp. those with Python 2 *and* 3 installed), you have to
+address Python 3 explicitly by using `python3` instead of `python`.
 
     python ./led-badge-11x44.py "Hello World!"