The best way to learn a new library API is to test out some examples. A working example shows that the installation of the library components is OK. And by adapting the example source code you can easily find out if your understanding of the documentation matches reality.
So libpruio includes a bunch of examples, all of them less than 200 lines of code and some of them in FreeBASIC and in C syntax. Since C doesn't support native grafics output, C examples are only available with console text output. For all examples there're pre-compiled executables in folder src/examples.
Some examples need wiring to work and show the desired effect. Therefor a minimal knowlege on electronics is required to avoid damaging your Beaglebone board when doing the wiring. The circuits are designed for minimal hardware requirements, so you need not spend a lot of money for testing.
The examples in this section produce console text output. The source code is available in FreeBASIC (folder src/examples) and C syntax (folder src/c_examples). The output between both versions may vary a bit, in order to keep the examples informative, but the C example code simple.
Description:
This is a minimal example printing a table of some analog samples from the ADC subsystem. It illustrates the principle usage of libpruio described in section Operation by a minimal number of code lines.
Preparation:
No preparation is required. Optionaly you can connect the analog ground at P9_34 (AGND) and some of the analog input lines AIN-0 to AIN-6 to a voltage source in the range of 0 V to 1V8 (ie. from a battery).
Operation:
Start the program in the terminal by typing ./1
and press the Return key. The output is a table containing 13 lines of all analog inputs. It looks like
The last column (AIN-7) is the on board voltage divided by 2 (&hEE50 / &hFFF0 * 1,8 = 1.67 V
). The fifth column is channel AIN-4, which is connected to ground (P9_34 = AGND) during the test. The other channels are open ended.
Source Code:
Description:
This example shows how to read the subsystem configurations. It creates a PruIo structure and prints out all startup registers context (Init).
Preparation:
No preparation is required.
Operation:
Start the program in the terminal by typing ./analyse
and press the Return key. The output is a long list of text lines, like
First, all header pin configurations are shown. Then the registers of the GPIO subsystems (0 to 3) get listed, followed by the ADC subsystem registers and the registers of the PWMSS subsystems (0 to 2). It's the context of the xyzSet strctures (BallSet, GpioSet, AdcSet and PwmssSet). The code may be helpful for debugging in your projects.
Source Code:
No C source available
Description:
This example shows how to get input from a digital line. It creates a new PruIo instance cinfigured in IO mode and continuously prints out the state of a single digital lines.
Preparation:
The code uses header pin P8_07 which is configured as GPIO input with pullup resistor by default. We use this standard configuration (no pinmuxing required) and ground the pin by a button to see some changes. Here's the wiring diagram
Operation:
Start the program by executing ./button
and you'll see a new line containing a continuously updated single number. 1
gets shown when the button is open and 0
(zero) when the button is closed. Press any key om your keyboard to end the program.
Source Code:
Description:
This example shows how to get input from digital and analog subsystems. It creates a new PruIo instance configured in IO mode and prints out continuously the state of all the GPIO and ADC lines. GPIO data gets read from the raw data (all bits from a subsystem by a single operation).
Preparation:
No preparation is required. Optionaly you can connect the analog ground P9_34 (AGND) and some of the analog input lines AIN-0 to AIN-6 to a source voltage in the range of 0 to 1V8 (ie. from a battery).
Operation:
Start the program by executing ./io_input
and you'll see continuously updated output like (FB version)
The first line is a scale to support identifying the bit positions. The next four lines show the state of the GPIO subsystems 0 to 3 (1 = high, 0 = low). The last line is the sampled ADC data form AIN 0 to 7 as hexadecimal values in 16 bit encoding.
You can watch the heartbeat (user LED 0) in the third line (GPIO-1, bit 21). The last analog value (AIN-7) is the measured voltage on the board (it should be the half of 3.3 V: &hEE60 / &hFFF0 * 1.8 V = 1.676 V)
.
To end the program press any key.
The C version outputs all in one line (make sure to use a wide console window) like
The first four columns are hexadecimal values of the GPIO subsystem states and the following columns are the ADC lines as in the FB version.
Source Code:
Description:
This examples demonstrates how to perform pulse width modulated (PWM) output and how to measure such a pulse train (CAP = Capture and Analyse a Pulsetrain) with libpruio. The code creates a PruIo instance configured in IO mode. One header pin (P9_21) gets configured as PWM output and an other (P9_42) as CAP input. The measured pulse train data get shown in a continously updated line. You can adapt the output and watch the changes in the input.
Preparation:
Pinmuxing is required for this example, since to used pins are in GPIO mode by default. So make sure that you accordingly prepared your system, see chapter Pin Configuration for details.
Here's the wiring diagram
Operation:
Start the program by sudo ./pwm_cap
and you'll see a single continously updated new line
which shows the measured frequency and duty cycle on the input pin, comming from the output pin. You can adapt the output by the following keystrokes.
To change the duty cycle, use
Key | Duty |
---|---|
0 | 0 % |
1 | 10 % |
2 | 20 % |
3 | 30 % |
4 | 40 % |
5 | 50 % |
6 | 60 % |
7 | 70 % |
8 | 80 % |
9 | 90 % |
, | 100 % |
To change the frequency (in the range of 0.5 Hz to 5.0 Hz), use
Key | Function |
---|---|
+ | set maximum frequency 1 000 000 Hz |
- | set manimum frequency 0.5 Hz |
* | multiply frequency by 2 (double) |
/ | divide frequency by 2 (half) |
m | decrease frequency by 5 (minus) |
p | increase frequency by 5 (plus) |
Any other key quits the program.
Each keystroke results in two new lines, one for the demands and the second is continously updated with the measured stuff. Ie. when the duty cycle gets changed to 30 %
, you'll see
There may be some difference between the demand and the measured values due to hardware limitations, which should be small in the middle of the possible frequency range and grows when you come to the upper or lower edge. When you switch to 100 % (always high) or 0 % (always low), there's no pulse train anymore and the frequency gets shown as 0 (zero). The minimal frequency is set to 2 Hz, so after 0.5 seconds the measured values jump to 0 Hz / 0 %. Any output frequency below 2 Hz also results in measured 0 Hz / 0 %. And in case of 2 Hz output the measured value jumps between
and
Source Code:
Description:
This example shows how to control a GPIO output that is not connected to header pin. It creates a PruIo structure configured in IO mode and controls the user LED-3, which is placed near the ethernet connector.
Preparation:
No preparation required.
Operation:
Start the program by ./sos
and you'll see user LED-3 blinking in SOS code (short, short, short - long, long, long - short, short, short). The output looks like:
The blinking code may get disturbed by the system (kernel), which is also blinking the LED on mmc1 interrupts. Execute the mentioned command to get rid of this interferences. (Replace 'none' by 'mmc1' to restore the original configuration.)
Press any key to quit the program.
Source Code:
Description:
This example shows how to control a unipolar stepper motor by libpruio. It creates a PruIo structure configured in IO mode and prepares four GPIO lines as output. You can change motor direction and speed, stop the motor and switch of all pins.
Preparation:
This example can run without any hardware preparation, but you can watch only some text output changing in the console window. It's better to prepare a simple stepper motor setting to see a shaft turning. The hardware (motor and driver board) is available as a set in good electronics stores (ie. search for ULN2003 stepper set).
First, the header pins (P8_08, P8_10, P8_12 and P8_14) need to get configured as GPIO output pins, so you'll have to prepare your system for pinmuxing capability, see section Pin Configuration for details. Then connect the GPIO output pins to the controler inputs, a common ground and a power supply (5 V) as in the following wiring diagram
Here's a photo of such a setting
Operation:
Start the program by sudo ./stepper
and you'll see some information on how to control the motor
The last line gets updated continously and shows the current state of the pins, the direction of the motor and the number of miliseconds the program waits before the next update of the output pins. The latest is equal to the speed of the motor, a high value (long sleep) represents a low speed. The speed range is form 1000 steps per second to two steps per second (sleep range 1 to 512). Direction can be either 1 for clockwise, -1 for counter clockwise or 0 for no rotation. The pins switch for half step movements, so you may see either one single or two pins at high state at a time.
The C version shows (couldn't get ride of that green block under Key)
Source Code:
The examples in this section produce grafic output. The source code is available only in FreeBASIC (folder src/examples) syntax, since C has no native grafic.
Description:
This example shows how to output a pulse width modulated (PWM) signal on some header pins and how to receive that signals as ADC input in IO mode. The code opens a grafic window and creates a new PruIo instance in IO mode for drawing continuously the sampled analog data from channels AIN-0 to AIN-2 (step 1 to 3) as line grafic with colored lines. By default it creates a full screen window without a frame. You can customize the window by setting the size as command line option (ie like ./pwm_io 640x100
for width = 640 and hight = 100).
You can manipulate the frequency and duty cycles of the signals and choose between drawing all inputs or just the manipulated one.
Preparation:
It needs some wiring to execute this example. The digital signals from the PWM pins (P9_14, P9_16 and P9_42) have to be connected to the analog inputs. Since digital output is 3V3 and analog inputs are maximum 1V8, we need to transform the signalsby voltage dividers. We use potentiometers (RV0, RV1 and RV2) for that purpose. The divider outputs get connected to the analog input pins (AIN-0 = P9_39, AIN-1 = P9_40 and AIN-2 = P9_37). The potentionmeters should be liniear and at least 1 k (47 k recommended). Make sure that the wipers are placed in a middle position before you connect the cables.
Here's a photo of such a setting. The colors of the cables (red = P9_14 / P9_39, green = P9_16 / P9_40 and blue = P9_42 / P9_37) correspond to the colors of the lines in the wiring diagram and the lines in the graphical window output of the example. Make sure to use high quality potentiometers and a reliable GND connection to avoid damaging the ADC subsystem by overvoltage.
The digital lines (P9_14, P9_16 and P9_42) need pinmuxing to operate in PWM mode. So you have to prepare your system for pinmuxing (see Section Pin Configuration ) and execute the binary with administrator privileges.
Operation:
Execute the binary with a customized window size by
and you'll see grafic window with three rectangle lines like
which is continously up-dating the signals. (Adjust the potentiometers to see three lines at different hights.)
The frequenz and the duty cycle of each signal can get customized. The active channel (the one to edit) is shown in the window title (P9_42 at startup). To switch to another channel, use
Key | Channel |
---|---|
A | P9_14 = PWMSS1-PWM-A |
B | P9_16 = PWMSS1-PWM-B |
C | P9_42 = PWMSS0-CAP |
To change the duty cycle, use
Key | Duty |
---|---|
0 | 0 % |
1 | 10 % |
2 | 20 % |
3 | 30 % |
4 | 40 % |
5 | 50 % |
6 | 60 % |
7 | 70 % |
8 | 80 % |
9 | 90 % |
, | 100 % |
To change the frequency (in the range of 0.5 Hz to 5.0 Hz), use
Key | Function |
---|---|
+ | increase frequency by 0.5 Hz |
- | decrease frequency by 0.5 Hz |
* | set frequency to 5.0 Hz |
/ | set frequency to 0.5 Hz |
Each of the above mentioned keys reduce the grafic to the active channel. To see all lines again, press
Key | Function |
---|---|
Return | Make all channels active |
Any other key quits the program.
You can study the differences between the available PWM subsystems.
The blue line comes from an independend subsystem (PWMSS0-eCAP). Both parameters (frequency and duty) can get customzed without affecting the other channels. Any change becomes effective after the current period is finished.
In contrast, the other channels (red = P9_14 and green = P9_16) are both connected to the same subsystem (PWMSS1-eHRPWM). Both signals may have individual duties, but they always operate at the same frequency. A change of the duty becomes effective after the current period is finished. But a change of the frequency interrupts the current period and starts immediately a new period with the new settings on both channels.
Source Code:
Description:
This example shows how to sample ADC data. It creates a PruIo structure configured in IO mode and draws a continously updated graph of the analog lines AIN-0 to AIN-7. The graph gets updated column by column by the currently sampled values. You can switch channels on or off to watch just a subset. By default it creates a full screen window without a frame. You can customize the window by setting the size as command line option (ie like ./oszi 640x400
for width = 640 and hight = 400).
Preparation:
No preparation is required. Optionaly you can connect the analog ground (AGND) and some of the analog input lines AIN-0 to AIN-6 to a voltage source in the range of 0 to 1V8 (ie. from a battery).
Operation:
Start the program by executing ./oszi 640x280
and you'll see a window like
The grafic is scaled 0 V at the bottom and 1.8 V at the top. You can toggle the channels on or off by pressing keys 0 to 7 (0 = AIN-0, ... 7 = AIN-7). The program prevents de-activating all channels (at least one channel stays active). Key '+' restores the default setting (all channels active). Any other key quits the program.
The less channels are activated, the faster the ADC subsystem samples the data. Ie. check it by connecting a constant frequency sine wave (0 to maximal 1.8 V) to any channel and switch off the others one by one.
Source Code:
Description:
This example shows how to sample ADC data in RB mode. It creates and configures a PruIo structure and draws a continously updated graph of the analog lines AIN-4 and AIN-7. The graph gets updated in one step when one half of the ring buffer is filled. By default it creates a full screen window without a frame. You can customize the window by setting the size as command line option (ie like ./rb_oszi 640x400
for width = 640 and hight = 400).
Preparation:
No preparation is required. Optionaly you can connect the analog ground P_34 (AGND) and the analog input line AIN-4 to a voltage source in the range of 0 to 1V8 (ie. from a battery).
Operation:
Start the program by executing ./rb_oszi 640x280
and you'll see a window like
The grafic is scaled 0 V at the bottom and 1.8 V at the top. Any keypress quits the program.
Source Code:
Description:
This example shows how to use triggers to start a measurement in MM mode and how to customize an ADC step (for the analog trigger 2). It opens a grafic window and creates a new PruIo instance for MM. By default it creates a full screen window without a frame. You can customize the window by setting the size as command line option (ie like ./triggers 640x400
for width = 640 and hight = 400).
The example offers to choose one from of four different trigger types
Preparation:
No pinmuxing is required, since the code uses P8_07 in its default configuration as digital input line (GPIO input with pullup resistor). To make a digital trigger event happen, you'll need at least a cable to ground that pin.
For analog triggers it is sufficient to handle the input signal (AIN-4) by a simple cable connected to header pin P9_33. The other end will get connected to either P9_32 (VADC) or P9_34 (AGND), depending on the choosen trigger event.
Instead of using simple cables, it's best to prepare a button for the digital trigger event and a variable resistor (5 k to 50 k) for the analog triggers as shown in the following figure
Here's a photo of such a setting
Operation:
First, execute the binary with a customized window size by
and you'll see the following menu in an empty grafic window.
The grafic is scaled 0 V at the bottom and 1.8 V at the top. The sampling rate is 1 kHz. You can start a measurement of two channels (AIN-4 and AIN-7) immediately or by a trigger.
After choosing a trigger type (1 to 3), the program waits for the trigger event. Further keystrokes (other than 0 to 3) quit the program.
The next steps depend on the trigger to test:
0 = no trigger (start immediately)
1 = GPIO trigger (pin P8_07)
You'll see a window like following (some input on AIN-4 here)
2 = analog trigger (AIN-4 > 0.9 V)
Adjust the variable resistor to the P9_32 side. After you reached the middle position, you'll see a window like the following (here AIN-4 signal is generated manually by the potentiometer)
Black = AIN-4 starts on the left side in the middle of the window hight (the trigger event) and shows any signal. Red = AIN-7 (board voltage = 1.65 V) is always at the top of the window. The menu showns up again for the next test.
In case of no potentiometer, release the cable. The channel AIN-7 will pull up the open trigger channel AIN-4 to a voltage above the trigger voltage. (If this doesn't happen, connect the cable between P9_32 (VADC) and P9_33 (AIN-4).)
3 = analog pre-trigger (any AIN < 0.9 V)
Adjust the variable resistor to the other side. After you reached the middle position, you'll see a window like the following (here AIN-4 signal is generated manually by the potentiometer)
Black = AIN-4 starts on the left side in the upper part of the window and passes through the middle (the trigger event). Red = AIN-7 (board voltage = 1.65 V) is always at the top of the window.
When any analog line is below 0.9 V at the start of the trigger, you'll see a window like
Here no pre-trigger samples are available (since the measurement starts immediately) and these samples get set to 0 (zero).
In case of no potentionmeter, release the cable. The open trigger channel AIN-4 starts to swing below the trigger voltage. (If this doesn't happen, connect the cable between P9_34 (AGND) and P9_33 (AIN-4).)
Source Code: