1 Examples {#ChaExamples}
5 The best way to learn a
new library API is to test out some examples. A
6 working example shows that the installation of the library components
7 is OK. And by adapting the example source code you can easily find out
8 if your understanding of the documentation matches reality.
10 So libpruio includes a bunch of examples, all of them less than 200
11 lines of code and some of them in FreeBASIC and in C syntax. Since C
12 doesn
't support native grafics output, C examples are only available
13 with console text output. For all examples there're pre-compiled
14 executables in folder src/examples.
16 Some examples need wiring to work and show the desired effect. Therefor
17 a minimal knowlege on electronics is required to avoid damaging your
18 Beaglebone board when doing the wiring. The circuits are designed
for
19 minimal hardware requirements, so you need not spend a lot of money
for
26 The examples in
this section produce console text output. The source
27 code is available in FreeBASIC (folder src/examples) and C syntax
28 (folder src/c_examples). The output between both versions may vary a
29 bit, in order to keep the examples informative, but the C example code
32 Simple (1) {#SubSecExaSimple}
37 This is a minimal example printing a table of some analog samples
38 from the ADC subsystem. It illustrates the principle usage of
39 libpruio described in section \ref SecOperation by a minimal number
44 No preparation is required. Optionaly you can connect the analog
45 ground at P9_34 (AGND) and some of the analog input lines AIN-0 to
46 AIN-6 to a voltage source in the range of 0 V to 1V8 (ie. from a
51 Start the program in the terminal by typing `./1` and press the
52 Return key. The output is a table containing 13 lines of all analog
55 D530 E0C0 DE20 CEE0 0080 0780 1850 EE20
56 E990 E150 DD80 D010 0000 07A0 1770 EE00
57 E980 E230 DE70 CEE0 0070 07B0 17A0 EE30
58 E9C0 E110 DD50 CF00 0090 08C0 18D0 EE40
59 E8D0 E0B0 DD10 CE60 0010 0880 1800 EE40
60 E9B0 E210 DDC0 CEC0 0090 0790 1850 EE00
61 E970 E220 DE40 D020 00D0 0840 17D0 EE70
62 E9D0 E1C0 DD90 CE90 00B0 06F0 1830 EE70
63 E920 E120 DC90 CD80 0040 0750 1850 EDF0
64 E8E0 E0D0 DD60 CEC0 00B0 0810 1780 EEB0
65 E8D0 E130 DD00 CE90 0000 0730 17D0 EE70
66 EA20 E210 DDD0 CED0 00E0 0820 1850 EEA0
67 E960 E0D0 DDE0 CF10 0010 0740 17B0 EE40
69 The
last column (AIN-7) is the on board voltage divided by 2 (`&hEE50
70 / &hFFF0 * 1,8 = 1.67 V`). The fifth column is channel AIN-4, which
71 is connected to ground (P9_34 = AGND) during the test. The other
72 channels are open ended.
82 analyse {#SubSecExaAnalyse}
87 This example shows how to read the subsystem configurations. It
88 creates a
PruIo structure and prints out all startup registers
93 No preparation is required.
97 Start the program in the terminal by typing `./analyse` and press the
98 Return key. The output is a
long list of text lines, like
101 P8_03, mode 1: input enabled, pullup
102 P8_04, mode 1: input enabled, pullup
103 P8_05, mode 1: input enabled, pullup
104 P8_06, mode 1: input enabled, pullup
105 P8_07, GPIO 2/02: input, pullup
106 P8_08, GPIO 2/03: input, pullup
110 GPIO-0 (DeAd: 44E07000, ClAd: 44E00408, ClVa: 00000002)
117 ADC (DeAd: 44E0D000, ClAd: 44E004BC, ClVa: 00000002)
120 IRQSTATUS_RAW: 00000407
124 PWMSS-0 (DeAd: 48300000, ClAd: 44E000D4, ClVa: 00000002)
133 First, all header pin configurations are shown. Then the registers of
134 the GPIO subsystems (0 to 3)
get listed, followed by the ADC
135 subsystem registers and the registers of the PWMSS subsystems (0 to
136 2). It
's the context of the xyzSet strctures (BallSet, GpioSet,
137 AdcSet and PwmssSet). The code may be helpful for debugging in your
142 src/examples/analyse.bas
144 No C source available
147 button {#SubSecExaButton}
152 This example shows how to get input from a digital line. It creates a
153 new PruIo instance cinfigured in IO mode and continuously prints out
154 the state of a single digital lines.
158 The code uses header pin P8_07 which is configured as GPIO input with
159 pullup resistor by default. We use this standard configuration (no
160 pinmuxing required) and ground the pin by a button to see some
161 changes. Here's the wiring diagram
163 
167 Start the program by executing `./button` and you
'll see a new line
168 containing a continuously updated single number. `1` gets shown when
169 the button is open and `0` (zero) when the button is closed. Press
170 any key om your keyboard to end the program.
174 src/examples/button.bas
176 src/c_examples/button.c
179 io_input {#SubSecExaIoInput}
184 This example shows how to get input from digital and analog
185 subsystems. It creates a new PruIo instance configured in IO mode and
186 prints out continuously the state of all the GPIO and ADC lines. GPIO
187 data gets read from the raw data (all bits from a subsystem by a
192 No preparation is required. Optionaly you can connect the analog
193 ground P9_34 (AGND) and some of the analog input lines AIN-0 to AIN-6
194 to a source voltage in the range of 0 to 1V8 (ie. from a battery).
198 Start the program by executing `./io_input` and you'll see
199 continuously updated output like (FB version)
202 11000000000000001100000000001100
203 00111110100000010000001100000000
204 00000000000000000000000000111101
205 00000000000001000000000000000000
206 EEA0 E7D0 E630 DA00 0C80 1510 24A0 EE60
208 The first line is a
scale to support identifying the bit positions.
209 The next four lines show the state of the GPIO subsystems 0 to 3 (1 =
210 high, 0 = low). The
last line is the sampled ADC data form AIN 0 to 7
211 as hexadecimal values in 16 bit encoding.
213 You can watch the heartbeat (user LED 0) in the third line (GPIO-1,
214 bit 21). The
last analog value (AIN-7) is the measured voltage on the
215 board (it should be the
half of 3.3 V: `&hEE60 / &hFFF0 * 1.8 V =
218 To end the program press any key.
220 The C version outputs all in one line (make sure to use a wide
223 C000C004 3E810300 3D 0 E6B0 D730 C9B0 B470 F0 9A0 1EB0 EDD0
225 The first four columns are hexadecimal values of the GPIO subsystem
226 states and the following columns are the ADC lines as in the FB
231 src/examples/io_input.bas
233 src/c_examples/io_input.c
236 pwm_cap {#SubSecExaPwmCap}
241 This examples demonstrates how to perform pulse width modulated (PWM)
242 output and how to measure such a pulse train (CAP = Capture and
243 Analyse a Pulsetrain) with libpruio. The code creates a
PruIo
244 instance configured in IO mode. One header pin (
P9_21) gets
245 configured as PWM output and an other (
P9_42) as CAP input. The
246 measured pulse train data get shown in a continously updated line.
247 You can adapt the output and watch the changes in the input.
251 Pinmuxing is required
for this example, since to used pins are in
252 GPIO mode by
default. So make sure that you accordingly prepared your
253 system, see chapter \ref SecPinConfig
for details.
255 Here
's the wiring diagram
257 
261 Start the program by `sudo ./pwm_cap` and you'll see a single
262 continously updated
new line
264 Frequency: 31250 , Duty: 0.5003125
266 which shows the measured frequency and duty cycle on the input pin,
267 comming from the output pin. You can adapt the output by the
268 following keystrokes.
270 To change the duty cycle, use
284 To change the frequency (in the range of 0.5 Hz to 5.0 Hz), use
286 | :-: | :--------------------------------- |
287 | + | set maximum frequency 1 000 000 Hz |
288 | - | set manimum frequency 0.5 Hz |
289 | * | multiply frequency by 2 (double) |
290 | / | divide frequency by 2 (
half) |
291 |
m | decrease frequency by 5 (minus) |
292 |
p | increase frequency by 5 (plus) |
293 Any other key quits the program.
295 Each keystroke results in two
new lines, one
for the demands and the
296 second is continously updated with the measured stuff. Ie. when the
297 duty cycle gets changed to `30 %`, you
'll see
299 --> Frequency: 31250 , Duty: 0.3
300 Frequency: 31250 , Duty: 0.300625
302 There may be some difference between the demand and the measured
303 values due to hardware limitations, which should be small in the
304 middle of the possible frequency range and grows when you come to the
305 upper or lower edge. When you switch to 100 % (always high) or 0 %
306 (always low), there's no pulse train anymore and the frequency gets
307 shown as 0 (zero). The minimal frequency is set to 2 Hz, so after 0.5
308 seconds the measured values jump to 0 Hz / 0 %. Any output frequency
309 below 2 Hz also results in measured 0 Hz / 0 %. And in
case of 2 Hz
310 output the measured value jumps between
312 --> Frequency: 2 , Duty: 0.5
313 Frequency: 1.999974 , Duty: 0.5
317 --> Frequency: 2 , Duty: 0.5
318 Frequency: 0 , Duty: 0
323 src/examples/pwm_cap.bas
325 src/c_examples/pwm_cap.c
333 This example shows how to control a GPIO output that is not connected
334 to header pin. It creates a
PruIo structure configured in IO mode and
335 controls the user LED-3, which is placed near the ethernet connector.
339 No preparation required.
343 Start the program by `./sos` and you
'll see user LED-3 blinking in
344 SOS code (short, short, short - long, long, long - short, short,
345 short). The output looks like:
347 watch SOS code on user LED 3 (near ethernet connector)
349 execute this command to get rid of mmc1 triggers
350 sudo su && echo none > /sys/class/leds/beaglebone:green:usr3/trigger && exit
352 press any key to quit
354 The blinking code may get disturbed by the system (kernel), which is
355 also blinking the LED on mmc1 interrupts. Execute the mentioned
356 command to get rid of this interferences. (Replace 'none
' by 'mmc1
'
357 to restore the original configuration.)
359 Press any key to quit the program.
368 stepper {#SubSecExaStepper}
373 This example shows how to control a unipolar stepper motor by
374 libpruio. It creates a PruIo structure configured in IO mode and
375 prepares four GPIO lines as output. You can change motor direction
376 and speed, stop the motor and switch of all pins.
380 This example can run without any hardware preparation, but you can
381 watch only some text output changing in the console window. It's
382 better to prepare a simple stepper motor setting to see a shaft
383 turning. The hardware (motor and driver board) is available as a set
384 in good electronics stores (ie. search
for ULN2003 stepper set).
387 configured as GPIO output pins, so you
'll have to prepare your system
388 for pinmuxing capability, see section \ref SecPinConfig for details.
389 Then connect the GPIO output pins to the controler inputs, a common
390 ground and a power supply (5 V) as in the following wiring diagram
392 
394 Here's a photo of such a setting
396 
400 Start the program by `sudo ./stepper` and you
'll see some information
401 on how to control the motor
404 Controls: (other keys quit, 1 and 3 only when Direction = 0)
406 4 = rotate CW 5 = stop, hold position 6 = rotate CCW
407 1 = single step CW 2 = slower 3 = single step CCW
413 The last line gets updated continously and shows the current state of
414 the pins, the direction of the motor and the number of miliseconds
415 the program waits before the next update of the output pins. The
416 latest is equal to the speed of the motor, a high value (long sleep)
417 represents a low speed. The speed range is form 1000 steps per second
418 to two steps per second (sleep range 1 to 512). Direction can be
419 either 1 for clockwise, -1 for counter clockwise or 0 for no
420 rotation. The pins switch for half step movements, so you may see
421 either one single or two pins at high state at a time.
423 The C version shows (couldn't
get ride of that green block under Key)
425 Pins Key Direction Sleep
431 src/examples/stepper.bas
433 src/c_examples/stepper.c
436 Grafic {#SecExaGrafic}
439 The examples in
this section produce grafic output. The source code is
440 available only in FreeBASIC (folder src/examples) syntax, since C has
443 pwm_adc {#SubSecExaPwmAdc}
448 This example shows how to output a pulse width modulated (PWM) signal
449 on some header pins and how to receive that signals as ADC input in
450 IO mode. The code opens a grafic window and creates a new
PruIo
451 instance in IO mode for drawing continuously the sampled analog data
452 from channels AIN-0 to AIN-2 (step 1 to 3) as line grafic with
453 colored lines. By default it creates a
full screen window without a
454 frame. You can customize the window by setting the size as command
455 line option (ie like `./pwm_io 640x100` for width = 640 and hight =
458 You can manipulate the frequency and duty cycles of the signals and
459 choose between drawing all inputs or just the manipulated one.
463 It needs some wiring to execute
this example. The digital signals
465 the analog inputs. Since digital output is 3V3 and analog inputs are
466 maximum 1V8, we need to transform the signalsby voltage dividers. We
467 use potentiometers (RV0, RV1 and RV2)
for that purpose. The divider
468 outputs
get connected to the analog input pins (AIN-0 =
P9_39, AIN-1
469 =
P9_40 and AIN-2 =
P9_37). The potentionmeters should be liniear and
470 at least 1
k (47
k recommended). Make sure that the wipers are placed
471 in a middle position before you connect the cables.
473 
475 Here
's a photo of such a setting. The colors of the cables (red =
476 P9_14 / P9_39, green = P9_16 / P9_40 and blue = P9_42 / P9_37)
477 correspond to the colors of the lines in the wiring diagram and the
478 lines in the graphical window output of the example. Make sure to use
479 high quality potentiometers and a reliable GND connection to avoid
480 damaging the ADC subsystem by overvoltage.
482 
484 The digital lines (P9_14, P9_16 and P9_42) need pinmuxing to operate
485 in PWM mode. So you have to prepare your system for pinmuxing (see
486 Section \ref SecPinConfig) and execute the binary with administrator
491 Execute the binary with a customized window size by
493 sudo ./pwm_adc 640x150
495 and you'll see grafic window with three rectangle lines like
497 
499 which is continously up-dating the signals. (Adjust the
500 potentiometers to see three lines at different hights.)
502 The frequenz and the duty cycle of each signal can
get customized.
503 The active channel (the one to edit) is shown in the window title
504 (
P9_42 at startup). To
switch to another channel, use
506 | :-: | :------------------- |
507 | A |
P9_14 = PWMSS1-PWM-A |
508 | B |
P9_16 = PWMSS1-PWM-B |
509 | C |
P9_42 = PWMSS0-CAP |
510 To change the duty cycle, use
524 To change the frequency (in the range of 0.5 Hz to 5.0 Hz), use
526 | :-: | :--------------------------- |
527 | + | increase frequency by 0.5 Hz |
528 | - | decrease frequency by 0.5 Hz |
529 | * | set frequency to 5.0 Hz |
530 | / | set frequency to 0.5 Hz |
531 Each of the above mentioned keys reduce the grafic to the active
532 channel. To see all lines again, press
534 | :----: | :----------------------- |
535 | Return | Make all channels active |
536 Any other key quits the program.
538 You can study the differences between the available PWM subsystems.
540 The blue line comes from an independend subsystem (PWMSS0-eCAP).
541 Both parameters (frequency and duty) can
get customzed without
542 affecting the other channels. Any change becomes effective after the
543 current period is finished.
545 In contrast, the other channels (red =
P9_14 and green =
P9_16) are
546 both connected to the same subsystem (PWMSS1-eHRPWM). Both signals
547 may have individual duties, but they always operate at the same
548 frequency. A change of the duty becomes effective after the current
549 period is finished. But a change of the frequency interrupts the
550 current period and starts immediately a new period with the new
551 settings on both channels.
555 src/examples/pwm_adc.bas
558 oszi {#SubSecExaOszi}
563 This example shows how to sample ADC data. It creates a
PruIo
564 structure configured in IO mode and draws a continously updated graph
565 of the analog lines AIN-0 to AIN-7. The graph gets updated column by
566 column by the currently sampled values. You can
switch channels on or
567 off to watch just a subset. By
default it creates a
full screen
568 window without a frame. You can customize the window by setting the
569 size as command line option (ie like `./oszi 640x400`
for width = 640
574 No preparation is required. Optionaly you can connect the analog
575 ground (AGND) and some of the analog input lines AIN-0 to AIN-6 to a
576 voltage source in the range of 0 to 1V8 (ie. from a battery).
580 Start the program by executing `./oszi 640x280` and you
'll see a
583 
585 The grafic is scaled 0 V at the bottom and 1.8 V at the top. You can
586 toggle the channels on or off by pressing keys 0 to 7 (0 = AIN-0, ...
587 7 = AIN-7). The program prevents de-activating all channels (at least
588 one channel stays active). Key '+
' restores the default setting (all
589 channels active). Any other key quits the program.
591 The less channels are activated, the faster the ADC subsystem samples
592 the data. Ie. check it by connecting a constant frequency sine wave
593 (0 to maximal 1.8 V) to any channel and switch off the others one by
598 src/examples/oszi.bas
601 rb_oszi {#SubSecExaRbOszi}
606 This example shows how to sample ADC data in RB mode. It creates and
607 configures a PruIo structure and draws a continously updated graph of
608 the analog lines AIN-4 and AIN-7. The graph gets updated in one step
609 when one half of the ring buffer is filled. By default it creates a
610 full screen window without a frame. You can customize the window by
611 setting the size as command line option (ie like `./rb_oszi 640x400`
612 for width = 640 and hight = 400).
616 No preparation is required. Optionaly you can connect the analog
617 ground P_34 (AGND) and the analog input line AIN-4 to a voltage
618 source in the range of 0 to 1V8 (ie. from a battery).
622 Start the program by executing `./rb_oszi 640x280` and you'll see a
625 
627 The grafic is scaled 0 V at the bottom and 1.8 V at the top. Any
628 keypress quits the program.
632 src/examples/rb_oszi.bas
635 triggers {#SubSecExaTriggers}
640 This example shows how to use triggers to start a measurement in MM
641 mode and how to customize an ADC step (
for the analog trigger 2). It
642 opens a grafic window and creates a
new PruIo instance
for MM. By
643 default it creates a
full screen window without a frame. You can
644 customize the window by setting the size as command line option (ie
645 like `./triggers 640x400`
for width = 640 and hight = 400).
647 The example offers to choose one from of four different trigger types
649 - a digital trigger, or
650 - an analog trigger at AIN-4 line, or
651 - an analog pre-trigger at any of the active lines.
655 No pinmuxing is required, since the code uses
P8_07 in its
default
656 configuration as digital input line (GPIO input with pullup
657 resistor). To make a digital trigger
event happen, you
'll need at
658 least a cable to ground that pin.
660 For analog triggers it is sufficient to handle the input signal
661 (AIN-4) by a simple cable connected to header pin P9_33. The other
662 end will get connected to either P9_32 (VADC) or P9_34 (AGND),
663 depending on the choosen trigger event.
665 Instead of using simple cables, it's best to prepare a button
for the
666 digital trigger
event and a variable resistor (5
k to 50
k)
for the
667 analog triggers as shown in the following figure
669 
671 Here's a photo of such a setting
673 
677 First, execute the binary with a customized window size by
681 and you
'll see the following menu in an empty grafic window.
684 0 = no trigger (start immediately)
685 1 = GPIO trigger (pin P8_07)
686 2 = analog trigger (AIN-4 > 0.9 V)
687 3 = analog pre-trigger (any AIN < 0.9 V)
689 The grafic is scaled 0 V at the bottom and 1.8 V at the top. The
690 sampling rate is 1 kHz. You can start a measurement of two channels
691 (AIN-4 and AIN-7) immediately or by a trigger.
693 After choosing a trigger type (1 to 3), the program waits for the
694 trigger event. Further keystrokes (other than 0 to 3) quit the
697 The next steps depend on the trigger to test:
699 <b>0 = no trigger (start immediately)</b>
701 -# Press key 0. After a short while (less than 1 second) a black
702 and a red line show up in the window. Black = AIN-4 (open
703 connector) shows any signal and red = AIN-7 (board voltage =
704 1.65 V) is always near the top of the window.
706 -# The menu showns up again for the next test.
708 <b>1 = GPIO trigger (pin P8_07)</b>
710 -# Press key 1 to start the trigger. The window gets cleared and
711 you'll see a
new message
713 waiting
for GPIO trigger (pin
P8_07 low) ...
715 Nothing
else happens, the system is waiting
for the trigger
718 -# Press the button or use a cable to connect P8_02 (GRND) and
719 P8_07 (trigger pin). After a
short while (less than 1 second) a
720 black and a red line show up in the window. Black = AIN-4
721 (potentiometer or open connector) shows any signal and red =
722 AIN-7 (board voltage = 1.65 V) is always at the top of the
725 -
# You'll see a window like following (some input on AIN-4 here)
727 
729 -# The menu showns up again
for the next test.
731 <b>2 = analog trigger (AIN-4 > 0.9 V)</b>
733 -# Adjust the variable resistor to the P9_34 side or connect a
734 cable between P9_34 (AGND) and
P9_33 (AIN-4).
736 -
# Press key 2 to start the trigger. The window gets cleared, a
737 grey circle marks the trigger position (in the middle of the
738 left border) and you
'll see a new message
740 waiting for analog trigger (AIN-4 > 0.9 V) ...
742 Nothing else happens, the system is waiting for the trigger
745 -# Adjust the variable resistor to the P9_32 side. After you
746 reached the middle position, you'll see a window like the
747 following (here AIN-4 signal is generated manually by the
750 
752 Black = AIN-4 starts on the left side in the middle of the
753 window hight (the trigger event) and shows any signal. Red =
754 AIN-7 (board voltage = 1.65 V) is always at the top of the
755 window. The menu showns up again
for the next test.
757 In
case of no potentiometer, release the cable. The channel
758 AIN-7 will pull up the open trigger channel AIN-4 to a voltage
759 above the trigger voltage. (If
this doesn
't happen, connect the
760 cable between P9_32 (VADC) and P9_33 (AIN-4).)
762 -# The menu showns up again for the next test.
764 <b>3 = analog pre-trigger (any AIN < 0.9 V)</b>
766 -# Adjust the variable resistor to the P9_32 side or connect a cable
767 between P9_32 (VADC) and P9_33 (AIN-4).
769 -# Press key 3 to start the trigger. The window gets cleared, a
770 grey circle marks the trigger position (in the middle of the
771 window) and you'll see a
new message
773 waiting
for analog pre-trigger (any AIN < 0.9 V) ...
775 Nothing
else happens, the system is waiting
for the trigger
778 -# Adjust the variable resistor to the other side. After you
779 reached the middle position, you
'll see a window like the
780 following (here AIN-4 signal is generated manually by the
783 
785 Black = AIN-4 starts on the left side in the upper part of the
786 window and passes through the middle (the trigger event). Red =
787 AIN-7 (board voltage = 1.65 V) is always at the top of the
790 When any analog line is below 0.9 V at the start of the trigger,
791 you'll see a window like
793 
795 Here no pre-trigger samples are available (since the measurement
796 starts immediately) and these samples
get set to 0 (zero).
798 In
case of no potentionmeter, release the cable. The open
799 trigger channel AIN-4 starts to swing below the trigger voltage.
800 (If
this doesn
't happen, connect the cable between P9_34 (AGND)
803 -# The menu showns up again for the next test.
808 src/examples/triggers.bas
#define P8_05
CPU ball number for pin 5 on header 8 (emmc2)
#define P9_21
CPU ball number for pin 21 on header 9.
Main structure, binding all components together.
#define P9_42
CPU ball number for pin 42 on header 9.
#define P8_04
CPU ball number for pin 4 on header 8 (emmc2)
VAR half
The half size of the ring buffer.
#define P9_37
number of analog line on pin 37 on header 9
#define P9_16
CPU ball number for pin 16 on header 9.
#define P9_40
number of analog line on pin 40 on header 9
VAR p
The position of the 'x' character (if any).
UInt32 last[...]
The previous data of the channels.
VAR full
Fullscreen or windowed mode.
#define P8_10
CPU ball number for pin 10 on header 8.
VAR scale
The factor to scale values.
#define P8_12
CPU ball number for pin 12 on header 8.
#define P9_33
number of analog line on pin 33 on header 9
#define P8_07
CPU ball number for pin 7 on header 8.
#define P9_39
number of analog line on pin 39 on header 9
#define P8_14
CPU ball number for pin 14 on header 8.
#define P8_08
CPU ball number for pin 8 on header 8.
#define P8_03
CPU ball number for pin 3 on header 8 (emmc2)
#define P9_14
CPU ball number for pin 14 on header 9.
#define P8_06
CPU ball number for pin 6 on header 8 (emmc2)