mirror of
git://projects.qi-hardware.com/ben-blinkenlights.git
synced 2024-11-27 16:42:48 +02:00
124 lines
3.7 KiB
Plaintext
124 lines
3.7 KiB
Plaintext
libubb - Helper functions for the Universal Breakout Board
|
|
==========================================================
|
|
|
|
libubb gives convenient access to the GPIOs accessible via UBB [1].
|
|
It also includes additional components that implement more advanced
|
|
functions, such as a software UART, or giving access to additional
|
|
CPU registers.
|
|
|
|
[1] http://en.qi-hardware.com/wiki/UBB
|
|
|
|
|
|
Installation, compiling, and linking
|
|
------------------------------------
|
|
|
|
The ubb/ directory under include/ should be placed in the
|
|
cross-compiler's include path and libubb.a goes into the
|
|
cross-linker's library search path.
|
|
|
|
Alternatively, the paths can be added when compiling or linking,
|
|
with -I<wherever>/libubb/include or -L<wherever>/libubb
|
|
|
|
When linking, add -lubb to include the library.
|
|
|
|
|
|
Skeleton program
|
|
----------------
|
|
|
|
This program fragment illustrates the key elements of basic UBB
|
|
use:
|
|
|
|
1 #include <ubb/ubb.h>
|
|
2
|
|
3 ...
|
|
4 #define MY_FOO UBB_CMD
|
|
5 #define MY_BAR UBB_DAT2
|
|
6 ...
|
|
7
|
|
8 if (ubb_open(0) < 0) {
|
|
9 perror("ubb_open");
|
|
10 exit(1);
|
|
11 }
|
|
12 ...
|
|
13 ubb_power(1);
|
|
14 ...
|
|
15 CLR(MY_FOO);
|
|
16 OUT(MY_FOO);
|
|
17
|
|
18 IN(MY_BAR);
|
|
19
|
|
20 while (PIN(MY_BAR)) {
|
|
21 SET(MY_FOO);
|
|
22 CLR(MY_FOO);
|
|
23 }
|
|
24 ...
|
|
25 ubb_close(0);
|
|
|
|
Including ubb/ubb.h at line 1 provides all the basic definitions.
|
|
|
|
Lines 4 and 5 define project-specific names for the IO pins.
|
|
libubb provides the macros UBB_CMD, UBB_CLK, UBB_DAT0, UBB_DAT1,
|
|
UBB_DAT2, and UBB_DAT3 for the signals available on the 8:10 card
|
|
connector. It also provides UBB_nPWR for the (inverted) signal
|
|
that controls power to the card.
|
|
|
|
Lines 8 to 11: To get access to UBB and to set the GPIOs to a known
|
|
state, call ubb_open. The default settings are:
|
|
|
|
UBB_nPWR GPIO, output
|
|
all others GPIO, input, pull-up enabled
|
|
|
|
ubb_open takes as argument a list of signals that should not be
|
|
changed. For example, if MY_FOO and MY_BAR had a configuration
|
|
state worth preserving already before running the program, one
|
|
would use ubb_open(MY_FOO | MY_BAR).
|
|
|
|
Note that all IO pins except UBB_CLK (and UBB_nPWR) have 10 kOhm
|
|
pull-ups soldered to them inside the Ben. Only UBB_CLK can
|
|
therefore be configured to have no pull-up at all.
|
|
|
|
If ubb_open fails for some reason, it returns a negative value
|
|
and sets "errno". If it succeeds, it returns zero.
|
|
|
|
Line 13: to make the Ben provide 3.3 V to UBB, call ubb_power(1).
|
|
ubb_power(0) turns off power. ubb_power(1) also adds a delay of
|
|
10 ms to let the card pre-charge any capacitors through the IO
|
|
pins. This is often necessary to limit the inrush current when
|
|
switching on power. If the inrush current is too large, it may
|
|
compromise the Ben's own voltage supply and cause the Ben to
|
|
freeze.
|
|
|
|
Lines 15 to 23: the convenience macros IN and OUT set the
|
|
respective pins to be inputs or outputs. The argument is a
|
|
bitmask of the pins to change. SET and CLR set the output to "1"
|
|
or "0" respectively. PIN returns 1 if any of the specified pins
|
|
is "1", 0 if they are all "0".
|
|
|
|
Line 25: To close UBB and restore the pins to their original
|
|
setting, call ubb_close. Like ubb_open, ubb_close accepts a
|
|
mask of pins that should be left as they are.
|
|
|
|
|
|
Low-level GPIO control
|
|
----------------------
|
|
|
|
include/ubb/regbase.h defines the registers that control the
|
|
GPIOs. Settable items generally have three registers: "FOO" to
|
|
read the current setting, "FOOS" to set bits, and "FOOC" to
|
|
clear bits.
|
|
|
|
When writing to the FOOS or FOOC registers, a 1 sets or clears
|
|
the respective bit while a 0 leaves it unchanged.
|
|
|
|
For example, the UBB_CLK pull-up would be turned off with
|
|
|
|
PDPULLS = UBB_CLK;
|
|
|
|
|
|
Access to timers, interrupts, etc.
|
|
----------------------------------
|
|
|
|
include/ubb/regs4740.h gives access to even more registers.
|
|
Please consult the JZ4740 Programming Manual for details on
|
|
their use.
|