-
Notifications
You must be signed in to change notification settings - Fork 4
Driver for Dream Cheeky USB LED message board. Home page: https://www.last-outpost.com/~malakai/dcled/
Conservatory/dcled
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Folders and files
Name | Name | Last commit message | Last commit date | |
---|---|---|---|---|
Repository files navigation
############################################################################## # # # This is the Conservatory archive of Jeff Jahr's 'dcled', an open source # # program for driving the Dream Cheeky USB message board. The upstream # # home page is https://www.last-outpost.com/~malakai/dcled/. # # # # Jeff Jahr still maintains dcled. (As far as we are currently aware, # # his own repository is not publicly accessible on the Net, which is why # # we created this one.) He does not monitor this repository, but he said # # that anyone with a contribution to make should send him patches by # # email as described in his original README below, and he'll be happy to # # consider them for inclusion into dcled. The Conservatory will try to # # watch for new upstream releases and incorporate them into the version # # control history here. # # # # The Conservatory (https://conservatory.github.io/) is a place where # # free software that has no other public version-controlled home on the # # Internet is made available in a git repository. For dcled, we did the # # usual treatment: each upstream release package is committed as one git # # revision, starting from dcled-1.0. Note that for some reason dcled-1.3 # # was absent from upstream's archive (though the 404 error page for it # # rocks -- try https://www.last-outpost.com/~malakai/dcled/dcled-1.3.tgz # # to see for yourself). # # # # This README is the only file we've changed from upstream, and the only # # change we made was to add this note. Below is the original content of # # the README file. # # # ############################################################################## dcled - userland driver for Dream Cheeky (Dream Link?) USB LED Message Board Copyright 2009-2014 Jeff Jahr <malakai@jeffrika.com> This is free software. G'head, use it all you want. Because of the use of libusb, however, this might now be considered GPL licensed. I kind of like the Artistic License myself. Anyway, if you are planning to incorporate this code into your product or are otherwised concerned about the licensing, have your people contact my people and we'll work it out. Version 1.0 took ~12 hours to write, and was my first foray into usb device programming. This is probably not a real good example of how to do ANYTHING. Dcled runs on linux, and perhaps other operating systesm. To use it, you need to have the usb hiddev loaded- on my system that seems to be the module named 'usbhid', and it is loaded by default. When you plug in the message board, the system ought to see it and create an entry in /dev/usb/hiddev* for it. You can check if the device is loaded correctly with this command: lsusb -d 1d34:0013 -v That out to output a whole lot of stuff that you probably dont care about- unless it outputs nothing. If it outputs nothing, then you have a problem with your usb. Or maybe you have message board with a different vendor and product id. BUILDING IT: As of dcled version 2.1, you no longer need libhid, but you are going to need a copy of the libusb-1.0 dev files in order to build dcled. If you are running debian or ubuntu, try running 'apt-get install libusb-1.0-0-dev' to get the right files installed. Type 'make'. That should build an executable called 'dcled'. If that doesnt work, try compling it by hand. There is an install option in the makefile. If the first make command was successful, run 'make install' as root to copy the executable into /usr/local/bin. As of dcled version 1.8, there is a linux udev rules file that will set the permissions of the dcled device such that members of the plugdev group can access the hardware without being root. It seems to work pretty well under Ubuntu linux, but it isn't very well tested elsewhere and I can't vouch for how will it will work under other OS's. If you want to give it a shot, type 'make udev'. That will copy the file into place and restart the udev subsystem. RUNNING IT: You are going to need read/write access to the mesage board device in order to use dcled. This means you can either run dcled as root, suid the exe, or figure out how to set the device permissions under hotplug if the method suggested by the installation instructions didn't work for you. If you choose to run it as root, do try not to hurt anything. You've been warned. Usage- ./dcled [opts] [files] --brightness -b How bright, 0-2 --clock -c Show the time --clock24h -C Show the 24h time --bcdclock -B Show the time in binary --debug -d Mostly useless --echo -e Send copy to stdout --help -h Show this message --message -m A single line message to scroll --nodev -n Don't use the device --preamble -p Send a graphic before the text. --repeat -r Keep scrolling forever --fastprint -f Jump to end of message. --speed -s General delay in ms --test -t Output a test pattern Available preamble graphics: 1 - dots - A string of random dots 2 - static - Warms up like an old TV 3 - squiggle - A squiggly line 4 - clock24 - Shows the 24 hour time 5 - clock - Shows the time 6 - spiral - Draws a spiral 7 - fire - A nice warm hearth 8 - bcdclock - Shows the time in binary I set up dcled so that it works like cat. If you run dcled with a list of files, it will cat each of those files to the message board. If you dont name any files at all, dcled reads from stdin, so that you can use it as a pipe. There is also the --message="" option in case you want to send a single line to it. EXAMPLES: Run a test pattern: dcled -t Hello World: dcled -m 'Hello World!' Hello World part 2: echo 'Hello World!' | dcled Hell World part 3: echo Hello >f1 echo Hello >f2 dcled f1 f2 If you want to have dcled run as a clock all the time, try adding using the clock and repeat options. dcled --clock --repeat As of dcled 1.6, you can call the preamble type either by number or by name: dcled -p static -m "Hello World" dcled -p 2 -m "Hello World" To see a demo of all the preamble types, run the test pattern: dcled --test Here is how I use it to monitor my game server syslog file: tail -f syslog | dcled -e -p static WHAT IS UP WITH BCDCLOCK? A couple of the guys at work have these LED desk clocks that show the time in a form of binary notation called 'BCD'. That stands for 'binary coded decimal'. The clock is showing the time like normal- 2:25:29 for twenty nine seconds after two twentyfive for example- but instead of printing it like normal, each digit is printed as a column of binary bits. The 1 bit is at the bottom of the screen, with 2, 4, and then 8 on top of it. Here is an example- ..................... ..................... ..................... .................O... ...........O......... .....O...O.....O..... ...........O.....O... 0 2 2 5 2 9 Having a BCD clock on your desk is pretty geeky... but I think having a USB programmable one that can scroll messages too is even better! WHAT IS UP WITH THE FONT FILE FORMAT? I was cleaning out my postmaster mail box and saw that Stefan Misch was having a hard time mailing me at my usual adress. Its a good thing that I thought to clean up the postmaster box, becuase it turns out he had submitted a patch that hard coded three new fonts into dcled! I felt really bad about having that patch sit around unseen for over a month, so to make up for it, I decided it was time to add loadable font files to the project. That, and it was raining. If you want to add a font of your own, check out one of the .dlf files included in the distribution. The first five lines of the file are the header, and are order dependant. i.e. The "Descirption" data has to appear on the third line of the file. After the header comes the individual character definitions. Each charater is defined on an 8x7 bitmap. The Size parameter in the header tells how much of the 8x7 bitmap is actually used by the font. The characters don't all have to be defined, and they don't have to appear in order in the file. The first two-digit hex number determines which ascii character being defined. The next character is skipped by dcled, it is just there as a human readable hint for what the character is. The next seven numbers are the row data for the character bit patterns. The default location for font files is /usr/local/share/dcled. Put your .dlf file into that location and dcled will try to load it. WHAT IS UP WITH MOVING TO LIBHID in 1.4? I got a message from Sam Dineley about a problem he was having with dcled under kernel 2.6.24. It looks like there is a problem with the linux usbhid driver that is causing a large number of warnings to be klogged when the display is in use. I bumped my kernel to 2.6.26 and am getting the same problem. The display still seems to work, although it is very slow, and the error messages fill up the logs. Sadly, it seems that the usb bus will eventually lock up too under these conditions. I started looking at what could be going wrong, but this is an area of the system that I have no familiarity with at all- this program was my first visit into the land of usb programming. This looks to be a problem with the linux usbhid driver, but maybe there is something that my program or the messageboard hardware is doing to trigger the problem? Who knows. As soon as I saw the linux hid 'quirks' section in the kernel, I figured that this was an area of experimentation that would have to wait for some other rainy afternoon. I'm in California and we are in the middle of a drought, so there it sat. In the mean time, Michael Wensley was smart enough to make dcled work with libhid, and kind enough to show me how he did it. It seems to work without error on my systems, so there we go! Problem solved. WHAT IS UP WITH MOVING FROM LIBHID TO LIBUSB-1.0 in 2.1? Libhid served us well for a long time. However, the Debian/Ubuntu maintainers felt the libhid package was buggy, unsupported, and not widely used, so they eventually dropped it from the distributions. Not a big deal, one could easily install libhid from source and dcled could keep using it, except for the following: libhid is unsupported, not widely used, building it is a pain, and I keep getting emailed about how to install it! Problem no longer solved. I took a few hours to read up on the libusb-1.0 API and was able to have dcled call libusb-1.0 directly instead of through libhid, so now the libhid requirement is dropped. WHAT IS UP WITH TACHOMETER MODE? I wanted to use the message board to continuously monitor some stats on my computer. I thought the easiest and most scriptable way to do this would be to have dcled read its input for a number from 0 to 100 (one nubmer per line), and 'graph' the value. I included cpuload in the distribution as an example of how to feed dcled some data to be monitored. To use dcled to monitor the CPU utilization on a Linux box, pipe the output of cpuload to dcled in tach mode like this: ./cpuload 0.2 | ./dcled -T tach You can feed the dcled tach gauge with any program you can think of, and dcled will update the tach gauge every time that it reads a new value, or four times per second if there is no data waiting to be read. CREDITS: I used the docs written by Alvin Wong of Dream Link to get the device protocol right. Way to go with releasing hardware specs! Awesome! I took the font data from pictures of the X11 "5x7" font. Its a long story. Additional contributions made by: * Sam Dineley - Bug reports * Andy Scheller - Clock code, redrew the 'g', great feedback * Michael Wensley - Application of libhid clue stick * James Bruce - First to get it to compile under Mac OSX. * Glen Smith - Wrote the spiral and fire animations. * Raymond - Initial udev rules file * Thomas Ilnseher - Bug reports * Robert Flick - Fast Print mode for keeping a still message displayed, Mac Homebrew build formula. * Stefan Misch - Created the small, sga, and small_inv fonts If you want to contribute to dcled, send me your code diffs! Be sure to specifiy if you DONT want me to include your name or email address in the credits. -jsj
About
Driver for Dream Cheeky USB LED message board. Home page: https://www.last-outpost.com/~malakai/dcled/
Resources
Stars
Watchers
Forks
Releases
No releases published
Packages 0
No packages published