How it works
bbusb runs in a three-step process:
- First, it reads the contents of a config file. This file contains a list of static text to be displayed and/or dynamic commands to run.
- If any dynamic commands were listed in the config, bbusb executes those commands and collects their printed output.
- Finally, bbusb processes any formatting codes in the output it's collected, and sends the processed results to the sign. This content will be continuously displayed on the sign until it is again updated by bbusb.
Examples
Let's take a quick tour of how this works from the ground up. First, we'll start with a program that produces the data we want to display. Then we'll take a look at the config file which tells bbusb how to run that program. Finally we'll run bbusb with the config file and see the chain in action.
An example program
Let's make a simple shell script which takes the output of the unix "date" command and adds some bbusb formatting around it:
#!/bin/sh
echo <color300><wide>The time is</wide> → <color030>$(date) <color300>←
When the above script is run and processed by bbusb, it will look like this on the sign:
The time is → Mon Oct 3 09:54:24 PDT 2011 ←
This is a fairly boring example, but it shows how powerful this system can be. As long as you can write a program which produces what you want to display when it's executed, bbusb can take that output and put it on your sign.
An example config
Now we should create the config file which will be passed to bbusb. The format for this file is simple:
- Comments start with # or //:
#comment
//comment - Dynamic commands start with "cmd":
cmd mode command - Static text starts with with "txt":
txt mode text
The available modes are listed below. Here's an example config:
//this is a comment
txt a <color300>hello world!
cmd b date
cmd c sh script.sh
Given the above config, bbusb will do the following:
- Ignore the first line, it's a comment.
- Display the text hello world! in bright red with mode a.
- Run the command date and display its output with mode b.
- Run the command sh test.sh and display its output with mode c. This would be for running the example script we just wrote.
Running the example
Now that we've written our config, let's send it to bbusb. The syntax for doing this is:
bbusb <-i/-u> <configfile>
As implied by the -i and -u flags, there are two ways of running bbusb. The first way is to -initialize the sign. The second is to -update the sign. Whenever you change your config file, you must initialize your sign before you update it. In other words, if you modify your config file or use a different config file, you'll need to run "-i" once against that new config before you'll be able to use "-u". Note that running "-i" will also update the content on your sign, so you don't need to immediately follow a "-i" with a "-u" to start seeing your new content.
Why does bbusb have two modes, instead of just always re-initializing the sign every time it's run? If you run with -i a few times, you'll notice that it causes the sign to flicker or go blank for a couple seconds, whereas with -u it smoothly updates the sign content without interruption. Turns out that initializing the sign causes it to flicker, so we only do that when it's actually necessary. After that first -initialization against a given config, we can then -update against it, flicker free, as many times as we want.
How does this work in practice? Here's an example scenario:
> bbusb -i configA
> bbusb -u configA
> bbusb -u configA
> bbusb -i configB
> bbusb -u configB
> bbusb -u configB
> bbusb -u configB
In this scenario, we start off by initializing against configA, followed by two updates against configA. We then decide to switch to configB, which is a modified copy of configA. Because this new config is different, we have to initialize against it, which causes the sign to flicker, before we can resume updating flicker-free.
Putting it all together
So now that we have a script, a config, and the procedure for running bbusb, let's give it a go:
Example script: script.sh
#!/bin/sh
echo <color300><wide>The time is</wide> → <color030>$(date) <color300>←
Example config: config.txt
//this is a comment
txt a <color300>hello world!
cmd b date
cmd c sh script.sh
Running our example:
> bbusb -i config.txt
> bbusb -u config.txt
> bbusb -u config.txt
...
That's all there is to it.
You can also view this reference by running "bbusb -h". You can also see some of this in action by playing with some of the scripts posted to this site.
These are the available modes for using in your config file.
I tend to just use "a" for everything. Feel free to experiment.
| Mode | Desc | Mode | Desc | Mode | Desc |
| a | rotate | p | rollin | n8 | welcome |
| b | hold | q | rollout | n9 | sale |
| c | flash | r | wipein | na | newsflash |
| e | rollup | s | wipeout | nb | happy4th |
| f | rolldn | t | comprotate | nc | cyclecolor |
| g | rolleft | n0 | twinkle | ns | thankyou |
| h | rollright | n1 | sparkle | nu | nosmoking |
| i | wipeup | n2 | snow | nv | dontdrink |
| j | wipedn | n3 | interlock | nw | fish |
| k | wipeleft | n4 | switch | nx | fireworks |
| l | wiperight | n5 | cyclecolor | ny | xmas |
| m | scroll | n6 | spray | nz | smile |
| o | automode | n7 | starburst |
This is the in-line formatting syntax for telling bbusb how you'd like text to be displayed. This is what you use to select fonts and colors. Note that some <code>s do not have a matching </code>, due to how the underlying sign protocol works.
| Format Code(s) | Description |
| <left> | Left-align the text in this frame. Only works in some frame modes (eg "hold") |
| <speedN> | Set frame display speed. speed1 = slowest, speed6 = fastest. |
| <br> | Start of next display frame (allows multiple frames in one command). |
| <blink>,</blink> | Enable/disable blinking text. Only works in some frame modes (eg "hold"). |
| <small> | Switch to a smaller font. |
| <normal> | Switch back to normal size. |
| <wide>,</wide> | Widen the text. |
| <dblwide>,</dblwide> | Widen the text more. |
| <serif>,</serif> | Switch to a serif font. |
| <shadow>,</shadow> | Apply a shadow to the text. |
| <colorRGB> | Change the text foreground color. R,G,B may each be any number between 0 and 3 (eg <color303> for bright purple, <color101> for dim purple) |
| <scolorRGB> | Change the text shadow color (for text with <shadow> applied). Uses same RGB codes as <colorRGB>. |
Symbol Entities
Use these to display special characters on your sign.
See the script above for an example use of the arrow entities.
| Code | Result | Code | Result |
| ↑ | ↑ | ↓ | ↓ |
| ← | ← | → | → |
| ¢ | ¢ | &gbp; | £ |
| ¥ | ¥ | € | € |
| &disk; | (Floppy Disk) | &printer; | (Printer) |
| ☎ | ☎ | &satdish; | (Satellite Dish) |
| &car; | (Car) | &boat; | (Boat) |
| ♂ | ♂ | ♀ | ♀ |
| &heart; | ♥ | &pacman; | (Pacman) |
| &ball; | (Sphere/Ball) | ¬e; | ♪ |
| &mug; | (Drinking Mug) | &bottle; | (Drinking Bottle) |
| &handicap; | (Handicap Symbol) | © | © |
| &rhino; | (Rhinoceros) | &infinity; | ∞ |
| ° | ° |