I²C on the Beagle Boards

I²C on the Beagle boards supports 7-bit/10-bit addressing, and bus frequencies of up to 400kHz. NXP (formerly Philips) has newer I²C Fast-mode Plus (Fm+) devices that can communicate at up to 1MHz¹, but this capability is not available on the Beagle boards.

The I²C bus requires pull-up resistors (R_P) on both the SDA and SCL lines, as illustrated in Figure 8-1. These are called termination resistors, and they usually have a value of between 1kΩ and 10kΩ. Their role is to pull the SDA and SCL lines up to V_CC when no I²C device is pulling them down to GND. This pull-up configuration enables multiple master devices to take control of the bus and for the slave device to “stretch” the clock signal (i.e., hold SCL low). Clock stretching can be used by the slave device to slow down data transfer until it has finished processing and is ready to transmit. Termination resistors are often also present on the breakout board that is associated with an I²C device. This can be a useful feature, but their equivalent parallel resistance should be factored into your design, particularly if you are using several boards on the same bus. In the I²C demonstration application discussed in this chapter, the PocketBeagle is the master device, and the ADXL345 slave device is on a breakout board that already has 4.7kΩ termination resistors on the board.

The optional serial resistors (R_S) shown in Figure 8-1 usually have low values (e.g., 250Ω) and can help protect against overcurrent conditions. The I²C devices are typically attached to the SDA and SCL lines using built-in Schmitt trigger inputs (see Chapter 4) to reduce the impact of signal noise by building in a degree of switching hysteresis.

I²C Devices on the Beagle Boards

The I²C buses are present by default on the Debian Linux image and are described in Table 8-1. The I²C devices are visible in the /dev/ directory.

debian@ebb:/dev$ ls -l i2c*
crw-rw---- 1 root i2c 89, 0 Jun  9 19:24 i2c-0
crw-rw---- 1 root i2c 89, 1 Jun  9 19:25 i2c-1
crw-rw---- 1 root i2c 89, 2 Jun  9 19:25 i2c-2 

You can see that these devices are owned by the i2c group, and the user debian is a member of that group.

debian@ebb:/dev$ whoami
debian
debian@ebb:/dev$ groups
debian … i2c … pwm gpio 

The c file attribute indicates that these are character devices. A character device typically transfers data to and from a user application—they behave like pipes or serial ports, instantly reading or writing the byte data in a character-by-character stream. They provide the framework for many typical drivers, such as those that are required for interfacing to serial communications hardware.

A Real-Time Clock

Unlike a desktop computer, the Beagle boards do not have an onboard battery-backed clock. This means that the clock time is lost on each occasion that the board reboots; however, a network-attached Beagle board can retrieve the current time from the network using the Network Time Protocol (NTP). If you are using a board that cannot remain connected to a stable network, then a battery-backed real-time clock (RTC) can be a valuable addition.

Devices synchronize time with an RTC only occasionally, so RTCs are typically attached to an I²C bus. If you are purchasing a module, then you should ensure that it is supported by an LKM for your kernel (or by the kernel itself). This allows for full OS integration of the RTC, which is discussed shortly.

debian@ebb:~$ uname -a
Linux ebb 4.14.44-ti-rt-r51 #1 SMP PREEMPT …
debian@ebb:~$ cd /lib/modules/4.14.44-ti-rt-r51/
debian@ebb:/lib/modules/4.14.44-ti-rt-r51$ cd kernel/drivers/rtc/
debian@ebb:/lib/modules/4.14.44-ti-rt-r51/kernel/drivers/rtc$ ls
rtc-bq4802.ko.xz  rtc-ds1742.ko.xz           rtc-msm6242.ko.xz
rtc-cmos.ko.xz    rtc-ds2404.ko.xz           rtc-rp5c01.ko.xz
rtc-ds1286.ko.xz  rtc-hid-sensor-time.ko.xz  … 

And there is evidence of additional built-in drivers in:

debian@ebb:/sys/bus/i2c/drivers$ ls
…     at24        rtc-ds1307      rtc-max6900      rtc-rx8581   … 

The DS3231 has been chosen for this chapter, as it is a high-accuracy RTC that keeps time to ±63 seconds per year (i.e., ±2ppm² at 0°C–50°C), and it is widely available in module form at very low cost (even less than $1). The DS3231 is compatible with the DS1307 LKM (rtc-ds1307.ko) or built-in kernel code.

The ADXL345 Accelerometer

The Analog Devices ADXL345 is a small, low-cost accelerometer that can measure angular position with respect to the direction of the earth's gravitational force. For example, a single-axis accelerometer at rest on the surface of the earth, with the sensitive axis parallel to the earth's gravity, will measure an acceleration of 1g (9.81m/s²) straight upward. While accelerometers provide absolute orientation measurement, they suffer from high-frequency noise, so they are often paired with gyroscopes for accurate measurement of change in orientation (e.g., in game controllers)—a process known as sensor fusion. However, accelerometers have excellent characteristics for applications in which low-frequency absolute rotation is to be measured. For simplicity, an accelerometer is used on its own in the following discussions because the main aim is to impart an understanding of the I²C bus.

The ADXL345 can be set to measure values with a fixed 10-bit resolution or using a 13-bit resolution at up to ±16 g. The ADXL335 analog accelerometer is utilized in Chapter 9—it provides voltages on its outputs that are proportional to its orientation. Digital accelerometers such as the ADXL345 include analog-to-digital conversion circuitry along with real-time filtering capabilities—they are more complex devices with many configurable options, but it is actually easier to attach them to the board than their analog equivalents. The ADXL345 can be interfaced to the board using an I²C or SPI bus, which makes it an ideal sensor to use in this chapter as an example for both bus types. The chapter web page identifies suppliers from whom you can purchase this particular sensor.

The I²C slave address is determined by the slave device itself. For example, the ADXL345 breakout board has the address 0x53, which is determined at manufacture. Many devices, including the ADXL345, have selection inputs that allow you to alter this value within a defined range.³ If the device does not have address selection inputs, then you cannot connect two of them to the same bus, as their addresses will conflict. However, there are I²C multiplexers available that would enable you to overcome this problem.

The data sheet for the ADXL345 is an important document that should be read along with this chapter. It is available at www.analog.com/ADXL345.

Wiring the Test Circuit

Figure 8-2 illustrates a test circuit that can be used to evaluate the function of I²C devices that are attached to the PocketBeagle. In this circuit, an ADXL345 and a DS3231 breakout board are connected to the same I2C1 bus. The ADXL345 has the address 0x53, and the DS3231 has the address 0x68, so there will not be a conflict. The CS input of the ADXL345 breakout board is set high to place the module in I²C mode.

Even if you do not have these particular sensors, the following discussion is fully representative of the steps required to connect any type of I²C sensor to the Beagle boards. See Table 8-1 for the pins to be used on the BeagleBone boards.

i2cdetect

The first step is to detect that the devices are present on the bus. When the I²C buses are enabled, the i2cdetect command displays this:

debian@ebb:~$ i2cdetect -l
i2c-1   i2c             OMAP I2C adapter                        I2C adapter
i2c-2   i2c             OMAP I2C adapter                        I2C adapter
i2c-0   i2c             OMAP I2C adapter                        I2C adapter 

If the circuit is wired as in Figure 8-2 with an ADXL345 and a DS3231 breakout board attached to the /dev/i2c-1 bus, then it can be probed for connected devices, which will result in the following output:

debian@ebb:~$ i2cdetect -y -r 1
     0  1  2  3  4  5  6  7  8  9  a  b  c  d  e  f
00:          -- -- -- -- -- -- -- -- -- -- -- -- --
10: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
20: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
30: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
40: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
50: -- -- -- 53 -- -- 56 -- -- -- -- -- -- -- -- --
60: -- -- -- -- -- -- -- -- 68 -- -- -- -- -- -- --
70: -- -- -- -- -- -- -- -- 

Hexadecimal addresses in the range 0x03 to 0x77 are displayed by default. Using -a will display the full range 0x00 to 0x7F. When -- is displayed, the address was probed, but no device responded. If UU is displayed, then probing was skipped, as the address is already in use by a driver.

The ADXL345 breakout board occupies address 0x53, and the DS3231 ZS-042 breakout board occupies addresses 0x68 and 0x56.⁴ Each of the attached breakout boards defines its own addresses, which means that problems will arise if two slave devices with the same address are connected to a single bus. Many I²C devices provide an address selection option that often involves setting an additional input high/low, which is typically implemented on breakout boards by jumper connections or contact points that can be bridged with solder.

i2cdump

The i2cdump command can be used to read in the values of the registers of the device attached to an I²C bus and display them in a hexadecimal block form. You should not use this command without consulting the datasheet for the slave device, as in certain modes the i2cdump command will write to the device. The argument -y ignores a related warning. The devices in Figure 8-2 can be safely used, and when the address 0x68 is probed on the i2c-1 bus in byte mode (b), it results in the following output:

debian@ebb:~$ i2cdump -y 1 0x68 b
     0  1  2  3  4  5  6  7  8  9  a  b  c  d  e  f    0123456789abcdef
00: 19 02 03 06 25 10 02 00 00 00 00 00 00 00 1c 88    ????%??…….??
10: 00 17 00 XX XX XX XX XX XX XX XX XX XX XX XX XX    .?.XXXXXXXXXXXXX 

If the device is probed again in quick succession, then a similar output results, but in this example the register value for address 0x00 changes from 19 to 41. This value actually represents the number of clock seconds (in decimal form) on the RTC module. Therefore, 22 seconds had elapsed between these two calls to the i2cdump command.

debian@ebb:~$ i2cdump -y 1 0x68 b
     0  1  2  3  4  5  6  7  8  9  a  b  c  d  e  f    0123456789abcdef
00: 41 02 03 06 25 10 02 00 00 00 00 00 00 00 1c 88    A???%??…….??
10: 00 17 00 XX XX XX XX XX XX XX XX XX XX XX XX XX    .?.XXXXXXXXXXXXX 

To understand the meaning of such registers, you need to read the datasheet for the device. The datasheet for the DS3231 is available at tiny.cc/beagle802, and the most important registers are illustrated in Figure 8-3. In this figure, the hwclock function (see the feature on Utilizing Linux Hardware RTC Devices that follows) is used to display the time value from the RTC module. The i2cdump command is called (a few seconds later) to display the registers, allowing their meaning to be verified. Note that the Irish standard time (IST) time zone results in a shift of plus one hour from UTC/GMT.

i2cget

The i2cget command can be used to read the value of a register to test the device or as an input for Linux shell scripts. For example, to read the number of seconds on the clock, you can use the following:

debian@ebb:~$ i2cget -y 1 0x68 0x00
0x30 

The Analog Discovery digital logic analyzer functionality can be used to analyze the physical I²C bus to view the interaction of the SDA and SCL signals as data is written to and read from the I²C bus. The logic analyzer functionality has interpreters for I²C buses, SPI buses, CAN buses, and UART communication, which can display the numerical equivalent values of the serial data carried on the bus. Figure 8-4 captures the signal transitions of the i2cget command used in the preceding example. Here, you can see that the clock is running at I²C standard data transfer mode (i.e., 100kHz).

The ADXL345 accelerometer can be accessed in the same way as the RTC module. Figure 8-5 illustrates the important registers that are utilized in this chapter. To test that the ADXL345 is correctly connected to the bus, read the DEVID of the attached device, which should be returned as 0xE5.

debian@ebb:~$ i2cget -y 1 0x53 0x00
0xe5 

You can see that the first value at address 0x00 is 0xE5, and this value corresponds to the DEVID entry in Figure 8-5—successful communication has been verified.

i2cset

As previously stated, the datasheet for the ADXL345 from Analog Devices is available at www.analog.com/ADXL345. It is a comprehensive and well-written datasheet that details every feature of the device. In fact, the real challenge in working with new bus devices is in decoding the datasheet and the intricacies of the device's behavior. The ADXL345 has 30 public registers, and Figure 8-5 illustrates those that are accessed in this chapter. Other registers enable you to set power save inactivity periods, orientation offsets, and interrupt settings for free-fall, tap, and double-tap detection.

The x-, y-, and z-axis acceleration values are stored using a 10-bit or 13-bit resolution; therefore, two bytes are required for each reading. Also, the data is in 16-bit two's complement form (see Chapter 4). To sample at 13 bits, the ADXL345 must be set to the ±16 g range. Figure 8-6 (based on the ADXL345 datasheet) describes the signal sequences required to read and write to the device. For example, to write a single byte to a device register, the master/slave access pattern in the first row is used as follows:

1. The master sends a start bit (i.e., it pulls SDA low, while SCL is high).
2. While the clock toggles, the 7-bit slave address is transmitted one bit at a time.
3. A read bit (1) or write bit (0) is sent, depending on whether the master wants to read or write to/from a slave register.
4. The slave responds with an acknowledge bit (ACK = 0).
5. In write mode, the master sends a byte of data one bit at a time, after which the slave sends back an ACK bit. To write to a register, the register address is sent, followed by the data value to be written.
6. Finally, to conclude communication, the master sends a stop bit (i.e., it allows SDA to float high, while SCL is high).

The i2cset command can be used to set a register. This is required, for example, to take the ADXL345 out of power-saving mode, by writing 0x08 to the POWER_CTL register, which is at 0x2D. The value is written and then confirmed as follows:

debian@ebb:~$ i2cset -y 1 0x53 0x2D 0x08
debian@ebb:~$ i2cget -y 1 0x53 0x2D
0x08 

The call to i2cset and i2cget invokes the handshaking sequences that are described in the ADXL345 datasheet and illustrated in Figure 8-6, which also identifies these numbered steps.

When the i2cdump command is subsequently used, the registers 0x32 through 0x37 (as identified in Figure 8-5) display the acceleration values, which change as the sensor is physically rotated and the i2cdump command is repeatedly called. The next step is to write program code that can interpret the values contained in the DS3231 and the ADXL345 registers.

Testing an SPI Bus

To test the SPI bus, you can use a program called spidev_test.c that is available from www.kernel.org. However, the latest version at the time of writing has added support for dual and quad data-wire SPI transfers, which are not supported on the Beagle boards. An older version of this code has been placed in /chp08/spi/spidev_test/ and can be built using the following:

…/chp08/spi/spidev_test$ gcc spidev_test.c -o spidev_test 

If this code is executed without connecting to the SPI1 pins, then the output displayed by the spidev_test program will consist of a block of 0x00 or 0xFF values, depending on whether the MISO pin is configured in pull-down or pull-up configuration, respectively.

…/chp08/spi/spidev_test$ ./spidev_test -D /dev/spidev1.0
spi mode: 0
bits per word: 8
max speed: 500000 Hz (500 KHz)
FF FF FF FF FF FF
FF FF FF FF FF FF
FF FF FF FF FF FF
FF FF FF FF FF FF
FF FF FF FF FF FF
FF FF FF FF FF FF
FF FF 

The source code for the spidev_test.c program includes a hard-coded array of values to test that the SPI communications line is working correctly. These values are as follows:

uint8_t tx[] = {
        0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF,
        0x40, 0x00, 0x00, 0x00, 0x00, 0x95,
        0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF,
        0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF,
        0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF,
        0xDE, 0xAD, 0xBE, 0xEF, 0xBA, 0xAD,
        0xF0, 0x0D,
}; 

if the SPI MOSI and SPI MISO pins are connected together, as illustrated in Figure 8-7(b) for SPI0. To test SPI0 on the BeagleBone, use P9_29 and P9_30, and on the PocketBeagle, use P2.25 and P2.27. When the test program is executed again, the output should be as follows:

…/chp08/spi/spidev_test$ ./spidev_test -D /dev/spidev1.0
spi mode: 0
bits per word: 8
max speed: 500000 Hz (500 KHz)
FF FF FF FF FF FF
40 00 00 00 00 95
FF FF FF FF FF FF
FF FF FF FF FF FF
FF FF FF FF FF FF
DE AD BE EF BA AD
F0 0D 

This is the exact block of data that is defined in the tx[] array inside the spidev_test.c code. Therefore, in this case, the block of data has been successfully transmitted from SPI1 MOSI and received by SPI1 MISO. You can see the same stream of data captured using the logic analyzer in Figure 8-8. The clock frequency of SCLK is 500kHz.

This program can be executed on the SPI0 bus as follows:

…/chp08/spi/spidev_test$ ./spidev_test -D /dev/spidev0.0 

Wiring the 74HC595 Circuit

The 74HC595 is connected to the PocketBeagle using three of the four SPI lines, as a MISO response from the 74HC595 is not required. In addition to the 5V and GND inputs, the SPI connections are as follows:

• SPI1-CLK is connected to the Serial Clock input (pin 11) of the 74HC595. This line is used to synchronize the transfer of SPI data on the MOSI line.
• SPI1-MOSI is the MOSI line and is used to transfer the data from the PocketBeagle to the 74HC595 Serial Input (pin 14). This will send one byte at a time, which is the full capacity of the 74HC595.
• SPI-CS is connected to the Serial Register Clock input, which is used to latch the 74HC595 state to the output pins, thus lighting the LEDs.

To avoid the need for an external power supply, this circuit is powered using the board's 5V supply. However, this means that the circuit is now using 5V logic levels, and it would damage your board if you were to connect any of the 74HC595 outputs (e.g., Q_H’) back to the board.

You can safely connect the board's MOSI line directly to the circuit, as a 3.3V output can be safely connected to a 5V input. However, strictly speaking, 3.3V is slightly below the threshold of 3.5V (i.e., 30 percent below 5V) required for an input to a 5V logic-level CMOS IC (see Figure 4-24 in Chapter 4). In practice, the circuit works fine; however, a 74LS595 (at V_CC = 5V) or a 74LVC595 (at V_CC = 3.3V) would be more appropriate, despite their high cost and lack of availability.

The LEDs on the seven-segment display will light according to the byte that is transferred. For example, sending 0xAA should light every second LED segment (including the dot) if the setup is working correctly, as 0xAA = 10101010₂. This circuit is useful for controlling eight outputs using a single serial data line, and it can be extended to further seven-segment displays by daisy chaining 74HC595 ICs together, as indicated in Figure 8-9.

Once the SPI device is enabled on the Beagle board, you can write directly to the device as follows to light most of the LEDs (-n suppresses the newline character, -e enables escape character interpretation, and x escapes the subsequent value as hexadecimal):

debian@ebb:~$ echo -ne "xFF" > /dev/spidev1.1 

The following will turn most of the LEDs off.

debian@ebb:~$ echo -ne "x00" > /dev/spidev1.1 

This may not work exactly as expected, as the current SPI communication mode does not align by default with the operation of the 74HC595, as wired in Figure 8-9. However, it is a useful test to confirm that there is some level of response from the circuit. The transfer mode issue is resolved within the code example in the next section.

SPI Communication Using C

A C program can be written to control the seven-segment display. Basic open() and close() operations on the /dev/spidevX.Y devices work, but if you need to alter the low-level SPI transfer parameters, then a more sophisticated interface is required.

The following program uses the Linux user space SPI API, which supports reading and writing to SPI slave devices. It is accessed using Linux ioctl() requests, which support SPI through the sys/ioctl.h and linux/spi/spidev.h header files. A full guide on the use of this API is available at www.kernel.org/doc/Documentation/spi/.

The program in Listing 8-4 counts in hexadecimal (i.e., 0 to F) on a single seven-segment display using the encoded value for each digit. For example, 0 is obtained by lighting only the segments A, B, C, D, E, and F in Figure 8-10—this value is encoded as 0b00111111 in Listing 8-4, where A is the LSB (on the right) and H (the dot) is the MSB (on the left) of the encoded value. The transfer() function is the most important part of the code example, as it transfers each encoded value to the 74HC595 IC.

#include<stdio.h>
#include<fcntl.h>
#include<unistd.h>
#include<sys/ioctl.h>
#include<stdint.h>
#include<linux/spi/spidev.h>
#define SPI_PATH "/dev/spidev1.1"
 
// The binary data that describes the LED state for each symbol
// A(top)         B(top right) C(bottom right)  D(bottom)
// E(bottom left) F(top left)  G(middle)        H(dot)
const unsigned char symbols[16] = {             //(msb) HGFEDCBA (lsb)
     0b00111111, 0b00000110, 0b01011011, 0b01001111,  // 0123
     0b01100110, 0b01101101, 0b01111101, 0b00000111,  // 4567
     0b01111111, 0b01100111, 0b01110111, 0b01111100,  // 89Ab
     0b00111001, 0b01011110, 0b01111001, 0b01110001   // CdEF
};
 
int transfer(int fd, unsigned char send[], unsigned char rec[], int len){
   struct spi_ioc_transfer transfer;        //transfer structure
   transfer.tx_buf = (unsigned long) send;  //buffer for sending data
   transfer.rx_buf = (unsigned long) rec;   //buffer for receiving data
   transfer.len = len;                      //length of buffer
   transfer.speed_hz = 1000000;             //speed in Hz
   transfer.bits_per_word = 8;              //bits per word
   transfer.delay_usecs = 0;                //delay in us
   transfer.cs_change = 0;       // affects chip select after transfer
   transfer.tx_nbits = 0;        // no. bits for writing (default 0)
   transfer.rx_nbits = 0;        // no. bits for reading (default 0)
   transfer.pad = 0;             // interbyte delay - check version
   // send the SPI message (all of the above fields, inc. buffers)
   int status = ioctl(fd, SPI_IOC_MESSAGE(1), &transfer);
   if (status < 0) {
      perror("SPI: SPI_IOC_MESSAGE Failed");
      return -1;
   }
   return status;
}
 
int main(){
   int fd, i;                          // file handle and loop counter
   unsigned char null=0x00;            // sending only a single char
   uint8_t mode = 3;                   // SPI mode 3
 
   // The following calls set up the SPI bus properties
   if ((fd = open(SPI_PATH, O_RDWR))<0){
      perror("SPI Error: Can't open device.");
      return -1;
   }
   if (ioctl(fd, SPI_IOC_WR_MODE, &mode)==-1){
      perror("SPI: Can't set SPI mode.");
      return -1;
   }
   if (ioctl(fd, SPI_IOC_RD_MODE, &mode)==-1){
      perror("SPI: Can't get SPI mode.");
      return -1;
   }
   printf("SPI Mode is: %d
", mode);
   printf("Counting in hexadecimal from 0 to F now:
");
   for (i=0; i<=15; i++)
   {
      // This function can send and receive data, just sending now
      if (transfer(fd, (unsigned char*) &symbols[i], &null, 1)==-1){
         perror("Failed to update the display");
         return -1;
      }
      printf("%4d
", i);   // print the number in the terminal window
      fflush(stdout);       // need to flush the output, no 

      usleep(500000);       // sleep for 500ms each loop
   }
   close(fd);               // close the file
   return 0;
} 

The main() function sets the SPI control parameters. These are ioctl() requests that allow you to override the device's current settings for parameters such as the following, where xx is both RD (read) and RW (write):

• SPI_IOC_xx_MODE: The SPI transfer mode (0–3).
• SPI_IOC_xx_BITS_PER_WORD: The number of bits in each word.
• SPI_IOC_xx_LSB_FIRST: 0 is MSB first, 1 is LSB first.
• SPI_IOC_xx_MAX_SPEED_HZ: The maximum transfer rate in Hz.

The current Linux implementation provides for synchronous transfers only. When executed, this code results in the following output, where the count value continually increases (0 to F) on the one line of the terminal window:

debian@ebb:~/exploringbb/chp08/spi/spi595Example$ ./spi595
SPI Mode is: 3
Counting in hexadecimal from 0 to F now:
   5 

At the same time, this code is sending signals to the 74HC595 as captured using the SPI interpreter of the logic analyzer in Figure 8-10, in which the symbol 0 is being displayed by the seven-segment display (i.e., 0b00111111). During this time period, the CS (SPI1-CS) line is pulled low, while the SCLK clock (SPI1-CLK) that is “high at idle” is toggled by the SPI master after a short delay. The data is then sent on the SDIO (SPI1-MOSI) line, MSB first, to the 74HC595, and it is transferred on the rising edge of the clock signal. This confirms that the SPI transfer is taking place in mode 3, as described in Table 8-3.

The data transfer takes ~9μs. This means that if the channel were held open, it would be capable of transferring a maximum of ~111kB/s (~0.9Mb/s) at a processor clock rate of 1MHz.

The ADXL345 SPI Interface

SPI is not a formal standard with a standards body controlling its implementation, and therefore it is vital that you study the datasheet for the device that you want to attach to your Beagle board. In particular, the SPI communication timing diagram should be studied in detail. This is presented for the ADXL345 in Figure 8-11.

Note the following important points, which can be observed directly from the datasheet figure, as summarized in Figure 8-11:

• To write to an address, the first bit on the SDI line must be low. To read from an address, the first bit on the SDI line must be high.
• The second bit is called MB. From further analysis of the datasheet, this bit enables multiple byte reading/writing of the registers (i.e., send the first address and data will be continuously read from that register forward). This leaves six bits in the first byte for the address (2⁶ = 64₁₀ = 40₁₆), which is sufficient to cover the available registers.
• As shown in Figure 8-11, the SCLK line is high at rest, and data is transferred on the rising edge of the clock signal. Therefore, the ADXL345 device must be used in communications mode 3 (refer to Table 8-3).
• When writing (top figure), the address (with a leading 0) is written to SDI, followed by the byte value to be written to the address.
• When reading (bottom figure), the address (with a leading 1) is written to SDI. A second byte is written to SDI and will be ignored. While the second (ignored) byte is being written to SDI, the response will be returned on SDO detailing the value stored at the register address.

Connecting the ADXL345 to the Beagle Boards

The ADXL345 breakout board can be connected to the SPI bus as illustrated in Figure 8-12(a), where MOSI on the BBB is connected to SDA and MISO is connected to SDO. The clock lines and the slave select lines are also interconnected. Figure 8-12(b) shows the equivalent connection for the PocketBeagle board.

Once again, a logic analyzer is useful for debugging problems that can occur with SPI bus communication. For example, Figure 8-13 captures a read operation at address 0x00. You may notice that the value that was sent was 0x80 and not 0x00. This is because (as detailed in Figure 8-11) the leading bit must be a 1 to read and a 0 to write from/to an address. Sending 0x00 is a write request to address 0x00 (which is not possible), and sending 0x80 (i.e., 10000000 + 00000000) is a request to read the value at address 0x00. The second bit is 0 in both cases, thus disabling multiple-byte read functionality for this example.

The code in Listing 8-4 is adapted in /spi/spiADXL345/spiADXL345.c so that it reads the first register (0x00) of the ADXL345, which should return the DEVID, as illustrated in Figure 8-5. This value should be E5₁₆, which is 229₁₀. The maximum recommended SPI clock speed for the ADXL345 is 5MHz, so this value is used in the program code.

debian@ebb:~/exploringbb/chp08/spi/spiADXL345$ gcc spiADXL345.c -o spiADXL345
debian@ebb:~/exploringbb/chp08/spi/spiADXL345$ ./spiADXL345
spi mode: 0x3
bits per word: 8
max speed: 5000000 Hz (5000 KHz)
Return value: 229 

Wrapping SPI Devices with C++ Classes

A C++ class is available in Listing 8-5 that wraps the software interface to the SPI bus, using the OOP techniques that are described in Chapter 5. This class is quite similar to the I2CDevice class that is described in Listing 8-2.

    class SPIDevice {
    public:
       enum SPIMODE{   //!< The SPI Mode
          MODE0 = 0,   //!< Low at idle,  capture on rising clock edge
          MODE1 = 1,   //!< Low at idle,  capture on falling clock edge
          MODE2 = 2,   //!< High at idle, capture on falling clock edge
          MODE3 = 3    //!< High at idle, capture on rising clock edge
       };
    public:
       SPIDevice(unsigned int bus, unsigned int device);
       virtual int open();
       virtual unsigned char readRegister(unsigned int registerAddress);
       virtual unsigned char* readRegisters(unsigned int number, unsigned int fromAddress=0);
       virtual int writeRegister(unsigned int registerAddress, unsigned char value);
       virtual void debugDumpRegisters(unsigned int number = 0xff);
       virtual int write(unsigned char value);
       virtual int write(unsigned char value[], int length);
       virtual int setSpeed(uint32_t speed);
       virtual int setMode(SPIDevice::SPIMODE mode);
       virtual int setBitsPerWord(uint8_t bits);
       virtual void close();
       virtual ~SPIDevice();
       virtual int transfer(unsigned char read[], unsigned char write[], int length);
    private:
       std::string filename; //!< The precise filename for the SPI device
       int file;             //!< The file handle to the device
       SPIMODE mode;         //!< The SPI mode as per the SPIMODE enumeration
       uint8_t bits;         //!< The number of bits per word
       uint32_t speed;       //!< The speed of transfer in Hz
       uint16_t delay;       //!< The transfer delay in usecs
    }; 

The SPI class in Listing 8-5 can be used in a stand-alone form for any SPI device type. For example, Listing 8-6 demonstrates how to probe the ADXL345 device.

    #include <iostream>
    #include <sstream>
    #include "bus/SPIDevice.h"
    #include "sensor/ADXL345.h"
    using namespace std;
    using namespace exploringBB;
 
    int main(){
       SPIDevice spi(0,0);
       spi.setSpeed(5000000);
       cout << "The device ID is: " << (int) spi.readRegister(0x00) << endl;
       spi.setMode(SPIDevice::MODE3);
       spi.writeRegister(0x2D, 0x08);
       spi.debugDumpRegisters(0x40);
    } 

This will give the following output when built and executed (0xE5 = 229₁₀):

debian@ebb:~/exploringbb/chp08/spi/spiADXL345_cpp$ ./build
debian@ebb:~/exploringbb/chp08/spi/spiADXL345_cpp$ ./SPITest
The device ID is: 229
SPI Mode: 3
Bits per word: 8
Max speed: 5000000
Dumping Registers for Debug Purposes:
e5 00 00 00 00 00 00 00 00 00 00 00 00 00 00 4a
82 00 30 00 00 01 fe 08 00 00 00 ea 00 00 00 00
00 00 00 00 00 00 00 00 00 00 00 00 0a 08 00 00
02 0b 3a 00 db ff 17 01 00 00 00 00 00 00 00 00 

The same SPIDevice class can be used as the basis for modifying the ADXL345 class in Listing 8-3 to support the SPI bus rather than the I²C bus. Listing 8-7 provides a segment of the class that is complete in the /chp08/spi/spiADXL345_cpp/ directory.

    class ADXL345{
    public:
       enum RANGE {  …  };
       enum RESOLUTION {   …   };
    private:
       SPIDevice *device;
       unsigned char *registers;
       …
    public:
       ADXL345(SPIDevice *busDevice);
       virtual int readSensorState();
       …
       virtual void displayPitchAndRoll(int iterations = 600);
       virtual ~ADXL345();
    }; 

The full class from Listing 8-7 can be used to build an example, as in Listing 8-8. This example helps demonstrate how an embedded device that is attached to one of the buses can be wrapped with a high-level OOP class.

    #include <iostream>
    #include <sstream>
    #include "bus/SPIDevice.h"
    #include "sensor/ADXL345.h"
    using namespace std;
    using namespace exploringBB;
 
    int main(){
       cout << "Starting EBB ADXL345 SPI Test" << endl;
       SPIDevice *busDevice = new SPIDevice(0,0);
       busDevice->setSpeed(5000000);
       ADXL345 acc(busDevice);
       acc.displayPitchAndRoll(100);
       cout << "End of EBB ADXL345 SPI Test" << endl;
    } 

When this program is executed, it displays the current accelerometer pitch and roll values on a single line of the terminal window.

debian@ebb:~/exploringbb/chp08/spi/spiADXL345_cpp$ ./build
debian@ebb:~/exploringbb/chp08/spi/spiADXL345_cpp$ ./testADXL345
Starting EBB ADXL345 SPI Test
Pitch:47.1902 Roll:-6.48042 

Three-Wire SPI Communication

The ADXL345 supports a three-wire SPI (half duplex) mode. In this mode, the data is read and transmitted on the same SDIO line. To enable this mode on the ADXL345, the value 0x40 must be written to the 0x31 (DATA_FORMAT) register, and a 10kΩ resistor should be placed between SD0 and V_CC on the ADXL345. There is a draft project in place in the chp08/spi/spiADXL345/3-wire/ directory, but at the time of writing, there is a lack of support for this mode in current Linux distributions.

Beagle Board Serial Client

The C program in Listing 8-9 sends a string to a desktop machine (or any other device) that is listening to the other end of the connection (e.g., using PuTTY). It uses the Linux termios library, which provides a general terminal interface that can control asynchronous communication ports.

    #include<stdio.h>
    #include<fcntl.h>
    #include<unistd.h>
    #include<termios.h>
    #include<string.h>
 
    int main(int argc, char *argv[]){
       int file, count;
       if(argc!=2){
           printf("Please pass a message string to send, exiting!
");
           return -2;
       }
       if ((file = open("/dev/ttyO4", O_RDWR | O_NOCTTY | O_NDELAY))<0){
          perror("UART: Failed to open the device.
");
          return -1;
       }
       struct termios options;
       tcgetattr(file, &options);
       options.c_cflag = B115200 | CS8 | CREAD | CLOCAL;
       options.c_iflag = IGNPAR | ICRNL;
       tcflush(file, TCIFLUSH);
       tcsetattr(file, TCSANOW, &options);
 
       // send the string plus the null character
       if ((count = write(file, argv[1], strlen(argv[1])+1))<0){
          perror("UART: Failed to write to the output.
");
          return -1;
       }
       close(file);
       printf("Finished sending the message, exiting.
");
       return 0;
    } 

This code uses the termios structure, setting flags to define the type of communication that should take place. The termios structure has the following members:

• tcflag_t c_iflag: Sets the input modes
• tcflag_t c_oflag: Sets the output modes
• tcflag_t c_cflag: Sets the control modes
• tcflag_t c_lflag: Sets the local modes
• cc_t c_cc[NCCS]: Used for special characters

A full description of the termios functionality and flag settings is available by typing man termios at the Linux shell prompt.

debian@ebb:~/exploringbb/chp08/uart/uartC$ gcc uart.c -o uart
…/exploringbb/chp08/uart/uartC$ ./uart "Hello Desktop!"
Finished sending the message, exiting.
…/exploringbb/chp08/uart/uartC$ ./uart " From the PocketBeagle."
Finished sending the message, exiting.
…/exploringbb/chp08/uart/uartC$ echo " Using echo!" >> /dev/ttyO4 

The output appears on the desktop PC as in Figure 8-18 when PuTTY is set to listen to the correct serial port (e.g., COM5 in my case). The C program functionality is similar to a simple echo to the terminal device; however, it does have access to set low-level modes such as the baud rate, parity types, and so on.

LED Serial Server

For some applications, it can be useful to allow a desktop computer master to take control of a Beagle board slave. In this section, a serial server runs on the PocketBeagle and awaits commands from a desktop serial terminal. Once again, the USB-to-TTL 3.3V cable is used; however, it is important to note that a similar setup could be developed with wireless technologies, such as Bluetooth, infrared transmitter/receivers, and serial ZigBee (see Chapter 12).

In this example, the PocketBeagle is connected to a simple LED circuit and the USB-to-TTL cable, as illustrated in Figure 8-19(a). When the PuTTY client on the desktop computer issues simple string commands such as LED on and LED off, as illustrated in Figure 8-19(b), the hardware LED that is attached to the board performs a corresponding action. Importantly, this program permits safe remote control of the board, as it does not allow the serial client access to any other functionality on the board—in effect, the serial server behaves like a shell that has only three commands! Please note that you may have to turn on local echo in the terminal window (e.g., in PuTTY use Terminal → Local echo and select the option “Force on”).

The source code for the serial server is provided in Listing 8-10. The example uses sysfs to control the LED circuit (see Chapter 5). On execution, the server displays the following output when you provide the input strings that are captured in Figure 8-19(b):

debian@ebb:~/exploringbb/chp08/uart/server$ gcc server.c -o server
debian@ebb:~/exploringbb/chp08/uart/server$ ./server
EBB Serial Server running
LED on
Server>>>[Turning the LED on]
LED off
Server>>>[Turning the LED off]
quit
Server>>>[goodbye] 

You can then add a new service entry for the server code in this section so that it starts on boot. If your intention is to run this program as a service, then you should, of course, remove the client-controlled “quit” functionality!

    #include<stdio.h>
    #include<fcntl.h>
    #include<unistd.h>
    #include<termios.h>
    #include<string.h>
    #include<stdlib.h>
    #define  LED_PATH  "/sys/class/gpio/gpio60/"
 
    // Sends a message to the client and displays the message on the console
    int message(int client, char *message){
       int size = strlen(message);
       printf("Server>>>%s
", (message+1));   // print message with new line
       if (write(client, message, size)<0){
          perror("Error: Failed to write to the client
");
          return -1;
       }
       write(client, "

EBB>", 7);           // display a simple prompt
       return 0;                               // 
 for a carriage return
    }
 
    void makeLED(char filename[], char value[]){
       FILE* fp;   // create a file pointer fp
       char  fullFileName[100];  // to store the path and filename
       sprintf(fullFileName, LED_PATH "%s", filename); // write path and filename
       fp = fopen(fullFileName, "w+"); // open file for writing
       fprintf(fp, "%s", value);  // send the value to the file
       fclose(fp);  // close the file using the file pointer
    }
 
    // Checks to see if the command is one that is understood by the server
    int processCommand(int client, char *command){
       int val = -1;
       if (strcmp(command, "LED on")==0){
          val = message(client, "
[Turning the LED on]");
          makeLED("value", "1");        // turn the physical LED on
       }
       else if(strcmp(command, "LED off")==0){
          val = message(client, "
[Turning the LED off]");
          makeLED("value", "0");        // turn the physical LED off
       }
       else if(strcmp(command, "quit")==0){    // shutting down server!
          val = message(client, "
[goodbye]");
       }
       else { val = message(client, "
[Unknown command]"); }
       return val;
    }
 
    int main(int argc, char *argv[]){
       int client, count=0;
       unsigned char c;
       char *command = malloc(255);
       makeLED("direction", "out");            // the LED is an output
       if ((client = open("/dev/ttyO4", O_RDWR | O_NOCTTY | O_NDELAY))<0){
          perror("UART: Failed to open the file.
");
          return -1;
       }
       struct termios options;
       tcgetattr(client, &options);
       options.c_cflag = B115200 | CS8 | CREAD | CLOCAL;
       options.c_iflag = IGNPAR | ICRNL;
       tcflush(client, TCIFLUSH);
       fcntl(STDIN_FILENO, F_SETFL, O_NONBLOCK);  // make reads non-blocking
       tcsetattr(client, TCSANOW, &options);
       if (message(client, "

EBB Serial Server running")<0){
          perror("UART: Failed to start server.
");
          return -1;
       }
 
       // Loop forever until the quit command is sent from the client or
       //  Ctrl-C is pressed in the server's terminal window
       do {
          if(read(client,&c,1)>0){
              write(STDOUT_FILENO,&c,1);
              command[count++]=c;
              if(c=='
'){
                 command[count-1]='';  // replace /n with /0
                 processCommand(client, command);
                 count=0;                // reset the command string
              }
          }
          if(read(STDIN_FILENO,&c,1)>0){ // can send from stdin to client
              write(client,&c,1);
          }
       }
       while(strcmp(command,"quit")!=0);
       close(client);
       return 0;
    }