This repository has been archived by the owner on Apr 29, 2021. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 4
/
Copy pathdocs.html
177 lines (127 loc) · 10.4 KB
/
docs.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
---
layout: default
title: bbusb/docs
---
<p class="header">How it works<p>
<p>bbusb runs in a three-step process:
<ol>
<li>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.</li>
<li>If any dynamic commands were listed in the config, bbusb executes those commands and collects their printed output.</li>
<li>Finally, bbusb processes any <a href="#formatting">formatting codes</a> 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.</li>
</ol>
<p class="header">Examples</p>
<p>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.
<p class="subheader">An example program</p>
<p>Let's make a simple shell script which takes the output of the unix "date" command and adds some <a href="#formatting">bbusb formatting</a> around it:</p>
<p class="code">#!/bin/sh<br/>
echo <color300><wide>The time is</wide> &rightarrow; <color030>$(date) <color300>&leftarrow;</p>
<p>When the above script is run and processed by bbusb, it will look like this on the sign:</p>
<p><font color="#FF0000"><b>The time is</b> → </font><font color="#00FF00">Mon Oct 3 09:54:24 PDT 2011 </font><font color="#FF0000">←</font></p>
<p>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.
<p class="subheader">An example config</p>
<p>Now we should create the config file which will be passed to bbusb. The format for this file is simple:</p>
<ul><li>Comments start with # or //:<br/>
<div class="code">#<i>comment</i><br/>
//<i>comment</i></div></li>
<li>Dynamic commands start with "cmd":<br/>
<div class="code">cmd <i>mode command</i></div></li>
<li>Static text starts with with "txt":<br/>
<div class="code">txt <i>mode text</i></div></li></ul>
<p>The available <i>mode</i>s are listed <a href="#modes">below</a>. Here's an example config:</p>
<p class="code">//this is a comment<br/>
txt a <color300>hello world!<br/>
cmd b date<br/>
cmd c sh script.sh</p>
<p>Given the above config, bbusb will do the following:</p>
<ol><li>Ignore the first line, it's a comment.</li>
<li>Display the text <i>hello world!</i> in bright red with mode <i>a</i>.</li>
<li>Run the command <i>date</i> and display its output with mode <i>b</i>.</li>
<li>Run the command <i>sh test.sh</i> and display its output with mode <i>c</i>. This would be for running the example script we just wrote.</li></ol>
<p class="subheader">Running the example</p>
<p>Now that we've written our config, let's send it to bbusb. The syntax for doing this is:
<p class="code">bbusb <-i/-u> <configfile></p>
<p>As implied by the -i and -u flags, there are two ways of running bbusb. The first way is to <i>-i</i>nitialize the sign. The second is to <i>-u</i>pdate the sign. Whenever you change your config file, you <b>must</b> 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 <i>don't</i> need to immediately follow a "-i" with a "-u" to start seeing your new content.</p>
<p>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 <i>-i</i>nitialization against a given config, we can then <i>-u</i>pdate against it, flicker free, as many times as we want.</p>
<p>How does this work in practice? Here's an example scenario:</p>
<p class="code">> bbusb -i configA<br/>
> bbusb -u configA<br/>
> bbusb -u configA<br/>
> bbusb -i configB<br/>
> bbusb -u configB<br/>
> bbusb -u configB<br/>
> bbusb -u configB</p>
<p>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.</p>
<p class="subheader">Putting it all together</p>
<p>So now that we have a script, a config, and the procedure for running bbusb, let's give it a go:</p>
<p class="code">Example script: <b>script.sh</b><br/>
#!/bin/sh<br/>
echo <color300><wide>The time is</wide> &rightarrow; <color030>$(date) <color300>&leftarrow;</p>
<p class="code">Example config: <b>config.txt</b><br/>
//this is a comment<br/>
txt a <color300>hello world!<br/>
cmd b date<br/>
cmd c sh <b>script.sh</b></p>
<p class="code">Running our example:<br/>
> bbusb -i <b>config.txt</b><br/>
> bbusb -u <b>config.txt</b><br/>
> bbusb -u <b>config.txt</b><br/>
...</p>
<p>That's all there is to it.</p>
<p class="header"><a name="syntax"></a>Syntax Reference</p>
<p>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 <a href="scripts.html">scripts</a> posted to this site.</p>
<p class="subheader"><a name="modes"></a>Config Modes</p>
<p>These are the available modes for using in your config file.<br/>
I tend to just use "a" for everything. Feel free to experiment.</p>
<table cellpadding="1" cellspacing="1">
<tr><td>Mode</td><td>Desc</td> <td>Mode</td><td>Desc</td> <td>Mode</td><td>Desc</td></tr>
<tr><td>a</td><td>rotate</td> <td>p</td><td>rollin</td> <td>n8</td><td>welcome</td></tr>
<tr><td>b</td><td>hold</td> <td>q</td><td>rollout</td> <td>n9</td><td>sale</td></tr>
<tr><td>c</td><td>flash</td> <td>r</td><td>wipein</td> <td>na</td><td>newsflash</td></tr>
<tr><td>e</td><td>rollup</td> <td>s</td><td>wipeout</td> <td>nb</td><td>happy4th</td></tr>
<tr><td>f</td><td>rolldn</td> <td>t</td><td>comprotate</td> <td>nc</td><td>cyclecolor</td></tr>
<tr><td>g</td><td>rolleft</td> <td>n0</td><td>twinkle</td> <td>ns</td><td>thankyou</td></tr>
<tr><td>h</td><td>rollright</td><td>n1</td><td>sparkle</td> <td>nu</td><td>nosmoking</td></tr>
<tr><td>i</td><td>wipeup</td> <td>n2</td><td>snow</td> <td>nv</td><td>dontdrink</td></tr>
<tr><td>j</td><td>wipedn</td> <td>n3</td><td>interlock</td> <td>nw</td><td>fish</td></tr>
<tr><td>k</td><td>wipeleft</td> <td>n4</td><td>switch</td> <td>nx</td><td>fireworks</td></tr>
<tr><td>l</td><td>wiperight</td><td>n5</td><td>cyclecolor</td><td>ny</td><td>xmas</td></tr>
<tr><td>m</td><td>scroll</td> <td>n6</td><td>spray</td> <td>nz</td><td>smile</td></tr>
<tr><td>o</td><td>automode</td> <td>n7</td><td>starburst</td></tr>
</table>
<p class="subheader"><a name="formatting"></a>Formatting Codes</p>
<p>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.</p>
<table cellpadding="1" cellspacing="1">
<tr><td>Format Code(s)</td><td>Description</td></tr>
<tr><td><left></td><td>Left-align the text in this frame. Only works in some frame modes (eg "hold")</td></tr>
<tr><td><speedN></td><td>Set frame display speed. speed1 = slowest, speed6 = fastest.</td></tr>
<tr><td><br></td><td>Start of next display frame (allows multiple frames in one command).</td></tr>
<tr><td><blink>,</blink></td><td>Enable/disable blinking text. Only works in some frame modes (eg "hold").</td></tr>
<tr><td><small></td><td>Switch to a smaller font.</td></tr>
<tr><td><normal></td><td>Switch back to normal size.</td></tr>
<tr><td><wide>,</wide></td><td>Widen the text.</td></tr>
<tr><td><dblwide>,</dblwide></td><td>Widen the text more.</td></tr>
<tr><td><serif>,</serif></td><td>Switch to a serif font.</td></tr>
<tr><td><shadow>,</shadow></td><td>Apply a shadow to the text.</td></tr>
<tr><td><colorRGB></td><td>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)</td></tr>
<tr><td><scolorRGB></td><td>Change the text shadow color (for text with <shadow> applied). Uses same RGB codes as <colorRGB>.</td></tr>
</table>
<p class="subheader">Symbol Entities</p>
<p>Use these to display special characters on your sign.<br/>
See the script above for an example use of the arrow entities.</p>
<table>
<tr><td>Code</td><td>Result</td> <td>Code</td><td>Result</td></tr>
<tr><td>&uparrow;</td><td>↑</td> <td>&downarrow;</td><td>↓</td></tr>
<tr><td>&leftarrow;</td><td>←</td> <td>&rightarrow;</td><td>→</td></tr>
<tr><td>&cent;</td><td>¢</td> <td>&gbp;</td><td>£</td></tr>
<tr><td>&yen;</td><td>¥</td> <td>&euro;</td><td>€</td></tr>
<tr><td>&disk;</td><td>(Floppy Disk)</td> <td>&printer;</td><td>(Printer)</td></tr>
<tr><td>&phone;</td><td>☎</td> <td>&satdish;</td><td>(Satellite Dish)</td></tr>
<tr><td>&car;</td><td>(Car)</td> <td>&boat;</td><td>(Boat)</td></tr>
<tr><td>&male;</td><td>♂</td> <td>&female;</td><td>♀</td></tr>
<tr><td>&heart;</td><td>♥</td> <td>&pacman;</td><td>(Pacman)</td></tr>
<tr><td>&ball;</td><td>(Sphere/Ball)</td> <td>&note;</td><td>♪</td></tr>
<tr><td>&mug;</td><td>(Drinking Mug)</td> <td>&bottle;</td><td>(Drinking Bottle)</td></tr>
<tr><td>&handicap;</td><td>(Handicap Symbol)</td><td>&copy;</td><td>©</td></tr>
<tr><td>&rhino;</td><td>(Rhinoceros)</td> <td>&infinity;</td><td>∞</td></tr>
<tr><td>&deg;</td><td>°</td> <td> </td><td> </td></tr>
</table>