Driving Small DC Motors (up to 1.5 A)

There are many more recently introduced drivers that can drive even larger currents using smaller package sizes than the SN754410. In this example, a DRV8835 dual low-voltage motor driver carrier on a breakout board ($4) from www.pololu.com is used, as illustrated in Figure 9-4. The DRV8835 itself is only 2 mm × 3 mm in dimension and can drive 1.5 A (max) per H-bridge at a motor supply voltage up to 11 V. It can be driven with logic levels of 2 V to 7 V, which enables it to be used directly with a Beagle board.

The DRV8835 breakout board can be connected to the BeagleBone as illustrated in Figure 9-4. This circuit uses four pins from the BeagleBone:

• P9_3 provides a 3.3 V supply for the control logic circuitry.
• P9_45 provides a GND for the logic supply circuitry.
• P9_42 provides a PWM output from the BeagleBone that can be used to control the rotation speed of the motor, as it is connected to the A_ENABLE input on the DRV8835.
• P9_41 provides a GPIO output that can be used to set whether the motor is rotating clockwise or counterclockwise, as it is connected to the A_PHASE input.

The motor power supply voltage is set according to the specification of the DC motor that is chosen. By tying the Mode pin high, the DRV8835 is placed in PHASE/ENABLE mode, which means that one input is used for direction, and the other is used for determining the rotation speed.

Controlling a DC Motor Using sysfs

With a circuit wired as shown in Figure 9-4, the DC motor can be controlled using sysfs. In this example, P9_41 (GPIO3_20 = 116) is connected to the A_PHASE input. Therefore, this pin can be enabled, and the motor's direction of rotation can be controlled using the following:

debian@ebb:~$ config-pin -a P9_41 out
debian@ebb:~$ config-pin -q P9_41
P9_41 Mode: gpio Direction: out Value: 0
debian@ebb:~$ cd /sys/class/gpio/gpio116
debian@ebb:/sys/class/gpio/gpio116$ ls
active_low  device  direction  edge  label  power  subsystem  uevent  value
debian@ebb:/sys/class/gpio/gpio116$ echo out > direction
debian@ebb:/sys/class/gpio/gpio116$ echo 1 > value
debian@ebb:/sys/class/gpio/gpio116$ echo 0 > value 

The speed of the motor can be controlled using a BeagleBone PWM output. The overlays can be loaded, and the motor can be controlled using the PWM overlay that is associated with P9_42, as follows:

debian@ebb:~$ config-pin -l P9_42
default gpio gpio_pu gpio_pd gpio_input spi_cs spi_sclk uart pwm pru_ecap
debian@ebb:~$ config-pin -a P9_42 pwm
debian@ebb:~$ config-pin -q P9_42 pwm
P9_42 Mode: pwm
debian@ebb:~$ cd /sys/class/pwm
debian@ebb:/sys/class/pwm$ ls
pwmchip0  pwmchip1  pwmchip3  pwmchip5  pwmchip6 

As described in Chapter 6, P9_42 is connected to ECAP0, which is mapped to the pwmchip0 device. This device must be enabled and configured, whereupon modifying the duty cycle will control the rotation speed of the motor.

debian@ebb:/sys/class/pwm$ cd pwmchip0
debian@ebb:/sys/class/pwm/pwmchip0$ ls
device  export  npwm  power  subsystem  uevent  unexport
debian@ebb:/sys/class/pwm/pwmchip0$ echo 0 > export
debian@ebb:/sys/class/pwm/pwmchip0$ ls
device  export  npwm  power  pwm-0:0  subsystem  uevent  unexport
debian@ebb:/sys/class/pwm/pwmchip0$ cd pwm-0:0/
debian@ebb:/sys/class/pwm/pwmchip0/pwm-0:0$ ls
capture  device  duty_cycle  enable  period  polarity  power  subsystem  uevent
debian@ebb:/sys/class/pwm/pwmchip0/pwm-0:0$ sudo sh -c "echo 4000 > period"
debian@ebb:/sys/class/pwm/pwmchip0/pwm-0:0$ sudo sh -c "echo 1000 > duty_cycle"
debian@ebb:/sys/class/pwm/pwmchip0/pwm-0:0$ cat polarity
normal
debian@ebb:/sys/class/pwm/pwmchip0/pwm-0:0$ sudo sh -c "echo 1 > enable"
debian@ebb:/sys/class/pwm/pwmchip0/pwm-0:0$ sudo sh -c "echo 2000 > duty_cycle"
debian@ebb:/sys/class/pwm/pwmchip0/pwm-0:0$ sudo sh -c "echo 4000 > duty_cycle"
debian@ebb:/sys/class/pwm/pwmchip0/pwm-0:0$ sudo sh -c "echo 0 > enable" 

Here, the PWM frequency is set to 250 kHz, and the duty cycle is adjusted from 25 percent to 50 percent and then to 100 percent, changing the rotation speed of the motor accordingly. As with servo motors, DC motors should be controlled with the PWM polarity set to normal (as opposed to inversed) so that the duty period represents the time when the pulse is high rather than low. The direction of rotation can be adjusted at any stage using the gpio116 sysfs directory.

Driving Larger DC Motors (Greater than 1.5  A)

The Pololu Simple Motor Controller family ($30–$55), illustrated in Figure 9-5(a), supports powerful brushed DC motors with continuous currents of up to 23 A and maximum voltages of 34 V. It supports USB, TTL serial, analog, and hobby radio-control (RC) PWM interfaces. The controller uses 3.3 V logic levels, but it is also 5 V tolerant.

Despite its name, this is an advanced controller that can be configured with settings such as maximum acceleration/deceleration, adjustable starting speed, electronic braking, over-temperature threshold/response, etc., which makes it a good choice for larger-scale robotic applications. The controller can be configured using a Windows GUI application, as illustrated in Figure 9-5(b), or by using a Linux command-line user interface. The Windows configuration tool can also be used to monitor motor temperature and voltage conditions and control the speed settings, braking, PWM, communications settings, and so on, over USB, even while the motor is connected to the Beagle board with a TTL serial interface.

The 3.3 V TTL serial interface is likely the best option for embedded applications, as it can be used directly with a UART device. A UART device can be utilized for communication, as described in Chapter 8.

The Simple Motor Controller can be configured to be in a serial ASCII mode, whereupon it can be controlled using a UART device from the Beagle board with minicom. For example, with ASCII mode enabled and a fixed baud rate of 115,200 (8N1) set in the Input Settings tab (see Figure 9-5(b)), the board can connect directly to the motor controller and issue text-based commands to control the motor, such as V (version), F (forward), B (brake), R (reverse), GO (exit safe-start mode), X (stop), and so on. See the comprehensive manual for the full list of commands (tiny.cc/beagle902).

debian@ebb:/dev$ minicom -b 115200 -o -D /dev/ttyO4
V
!161 01.04
GO
.
F 50%
.
B
?
GO
.
R 25%
. 

The Simple Motor Controller can also be controlled directly using the C/C++ UART communications code that is described in Chapter 8. The configuration tool can be used to set the serial TTL mode to be Binary mode with a baud rate of 115,200. Assuming the motor controller is attached to /dev/ttyO4 (as shown previously), the motor.c code example in the /chp09/simple/ directory can be used to control the motor directly.

debian@ebb:~/exploringbb/chp09/simple$ gcc motor.c -o motor
debian@ebb:~/exploringbb/chp09/simple$ ./motor
Starting the motor controller example
Error status: 0x0000
Current Target Speed is 0.
Setting Target Speed to 3200. 

Controlling a DC Motor Using C++

A C++ class that you can use to control a DC motor is available in the GitHub repository. The constructor expects a named PWM input, which has already been configured via sysfs, and a GPIO object or GPIO number. Listing 9-1 displays the C++ header file for the DCMotor class.

class DCMotor {
public:
   enum DIRECTION{ CLOCKWISE, ANTICLOCKWISE };
private:
   …
public:
   DCMotor(PWM *pwm, GPIO *gpio);
   DCMotor(PWM *pwm, int gpioNumber);
   DCMotor(PWM *pwm, GPIO *gpio, DCMotor::DIRECTION direction);
   DCMotor(PWM *pwm, int gpioNumber, DCMotor::DIRECTION direction);
   DCMotor(PWM *pwm, GPIO *gpio, DCMotor::DIRECTION direction, float speedPercent);
   DCMotor(PWM *pwm, int gpioNumber, DCMotor::DIRECTION direction, float speedPercent);
   virtual void go();
   virtual void setSpeedPercent(float speedPercent);
   virtual float getSpeedPercent() { return this->speedPercent; }
   virtual void setDirection(DIRECTION direction);
   virtual DIRECTION getDirection() { return this->direction; }
   virtual void reverseDirection();
   virtual void stop();
   virtual void setDutyCyclePeriod(unsigned int period_ns);
   virtual ~DCMotor();
}; 

An example application that uses the DCMotor class is provided in Listing 9-2. Notice that the header file is in the motor subdirectory.

#include <iostream>
#include <unistd.h>
#include "motor/DCMotor.h"
using namespace std;
using namespace exploringBB;
 
int main(){
   cout << "Starting EBB DC Motor Example" << endl;
   DCMotor dcm(new PWM("pwmchip0/pwm-0:0/"), 116); // exports GPIO116
   dcm.setDirection(DCMotor::ANTICLOCKWISE);
   dcm.setSpeedPercent(50.0f);   //make it clear that a float is passed
   dcm.go();
   cout << "Rotating Anticlockwise at 50% speed" << endl;
   usleep(5000000);    //sleep for 5 seconds
   dcm.reverseDirection();
   cout << "Rotating clockwise at 50% speed" << endl;
   usleep(5000000);
   dcm.setSpeedPercent(100.0f);
   cout << "Rotating clockwise at 100% speed" << endl;
   usleep(5000000);
   dcm.stop();
   cout << "End of EBB DC Motor Example" << endl;
} 

The build script assumes that the example application source is in /exporingbb/chp09/dcmotor/ and that the shared library and header files are in the directory /exploringbb/library/. This conforms to the directory structure of the GitHub repository. The code can be built using the build script that is in the dcmotor directory and executed using the following:

debian@ebb:~/exploringbb/chp09/dcmotor$ more build 
#!/bin/bash
g++ DCMotorApp.cpp ../../library/libEBBLibrary.so -o DCApp -I "../../library"
debian@ebb:~/exploringbb/chp09/dcmotor$ ./build 
debian@ebb:~/exploringbb/chp09/dcmotor$ ls     
DCApp  DCMotorApp.cpp  build
debian@ebb:~/exploringbb/chp09/dcmotor$ sudo ./DCApp 
Starting EBB DC Motor Example
Rotating Anti-clockwise at 50% speed
Rotating clockwise at 50% speed
Rotating clockwise at 100% speed
End of EBB DC Motor Example 

At the end of this chapter a description is provided that shows how to build code into dynamic libraries, such as libEBBLibrary.so. This enables you to alter the library to suit your requirements.

The EasyDriver Stepper Motor Driver

An easy way to generate the stepper motor pulse signals is to use a stepper-motor driver board. The EasyDriver board (illustrated in Figure 9-7) is a low-cost (~$15) open-hardware stepper motor driver board that is widely available. It can be used to drive four-, six-, and eight-wire stepper motors. The board has an output drive capability of between 7 V and 30 V at ±750 mA per phase. The board uses the Allegro A3967 Microstepping Driver with Translator, which allows for full, half, quarter, and one-eighth step microstepping modes. In addition, the board can be driven with 5 V or 3.3 V logic levels, which makes it an ideal board for use with the Beagle boards. For 3.3 V logic control levels, there is a jumper (SJ2) that has to be solder bridged.

The merit in examining this board is that many boards can be used for higher-powered stepper motors that have a similar design.

A Beagle Board Stepper Motor Driver Circuit

The EasyDriver board can be connected to the PocketBeagle as illustrated in Figure 9-8, using GPIOs for each of the control signals. The pins on the EasyDriver board are described in Figure 9-7, and a table is provided in the figure for the MS1/MS2 inputs. A C++ class called StepperMotor is available that accepts alternative GPIO numbers.

Controlling a Stepper Motor Using C++

Listing 9-3 presents the description of a class that can be used to control the EasyDriver board using five PocketBeagle GPIO pins. This code can be adapted to drive most types of stepper driver boards from any Beagle board.

class StepperMotor {
public:
   enum STEP_MODE { STEP_FULL, STEP_HALF, STEP_QUARTER, STEP_EIGHT };
   enum DIRECTION { CLOCKWISE, ANTICLOCKWISE };
private:
   // The GPIO pins MS1, MS2 (Microstepping options), STEP (The low->high step)
   // SLP (Sleep - active low) and DIR (Direction)
   GPIO *gpio_MS1, *gpio_MS2, *gpio_STEP, *gpio_SLP, *gpio_DIR;
   …
public:
   StepperMotor(GPIO *gpio_MS1, GPIO *gpio_MS2, GPIO *gpio_STEP, GPIO *gpio_SLP,
               GPIO *gpio_DIR, int speedRPM = 60, int stepsPerRevolution = 200);
   StepperMotor(int gpio_MS1, int gpio_MS2, int gpio_STEP, int gpio_SLP,
               int gpio_DIR, int speedRPM = 60, int stepsPerRevolution = 200);
   virtual void  step();
   virtual void  step(int numberOfSteps);
   virtual int   threadedStepForDuration(int numberOfSteps, int duration_ms);
   virtual void  threadedStepCancel() { this->threadRunning = false; }
   virtual void  rotate(float degrees);
   virtual void  setDirection(DIRECTION direction);
   virtual DIRECTION getDirection() { return this->direction; }
   virtual void  reverseDirection();
   virtual void  setStepMode(STEP_MODE mode);
   virtual STEP_MODE getStepMode() { return stepMode; }
   virtual void  setSpeed(float rpm);
   virtual float getSpeed() { return speed; }
   virtual void  setStepsPerRevolution(int steps) { stepsPerRevolution = steps; }
   virtual int   getStepsPerRevolution() { return stepsPerRevolution; }
   virtual void  sleep();
   virtual void  wake();
   virtual bool  isAsleep() { return asleep; }
   virtual ~StepperMotor();
   …   //Full code available in /library/motor/StepperMotor.h
}; 

The library code is used in Listing 9-4 to create a StepperMotor object and rotate the motor counterclockwise 10 times at full-step resolution. It then uses a threaded step function to microstep the stepper motor clockwise for one full revolution over five seconds at one-eighth step resolution.

#include <iostream>
#include <unistd.h>
#include "motor/StepperMotor.h"
using namespace std;
using namespace exploringBB;
 
int main(){
   cout << "Starting EBB Stepper Motor Example:" << endl;
   //Using 5 GPIOs, RPM=60 and 200 steps per revolution
   //MS1=52, MS2=44, STEP=64, SLP=60, DIR=46
   StepperMotor m(52,44,64,60,46,60,200);
   m.setDirection(StepperMotor::ANTICLOCKWISE);
   m.setStepMode(StepperMotor::STEP_FULL);
   m.setSpeed(100);  //rpm
   cout << "Rotating 10 times at 100 rpm anti-clockwise, full step…" << endl;
   m.rotate(3600.0f);   //in degrees
   cout << "Finished regular (non-threaded) rotation)" << endl;
   m.setDirection(StepperMotor::CLOCKWISE);
   cout << "Performing 1 threaded revolution in 5 seconds using micro-stepping:" << endl;
   m.setStepMode(StepperMotor::STEP_EIGHT);
   if(m.threadedStepForDuration(1600, 5000)<0){
      cout << "Failed to start the Stepper Thread" << endl;
   }
   cout << "Thread should now be running…" << endl;
      for(int i=0; i<10; i++){ // sleep for 10 seconds.
      usleep(1000000);
      cout << i+1 << " seconds has passed…" << endl;
   }
   m.sleep();   // cut power to the stepper motor
   cout << "End of Stepper Motor Example" << endl;
} 

After calling the associated build script, the program can be executed and should result in the following output:

debian@ebb:~/exploringbb/chp09/stepper$ ./StepperApp 
Starting EBB Stepper Motor Example:
Rotating 10 times at 100 rpm anti-clockwise, full step…
Finished regular (non-threaded) rotation)
Performing 1 threaded revolution in 5 seconds using micro-stepping:
Thread should now be running…
1 seconds has passed…
2 seconds has passed…
…
10 seconds has passed…
End of Stepper Motor Example 

It is important to note that the threaded revolution completes the revolution after five seconds. The counter continues for a further five seconds, during which time a holding torque is applied. The final call to m.sleep() removes power from the stepper motor coils, thus removing holding torque.

It is possible to further reduce the number of pins that are used in this motor controller example by using 74HC595 ICs and the SPI bus, as described in Chapter 8.

Diode Clamping

Figure 9-10(a) illustrates a simple diode clamping circuit that is typically used to limit voltage levels applied to ADCs. The circuit consists of two diodes and a current limiting resistor. The diodes are reverse biased when the voltage level is within the range 0 V to Vref. Current flows to the notional AIN0 input, and the circuit behaves correctly as illustrated in Figure 9-10(b) when a sine wave is applied (V_IN ) that oscillates within the 0 V to Vref range. However, if V_IN exceeds the Vref level (plus the forward voltage drop of the diode), then the upper diode is forward biased and current would flow to the Vref rail. If Vref is 1.8 V and silicon diodes are used (~0.7 V forward voltage), then this signal will be clamped at 2.5 V. For the lower diode, if V_IN falls below 0 V–0.7 V, then the diode will be forward biased and AGND will source current. The resistor R can be used to limit the upper current level. The resulting clamped output is illustrated in Figure 9-10(c) when a sine wave is applied to the input that exceeds the permitted range.

The clamping circuit in Figure 9-10(a) is not recommended for use with the AM335x for two reasons. First, the forward voltage drop of a typical silicon diode extends the nonclamped range to approximately -0.7 V to 2.5 V, which is well outside acceptable levels. More expensive Schottky diodes can be used that have a forward voltage drop of about 0.25 V at 2 mA and 25°C (e.g., the 1N5817G). These would bring the effective output range to about -0.25 V to 2.05 V, which is better but still not ideal. The second reason is that when clamping occurs, the current would need to be sourced from or sinked to the Beagle board's AGND or Vref rails. Sinking current to the Vref rail could damage the Vref input and/or affect the reference voltage level. However, diode clamping is preferable to no protection whatsoever.

Op-Amp Clamping

A recommended circuit to protect the ADC circuitry is presented in Figure 9-11(a). While it appears complex, it is reasonably easy to connect, as it requires only three ICs and seven resistors to protect all seven or eight AINs. This voltage follower circuit uses a 5 V powered single op-amp package to provide a 1.8 V voltage reference source to an array of low-voltage op-amps. The Microchip MCP6001/2 or LM358 can be used for this voltage supply task.

An array of modern op-amps, supplied at 1.8 V (i.e., V_CC+ = 1.8 V), are configured in voltage follower configuration and placed in front of each of the ADC inputs AIN0 to AIN6/7. You can use a 3.3 V reference voltage for the AIN5 and AIN6 inputs on the PocketBeagle.

These op-amps are supplied with V_DD = V_CC+ = 1.8 V and V_SS = V_CC- = GND, so it is not possible for their output voltage levels to exceed the range 0 V to 1.8 V. The MCP600x is a low-cost DIP packaged op-amp that is suitable for this role. In particular, the MCP6004 has four op-amps within the one package, so only two MCP6004s (plus the 1.8 V supply circuit op-amp) are required to protect all seven/eight ADC inputs.

Figure 9-11(b) illustrates the behavior of this circuit when a 0.9 V amplitude sine wave (biased at +0.9 V) is applied to the Analog0 circuit input. The output signal overlays precisely on the input signal. Older op-amps (including the LM358) would have difficulty with this type of rail-to-rail operation (i.e., 0 V to 1.8 V) and would behave in a nonlinear way near the rail voltages. As shown in the plot of the Analog0 input versus the AIN0 output in Figure 9-11(b), there is a strong linear relationship, even at the supply rail voltage levels. Figure 9-11(c) and (d) illustrate the consequence of the input signal (accidently) exceeding the allowable range. In both cases the output is clamped to the 0 V to 1.8 V range and the AM335x ADC is protected, though (of course) the signal input to the ADC is distorted.

The circuit can be connected to the Beagle board as illustrated in Figure 9-11(a), and its impact can be evaluated in a terminal using the following steps (e.g., on the PocketBeagle):

debian@ebb:~$ cd /sys/bus/iio/devices/iio:device0
debian@ebb:/sys/bus/iio/devices/iio:device0$ ls
buffer           in_voltage2_raw  in_voltage6_raw  power
dev              in_voltage3_raw  in_voltage7_raw  scan_elements
in_voltage0_raw  in_voltage4_raw  name             subsystem
in_voltage1_raw  in_voltage5_raw  of_node          uevent 

Setting the DC voltage levels at Analog0 (P1.19) to be 0 V (P1.19 connected to P1.17 VREFN), 0.9 V, 1.8 V, and 2.1 V results in the respective raw input values from the 12-bit ADC (0-4095) as follows:

debian@ebb:/sys/bus/iio/devices/iio:device0$ cat in_voltage0_raw
0
debian@ebb:/sys/bus/iio/devices/iio:device0$ cat in_voltage0_raw
2107
debian@ebb:/sys/bus/iio/devices/iio:device0$ cat in_voltage0_raw
4026
debian@ebb:/sys/bus/iio/devices/iio:device0$ cat in_voltage0_raw
4024 

The 100  kΩ resistor ensures that current flows to GND through the resistor rather than through the AINx input. (For your reference, the Touchscreen Controller ADC functional block diagram is shown in Figure 12-2 of the AM335x TRM.) The AM335x datasheet at tiny.cc/beagle903 provides further details about the limitations of the AM335x ADC.

Scaling Using Voltage Division

The voltage divider circuit described at the beginning of Chapter 4 can be used to condition a sensor output. If the output voltage from the sensor is greater than 1.8 V but not less than 0 V, then a voltage divider circuit can be used to linearly reduce the voltage to remain within a 0 V–1.8 V range.

Figure 9-13 illustrates a voltage division circuit and its integration with the 1.8 V op-amp protection circuitry discussed in the previous section. Voltage follower circuits also act as buffer circuits. The maximum input impedance of the AM335x ADC inputs ranges from about 76 kΩ at the highest frequencies to many megaohms at low frequencies.³ The voltage divider circuit will further load the sensor output impedance (perhaps requiring further unity-gain buffers before the voltage divider). However, the MCP6002 will act as a buffer that prevents the sensor circuit from exceeding the maximum input impedance of the ADC (remember that ideal voltage follower circuits have infinite input impedance and zero output impedance). There are some important points to note about this circuit:

• Resistors have a manufacturing tolerance (often 5%–10% of the resistance value), which will affect the scaling accuracy of the voltage division circuit. You may need to experiment with combinations or use a potentiometer to adjust the resistance ratio.
• A capacitor C₁ can be added across V_OUT to reduce noise if required. The value of C₁ can be chosen according to the value of R₁ and the desired cutoff frequency f_C, according to the equation , where . (i.e., R₁ in parallel with R₂). There is an example in the next section.
• With multi-op-amp packages, unused inputs should be connected as shown in Figure 9-13 (in light gray) to avoid random switching noise.

This circuit works well for linearly scaling down an input signal, but it would not work for a zero-centered or negatively biased input signal. For that, a more general and slightly more complex op-amp circuit is required.

Signal Offsetting and Scaling

Figure 9-14(a) provides a general op-amp circuit that can be used to set the gain and offset of an input signal. Do not connect this circuit directly to the Beagle board—it is designed as an adjustable prototyping circuit to use in conjunction with an oscilloscope to design a fixed-signal conditioning circuit for your particular application. Some notes on this circuit:

• The Vcc- input of the op-amp is tied to GND, which is representative of the type of circuit that is built using the Beagle boards, as a –5 V rail is not readily available.
• If an LM358 is used, then a load resistor is required to prevent the output from being clamped below 0.7 V. According to the National Semiconductor Corporation (1994), “the LM358 output voltage needs to raise approximately one diode drop above ground to bias the on-chip vertical PNP transistor for output current sinking applications.”
• The 1.8 V level can be provided by the analog voltage reference on the Beagle boards, but do not connect it without the use of a voltage follower circuit as shown earlier. Alternatively, a voltage divider could be used with the 5 V rail.
• A 100 nF decoupling capacitor can be used on the V_IN input to remove the DC component of the incoming sensor signal. However, for many sensor circuits, the DC component of the sensor signal is important and should not be removed.

The circuit in Figure 9-14(a) amplifies (or attenuates), offsets, and inverts the input signal according to the settings of the potentiometers:

• The gain is set using the adjustable gain potentiometer, where .
• The offset is set using the adjustable offset potentiometer. This can be used to center the output signal at 0.9 V.
• The output voltage is approximately . As such, the output is an inverted and scaled version of the input signal.
• The inversion of the signal (you can see that the output is at a maximum when the input is at a minimum) is a consequence of the circuit used. Non-inverting circuits are possible but they are more difficult to configure. The inversion can easily be corrected in software by subtracting the received ADC input value from 4,095.

In Figure 9-14(b), (c), and (d) the offset voltage is set to 0.9 V, and the gain is adjusted to maximize the output signal (between 0 and 1.8 V) without clipping the signal. In Figure 9-14(b), the gain and offset are adjusted to map a 0 V to +5 V signal to a 1.8 V to 0 V inverted output signal. In Figure 9-14(c), a –5 V to +5 V signal is mapped to a 1.8 V to 0 V signal. Finally, in Figure 9-14 (d), a 1.9 V to 2.1 V input signal is mapped to a 1.3 V to 0 V output (this is the limit for the LM358 in this case). The last case is applied to an example application in the next section.

Figure 9-15 illustrates a full implementation of the op-amp signal conditioning circuit as it is attached to the BeagleBone board. In this example, only two op-amps are required in total. This is because the MCP6002 on the left is used to both condition the signal and protect the ADC input. This is possible because it is powered using a V_CC = 1.8 V supply, which is provided by the 1.8 V voltage follower circuit on the right side. The MCP6002 is a dual op-amp package, and it is used because the MCP6001 is not readily available in a DIP package. You could use the MCP6002 to condition two separate sensor signals.

The potentiometers in Figure 9-14 are replaced by fixed-value resistors in Figure 9-15 to demonstrate how a fixed offset and gain can be configured. In addition, the MCP6002 does not require a load resistor on the output, but a 100 kΩ resistor is used to protect the ADC input.

If the input voltage is –5 V to +5 V, then this circuit will give an output of 0.048 V to 1.626 V with the resistor values R₁ = 9.1 kΩ, R₂ = 1.5 kΩ, R₃ = 4.7 kΩ, and R₄ = 6.5 kΩ. A general equation to describe the relationship between the input and output can be determined as follows:

At V_IN = 5 V, V_OUT = –0.05 V, and at V_IN = –5 V, V_OUT = 1.71 V.

Listing 9-5 displays a test program that can be used to read in 1,000 values from AIN0 at about 20 Hz, with the output presented on a single line.

#define LDR_PATH "/sys/bus/iio/devices/iio:device0/in_voltage"
 
int readAnalog(int number){
   stringstream ss;
   ss << LDR_PATH << number << "_raw";
   fstream fs;
   fs.open(ss.str().c_str(), fstream::in);
   fs >> number;
   fs.close();
   return number;
}
 
int main(int argc, char* argv[]){
   cout << "The value on the ADC is:" << endl;
   for(int i=0; i<1000; i++){
      int value = readAnalog(0);
      cout << "  = " << readAnalog(0) << "/4095    " << '
' << flush;
      usleep(50000);
   }
   return 0;
} 

When built and executed, this code gives the following output:

debian@ebb:~/exploringbb/chp09/testADC$ ./build
debian@ebb:~/exploringbb/chp09/testADC$ ./testADC
The value on the ADC is: = 2140/4095 

If a sine wave is inputted at a frequency of 0.1 Hz, then the output of the program will slowly increase and decrease between a value close to 0 and a value close to 4,095.

Infrared Distance Sensing

Sharp infrared (IR) distance measurement sensors are useful for robotic navigation applications (e.g., object detection and line following) and proximity switches (e.g., automatic faucets and energy-saving switches). These sensors can also be attached to servo motors and used to calculate range maps (e.g., on the front of a mobile robot). They work well in indoor environments but have limited use in direct sunlight. They have a response time of ~39 ms, so at 25–26 readings per second they will not provide dense range images. Figure 9-16(a) shows two aspect views of a low-cost sensor, the Sharp GP2D12.

This is a good analog sensor integration example because four problems need to be resolved, which occur generally with other sensors.

1. The sensor response in Figure 9-16(b) is highly nonlinear so that two different distances can give the same sensor output. Thus, you need to find a way to disambiguate the sensor output. For example, if the sensor output is 1.5 V, it could mean that the detected object is either 5 cm or 17 cm from the sensor. A common solution to this problem is to mount the sensor so that it is physically impossible for an object to be closer than 10 cm from the sensor. This problem is not examined in further detail, and it is assumed here that the detected object cannot be closer than 10 cm from the sensor.
2. The voltage value (0 V to 2.6 V) exceeds the ADC range. As shown, a signal conditioning circuit can be designed to solve this problem.
3. The output signal is prone to high-frequency noise. A low-pass RC filter can be designed to solve this problem.
4. Even for the assumed distances of 10 cm or greater, the relationship between distance and voltage output is still nonlinear. A curve-fitting process can be employed to solve this problem if a linear relationship is required (e.g., threshold applications do not require a linear relationship—just a set value).

To solve the second problem, a voltage divider configuration can be employed to map the output voltage range from 0 V–2.6 V to 0 V –1.8 V. A 10 kΩ potentiometer can be used for this task, as shown in Figure 9-17(a), where 69.2 percent (100 × 1.8 V/2.6 V) of the voltage needs to be dropped across the lower resistor. Therefore, if the total resistance is 10 kΩ, then the lower resistor would be 6.92 kΩ. If fixed-value resistors are to permanently replace the adjustable potentiometer, then 6.8 kΩ and 3.3 kΩ could be used. Accuracy is not vital, as the op-amp circuit protects the ADC input and the sensor is itself separately calibrated based on the actual resistor values used.

To solve the third problem, the circuit in Figure 9-17(a) includes a low-pass RC filter to remove high-frequency signal noise. The last step determined the series resistor to be approximately 3.3 kΩ; therefore, a capacitor value must be chosen to suit the cutoff sampling frequency, which is about 52 Hz (i.e., 2 × 26 Hz) in this case (taking account of the Nyquist criterion). A capacitor value of 1 μF provides an appropriate value, given the equation .

To solve the final problem, a small test rig can be set up to calibrate the distance sensor. A measuring tape can be placed at the front of the sensor, and a large object can be positioned at varying distances from the sensor, between 10 cm and 80 cm. In my case, this provided the raw data for the table in Figure 9-17(b), which is plotted on the graph with the square markers.

This raw data is not sufficiently fine to determine the distance value represented by an ADC measurement intermediate between the values corresponding to the squares. Therefore, curve fitting can be employed to provide an expression that can be implemented in program code. The data can be supplied to the curve fitting tools that are freely available on the Wolfram Alpha website at www.wolframalpha.com. Using the following command string:

exponential fit {{3925,10}, {2790,15}, {2200,20}, {1755,25}, {1528,30}, 
{1273,40}, {851,50}, {726,60}, {620,70}, {528,80}} 

results in the expression (see tiny.cc/beagle906). This curve is plotted in Figure 9-17(b) with the triangular markers. It could also be modeled with a quadratic using the following command string:

quadratic fit {{3925,10}, {2790,15}, {2200,20}, {1755,25}, {1528,30}, 
{1273,40}, {851,50}, {726,60}, {620,70}, {528,80}} 

which results in the expression (see tiny.cc/ebb907).

Note that this process can be used for many analog sensor types to provide an expression that can be used to interpolate between the measured sensor values. What type of fitting curve best fits the data will vary according to the underlying physical process of the sensor. For example, you could use the linear fit command on the Wolfram Alpha website to derive an expression for the LDR described in Chapter 6. A C++ code example can be written to read in the ADC value and convert it into a distance, as shown in Listing 9-6, where the exponential fix expression is coded on a single line.

…
int main(int argc, char* argv[]){
   cout << "Starting the IR distance sensor program:" << endl;
   for(int i=0; i<1000; i++){
      int value = readAnalog(0);
      float distance = 115.804f * exp(-0.000843107f * (float)value);
      cout << "The distance is: " << distance << " cm" << '
' << flush;
      usleep(100000);
   }
   return 0;
} 

When the code example is executed, it continues to output the distance of a detected object in centimeters, for about 100 seconds.

debian@ebb:~/exploringbb/chp09/IRdistance$ ./build
debian@ebb:~/exploringbb/chp09/IRdistance$ ./IRdistance
Starting the IR distance sensor program:
The distance is: 17.7579 cm 

If the speed of execution of such code is vital in the application, then it is preferable to populate a lookup table (LUT) with the converted values. This means that each value is calculated once, either at the initialization stage of the program, or perhaps during code development, rather than every time a reading is made and has to be converted. When the program is in use, the subsequent memory accesses (for reading the LUT) are much more efficient than the corresponding floating-point calculations. This is possible because a 12-bit ADC can output only 4,096 unique values, and it is not unreasonable to store an array of the 4,096 possible outcomes in the memory associated with the program.

ADXL335 Conditioning Example

The ADXL335 is a small three-axis accelerometer that outputs an analog signal that has undergone conditioning. It behaves just like the ADXL345 except that the output is from three analog pins, one for each axis.

When measuring in a range of ±1g, the x-axis outputs ~1.30 V at 0°, ~1.64 V at 90°, and ~1.98 V at 180°. This means that the output signal of the breakout board is centered on 1.64 V and has a variation of ±0.34 V. A circuit can be designed as shown in Figure 9-18 to map the center point to 0.9 V and to extend the variation over the full 1.8 V range.

Unfortunately, there are output impedance problems with this particular ADXL335 breakout board, and the voltage divider circuit in the conditioning circuit will not function correctly. A buffer circuit is therefore required, and an op-amp in voltage follower configuration can be used. The 1.8 V powered op-amp could not be used for this task, as the upper sensor output (at 1.98 V) exceeds the 1.8 V output limit of that op-amp and would thus have been clamped. The 1.8 V supply op-amp IC on the right side has a limit of 5 V, so it is used for this task.

This circuit is a little complex, and it may be overkill, as the amplification of a signal does not necessarily improve the information content of that signal—noise is amplified along with the signal. It is quite possible that the 12-bit ADC performs just as well over a linearly scaled 1.3 V to 1.98 V range as it does over the full 0 V–1.8 V range for this particular sensor. However, it is important that you are exposed to the process of offsetting and scaling a signal using op-amps, as it is required for many sensor types, particularly those that are centered on 0 V, such as microphone audio signals.

The testADC program that was used previously can be used to print out the digitized AIN value from the accelerometer. In this case, the program prints out

debia@ebb:~/exploringbb/chp09/testADC$ ./testADC
The value on the ADC is:  = 2174/4095 

at rest (90°), 250 at 0°, and 4,083 at +180°. A simple linear interpolation can be used to approximate the intermediate values.

A Hello World Example

The first project to test CMake is available in the /chp09/cmake/ directory. It consists of the hello.cpp file and a text file called CMakeLists.txt, as provided in Listing 9-10.

cmake_minimum_required(VERSION 3.7.2)
project (hello)
add_executable(hello hello.cpp) 

The CMakeLists.txt file in Listing 9-10 consists of three lines.

• The first line sets the minimum version of CMake for this project, which is major version 3, minor version 7, and patch version 2 in this example. This version is somewhat arbitrary, but providing a version number allows for future support for your build environment. Therefore, you should use the current version of CMake on your system.
• The second line is the project() command that sets the project name.
• The third line is the add_executable() command, which requests that an executable is to be built using the hello.cpp source file. The first argument to the add_executable() function is the name of the executable to be built, and the second argument is the source file from which to build the executable.

The Hello World project can now be built by executing the cmake utility and by passing to it the directory that contains the source code and the CMakeLists.txt file. In this case, . refers to the current directory.

debian@ebb:~/exploringbb/chp09/cmake$ ls
CMakeLists.txt  hello.cpp
debian@ebb:~/exploringbb/chp09/cmake$ cmake .
-- The C compiler identification is GNU 6.3.0
-- The CXX compiler identification is GNU 6.3.0
…
debian@ebb:~/exploringbb/chp09/cmake$ ls
CMakeCache.txt  cmake_install.cmake  hello.cpp
CMakeFiles      CMakeLists.txt       Makefile 

CMake identified the environment settings for the Linux device and created the Makefile for this project. You can view the content of this file, but do not make edits to it, because any edits will be overwritten the next time that the cmake utility is executed. You can now use the make command to build the project.

debian@ebb:~/exploringbb/chp09/cmake$ make
Scanning dependencies of target hello
[ 50%] Building CXX object CMakeFiles/hello.dir/hello.cpp.o
[100%] Linking CXX executable hello
[100%] Built target hello
debian@ebb:~/exploringbb/chp09/cmake$ ls -l hello
-rwxr-xr-x 1 debian debian 9144 Jul  1 02:38 hello
debian@ebb:~/exploringbb/chp09/cmake$ ./hello
Hello from the Beagle board! 

This is a lot of additional effort to build a simple Hello World example, but as your project scales, this approach can be invaluable.

Building a C/C++ Library

The code that is utilized throughout this book can be grouped together and organized into a single directory structure so that you can use it within your project as a library of code. For example, selected code is organized in the library directory within the repository, as follows:

debian@ebb:~/exploringbb/library$ tree .
…
└─ bus
│  └─ BusDevice.cpp
│  └─ BusDevice.h
│  └─ I2CDevice.cpp
│  └─ I2CDevice.h
│  └─ SPIDevice.cpp
│  └─ SPIDevice.h
└─ CMakeLists.txt
└─ display
│  └─ LCDCharacterDisplay.cpp
│  └─ LCDCharacterDisplay.h
│  └─ SevenSegmentDisplay.cpp
│  └─ SevenSegmentDisplay.h
…
25 directories, 93 files 

A build directory (which should initially be empty) is used to contain the final binary library and any temporary files that are required for the build. The CMakeLists.txt file is created in the library root, as in Listing 9-11.

debian@ebb:~/exploringbb/library$ more CMakeLists.txt
cmake_minimum_required(VERSION 3.7.2)
project(EBBLibrary)
find_package (Threads)
set(CMAKE_BUILD_TYPE Release)
#set(CMAKE_BUILD_TYPE Debug)
 
#Only available from version 2.8.9 on
set(CMAKE_POSITION_INDEPENDENT_CODE TRUE)
 
#Bring the headers, such as Student.h into the project
include_directories(bus display gpio motor network sensor)
 
#However, the file(GLOB…) will allow for wildcard additions:
file(GLOB_RECURSE SOURCES "./*.cpp")
 
#Can build statically to libEBBLibrary.a using the next line
#add_library(EBBLibrary STATIC ${SOURCES})
 
#Building shared library to libEBBLibrary.so using the next line
add_library(EBBLibrary SHARED ${SOURCES})
 
target_link_libraries(EBBLibrary ${CMAKE_THREAD_LIBS_INIT})
 
install (TARGETS EBBLibrary DESTINATION /usr/lib) 

The important features of the CMakeLists.txt file in Listing 9-11 are as follows:

• The find_package(Threads) adds pthread support to the build.
• The set(CMAKE_BUILD_TYPE Release) function is used to set the build type. A Release build will have slightly improved execution performance. The next call to set() adds the -fPIC compile flag to the build so that the machine code is not dependent on being located at a specific memory address, which makes it suitable for inclusion in a library.
• The include_directories() function is used to bring the header files into the build environment.
• The file() command is used to add the source files to the project. GLOB (or GLOB_RECURSE) is used to create a list of all the files that meet the globbing expression (i.e., src/*.cpp) and add them to a variable SOURCES.
• This example uses the add_library() function. The library is built as a shared library using the SHARED flag (other options are STATIC or MODULE), and EBBLibrary is used as the name of the shared library.
• The last line uses the install() function to define an installation location for the library (in this case it is the /usr/lib/ directory). Deployment is invoked using a call to sudo make install in this case.

Once the CMakeLists.txt file has been created, the library can be built as follows:

debian@ebb:~/exploringbb/library/build$ cmake ..
-- The C compiler identification is GNU 6.3.0
-- The CXX compiler identification is GNU 6.3.0
debian@ebb:~/exploringbb/library/build$ make
Scanning dependencies of target EBBLibrary
[  5%] Building CXX object …
[100%] Built target EBBLibrary
debian@ebb:~/exploringbb/library/build$ ls -l *.so
-rwxr-xr-x 1 debian debian 95448 Jul  1 02:52 libEBBLibrary.so 

The CMakeLists.txt file also includes a deployment step, which allows you to install the library in a suitably accessible location. Shared library locations can be added to the path, or if you want to make the libraries available for all users, then you can deploy them to the /usr/lib/ directory. This step requires root access to write to the /usr/lib/ directory. For example, the libEBBLibrary.so library can be installed for all users as follows:

debian@ebb:~/exploringbb/library/build$ sudo make install
[sudo] password for debian:
[100%] Built target EBBLibrary
Install the project…
-- Install configuration: "Release"
-- Installing: /usr/lib/libEBBLibrary.so
debian@ebb:~/exploringbb/library/build$ cd /usr/lib
debian@ebb:/usr/lib$ ls -l libEBB*
-rw-r--r-- 1 root root 132378 Jun 16 02:27 libEBBLibrary.a
-rw-r--r-- 1 root root  95448 Jul  1 02:52 libEBBLibrary.so 

You will also find a file in the build directory, called install_manifest.txt, that describes the locations at which the make install command applied changes.

Using a Shared (.so) or Static (.a) Library

Once a library has been developed, the next question is how you use the library in your projects. To simplify this process, CMake can once again be used to generate the makefiles for your project.

Listing 9-12 provides the source code for a CMakeLists.txt file that can be used to build a program that links to your project library (either dynamically or statically). The libEBBLibrary.so shared library is used for this example. A short C++ program is available in Listing 9-13 that utilizes the functionality of the shared library, in this case to display a message on an LCD character display. This code is provided in the directory /chp09/libexample/.

cmake_minimum_required(VERSION 3.0.2)
project (TestEBBLibrary)
 
#For the shared library:
set ( PROJECT_LINK_LIBS libEBBLibrary.so )
link_directories( ~/exploringbb/library/build )
 
#For the static library:
#set ( PROJECT_LINK_LIBS libEBBLibrary.a )
#link_directories( ~/exploringbb/library/build )
 
include_directories(~/exploringbb/library/)
 
add_executable(libtest libtest.cpp)
target_link_libraries(libtest ${PROJECT_LINK_LIBS} ) 

#include <iostream>
#include <sstream>
#include "display/LCDCharacterDisplay.h"
using namespace exploringBB;
using namespace std;
 
int main() {
   cout << "Testing the EBB library" << endl;
   SPIDevice *busDevice = new SPIDevice(1,1);
   busDevice->setSpeed(1000000);      // access to SPI Device object
   ostringstream s;                   // using to combine text and ints
   LCDCharacterDisplay display(busDevice, 20, 2); // a 20x4 display
   display.clear();                   // Clear the character LCD module
   display.home();                    // Move to the (0,0) position
   display.print("   Exploring BB");
   cout << "End of the EBB library test" << endl;
   return 0;
} 

There are only two files in the project (Listing 9-12 and Listing 9-13). The library of code (libEBBLibrary.so) and associated header files are assumed to be in the ~/exploringbb/library/ directory. The following steps can be used to build the executable:

debian@ebb:~/exploringbb/chp09/libexample$ ls
CMakeLists.txt  libtest.cpp
debian@ebb:~/exploringbb/chp09/libexample$ mkdir build
debian@ebb:~/exploringbb/chp09/libexample$ cd build
debian@ebb:~/exploringbb/chp09/libexample/build$ cmake ..
-- The C compiler identification is GNU 6.3.0
-- The CXX compiler identification is GNU 6.3.0
…
debian@ebb:~/exploringbb/chp09/libexample/build$ make
Scanning dependencies of target libtest
…
debian@ebb:~/exploringbb/chp09/libexample/build$ ls -l libtest
-rwxr-xr-x 1 debian debian 14324 Jul  1 03:19 libtest
debian@ebb:~/exploringbb/chp09/libexample/build$ ./libtest
Testing the EBB library
End of the EBB library test 

It is important to note that any changes to the libtest.cpp program in Listing 9-13 will not require recompilation of the library. Indeed, that is also true of other C/C++ files in the same project. For further information on CMake, see the www.cmake.org website. In particular, the CMake Documentation Index provides a useful list of available commands.