libpruio  0.2
Input/Output driver for digital/analog lines on Beagleboard hardware
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
src/examples.md
1 Examples {#ChaExamples}
2 ========
3 \tableofcontents
4 
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.
9 
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.
15 
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
20 testing.
21 
22 
23 Text {#SecExaText}
24 ====
25 
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
30 simple.
31 
32 Simple (1) {#SubSecExaSimple}
33 ----------
34 
35 \Item{Description}
36 
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
40  of code lines.
41 
42 \Item{Preparation}
43 
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
47  battery).
48 
49 \Item{Operation}
50 
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
53  inputs. It looks like
54 ~~~{.txt}
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
68 ~~~
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.
73 
74 
75 \Item{Source Code}
76 
77  src/examples/1.bas
78 
79  src/c_examples/1.c
80 
81 
82 analyse {#SubSecExaAnalyse}
83 -------
84 
85 \Item{Description}
86 
87  This example shows how to read the subsystem configurations. It
88  creates a PruIo structure and prints out all startup registers
89  context (Init).
90 
91 \Item{Preparation}
92 
93  No preparation is required.
94 
95 \Item{Operation}
96 
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
99 ~~~{.txt}
100 Header Pins:
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
107 
108 ...
109 
110 GPIO-0 (DeAd: 44E07000, ClAd: 44E00408, ClVa: 00000002)
111  REVISION: 50600801
112  SYSCONFIG: 0000001D
113  EOI: 00000000
114 
115 ...
116 
117 ADC (DeAd: 44E0D000, ClAd: 44E004BC, ClVa: 00000002)
118  REVISION: 47300001
119  SYSCONFIG: 00000000
120  IRQSTATUS_RAW: 00000407
121 
122 ...
123 
124 PWMSS-0 (DeAd: 48300000, ClAd: 44E000D4, ClVa: 00000002)
125  IDVER: 47400001
126  SYSCONFIG: 00000008
127  CLKCONFIG: 00000111
128  CLKSTATUS: 00000111
129  eCAP
130  TSCTR: 00000000
131  CTRPHS: 00000000
132 ~~~
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
138  projects.
139 
140 \Item{Source Code}
141 
142  src/examples/analyse.bas
143 
144  No C source available
145 
146 
147 button {#SubSecExaButton}
148 ------
149 
150 \Item{Description}
151 
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.
155 
156 \Item{Preparation}
157 
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
162 
163  ![Wiring diagram for button example](button_circuit.png)
164 
165 \Item{Operation}
166 
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.
171 
172 \Item{Source Code}
173 
174  src/examples/button.bas
175 
176  src/c_examples/button.c
177 
178 
179 io_input {#SubSecExaIoInput}
180 --------
181 
182 \Item{Description}
183 
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
188  single operation).
189 
190 \Item{Preparation}
191 
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).
195 
196 \Item{Operation}
197 
198  Start the program by executing `./io_input` and you'll see
199  continuously updated output like (FB version)
200 ~~~{.txt}
201  . | . | . | . |
202 11000000000000001100000000001100
203 00111110100000010000001100000000
204 00000000000000000000000000111101
205 00000000000001000000000000000000
206 EEA0 E7D0 E630 DA00 0C80 1510 24A0 EE60
207 ~~~
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.
212 
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 =
216  1.676 V)`.
217 
218  To end the program press any key.
219 
220  The C version outputs all in one line (make sure to use a wide
221  console window) like
222 ~~~{.txt}0
223 C000C004 3E810300 3D 0 E6B0 D730 C9B0 B470 F0 9A0 1EB0 EDD0
224 ~~~
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
227  version.
228 
229 \Item{Source Code}
230 
231  src/examples/io_input.bas
232 
233  src/c_examples/io_input.c
234 
235 
236 pwm_cap {#SubSecExaPwmCap}
237 -------
238 
239 \Item{Description}
240 
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.
248 
249 \Item{Preparation}
250 
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.
254 
255  Here's the wiring diagram
256 
257  ![Wiring diagram for pwm_cap example](pwm_cap_circuit.png)
258 
259 \Item{Operation}
260 
261  Start the program by `sudo ./pwm_cap` and you'll see a single
262  continously updated new line
263 ~~~{.txt}
264  Frequency: 31250 , Duty: 0.5003125
265 ~~~
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.
269 
270  To change the duty cycle, use
271  | Key | Duty |
272  | :-: | ----: |
273  | 0 | 0 % |
274  | 1 | 10 % |
275  | 2 | 20 % |
276  | 3 | 30 % |
277  | 4 | 40 % |
278  | 5 | 50 % |
279  | 6 | 60 % |
280  | 7 | 70 % |
281  | 8 | 80 % |
282  | 9 | 90 % |
283  | , | 100 % |
284  To change the frequency (in the range of 0.5 Hz to 5.0 Hz), use
285  | Key | Function |
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.
294 
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
298 ~~~{.txt}
299 --> Frequency: 31250 , Duty: 0.3
300  Frequency: 31250 , Duty: 0.300625
301 ~~~
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
311 ~~~{.txt}
312 --> Frequency: 2 , Duty: 0.5
313  Frequency: 1.999974 , Duty: 0.5
314 ~~~
315  and
316 ~~~{.txt}
317 --> Frequency: 2 , Duty: 0.5
318  Frequency: 0 , Duty: 0
319 ~~~
320 
321 \Item{Source Code}
322 
323  src/examples/pwm_cap.bas
324 
325  src/c_examples/pwm_cap.c
326 
327 
328 sos {#SubSecExaSos}
329 ---
330 
331 \Item{Description}
332 
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.
336 
337 \Item{Preparation}
338 
339  No preparation required.
340 
341 \Item{Operation}
342 
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:
346 ~~~{.txt}
347 watch SOS code on user LED 3 (near ethernet connector)
348 
349 execute this command to get rid of mmc1 triggers
350  sudo su && echo none > /sys/class/leds/beaglebone:green:usr3/trigger && exit
351 
352 press any key to quit
353 ~~~
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.)
358 
359  Press any key to quit the program.
360 
361 \Item{Source Code}
362 
363  src/examples/sos.bas
364 
365  src/c_examples/sos.c
366 
367 
368 stepper {#SubSecExaStepper}
369 -------
370 
371 \Item{Description}
372 
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.
377 
378 \Item{Preparation}
379 
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).
385 
386  First, the header pins (P8_08, P8_10, P8_12 and P8_14) need to get
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
391 
392  ![Wiring diagram for stepper example](stepper_circuit.png)
393 
394  Here's a photo of such a setting
395 
396  ![Setting for stepper example](stepper_foto.jpg)
397 
398 \Item{Operation}
399 
400  Start the program by `sudo ./stepper` and you'll see some information
401  on how to control the motor
402 ~~~{.txt}
403 
404 Controls: (other keys quit, 1 and 3 only when Direction = 0)
405  8 = faster
406  4 = rotate CW 5 = stop, hold position 6 = rotate CCW
407  1 = single step CW 2 = slower 3 = single step CCW
408  0 = stop, power off
409 
410 Pins Direction Sleep
411 1-0-0-1 0 128
412 ~~~
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.
422 
423  The C version shows (couldn't get ride of that green block under Key)
424 ~~~{.txt}
425 Pins Key Direction Sleep
426 1-0-0-1 0 128
427 ~~~
428 
429 \Item{Source Code}
430 
431  src/examples/stepper.bas
432 
433  src/c_examples/stepper.c
434 
435 
436 Grafic {#SecExaGrafic}
437 ======
438 
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
441 no native grafic.
442 
443 pwm_adc {#SubSecExaPwmAdc}
444 -------
445 
446 \Item{Description}
447 
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 =
456  100).
457 
458  You can manipulate the frequency and duty cycles of the signals and
459  choose between drawing all inputs or just the manipulated one.
460 
461 \Item{Preparation}
462 
463  It needs some wiring to execute this example. The digital signals
464  from the PWM pins (P9_14, P9_16 and P9_42) have to be connected to
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.
472 
473  ![Wiring diagram for pwm_adc example](pwm_adc_circuit.png)
474 
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.
481 
482  ![Setting for pwm_adc example](pwm_adc_foto.jpg)
483 
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
487  privileges.
488 
489 \Item{Operation}
490 
491  Execute the binary with a customized window size by
492 ~~~{.txt}
493 sudo ./pwm_adc 640x150
494 ~~~
495  and you'll see grafic window with three rectangle lines like
496 
497  ![3 PWM outputs at 2.5 Hz (red = P9_14@50%, green = P9_16@20% and blue = P9_42@80%)](pwm_adc_screen.png)
498 
499  which is continously up-dating the signals. (Adjust the
500  potentiometers to see three lines at different hights.)
501 
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
505  | Key | Channel |
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
511  | Key | Duty |
512  | :-: | ----: |
513  | 0 | 0 % |
514  | 1 | 10 % |
515  | 2 | 20 % |
516  | 3 | 30 % |
517  | 4 | 40 % |
518  | 5 | 50 % |
519  | 6 | 60 % |
520  | 7 | 70 % |
521  | 8 | 80 % |
522  | 9 | 90 % |
523  | , | 100 % |
524  To change the frequency (in the range of 0.5 Hz to 5.0 Hz), use
525  | Key | Function |
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
533  | Key | Function |
534  | :----: | :----------------------- |
535  | Return | Make all channels active |
536  Any other key quits the program.
537 
538  You can study the differences between the available PWM subsystems.
539 
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.
544 
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.
552 
553 \Item{Source Code}
554 
555  src/examples/pwm_adc.bas
556 
557 
558 oszi {#SubSecExaOszi}
559 ----
560 
561 \Item{Description}
562 
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
570  and hight = 400).
571 
572 \Item{Preparation}
573 
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).
577 
578 \Item{Operation}
579 
580  Start the program by executing `./oszi 640x280` and you'll see a
581  window like
582 
583  ![Screenshot of the oszi window (eight analog lines)](oszi_screen.png)
584 
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.
590 
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
594  one.
595 
596 \Item{Source Code}
597 
598  src/examples/oszi.bas
599 
600 
601 rb_oszi {#SubSecExaRbOszi}
602 -------
603 
604 \Item{Description}
605 
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).
613 
614 \Item{Preparation}
615 
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).
619 
620 \Item{Operation}
621 
622  Start the program by executing `./rb_oszi 640x280` and you'll see a
623  window like
624 
625  ![Screenshot of the rb_oszi window (two analog lines)](rb_oszi_screen.png)
626 
627  The grafic is scaled 0 V at the bottom and 1.8 V at the top. Any
628  keypress quits the program.
629 
630 \Item{Source Code}
631 
632  src/examples/rb_oszi.bas
633 
634 
635 triggers {#SubSecExaTriggers}
636 --------
637 
638 \Item{Description}
639 
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).
646 
647  The example offers to choose one from of four different trigger types
648  - no trigger, or
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.
652 
653 \Item{Preparation}
654 
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.
659 
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.
664 
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
668 
669  ![Wiring diagram for digital (button) and analog (variable resistor) triggers](triggers_circruit.png)
670 
671  Here's a photo of such a setting
672 
673  ![Setting for triggers example](triggers_foto.jpg)
674 
675 \Item{Operation}
676 
677  First, execute the binary with a customized window size by
678 ~~~{.txt}
679 ./triggers 640x280
680 ~~~
681  and you'll see the following menu in an empty grafic window.
682 ~~~{.txt}
683 Choose trigger type
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)
688 ~~~
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.
692 
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
695  program.
696 
697  The next steps depend on the trigger to test:
698 
699  <b>0 = no trigger (start immediately)</b>
700 
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.
705 
706  -# The menu showns up again for the next test.
707 
708  <b>1 = GPIO trigger (pin P8_07)</b>
709 
710  -# Press key 1 to start the trigger. The window gets cleared and
711  you'll see a new message
712 ~~~{.txt}
713 waiting for GPIO trigger (pin P8_07 low) ...
714 ~~~
715  Nothing else happens, the system is waiting for the trigger
716  event.
717 
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
723  window.
724 
725  -# You'll see a window like following (some input on AIN-4 here)
726 
727  ![Analog input on AIN-4 (black = any signal) and AIN-7 (red = 1.65 V on board)](triggers_pin.png)
728 
729  -# The menu showns up again for the next test.
730 
731  <b>2 = analog trigger (AIN-4 > 0.9 V)</b>
732 
733  -# Adjust the variable resistor to the P9_34 side or connect a
734  cable between P9_34 (AGND) and P9_33 (AIN-4).
735 
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
739 ~~~{.txt}
740 waiting for analog trigger (AIN-4 > 0.9 V) ...
741 ~~~
742  Nothing else happens, the system is waiting for the trigger
743  event.
744 
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
748  potentiometer)
749 
750  ![Analog input on AIN-4 (black = trigger signal) and AIN-7 (red = 1.65 V on board)](triggers_ain.png)
751 
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.
756 
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).)
761 
762  -# The menu showns up again for the next test.
763 
764  <b>3 = analog pre-trigger (any AIN < 0.9 V)</b>
765 
766  -# Adjust the variable resistor to the P9_32 side or connect a cable
767  between P9_32 (VADC) and P9_33 (AIN-4).
768 
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
772 ~~~{.txt}
773 waiting for analog pre-trigger (any AIN < 0.9 V) ...
774 ~~~
775  Nothing else happens, the system is waiting for the trigger
776  event.
777 
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
781  potentiometer)
782 
783  ![Valid pre-trigger input on AIN-4 (black = trigger signal) and AIN-7 (red = 1.65 V on board)](triggers_pre_full.png)
784 
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
788  window.
789 
790  When any analog line is below 0.9 V at the start of the trigger,
791  you'll see a window like
792 
793  ![Invalid pre-trigger samples (black = trigger signal AIN-4 below 0.9 V)](triggers_pre_empty.png)
794 
795  Here no pre-trigger samples are available (since the measurement
796  starts immediately) and these samples get set to 0 (zero).
797 
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)
801  and P9_33 (AIN-4).)
802 
803  -# The menu showns up again for the next test.
804 
805 
806 \Item{Source Code}
807 
808  src/examples/triggers.bas
#define P8_05
CPU ball number for pin 5 on header 8 (emmc2)
Definition: pruio_pins.bi:21
#define P9_21
CPU ball number for pin 21 on header 9.
Definition: pruio_pins.bi:126
Main structure, binding all components together.
Definition: pruio.bi:118
#define P9_42
CPU ball number for pin 42 on header 9.
Definition: pruio_pins.bi:150
VAR k
The key code.
Definition: oszi.bas:91
#define P8_04
CPU ball number for pin 4 on header 8 (emmc2)
Definition: pruio_pins.bi:19
VAR half
The half size of the ring buffer.
Definition: rb_oszi.bas:87
#define P9_37
number of analog line on pin 37 on header 9
Definition: pruio_pins.bi:157
#define P9_16
CPU ball number for pin 16 on header 9.
Definition: pruio_pins.bi:116
#define P9_40
number of analog line on pin 40 on header 9
Definition: pruio_pins.bi:155
VAR p
The position of the 'x' character (if any).
Definition: oszi.bas:28
UInt32 last[...]
The previous data of the channels.
Definition: oszi.bas:59
VAR full
Fullscreen or windowed mode.
Definition: oszi.bas:24
#define P8_10
CPU ball number for pin 10 on header 8.
Definition: pruio_pins.bi:31
VAR scale
The factor to scale values.
Definition: oszi.bas:80
VAR m
The step mask.
Definition: oszi.bas:93
#define P8_12
CPU ball number for pin 12 on header 8.
Definition: pruio_pins.bi:35
#define P9_33
number of analog line on pin 33 on header 9
Definition: pruio_pins.bi:161
#define P8_07
CPU ball number for pin 7 on header 8.
Definition: pruio_pins.bi:25
#define P9_39
number of analog line on pin 39 on header 9
Definition: pruio_pins.bi:153
#define P8_14
CPU ball number for pin 14 on header 8.
Definition: pruio_pins.bi:39
#define P8_08
CPU ball number for pin 8 on header 8.
Definition: pruio_pins.bi:27
#define P8_03
CPU ball number for pin 3 on header 8 (emmc2)
Definition: pruio_pins.bi:17
#define P9_14
CPU ball number for pin 14 on header 9.
Definition: pruio_pins.bi:112
#define P8_06
CPU ball number for pin 6 on header 8 (emmc2)
Definition: pruio_pins.bi:23