Debugging USB Firmware

You’ve written firmware for your USB device and are ready to test it. You attach the device to a PC and the hardware wizard announces: “The device didn’t start.” Or, the device installs but doesn’t send or receive data. Or, data is being dropped, the throughput is low, or some other problem presents itself. What do you do?

This article explores tools and techniques to debug the USB devices you design. The focus is on USB 2.0 devices, but much of the information also applies to developing USB 3.0 (SuperSpeed) devices and USB hosts for embedded systems.

VIEWING BUS TRAFFIC

If you do anything beyond a small amount of USB developing, a USB protocol analyzer will save you time and trouble. Analyzers cost less than they used to and are well worth the investment.

A hardware-based analyzer connects in a cable segment upstream from the device under test (see Photo 1).

Photo 1: The device under test connects to the analyzer, which
captures the data and passes it unchanged to the device’s host. The
cable on the back of the analyzer carries the captured data to the
analyzer’s host PC for display.

You can view the data down to each packet’s individual bytes and see exactly what the host and device did and didn’t send (see Photo 2).

Photo 2: This bus capture shows the host’s request for a configuration
descriptor and the bytes the device sent in response. Because the endpoint’s
maximum packet size is eight, the device sends the first 8 bytes in one
transaction and the final byte in a second transaction.

An analyzer can also decode data to show standard USB requests and class-specific data (see Photo 3).

Photo 3: This display decodes a received configuration descriptor and its subordinate descriptors.

To avoid corrupted data caused by the electrical effects of the analyzer’s connectors and circuits, use short cables (e.g., 3’ or less) to connect the analyzer to the device under test.

Software-only protocol analyzers, which run entirely on the device’s host PC, can also be useful. But, this kind of analyzer only shows data at the host-driver level, not the complete packets on the bus.

DEVELOPMENT STRATEGIES

The first rule for developing USB device firmware is to remember that the host computer controls the bus. Devices just need to respond to received data and events. Device firmware shouldn’t make assumptions about what the host will do next.

For example, some flash drives work under Windows but break when attached to a host with an OS that sends different USB requests or mass-storage commands, sends commands in a different order, or detects errors Windows ignores. This problem is so common that Linux has a file, unusual_devs.h, with fixes for dozens of misbehaving drives.

The first line of defense in writing USB firmware is the free USB-IF Test Suite from the USB Implementers Forum (USB-IF), the trade group that publishes the USB specifications. During testing, the suite replaces the host’s USB driver with a special test driver. The suite’s USB Command Verifier tool checks for errors (e.g., malformed descriptors, invalid responses to standard USB requests, responses to Suspend and Resume signaling, etc.). The suite also provides tests for devices in some USB classes, such as human interface devices (HID), mass storage, and video.

Running the tests will usually reveal issues that need attention. Passing the tests is a requirement for the right to display the USB-IF’s Certified USB logo.

LAYERED COMMUNICATIONS

Like networks, USB communications have layers that isolate different logical functions (see Table 1).

Table 1: USB communications use layers, which are each responsible for a
specific logical function.

The USB protocol layer manages USB transactions, which carry data packets to and from device endpoints. A device endpoint is a buffer that is a source or sink of data at the device. The host sends data to Out endpoints and receives data from In endpoints. (Even though endpoints are on devices, In and Out are defined from the host’s perspective.)

The device layer manages USB transfers, with each transfer moving a chunk of data consisting of one or more transactions. To meet the needs of different peripherals, the USB 2.0 specification defines four transfer types: control, interrupt, bulk, and isochronous.

The function layer manages protocols specific to a device’s function (e.g., mouse, printer, or drive). The function protocols may be a combination of USB class, industry, and vendor-defined protocols.

CONTROLLER ARCHITECTURES

The layers supported by device firmware vary with the device hardware. At one end of the spectrum, a Future Technology Devices International (FTDI) FT232R USB UART controller handles all the USB protocols in hardware. The chip has a USB device port that connects to a host computer and a UART port that connects to an asynchronous serial port on the device.

Device firmware reads and writes data on the serial port, and the FT232R converts it between the USB and UART protocols. The device firmware doesn’t have to know anything about USB. This feature has made the FT232R and similar chips popular!

An example of a chip that is more flexible but requires more firmware support is Microchip Technology’s PIC18F4550 microcontroller, which has an on-chip, full-speed USB device controller. In return for greater firmware complexity, the PIC18F4550 isn’t limited to a particular host driver and can support any USB class or function.

Each of the PIC18F4550’s USB endpoints has a series of registers—called a buffer descriptor table (BDT)—that store the endpoint buffer’s address, the number of bytes to send or receive, and the endpoint’s status. One of the BDT’s status bits determines the BDT’s ownership. When the CPU owns the BDT, firmware can write to the registers to prepare to send data or to retrieve received data. When the USB module owns the BDT, the endpoint can send or receive data on the bus.

To send a data packet from an In endpoint, firmware stores the bytes’ starting address to send and the number of bytes and sets a register bit to transfer ownership of the BDT to the USB module. The USB module sends the data in response to a received In token packet on the endpoint and returns BDT ownership to the CPU so firmware can set up the endpoint to send another packet.

To receive a packet on an Out endpoint, firmware stores the buffer’s starting address for received bytes and the maximum number of bytes to receive and transfers ownership of the BDT to the USB module. When data arrives, the USB module returns BDT ownership to the CPU so firmware can retrieve the data and transfer ownership of the BDT back to the USB module to enable the receipt of another packet.

Other USB controllers have different architectures and different ways of managing USB communications. Consult your controller chip’s datasheet and programming guide for details. Example code from the chip vendor or other sources can be helpful.

DEBUGGING TRANSACTIONS

A USB 2.0 transaction consists of a token packet and, as needed, a data packet and a handshake packet. The token packet identifies the packet’s type (e.g., In or Out), the destination device and endpoint, and the data packet direction.

The data packet, when present, contains data sent by the host or device. The handshake packet, when present, indicates the transaction’s success or failure.

The data and handshake packets must transmit quickly after the previous packet, with only a brief inter-packet delay and bus turnaround time, if needed. Thus, device hardware typically manages the receiving and sending of packets within a transaction.

For example, if an endpoint’s buffer has room to accept a data packet, the endpoint stores the received data and returns ACK in the handshake packet. Device firmware can then retrieve the data from the buffer. If the buffer is full because firmware didn’t retrieve previously received data, the endpoint returns NAK, requiring the host to try again. In a similar way, an In endpoint will NAK transactions until firmware has loaded the endpoint’s buffer with data to send.

Fine tuning the firmware to quickly write and retrieve data can improve data throughput by reducing or eliminating NAKs. Some device controllers support ping-pong buffers that enable an endpoint to store multiple packets, alternating between the buffers, as needed.

LOST DATA

In all but isochronous transfers, a data-toggle value in the data packet’s packet identification (PID) field guards against missed or duplicate data packets. If you’re debugging a device where data is transmitting on the bus and the receiver is returning ACK but ignoring or discarding the data, chances are good that the device isn’t sending or expecting the correct data-toggle value. Some device controllers handle the data toggles completely in hardware, while others require some firmware control.

Each endpoint maintains its own data toggle. The values are DATA0 (0011B) and DATA1 (1011B). Upon detecting an incoming data packet, the receiver compares its data toggle’s state with the received data toggle. If the values match, the receiver toggles its value and returns ACK, causing the sender to toggle its value for the next transaction.

The next received packet should contain the opposite data toggle, and again the receiver toggles its bit and returns ACK. Except for control transfers, the data toggle on each end continues to alternate in each transaction. (Control transfers always use DATA0 in the Setup stage, toggle the value for each transaction in the Data stage, and use DATA1 in the Status stage.)

If the receiver returns NAK or no response, the sender doesn’t toggle its bit and tries again with the same data and data toggle. If a receiver returns ACK, but for some reason the sender doesn’t see the ACK, the sender thinks the receiver didn’t receive the data and tries again using the same data and data toggle. In this case, the repeated data receiver ignores the data, doesn’t toggle the data toggle, and returns ACK, resynchronizing the data toggles. If the sender mistakenly sends two packets in a row with the same data-toggle value, upon receiving the second packet, the receiver ignores the data, doesn’t toggle its value, and returns ACK.

DEFINING A TRANSFER

All USB devices must support control transfers and may support other transfer types. Control transfers provide a structure for sending requests but have no guaranteed delivery time. Interrupt transfers have a guaranteed maximum latency (i.e., delay) between transactions, but the host permits less bandwidth for interrupt transfers compared to other transfer types. Bulk transfers are the fastest on an otherwise idle bus, but they have no guaranteed delivery time, and thus can be slow on a busy bus. Isochronous transfers have guaranteed delivery time but no built-in error correction.

A transfer’s amount of data depends in part on the higher-level protocol that determines the data packets’ contents. For example, a keyboard sends keystroke data in an interrupt transfer that consists of one transaction with 8 data bytes. To send a large file to a drive, the host typically uses one or more large transfers consisting of multiple transactions. For a high-speed drive, each transaction, except possibly the last one, has 512 data bytes, which is the maximum-allowed packet size for high-speed bulk endpoints.

What determines a transfer’s end varies with the USB class or vendor protocol. In many cases, a transfer ends with a short packet, which is a packet that contains less than the packet’s maximum-allowed data bytes. If the transfer has an even multiple of the packet’s maximum-allowed bytes, the sender may indicate the end of the transfer with a zero-length packet (ZLP), which is a data packet with a PID and error-checking bits but no data.

For example, USB virtual serial-port devices in the USB communications device class use short packets to indicate the transfer’s end. If a device has sent data that is an exact multiple of the endpoint’s maximum packet size and the host sends another In token packet, the endpoint should return a ZLP to indicate the data’s end.

DEBUGGING ENUMERATION

Upon device attachment, in a process called enumeration, the host learns about the device by requesting a series of data structures called descriptors. The host uses the descriptors’ information to assign a driver to the device.

If enumeration doesn’t complete, the device doesn’t have an assigned driver, and it can’t perform its function with the host. When Windows fails to find an appropriate driver, the setupapi.dev.log file in Windowsinf (for Windows 7) can offer clues about what went wrong. A protocol analyzer shows if the device returned all requested descriptors and reveals mistakes in the descriptors.

During device development, you may need to change the descriptors (e.g., add, remove, or edit an endpoint descriptor). Windows has the bad habit of remembering a device’s previous descriptors on the assumption that a device will never change its descriptors. To force Windows to use new descriptors, uninstall then physically remove and reattach the device from Windows Device Manager. Another option is to change the device descriptor’s product ID to make the device appear as a different device.

DEBUGGING TRANSFERS

Unlike the other transfer types, control transfers have multiple stages: setup, (optional) data, and status. Devices must accept all error-free data packets that follow a Setup token packet and return ACK. If the device is in the middle of another control transfer and the host sends a new Setup packet, the device must abandon the first transfer and begin the new one. The data packet in the Setup stage contains important information firmware should completely decode (see Table 2).

Table 2: Device firmware should fully decode the data received in a control transfer’s Setup stage. (Source: USB Implementers Forum, Inc.)

The wLength field specifies how many bytes the host wants to receive. A device shouldn’t assume how much data the host wants but should check wLength and send no more than the requested number of bytes.

For example, a request for a configuration descriptor is actually a request for the configuration descriptor and all of its subordinate descriptors. But, in the first request for a device’s configuration descriptor, the host typically sets the wLength field to 9 to request only the configuration descriptor. The descriptor contains a wTotalLength value that holds the number of bytes in the configuration descriptor and its subordinate descriptors. The host then resends the request setting wLength to wTotalLength or a larger value (e.g., FFh). The device returns the requested descriptor set up to wTotalLength. (Don’t assume the host will do it this way. Always check wLength!)

Each Setup packet also has a bmRequestType field. This field specifies the data transfer direction (if any), whether the recipient is the device or an interface or endpoint, and whether the request is a standard USB request, a USB class request, or a vendor-defined request. Firmware should completely decode this field to correctly identify received requests.

A composite device has multiple interfaces that function independently. For example, a printer might have a printer interface, a mass-storage interface for storing files, and a vendor-specific interface to support vendor-defined capabilities. For requests targeted to an interface, the wIndex field typically specifies which interface applies to the request.

INTERRUPT TRANSFER TIMING

For interrupt endpoints, the endpoint descriptor contains a bInterval value that specifies the endpoint’s maximum latency. This value is the longest delay a host should use between transaction attempts.

A host can use the bInterval delay time or a shorter period. For example, if a full-speed In endpoint has a bInterval value of 10, the host can poll the endpoint every 1 to 10 ms. Host controllers typically use predictable values, but a design shouldn’t rely on transactions occurring more frequently than the bInterval value.

Also, the host controller reserves bandwidth for interrupt endpoints, but the host can’t send data until a class or vendor driver provides something to send. When an application requests data to be sent or received, the transfer’s first transaction may be delayed due to passing the request to the driver and scheduling the transfer.

Once the host controller has scheduled the transfer, any additional transaction attempts within the transfer should occur on time, as defined by the endpoint’s maximum latency. For this reason, sending a large data block in a single transfer with multiple transactions can be more efficient than using multiple transfers with a portion of the data in each transfer.

DEVICE FUNCTIONS

Most devices’ functions fit a defined USB class (e.g., mass storage, printer, audio, etc.). The USB-IF’s class specifications define protocols for devices in the classes.

For example, devices in the HID class must send and receive all data in data structures called reports. The supported report’s length and the meaning of its data (e.g., keypresses, mouse movements, etc.) are defined in a class-specific report descriptor.

If your HID-class device is sending data but the host application isn’t seeing the data, verify the number of bytes the device is sending matches the number of bytes in a defined report. The device should prepend a report-ID byte to the data only if the HID supports report IDs other than the zero default value.

In many devices, class specifications define class-specific requests or other requirements. For example, a mass storage device that uses the bulk-only protocol must provide a unique serial number in a string descriptor. Carefully read and heed any class specifications that apply to your device!

Many devices also support industry protocols to perform higher-level functions. Printers typically support one or more printer-control languages (e.g., PCL and Postscript). Mass-storage devices support SCSI commands to transfer data blocks and a file system (e.g., FAT32) to define a directory structure.

The higher-level industry protocols don’t depend on a particular hardware interface, so there is little about debugging them that is USB-specific. But, because these protocols can be complicated, example code for your device can be helpful.

In the end, much about debugging USB firmware is like debugging any hardware or software. A good understanding of how the communications should work provides a head start on writing good firmware and finding the source of any problems that may appear.

Jan Axelson is the author of USB Embedded Hosts, USB Complete, and Serial Port Complete. Jan’s PORTS web forum is available at www.lvr.com.

RESOURCES

Jan Axelson’s Lakeview Research, “USB Development Tools: Protocol analyzers,” www.lvr.com/development_tools.htm#analyzers.

This article appears in Circuit Cellar 268 (November 2012).

DIY Green Energy Design Projects

Ready to start a low-power or energy-monitoring microcontroller-based design project? You’re in luck. We’re featuring eight award-winning, green energy-related designs that will help get your creative juices flowing.

The projects listed below placed at the top of Renesas’s RL78 Green Energy Challenge.

Electrostatic Cleaning Robot: Solar tracking mirrors, called heliostats, are an integral part of Concentrating Solar Power (CSP) plants. They must be kept clean to help maximize the production of steam, which generates power. Using an RL78, the innovative Electrostatic Cleaning Robot provides a reliable cleaning solution that’s powered entirely by photovoltaic cells. The robot traverses the surface of the mirror and uses a high voltage AC electric field to sweep away dust and debris.

Parts and circuitry inside the robot cleaner

Cloud Electrofusion Machine: Using approximately 400 times less energy than commercial electrofusion machines, the Cloud Electrofusion Machine is designed for welding 0.5″ to 2″ polyethylene fittings. The RL78-controlled machine is designed to read a barcode on the fitting which determines fusion parameters and traceability. Along with the barcode data, the system logs GPS location to an SD card, if present, and transmits the data for each fusion to a cloud database for tracking purposes and quality control.

Inside the electrofusion machine (Source: M. Hamilton)

The Sun Chaser: A GPS Reference Station: The Sun Chaser is a well-designed, solar-based energy harvesting system that automatically recalculates the direction of a solar panel to ensure it is always facing the sun. Mounted on a rotating disc, the solar panel’s orientation is calculated using the registered GPS position. With an external compass, the internal accelerometer, a DC motor and stepper motor, you can determine the solar panel’s exact position. The system uses the Renesas RDKRL78G13 evaluation board running the Micrium µC/OS-III real-time kernel.

[Video: ]

Water Heater by Solar Concentration: This solar water heater is powered by the RL78 evaluation board and designed to deflect concentrated amounts of sunlight onto a water pipe for continual heating. The deflector, armed with a counterweight for easy tilting, automatically adjusts the angle of reflection for maximum solar energy using the lowest power consumption possible.

RL78-based solar water heater (Source: P. Berquin)

Air Quality Mapper: Want to make sure the air along your daily walking path is clean? The Air Quality Mapper is a portable device designed to track levels of CO2 and CO gasses for constructing “Smog Maps” to determine the healthiest routes. Constructed with an RDKRL78G13, the Mapper receives location data from its GPS module, takes readings of the CO2 and CO concentrations along a specific route and stores the data in an SD card. Using a PC, you can parse the SD card data, plot it, and upload it automatically to an online MySQL database that presents the data in a Google map.

Air quality mapper design (Source: R. Alvarez Torrico)

Wireless Remote Solar-Powered “Meteo Sensor”: You can easily measure meteorological parameters with the “Meteo Sensor.” The RL78 MCU-based design takes cyclical measurements of temperature, humidity, atmospheric pressure, and supply voltage, and shares them using digital radio transceivers. Receivers are configured for listening of incoming data on the same radio channel. It simplifies the way weather data is gathered and eases construction of local measurement networks while being optimized for low energy usage and long battery life.

The design takes cyclical measurements of temperature, humidity, atmospheric pressure, and supply voltage, and shares them using digital radio transceivers. (Source: G. Kaczmarek)

Portable Power Quality Meter: Monitoring electrical usage is becoming increasingly popular in modern homes. The Portable Power Quality Meter uses an RL78 MCU to read power factor, total harmonic distortion, line frequency, voltage, and electrical consumption information and stores the data for analysis.

The portable power quality meter uses an RL78 MCU to read power factor, total harmonic distortion, line frequency, voltage, and electrical consumption information and stores the data for analysis. (Source: A. Barbosa)

High-Altitude Low-Cost Experimental Glider (HALO): The “HALO” experimental glider project consists of three main parts. A weather balloon is the carrier section. A glider (the payload of the balloon) is the return section. A ground base section is used for communication and display telemetry data (not part of the contest project). Using the REFLEX flight simulator for testing, the glider has its own micro-GPS receiver, sensors and low-power MCU unit. It can take off, climb to pre-programmed altitude and return to a given coordinate.

High-altitude low-cost experimental glider (Source: J. Altenburg)

AC Tester Schematic Update

An error was found in one of the AC tester schematics that ran in Kevin Gorga’s June 2012 article, “AC Tester” (Circuit Cellar 263). As a reader indicated, T2 is disconnected in the published version of the schematic. An edited schematic follows.

Edited version of Figure 2 in K. Gorga’s June 2012 article, “AC Tester” (Source: Paul Alciatore)

The correction is now available on Circuit Cellar‘s Errata, Corrections, & Updates page.

Implement a Tilt and Interference-Compensated Electronic Compass

Would you like to incorporate an electronic compass in a consumer product you’re designing or a personal device you’re constructing? If so, you’ll do well to understand as much as possible about the differences between various sensors and how certain forms of interference can affect their accuracies.

Mark Pedley of Freescale Semiconductor has an article in Circuit Cellar 265 (August 2012) on these topics. An abridged version of his article follows. Pedley writes:

 Whenever a new high-volume consumer electronics market develops, the semiconductor companies are never far behind, providing excellent components at surprisingly low prices. The market for sensors in consumer products is a recent example. It all started with an accelerometer used to select between portrait and landscape display orientations and then, with the addition of a magnetometer, evolved into the electronic compass (eCompass) used to align street maps to the smartphone’s geographic heading or to enable augmented reality overlays. As a result, high-volume pricing for smartphone accelerometer and magnetometer sensors is now less than $1 each.

A magnetometer sensor alone cannot provide an accurate compass heading for two reasons. First, the magnetic field measured at the magnetometer varies significantly with tilt angle. Second, the magnetometer requires calibrating not only for its own offset but also against spurious magnetic fields resulting from any nearby ferromagnetic components on the circuit board. This article describes how the accelerometer is used to compensate the magnetometer for tilt and includes a simple technique for calibrating the magnetometer.

SENSOR SELECTION

The accelerometer should be three axis and capable of operating in the ±2-g range with a minimum of 10 bits of resolution. The output of a 10-bit accelerometer operating in the ±2-g range will change by 512 counts as the accelerometer is rotated 180° from pointing downward to upward, giving an average sensitivity of one count per 0.35° change in tilt. This is more than adequate for tilt-compensation purposes.

It is important to check the accelerometer datasheet for the “0-g offset accuracy” which is the output when the accelerometer is in 0-g freefall. Since this value is a constant additive error on each accelerometer channel, it adds a bias in the calculated tilt angles, so look for accelerometers where this parameter does not exceed 50 mg.

The magnitude of the earth’s geomagnetic field is typically about 50 µT with a horizontal component that varies over the earth’s surface, from a maximum of about 40 µT down to 0 at the geomagnetic poles. If an eCompass is required to operate in horizontal geomagnetic fields down to 10 µT (in arctic Canada, for example) with a noise jitter of ±3°, then a back-of-the-envelope calculation indicates that a magnetometer with a maximum noise level of 0.5 µT is needed.

Most of my projects have used Freescale’s MMA8451Q Xtrinsic three-axis, 14-bit accelerometer and MAG3110 three-axis magnetometer. The MMA8451Q is supplied in a 3-mm × 3-mm × 1-mm, 16-pin QFN package and provides a 14-bit data output with ±30-mg, 0-g offset accuracy. The MAG3110 magnetometer is supplied in a 2-mm × 2-mm × 0.85 mm, 10-pin DFN package and provides a measurement range of ±1,000 µT with 0.1-µT resolution and a noise level down to 0.25 µT. Both parts operate with a supply voltage between 1.95 V and 3.6 V.

Similar sensors are supplied by Asahi Kasei (AKM), Kionix, STMicroelectronics, and other manufacturers. Your best strategy is to go to the manufacturers’ websites and make a list of those that provide samples in single units or low-volume packs of up to five devices. With a bit of luck, you may be able to get both the accelerometer and magnetometer sensors for free. Add a handful of decoupling capacitors and pull-up resistors and you should be well within the $5 component cost.

Each reader has a preferred microcontroller to read the raw data from the two sensors and implement the eCompass. This article assumes the microcontroller provides an I2C bus to interface to the sensors, supports floating-point operations whether natively or through software emulation libraries, and has a few spare bytes of program and data memory…

LAYOUT & BOARD BRING-UP

Once you’ve selected your sensors, the next step is to design the accelerometer and magnetometer daughterboard with I2C bus connection to the microcontroller. Reference schematics for the MMA8451Q and MAG3110 are provided in the sensor datasheets and reproduced in Figure 1.

Figure 1: Schematics for (a) MMA8451Q and (b) MAG3110 sensors (Source: M. Pedley, Circuit Cellar 265)

Don’t waste any time rotating the accelerometer or magnetometer packages to align their x-, y-, and z-sensing directions to each other since this will be  fixed later in software. But do ensure the sensor board will not be mounted in the immediate vicinity of any ferromagnetic materials since these will produce a constant additive magnetic field termed the “hard-iron field.” The most common ferromagnetic materials are iron, steel, ferrite, nickel, and cobalt. Non-ferromagnetic materials are all safe to use (e.g., aluminum, copper, brass, tin, silver, and gold).

The calibration process described later enables the estimation and software subtraction of any hard-iron field, but it’s good practice to minimize hard iron interference at the design stage. Remember, a current trace will create a cylindrical magnetic field that falls off relatively slowly with the inverse of distance, so place the magnetometer as far away from high current traces as possible. A 0.1-A current trace at 10-mm distance will produce a 2-µT magnetic field, four times our 0.5-µT error budget, only reducing to 0.5 µT at a 40-mm distance. More detailed layout guidance is provided in Freescale Semiconductor’s application note AN4247: “Layout Recommendations for PCBs Using a Magnetometer Sensor.”

You’ll be surprised at the number of features implemented in the latest consumer sensors (i.e., freefall detection, high- and low-pass filtering options, automatic portrait and landscape detection, etc.), but disable all these since you simply want the raw accelerometer and magnetometer data. Configure the accelerometer into a 2-g range and check that you can read the x, y, and z accelerometer and magnetometer data (in units of bit counts) from the sensors’ internal registers at a sampling rate of between 10 Hz and 50 Hz. Smartphones commonly use IDH3 to minimize power consumption while anything above 50 Hz is overkill. Check the accelerometer datasheet for the conversion factor between counts and g (4,096 counts per g for the MMA8451Q in ±2-g mode) and use this to scale the x, y, z accelerometer readings into units of g. Do the same for the x, y, z magnetometer data again taking the conversion factor from the magnetometer datasheet (10 counts per µT for the MAG3110).

COORDINATE SYSTEM

The equations and C software in Listing 1 use the “aerospace,” or “x-North y-East z-Down,” coordinate system depicted in Photo 1.

Listing 1: C source code for the tilt-compensated eCompass (Source: M. Pedley, Circuit Cellar 265)

This defines the initial eCompass orientation to be where the x-axis points north, the y-axis points east, and the z-axis points downwards. The three orientation angles, roll (ϕ), pitch (θ), and compass heading, or yaw (ψ)—are defined as clockwise rotations about the positive x, y, and z axes— respectively. Photo 1 also shows the earth’s gravitational vector which points downward with magnitude of 1 g or 9.81 ms-2 and the earth’s geomagnetic field vector, which points downward from horizontal (in the northern hemisphere) by the inclination angle δ to give a horizontal component B0cosδ and a downward component B0sinδ.

Photo 1: The aerospace noth-east-down coordinate system (Source: M. Pedley, Circuit Cellar 265)

Based on how your eCompass housing will be held, you should be able to assign the compass-pointing direction or x-axis, the downward or z-axis, and the y-axis, which should point to the right to complete a right-handed coordinate system.

AXIS ALIGNMENT & MAGNETIC CALIBRATION

You now need to align the sensor data to the aerospace coordinate system. As with all work with magnetometers, this should be performed on a wooden table well away from any laboratory power supplies or steel furniture. Place the eCompass flat and upright so the z-axis points downward and is aligned with gravity. Check that the accelerometer z-axis reads approximately 1 g and the x- and y-axes are near 0. Invert the eCompass so its z-axis points upward and check that the z-axis now reads approximately –1 g. Repeat with the x- and y-axes pointing downward and then upward and check that the x- and  y-axis accelerometer readings are near 1 g and –1 g, respectively. It’s not important if the accelerometer readings are a few tens of mg away from the required reading since all you’re doing here is correcting for gross rotations of the sensor packages and the sensor daughterboard in multiples of 90°. Any needed correction will be unique for your board layout and mounting orientation but will be no more complicated than “swap the x- and y-accelerometer channels and negate the z-channel reading.” Code this accelerometer axis mapping into your software and don’t touch it again.

Figure 2 may help explain this visually. The accelerometer sensor measures both gravity and linear acceleration and, in the absence of any linear acceleration (as is the case when sitting on a desk), the magnitude of the accelerometer reading will always equal 1 g, and therefore, lie on the surface of a 1-g sphere, irrespective of the orientation.

Figure 2: Accelerometer axis alignment points (Source: M. Pedley, Circuit Cellar 265)

The six measurements  lie on the vertices of an octahedron inscribed within the 1-g sphere and the axis mapping simply rotates and reflects the octahedron as needed until the accelerometer channels are correctly aligned.

The magnetometer axis alignment is similar to that of the accelerometer, but makes use of the geomagnetic field vector. Place the eCompass flat, upright, and pointing northward and then rotate in yaw angle by 270° to the east, south, and finally west. The x-channel magnetometer reading should be a maximum when the eCompass is pointed north and a minimum when pointed south. The y-channel magnetometer reading should be a minimum when the eCompass is pointed east and a maximum when pointed west. The z-channel reading should be approximately constant since the vertical component of the geomagnetic field is constant irrespective of rotation in yaw.

Then invert the eCompass on the desk and repeat the process. As before, the magnetometer x-axis reading should be a maximum when the eCompass is pointed north and a minimum when pointed south. But now, because of the inverted position, the magnetometer y-axis should be a maximum when the eCompass is pointed east and a minimum when pointed west. The magnetometer z-axis reading should still be constant but, in the northern hemisphere, lower than the previous upright readings since the magnetometer z-axis is now aligned against the downward component of the geomagnetic field vector.

Figure 3 shows upright and inverted magnetometer measurements taken in the northern hemisphere with a 270o compass rotation.

Figure 3: The upright (a) and inverted (b) magnetometer measurements (Source: M. Pedley, Circuit Cellar 265)

The maximum and minimum of the x- and y-axis magnetometer measurements occur at the expected angles and the z-axis measurement is less when inverted than when upright. These magnetometer axes are therefore correctly aligned but, as with the accelerometer correction, swap and negate the measurements from your three magnetometer channels as needed until correctly aligned and then lock down this part of your code.

A lot can be learned by closely looking at the measurements in Figure 3. The x- and y-magnetometer measurements lie on a circle with radius of approximately 25 µT enabling us to deduce that the horizontal geomagnetic field is approximately 25 µT. But the measurements are offset from zero by the magnetic “hard iron” interfering field, which results from both permanently magnetized ferromagnetic materials on the circuit board and from a zero-field offset in the magnetometer sensor itself. Consumer sensor manufacturers long ago realized it was pointless to accurately calibrate their magnetometers when their target market is smartphones, each with a different hard-iron interfering field. The magnetometer sensor offset is, therefore, calibrated together with the circuit board hard-iron magnetic field. For now, simply note that the x and y components of the hard iron offset have values of approximately 215 µT and 185 µT. A simple method to determine all three hard-iron components is described later.

Refer to the complete article for information about calculating the roll and pitch angles and determining the compass heading angle.

Mark Pedley has a Physics degree from Oxford University and now works on sensor fusion algorithms for Freescale Semiconductor in Tempe, Arizona.

The Basics of Thermocouples

Whether you’re looking to build a temperature-sensing device or you need to add sensing capabilities to a larger system, you should familiarize yourself with thermocouples and understand how to design thermocouple interfaces. Bob Perrin covered these topics and more in 1999 Circuit Cellar Online article , “The Basics of Thermocouples.” The article appears below in its entirety.

A mathematician, a physicist, and an engineer were at lunch. The bartender asked the three gentlemen, “what is this pi I hear so much about?”

The mathematician replied, “pi is the ratio of a circle’s circumference to its diameter.”

The physicist answered, “pi is 3.14159265359.”

The engineer looked up, flatly stated, “Oh, pi’s about three,” then promptly went back to doodling on the back of his napkin.

The point is not that engineers are sloppy, careless, or socially inept. The point is that we are eminently practical. We are solvers of problems in a non-ideal world. This means we must be able to apply concepts to real problems and know when certain effects are negligible in our application.

For example, when designing first- or second-order filters, 3 is often a close enough approximation for pi, given the tolerance and temperature dependence of affordable components.

But, before we can run off and make gross approximations, we must understand the physical principles involved in the system we’re designing. One topic that seems to suffer from gross approximations without a firm understanding of the issues involved is temperature measurement with thermocouples.

Thermocouples are simple temperature sensors consisting of two wires made from dissimilar alloys. These devices are simple in construction and easy to use. But, like any electronic component, they require a certain amount of explanation. The intent of this paper is to present and explain how to use thermocouples and how to design thermocouple interfaces.

A TAIL OF TWO METALS

Figure 1a shows a thermocouple. One junction is designated the hot junction. The other junction is designated as the cold or reference junction. The current developed in the loop is proportional to the difference in temperature between the hot and cold junctions. Thermocouples measure differences in temperature, not absolute temperature.

Figure 1a: Two wires are all that are required to form a thermocouple.

To understand why a current is formed, we must revert to physics. Unfortunately, I’m not a physicist, so this explanation may bend a concept or two, but I’ll proceed nonetheless.

Consider a homogenous metallic wire. If heat is applied at one end, the electrons at that end become more energetic. They absorb energy and move out of their normal energy states and into higher ones. Some will be liberated from their atoms entirely. These newly freed highly energetic electrons move toward the cool end of the wire. As these electrons speed down the wire, they transfer their energy to other atoms. This is how energy (heat) is transferred from the hot end to the cool end of the wire.

As these electrons build up at the cool end of the wire, they experience an electrostatic repulsion. The not-so-energetic electrons at the cool end move toward the hot end of the wire, which is how charge neutrality is maintained in the conductor.

The electrons moving from the cold end toward the hot end move slower than the energetic electrons moving from the hot end move toward the cool end. But, on a macroscopic level, a charge balance is maintained.

When two dissimilar metals are used to form a thermocouple loop, as in Figure 1a, the difference in the two metal’s affinity for electrons enables a current to develop when a temperature differential is set up between the two junctions.

As electrons move from the cold junction to the hot junction, these not-so-energetic electrons are able to move easier in one metal than the other. The electrons that are moving from the hot end to the cold end have already absorbed a lot of energy, and are free to move almost equally well in both wires. This is why an electric current is developed in the loop.

I may have missed some finer points of the physics, but I think I hit the highlights. If anyone can offer a more in-depth or detailed explanation, please e-mail me. One of the best things about writing for a technical audience is learning from my readers.

BREAKING THE LOOP

If you use thermocouples, you must insert a measurement device in the loop to acquire information about the temperature difference between the hot and cold junctions. Figure 1b shows a typical setup. The thermocouple wires are brought to a terminal block and an electric circuit measures the open circuit voltage.

Figure 1b: To use a thermocouple, you must have a measurement system.

When the thermocouple wires are connected to the terminal block, an additional pair of thermocouples is formed (one at each screw terminal). This is true if the screw-terminals are a different alloy from the thermocouple wires. Figure 1c shows an alternate representation of Figure 1b. Junction 2 and junction 3 are undesired artifacts of the connection to the measurement circuitry. These two junctions are commonly called parasitic thermocouples.

Figure 1c: The act of connecting a measurement system made of copper introduces two parasitic thermocouples.

In a physical circuit, parasitic thermocouples are formed at every solder joint, connector, and even every internal IC bond wire. If it weren’t for something called the Law of Intermediate Metals, these parasitic junctions would cause us endless trouble.

The Law of Intermediate Metals states that a third metal may be inserted into a thermocouple system without affecting the system if, and only if, the junctions with the third metal are kept isothermal (at the same temperature).

In Figure 1c, if junction 2 and junction 3 are at the same temperature, they will have no effect on the current in the loop. The voltage seen by the voltmeter in Figure 1b will be proportional to the difference in temperature between Junction 1 and Junctions 2 and 3.

Junction 1 is the hot junction. The isothermal terminal block is effectively removed electrically from the circuit, so the temperature of the cold junction is the temperature of the terminal block.

MEASURING TEMPERATURE

Thermocouples produce a voltage (or loop current) that is proportional to the difference in temperature between the hot junction and the reference junction. If you want to know the absolute temperature at the hot junction, you must know the absolute temperature of the reference junction.

There are three ways to find out the temperature of the reference junction. The simplest method is to measure the temperature at the reference junction with a thermistor or semiconductor temperature sensor such as Analog Devices’ TMP03/04. Then, in software, add the measured thermocouple temperature (the difference between the hot junction and the reference junction) to the measured temperature of the reference junction. This calculation will yield the absolute temperature of the hot junction.

The second method involves holding the reference junction at a fixed and known temperature. An ice bath, or an ice slushy, is one of the most common methods used in laboratory settings. Figure 2 shows how this is accomplished.

Figure 2: By inserting a short pigtail of Metal A onto the terminal block where Metal B would normally connect, we move the cold junction.

Alternately, we could have omitted the pigtail of Metal A and just immersed the terminal block in the ice. This would work fine, but it would be much messier than the method shown in Figure 2.

Sometimes, the temperature of the cold junction (terminal block) in Figure 1c is allowed to float to ambient. Then ambient is assumed to be “about 25°C,” or some other “close enough” temperature. This method is usually found in systems where knowing the temperature of the hot junction is not overly critical.

The third method used to nail down the cold junction temperature is to use a cold junction compensation IC such as the Analog Devices AD594 or Linear Technology LT1025. This method sort of combines the first two methods.

These ICs have a temperature sensor in them that detects the temperature of the cold junction. This is presumably the same temperature as the circuit board on which the IC is mounted. The IC then produces a voltage that is proportional to the voltage produced by a thermocouple with its hot junction at ambient and its cold junction at 0°C. This voltage is added to the EMF produced by the thermocouple. The net effect is the same as if the cold junction were physically held at 0°C.

The act of knowing (or approximating) the cold junction temperature and taking this information in to account in the overall measurement is referred to as cold junction compensation. The three techniques I discussed are each methods of cold junction compensation.

The ice bath is probably the most accurate method. An ice slushy can maintain a uniformity of about 0.1°C without much difficulty. I’ve read that an ice bath can maintain a uniformity of 0.01°C, but I’ve never been able to achieve that level of uniformity. Ice baths are physically awkward and therefore usually impractical for industrial measurements.

The off-the-shelf cold junction compensation ICs can be expensive and generally are only accurate to a few degrees Celsius, but many systems use these devices.

Using a thermistor, or even the PN junction on a diode or BJT, to measure the cold junction temperature can be fairly inexpensive and quite accurate. The most common difficulty encountered with this system is calibration. Prudent positioning of the sensor near, or on the terminal block is important.

If the terminal block is to be used as the cold junction (see Figure 1b), the terminal block must be kept isothermal. In practice, keeping the terminal block truly isothermal is almost impossible. So, compromises must be made. This is the stock and trade of engineers. Knowing what is isothermal “enough” for your application is the trick.

Lots of money can be wasted on precision electronics if the terminal block’s screw terminals are allowed to develop a significant thermal gradient. This condition generally happens when power components are placed near the terminal blocks. You must pay careful attention to keeping the temperature stable around the terminal blocks.

There are two broad classes of temperature-measurement applications. The first class involves measuring absolute temperature. For example, you may want to know the temperature of the inside of an oven relative to a standard temperature scale (like the Celsius scale). This type of application requires that you know precisely the absolute temperature of the reference junction.

The second type of measurement involves measuring differences in temperature. For example, in a microcalorimeter, you may want to measure the temperature of the system, then start some chemical reaction and measure the temperature as the reaction proceeds. The information of value is the difference between first measurement and the subsequent ones.

Systems that measure temperature differences are generally easier to construct because control or precise measurement of the reference junction isn’t required. What is required is that the reference junction remain at a constant temperature while the two measurements occur. Whether the reference junction is at 25.0°C or 30.0°C isn’t relevant because the subtraction of consecutive measurements will remove the reference junction temperature from the computed answer.

You can use thermocouples to make precise differential temperature measurements, but you must ensure the terminal block forming the cold junction is “close enough” to isothermal. You must also ensure that the cold junction has enough thermal mass so it will not change temperature over the time you have between measurements.

PRACTICAL MATTERS

Thermocouples are given a letter designation that indicates the materials they are fabricated from. This letter designation is called the thermocouples “type.” Table 1 shows the common thermocouples available and their usable temperature ranges.

Table 1: There are a wide variety of industry-standard alloy combinations that form standard thermocouples. The most commonly used are J, K, T, and E.

Each thermocouple type will produce a different open-circuit voltage (Seebeck voltage) for a given set of temperature conditions. None of these devices are linear over a full range of temperatures. There are standard tables available that tabulate Seebeck voltages as a function of temperature.[1] There are also standard polynomial models available for thermocouples.

Thermocouples produce a small Seebeck voltage. For example, a type K thermocouple produces about 40 µV per degree Celsius when both junctions are near room temperature. The most sensitive of the thermocouples, type E, produces about 60 µV per degree Celsius when both junctions are near room temperature.

In many applications, the range of temperatures being measured is sufficiently small that the Seebeck voltage is assumed to be linear over the range of interest. This eliminates the need for lookup tables or polynomial computation in the system. Often the loss of absolute accuracy is negligible, but this tradeoff is one the design engineer must weigh carefully.

CIRCUITS

When designing a thermocouple interface, there are only a few pieces of information you need to know:

  • what type of thermocouple will be used
  • what is the full range of temperatures the hot junction will be exposed to
  • what is the full range of temperatures the cold junction will be exposed to
  • what is the temperature resolution required for your application
  • does your system require galvanic isolation
  • what type of cold junction compensation will be used

If the answer to the last question requires the analog addition of a voltage from a commercial cold junction compensation IC, then the manufacturer of the IC will probably supply you with an adequate reference design. If you plan to do the cold-junction compensation either physically (by an ice bath) or in software (by measuring the cold junction’s temperature with another device), then you must build or buy a data-acquisition system.

Galvanic isolation is an important feature in many industrial applications. Because thermocouples are really just long loops of wire, they will often pick up high levels of common-mode noise. In some applications, the thermocouples may be bonded to equipment that is at line voltage (or higher).

In this case, galvanic isolation is required to keep high-voltage AC out of your data acquisition system. This type of isolation is usually accomplished in one of two ways—using either an opto-isolator or a transformer. Both systems require the thermocouple signal conditioner to allow its ground to float with respect to earth ground. Figure 3a and 3b outlines these schemes.

Figure 3: Galvanic isolation to a few thousand volts is easy (but a little expensive) using opto-isolation (a) and inexpensive (but a bit more challenging) using a VFC and a transformer (b).

Because the focus of this article is on the interface to the thermocouple, I’ll have to leave the details of implementing galvanic isolation to another article.

Given the tiny voltage levels produced by a thermocouple, the designer of the signal-conditioning module should focus carefully on noise rejection. Using the common-mode rejection (CMR) characteristics of a differential amplifier is a good place to start. Figure 4 shows a simple yet effective thermocouple interface

Figure 4: The common-mode filter and common-mode rejection characteristics pay off in thermocouple amplifiers.

The monolithic instrumentation amplifier (in-amp) is a $2–$5 part (depending on grade and manufacturer). These are usually 8-pin DIP or SOIC devices. In-amps are simple differential amplifiers. The gain is set with a single external resistor. The input impedance of an in-amp is typically 10 gigaohms.

Certainly you can use op-amps, or even discrete parts to build a signal conditioner. However, all the active components on a monolithic in-amp are on the same dice and are kept more-or-less isothermal. This means in-amp characteristics behave nicely over temperature. Good CMR, controllable gain, small size, and high input impedance make in-amps perfect as the heart of a thermocouple conditioning circuit.

Temperature tends to change relatively slowly. So, if you find your system has noise, you can usually install supplementary low-pass filters. These can be implemented in hardware or software. In many systems, it’s not uncommon to take 128 measurements over 1 s and then average the results. Digital filters are big cost reducers in production systems.

Another problem often faced when designing thermocouple circuits is nulling amplifier offset. You can null the amplifier offset in a variety of ways [2], but my favorite is by chopping the input. Figure 5 shows how this process can be accomplished.

Figure 5: An input chopper like a CD4052 is all that is necessary to null signal conditioner offsets.

Thermocouples have such small signal levels, gains on the order of 1000 V/V are not uncommon, which means an op-amp or in-amp with a voltage offset of even 1 mV will have an offset at the output on the order of volts.

The chopper in Figure 5 allows the microcontroller to reverse the polarity of the thermocouple. To null the circuit, the microcontroller will take two measurements then subtract them.

First, set the chopper so the ADC measures GAIN (Vsensor + Voffset). Second, set the chopper so the ADC measures GAIN (–Vsensor + Voffset).

Subtract the second measurement from the first and divide by two. The result is GAIN*Vsensor. As you can see, this is exactly the quantity we are interested in. The in-amp’s offset has been removed from the measurement.

CLOSING TIME

In 1821, Thomas J. Seebeck discovered that if a junction of two dissimilar metals is heated, a voltage is produced. This voltage has since been dubbed the Seebeck voltage.

Thermocouples are found in everything from industrial furnaces to medical devices. At first glance, thermocouples may seem fraught with mystery. They are not. After all, how can a device that’s built from two wires and has been around for 180 years be all that tough to figure out?

When designing with thermocouples, just keep these four concepts in mind and the project will go much smoother. First, thermocouples produce a voltage that is proportional to the difference in temperature between the hot junction and the reference junction.

Second, because thermocouples measure relative temperature differences, cold junction compensation is required if the system is to report absolute temperatures. Cold-junction compensation simply means knowing the absolute temperature of the cold junction and adjusting the reparted temperature value accordingly.

The third thing to remember is that thermocouples have a small Seebeck voltage coefficient, typically on the order of tens of microvolts per degree Celsius. And last, thermocouples are non-linear across their temperature range. Linearization, if needed, is best done in software.

Armed with these concepts, the circuits in this article, and a bit of time, you should have a good start on being able to design a thermocouple into your next project.

Bob Perrin has designed instrumentation for agronomy, soil physics, and water activity research. He has also designed embedded controllers for a variety of other applications.

REFERENCES

[1] www.omega.com/pdf/temperature/z/zsection.asp

[2] B.Perrin, “Practical Analog Design,” Circuit Cellar, #94, May 1998.

SOURCES

AD594, TMP03/04
Analog Devices
www.analog.com

INA118
Texas Instruments (Burr-Brown Corp.)
www.ti.com/ww/analog/index.html

LT1025
Linear Technology
www.linear-tech.com

This article was originally published in Circuit Cellar Online in 1999. Posted with permission. Circuit Cellar and CircuitCellar.com are Elektor International Media publications.