Scientific Instruments Using the TI MSP430

Tutorial 16e: Programming the Flash Memory

2011-11-03T17:36:00.000-04:00

When we call the calibration values CALDCO_1MHZ and CALBC1_1MHZ in the code for our MSP430, those values refer to the address in SegmentA where the values are stored. They're not located in a place that's easy to find, however; they're stored in the linker command file, specific to each device. (If you're curious, take a look at the file in ${base dir}/Texas Instruments/ccsv4/msp430/include/msp430g2231.cmd, where your base directory is wherever you've installed CCS (likely in C:\Program Files for Windows). Be careful not to change anything in this file, though; this file is essential for proper programming of the G2231 device, as each is to their respective devices.) We could make a copy of this file and use it in our linker when we program the MSP430, but that requires a number of steps that are difficult to remember. All we really need is a way to tell our program to look at the specific address where we've saved the calibration values for our UART. All we really need is a pointer.

Pointers
We've not dealt with pointers up to this tutorial, but they're not really a difficult concept. Let's say we have code that declares the following two items:

int var;

int *ptr;

The first is what we're used to seeing; we declare a variable of type int (16 bits in MSP430), which will store a signed integer value. The second is also a declaration of type int, but rather than a variable, it is a pointer. The stored number in ptr doesn't refer to the value of a variable, but rather the address where a variable of type int is stored. (The actual size of the pointer in an MSP430 is 16 bits, so char *ptr; would also be a 16 bit value, even though it points to memory where an 8 bit value is being stored.)

In the C language, we have a way to refer to the address of a specific variable by using the & character. So from this point, if we assign ptr = &var; then ptr now points to the address where we've stored the int value var. Similarly, we can reference the value stored in a pointer with the * character. int var2 = *ptr; would store the value at address ptr in the new variable var2. If we want to assign a specific address to a pointer, rather than reference the address of a variable, we can use a literal of the form (int *)0x1234.

In the MSP430, an int variable takes 16 bits, while a char variable take 8. When we want to reference a specific word, we'll use a pointer of type int. If we want to reference a specific byte, such as the calibration values for the DCO, we'll use a pointer of type char. To use the DCO values we'll program in SegmentB, we can use the following:
char *CALBC1_UART = (char *) 0x10BE;
char *CALDCO_UART = (char *) 0x10BF;

or, if we'd rather not use extra memory, define in the header:
#define CALBC1_UART *(char *) 0x10BE
#define CALDCO_UART *(char *) 0x10BF

The Flash Memory Controller
Ok, now we've got a handle on how to reference portions of the flash memory. Now it's time to learn how to actually write to it. The MSP430 has a peripheral designed specifically to handle managing the flash memory called the Flash Memory Controller. Since it would be dangerous to manipulate the flash memory willy-nilly, it's set up like the Watchdog Timer, so that a key is needed to change any of its four control registers. The key value is 0xA5, conveniently provided in the header files as the value FWKEY. Here are the portions we'll need to know about:

FCTL1

FWKEY (bits 15-8): The key is read as the value 0x96. Each register has this.
BLKWRT (bit 7): control bit for block write mode. We will be writing word by word, so we'll save this function for a future tutorial.
WRT (bit 6): write mode enable. Before we can write to any flash segment, this bit must be enabled.
MERAS & ERASE (bits 2 and 1): Control the mode of erasure. You can erase a single segment, the entire main memory, or the main memory and information segments both. (Depending on whether SegA is unlocked.)

FCTL2

FSSELx (bits 7-6): These bits select which clock source to use for the programming.
FNx (bits 5-0): These bits allow you to divide the source clock by any factor up to 64. (Divide by FNx + 1)

FCTL3

FAIL (bit 7): We don't want to see this bit set! For our purposes, it could mean the clock source has failed for some reason. If this happens, it needs to be reset by software before anything else can be done.
LOCKA (bit 6): I won't go into how this works; this bit controls whether SegA can be erased/written. If you find you absolutely must change something in this segment, you can read in the Family User's Guide to learn how to use this bit.
LOCK (bit 4): When this bit is set, the flash memory is completely locked, and cannot be erased or written.
WAIT (bit 3): Indicates when the flash memory is being erased or written.

FCTL4

This register is not available on all devices; it controls the 'marginal read mode'. We won't be using it here.

To do a successful programming of the Information Segment, we first set the clock for the controller. The actual frequency isn't terribly important, as long as it falls between 257 and 476 kHz. The default DCO setting of the MSP430 is about 1.1 MHz, and so a division of 3 (FNx = 2) works well, giving us roughly 370 kHz. We'll calibrate the DCO to 7.3728 MHz, so a division of 20 (FNx = 19) will give us about the same.

If we have anything we want to save in the segment, then the entire contents would need to be saved to a buffer. Likely, your SegB is blank, so we'll just proceed forward. Next, we set the controller to erase mode. We don't want to erase the main memory segments, so we only need the ERASE bit. We then clear the LOCK bit to allow changing the flash memory. When the controller is configured this way, we initiate the erase cycle by writing to any address within the segment. There's nothing magic about what value we write, but it is absolutely crucial that you have your address pointer pointing to somewhere in the segment you actually want to erase!

Once it has erased, we reconfigure the controller to write mode (not block write), and then proceed to write the values we need, either as bytes or words. If you preserved the prior contents, a better method is to change the contents to the new values and use block write mode. For this tutorial, we'll keep it simple.

Finally, when everything is written, we clean up, clearing the write mode bit and locking the flash memory.

Thecode I wrote for writing the UART DCO calibration to Segment B using the TLV format is found in uartcalG2231.c. Remember, if you runthis, it requires the watch crystal. If there is anything alreadystored in SegB, itwill be lost.If you'd rather store it in Segment C (0x1040 to 0x107F) or Segment D(0x1000 to 0x103F), change the address in the assignment instructionsaccordingly. If you choose to put in in Segment A (0x10C0 to 0x10FF),look in the Family User's Guide for instructions on unlocking theSegment. I do not recommend this, however, since we're calibrating anon-standard DCO frequency. Wherever you choose to store it, you'llneed to remember the address. If you use my method here, that addressis 0x10BE for the CALBC1 value and 0x10BF for the CALDCO value. Next time we'll write code that pulls these calibrationvalues from memory and configures the DCO and TimerA to start settingup our software UART.

This tool will be very useful to you; keep in mind that though the Value Line devices only have one DCO calibration and don't appear to have any calibrations for the ADC, there is space for them! This process is not too difficult, you can upgrade your devices to have better calibrations, essential for accurate scientific work. For more information on the ADC calibration values that are often included in MSP430 devices, see the TLV chapter of the Family User's Guide.

Tutorial 16d: Flash Memory and TLV

2011-11-02T14:18:00.000-04:00

I've used a number of resources in preparing this tutorial; in addition to the Family User's Guide and the device datasheets, one of the most helpful was an application report titled MSP430 Flash Memory Characteristics.

We'd really like to hold onto our DCO calibration for two reasons. We'd like to be able to use it later, but we'd also like to do so without using up our limited code space with self-calibration. In addition, we may need it in an application where we don't have a crystal connected to the device. (Rather, we could program the calibrations in our LaunchPad with a crystal connected, and then transfer the chip to our intended application while retaining the calibration values in memory.) Programming the flash memory in the MSP430 is not difficult, but there are a few things that have to be done properly to protect your device. The steps done in programming make more sense when we understand how flash memory works.

The Science in Flash

A NOR flash bit is a transistor with a little pocket for storing charge.

The flash memory inside the MSP430 is what we call NOR flash (as opposed to the NAND flash that makes up your typical USB flash drive, for example). It works by trapping charge in an isolated region called a floating gate. The charge in the floating gate changes the transistor's threshold, and determines what value is read from the bit. Acting much like a switch, a positive charge in the floating gate makes it so the read voltage "closes" the switch, and we read a logic 1. A negative charge keeps the switch open, and we read a logic 0.

When we erase flash memory, each bit is put in a state where the floating gate is positively charged. Thus, a "blank" bit will always read 1; a byte of erased flash will read 0xFF. We can program the bit to a 0 by applying a high voltage to the control gate, which allows the floating gate to push charges through the drain. The resulting negative charge in the floating gate is retained, barring physical effects like quantum tunneling that take 100's of years to de-program the bit. (At 25°C, the typical lifetime of a NOR flash bit is on the order of 1,000 years!) Fortunately, the ability to generate this high voltage is built into the Flash Controller peripheral of the MSP430, so we are able to program the flash memory as long as the operating voltage on our microcontroller is at least 2.2 V.

The flash memory in the MSP430 is organized in chunks called segments. The Main Memory portion is divided into segments of 512 bytes. (That means there are 4 segments in the main memory of both the G2211 and G2231, which each have 2 kB available.) Each segment is further subdivided into blocks of 64 bytes. Additionally, an extra 512 bytes is included in each MSP430 device, divided into segments of either 64 or 128 bytes (one or two blocks, respectively). These segments make up the Information Memory portion of the device. The Value Line devices that come with the LaunchPad have four information memory segments of 64 bytes each, called Segment A–D.

The physical structure of the flash cells is important to us, as it has direct bearing on how we deal with it. First of all, when we erase flash memory, we can only erase an entire segment at a time! This means any time we need to change a 0 in a single cell to a 1, every cell in the segment has to be erased. When we program flash memory, the high voltage is applied across an entire block at a time, even if we are only programming one cell. This voltage causes stress to the flash cells, and so we cannot exceed a specified "cumulative programming time", typically 10 ms. Erasing releases the stress, and essentially resets our cumulative timer to 0. These stipulations affect our programming speeds and how often the block needs to be erased.

At the typical speeds we can use (between 257 and 476 kHz), we can program an entire block twice. (Note that in this case, "program" doesn't mean we can write any value-- we can change 1's to 0's twice. To change 0's to 1's, we are forced to erase the entire segment.) We cannot, however, program the same byte multiple times, even if we don't program any other bytes in the block. The rule of thumb, then, is if you reach 10 ms of programming time or write to the same byte twice, the block (and thus the entire segment for main memory) must be erased. This is a real pain, especially if we want to use main memory to store our calibrations. Because of this, I would recommend using the Information segments for storing anything you want to retain outside of the actual program in the device. The process you would use would be to read the entire contents of the block to a buffer (in RAM), erase the Information Segment, change anything necessary in the buffer value, and re-write the buffer to the segment. (It seems like a lot more to do than you're used to when using a flash drive, but in reality the same thing is happening there. Your computer just does a fantastic job of hiding it so you don't have to worry about it.)

Information Memory
A quick word about the various segments: segments B–D are each alike in dignity. However, SegmentA is set aside specifically by TI to store information that should be retained regardless of any programming changes. The factory calibrations, for example, are stored in this segment. As a result, this segment is locked, and you will have to set a particular bit before any instructions erasing or programming within this segment. In addition, to ensure integrity of the data stored in SegA, one word (two bytes) of it is set aside as a checksum, which I'll explain shortly. If you change anything in the segment, a checksum calculation will fail. Some programs rely on this, so if you really must change something in this segment, be prepared to deal with the consequences. Well, at least be prepared to recalculate what the checksum value will be. For our purposes in this tutorial, we'll use SegmentB instead, but we will program it in much the same way that SegmentA is structured. That way, if you choose, you can use SegA to store your calibrations, since that is where they are intended to be.

Memory Save
Button

Let's take a look at how SegA is put together. Fire up the debugger in CCS; it doesn't matter what code you're using, as we won't even be running the program. We just want to enter the debug mode. Once there, the default view has a panel on the right side with tabs for the code disassembly and memory; the memory tab shows the contents of the flash memory of the device. (If this window is not visible for you, you can find it by selecting Window → Show View → Memory.) The information memory is located (as specified in the datasheet) from address 0x1000 to 0x10FF. SegA starts at 0x10C0 and ends at 0x10FF. You can use this window to browse that region, or you can save a particular region of memory to a text file. To do this, click the save button, navigate to a file you want to save the data to, and enter a Start Address of 0x10C0 and a length of 0x20. (Note it specifies to give the length in words; a word is 16 bits in the MSP430, so there are 0x20 (32) words in the 64-byte segment.)

An example of the output from my G2231 device is here. The first line specifies where in the memory the dump comes from. The first line has one word–it comes from the two bytes at addresses 0x10C0 and 0x10C1. Take note that the lower address of the word refers to the least significant byte (LSB, as opposed to lower case lsb for least significant bit), while the higher address refers to the most significant byte (MSB). The last line has the 32nd word–from addresses 0x10FE (LSB) and 0x10FF (MSB). Most of the memory in SegA is obviously blank, as most of the entries are 0xFFFF. (Remember, when flash is erased it reads logic 1.) There are a few programmed words, however, so let's see what each one means. In the x2xx Family User's Guide (current revision as of this writing is slau144h), turn to the chapter on TLV, chapter 24. TLV stands for Tag-Length-Value. This is the format TI uses in SegA to store information. Basically, one word is dedicated to specifying the length of memory allocated to a specific type of data and what type of data is stored there. Table 24-1 gives an example of how this is done. The first word in the segment stores a checksum value. Note that it specifies the checksum as the two's complement of the bitwise XOR. If you start with the next word and XOR it with the third word, that result with the fourth word, and so on, then add it to the checksum value, it will add up to zero. Something like this:

int chksum = 0;
char passed;
int *i;
for (i=(int *)0x10C2; i<(int *)0x1100; i++) {
chksum ^= *i;
}
if (chksum + *(int *)0x10C0 == 0)
passed = 1;
else
passed = 0;

Note: I'm not completely familiar with pointers just yet; I'm working that out in preparation for the next tutorial. If there's an error in this code, I'll correct it then. For now, think of it more as pseudocode.

Now that we understand how the segment memory is organized, let's look at what's inside it. Using my device, I have a checksum value of 0xB22C. The next word is 0x26FE. This means that the next 0x26 entries (38 bytes) are of type 0xFE. Looking in Table 24-2, we see that 0xFE refers to "TAG_EMPTY", meaning the next 38 bytes (or 19 words) are unused. Sure enough, the next 19 lines are all 0xFFFF. The next line gives the next Tag-Length entry: 0x1010. The next 0x10 entries (16 bytes or 8 words) are of type 0x10, which isn't specified in the Family User's Guide. I've submitted a question to TI support to find out about this. In any case, each entry is blank. The next Tag-Length listed is 0x0201, which means there's one word of type "TAG_DCO_30". Here we have the DCO calibration values at room temperature and 3 V. (Note that the Vcc value of the LaunchPad itself is 3.3 V, and remember that different voltage has a significant impact on the DCO!) There's only one entry, which we know has the values for CALBC1_1MHZ (0x86 on mine) and CALDCO_1MHZ (0xC4 on mine) as per the G2231 datasheet.

Reader Exercise: Using either your memory dump or mine, calculate the checksum of SegA and compare it to the value at address 0x10C0. Hint: xor'ing 0xFFFF twice has no effect; an even number of these lines can be ignored. When added to the stored checksum value, do you get zero? Calculate the two's complement by ~chksum + 1 and compare it to the stored value.

Preparing the Custom DCO Calibration
Here's the plan for our code: we'll find a custom calibration value for 7.3278 MHz and store it in SegB using the standard TLV coding set by TI. (You could do this in SegA if you wish, but since we're using a non-standard DCO frequency, I've opted to keep it out for now.) SegB is found in the memory range 0x1080 to 0x10BF. The organization of what we'll be writing will then be like this:

There's a typo here.. should be 0x38FE. I will fix the image soon.

We use the crystal to find the calibration value for 7.3278 MHz. This value is put into the above table to calculate the checksum:
chksum = 0x38FE ^ 0x0201 ^ {calibration values}
= 0x3AFF ^ {calibration values}
The value stored at 0x1080 is then ~chksum + 1.

Next, we erase SegB, and write in the following addresses:

0x1080: two's complement of chksum
0x1082: 0x37FE
0x10BC: 0x0201
0x10BE: 0x{CALBC1}{CALDCO}

This tutorial has ended up pretty long, so we'll end the discussion here. The next tutorial will review the registers in the MSP430 Flash Memory controller and describe how to program this information to the Information Memory.

Reader Exercise: The Value Line devices do not come with the other standard calibrations: 8 MHz, 12 MHz, and 16 MHz. In the chapter on TLV of the Family User's Guide, we see that the locations of these calibrations are standardized for SegA to appear in the order TLV Tag, CAL_16MHz, CAL_12MHz, CAL_8MHz, CAL_1MHz. The data in SegA for the Value Line devices doesn't leave room for these with the other three calibrations left blank, so the entire segment structure needs to be shifted. If we want to add these without loosing any of the remaining structure, how will the segment be set up? Draw up a table similar to that used in this tutorial to map out the segment structure, and show how to calculate the new checksum value based on this table.

Tutorial 16c: Accurate Clocks

2011-10-23T20:44:00.000-04:00

Perfectly synchronized clocks can measure the bits
anywhere in the middle.

Clock Accuracy
So just how accurate does a clock need to be for UART? First, consider a perfect pair of clocks, each operating at exactly the same frequency. In this case, it doesn't much matter where we measure the incoming bits, as long as we measure after the bit has changed to the next one. If there's some error, however, a slow clock will measure later and later, until it missed a bit completely. A fast clock will likewise measure earlier and earlier, until it measures the same bit twice. Not knowing before hand if your clock is fast or slow, it makes sense to shoot for the middle of the bit; that way you have as much time as possible before the error takes over and you make a mistake.

Errors can add up very quickly when there are
small differences between clocks.

Looking at the plot on the left, using clocks that are off by only 6%, notice where the first problem occurs: bit 9 is completely skipped! Using these clocks, we can't even reliably send one frame of data! (By the way, this type of transmission error is classified as a frame error.) My choice of 6% for this plot isn't arbitrary; the error quoted in the datasheets for the MSP430 give the calibrated DCO frequencies (calibrated, mind you; not just the DCO in general) a tolerance over temperature and any other changes of ±3%. If we use calibrated DCO as the clock for both sender and receiver, we could feasibly have as much as a 6% error, making UART transmission completely unreliable!

In reality, not all hope is lost; this is a worst case scenario, and likely the clock in your computer (assuming you want to communicate with it instead of another MSP430) is more accurate than that. A total of 5% tolerance between the clocks would, on average, encounter a frame error on bit 11, and 4% tolerance on bit 13, so as long as we have better tolerance than that and have a short gap between frames to "resynchronize", we should be able to communicate. Note this does mean we are limited in the frame sizes we can use reliably, and our actual data transmission rate will be a little less since we need a recovery between frames. If you want fast communication, you need an accurate clock!

Crystal Oscillators
The best option for accuracy in a clock is to use a crystal. The watch crystal that comes with the LaunchPad is accurate over a wide temperature range to 20 ppm (0.002%)! There are some disadvantages, however: crystals take a while to stabilize, and use more power. In addition, at 32,768 Hz, we can't achieve very high transmission rates. Typically we want at least 16 clock cycles per bit to accurately catch the start bit and start sampling at the center of each bit. Using that rule of thumb, the highest bit rate we could attain with the watch crystal is 2048 baud. Larger MSP430 devices allow for high frequency crystals, but the G2xx series that are compatible with the LaunchPad do not. However, if we're careful, getting transmission rates up to 9600 baud with the watch crystal can be done.

Soldering the crystal to your LaunchPad might seem a daunting task with such a small part, but in reality it's not terribly difficult. A little bit of patience (mostly in the form of a little piece of masking tape) is all you need. Aside from a soldering iron and solder, of course. If you have not already put a crystal on your LaunchPad and would like to, there are a number of good demonstrations of the technique for soldering the crystal to the board available on YouTube. For now, I'll assume you've successfully put it on.

You may have noticed a couple of empty pads near the crystal for capacitors. For a crystal to oscillate at the right frequency, it needs to see a particular capacitance to ground. If the capacitance is off, the frequency may be off, or the crystal may not oscillate at all. The crystal included in the LaunchPad kit wants to see 12.5 pF. The MSP430 crystal inputs also have user-selectable capacitances internal to the device. The user can select from 1, 6, 10, and 12.5 pF as the effective capacitance seen by the crystal. (The device defaults to 6 pF.) The selection is done by the two XCAPx bits in the BCSCTL3 register.

If for some reason you need a capacitance other than one of these, you can solder the proper capacitors to the pads on the outside. Unfortunately, it's not as easy as putting 12.5 pF capacitors on the pads; the capacitors you put on will be in parallel with the capacitance from the traces and the chip itself. The formula for calculating the right load capacitors is: C1 = C2 = 2*C_Load - (Cp + Ci). C_Load would be whatever capacitance the crystal expects to see, Cp any parasitic capacitance from traces etc., and Ci the Capacitance of the MSP430 device. The last two terms can be assumed to be whatever is set in XCAPx. So for a crystal that wants 18 pF, you would want to put 30 pF capacitors on the board (using the default 6 pF).

Most of what's needed to use the watch crystal is set as the default values in the BCS+ module. To use the supplied crystal, you really only need two lines:

BCSCTL3 |= XCAP_3; // 12.5 pF for LaunchPad crystal
__delay_cycles(55000); // let crystal stabilize

The first line sets up the proper capacitance for your crystal, and should be changed if you're using a different capacitance value. The second line lets enough time pass for the crystal to stabilize at the operating frequency. How long do you really need to wait? Typically you need a few hundreds of milliseconds. The above code will wait for 55000 clock cycles; at the default DCO of 1.1 MHz, that's about 50 milliseconds. Depending on your application, you can wait longer if necessary.

Self-Calibrating the DCO
If you're paying attention, you might have spotted another problem with the watch crystal: how do we get a standard clock rate from the crystal? 9600 baud is 3.41 clock cycles. 1200 baud uses more clock cycles, so is more reliable, but it's still 27.31 clock cycles. The closest division we can get is 27 clock cycles, which would correspond to 1213.6 baud, an error of 1.1%. It seems we've lost a lot of the accuracy we gained using the crystal! There are crystals available that divide perfectly into the standard baud rates. A 7.3728 MHz crystal, for example, has exactly 768 clock cycles per bit for 9600 baud. If you use an MSP430 device that allows for a high frequency crystal, this is an excellent choice for serial communication at standard rates. Another option, however, is to use the DCO.

But wait, didn't we just argue that the calibrated values of the DCO are too large to be reliable? Yes, but under certain circumstances we can do better. For one, the error margins quoted in the data sheet cover both the entire temperature range where the MSP430 can be used-- from -40° to 85°F-- and the entire range of voltages at which it can operate-- from 1.8 to 3.6 V. Generally we won't be operating in such extremes. Even if we are, as long as the temperature and operating voltage aren't going to change too much during operation, we can recalibrate the DCO to that particular configuration! The accuracy of the clock will be much better than the quoted 3% in this case; the datasheet even specifies that from 0° to 85°F, the calibration is good to 0.5% at 3 V. (Obviously a consistent voltage is the real key to a stable DCO.)

Calibrating the DCO is quite simple, but it requires a very accurate clock to compare the DCO against; this is a job for a crystal. The idea is simple-- use the crystal to time an accurate interval (say 1 s.) We know how many oscillations should occur for a given frequency in that interval, so we adjust the DCO until we get as close to that as we can get. Then we save the values for DCOCTL and BCSCTL1, and we have an accurate calibration for our clock! Here's how all the magic happens:

void Set_DCO(unsigned int Delta) { // Set DCO to selected
// frequency
unsigned int Compare, Oldcapture = 0;

BCSCTL1 |= DIVA_3; // ACLK = LFXT1CLK/8
TACCTL0 = CM_1 + CCIS_1 + CAP; // CAP, ACLK
TACTL = TASSEL_2 + MC_2 + TACLR; // SMCLK, cont-mode, clear

while (1) {
while (!(CCIFG & TACCTL0)); // Wait until capture
// occured
TACCTL0 &= ~CCIFG; // Capture occured, clear
// flag
Compare = TACCR0; // Get current captured
// SMCLK
Compare = Compare - Oldcapture; // SMCLK difference
Oldcapture = TACCR0; // Save current captured
// SMCLK

if (Delta == Compare)
break; // If equal, leave
// "while(1)"
else if (Delta < Compare) {
DCOCTL--; // DCO is too fast, slow
// it down
if (DCOCTL == 0xFF) // Did DCO roll under?
if (BCSCTL1 & 0x0f)
BCSCTL1--; // Select lower RSEL
}
else {
DCOCTL++; // DCO is too slow, speed
// it up
if (DCOCTL == 0x00) // Did DCO roll over?
if ((BCSCTL1 & 0x0f) != 0x0f)
BCSCTL1++; // Sel higher RSEL
}
}
TACCTL0 = 0; // Stop TACCR0
TACTL = 0; // Stop Timer_A
BCSCTL1 &= ~DIVA_3; // ACLK = LFXT1CLK
}

This code comes from the dco_flashcal.c example code available with most of the MSP430 devices. The example code file for the G2xx1 devices seems to not have it; I copied this from the F21x2 examples and changed TACCTL2 to TACCTL0 to be compatible with LaunchPad devices.

It's a bit of code to sort through, but it turns out to be straightforward. ACLK is configured to use the watch crystal divided by 8-- 4096 Hz. The timer is set to capture mode, triggering off a rising edge of CCI0B. (From the G2231 or G2211 datasheets, this corresponds to ACLK. If these terms seem confusing, review the tutorial on the capacitance meter which used the capture mode.) The timer itself is running off SMCLK, sourced by the DCO. If we want to calibrate 2 MHz, then in one clock cycle of ACLK, we expect 2 MHz/ 4096 Hz = 488.3 SMCLK cycles. We pass the value 488 to this routine, which starts the clocks and timers. When a capture occurs, it checks to see if more or fewer cycles of SMCLK have happened, and adjusts DCO and RSEL accordingly. It repeats this, until it finds the configuration that returns exactly 488 cycles in the interval. The values in DCO and RSEL are then the calibration values we want to save; we just look at the DCOCTL and BCSCTL1 registers and save their values for future use.

This routine is used in the example code found in DCOcalibrate.c. Try it out (with the crystal soldered on, of course), and see what values are obtained for DCOCTL and BCSCTL1 for each frequency it calibrates. If you happen to have an oscilloscope, measure them on P1.4 to see if they're right. (The code finishes on the last calibration done; you can modify the code to end with the one you want to measure, or add code to change to the frequency you want to see.) You can write these values down for future reference, but next time we'll look briefly at writing to the flash memory in the MSP430 so you can save it for use later on!

Reader Exercises: How good is the calibration done in the factory? Modify the code to find the calibration values for 1 MHz. How do they compare to the values stored in CALDCO_1MHZ and CALBC1_1MHZ? It seems many have reported that the 1 MHz calibration from the factory, at least for early batch runs of the value line devices, is closer to 980 kHz.

How much does temperature affect the results? Place your LaunchPad somewhere warm for a while (or cold; a freezer might not be best, though-- too much water around!) and re-run the code. How much difference is there in the calibration values?

Could you use a calibrated frequency to go the other direction and measure the crystal frequency? Imagine doing an experiment to see how the four XCAPx settings might affect the crystal. Which ones oscillate? How much does the frequency change if you use 10 pF instead of 12.5 pF? See if you can write some code to find out!

Tutorial 16b: UART Definition

2011-10-23T17:08:00.000-04:00

Universal
So what exactly makes the Universal Asynchronous Receiver-Transmitter universal? The UART has a long history, starting way back in the 1840's with some of the first telegraph systems. Back then, when the telegraph key was held down, a current would flow in the receiver, pushing a stylus into a strip of paper, leaving a "mark". The Morse code signals sent would then visually display on the paper, making it simple to read the transmitted message. Of course, it didn't take long before the operators got so used to hearing the patterns of clicks that they found they could just as easily listen to the message as write it on a piece of paper, and sounds began being used instead of a mechanical system. Of course, the sounds would turn on when a current was flowing in the receiver, so the signal was still divided into "marks", where current was flowing, and "spaces", where it was not. In other words, the "standard" had changed from a stylus on a paper to listening by ear, but the "protocol" of Morse code stayed the same.

Morse code was a phenomenal technology change, making it possible to send messages easily over very long distances, particularly when radio was implemented, and wires connecting between the source and destination were no longer needed. While that was happening, someone realized a financial benefit could be obtained by using the technology, and hence was born the first ticker tape machine for the stock market. These machines changed the technique slightly. Instead of using special codes for each character, a series of pulses would be sent to turn a printing wheel from its current position to the next letter to be printed. A special pulse signal would instruct the printer to stamp the current letter onto the tape. As technology improved, rather than a rotary printing wheel the Baudot code was developed as a new protocol, equating particular pulse patterns to particular characters.

Like telegraphy, the teletype grew with the new technologies of radio and, in particular, the computer. Teletype machines became useful not only as a means of communication between people, but also as an interface to early computers. Instructions could be sent by typing a particular pattern of keys, sending a particular pattern of pulses to the computer. Results would be sent back with a similar pattern of pulses to a printer, which would translate them back to the letters and numbers we needed to understand them. But even though the technologies had taken different paths, both came from the same beginnings with Samuel Morse. As such, some characteristics and naming conventions stuck; in particular the use of "mark" and "space" to designate when current was flowing (logic high) and when it was not (logic low).

In computers, a change was made from detecting current flow to just measuring a voltage. Some of the conventions continued, which is why in the RS-232 standard has logic high as a negative voltage. The negative voltage originally would open the current of a teletype machine to produce a "mark" signal. A positive voltage would cut off the current, producing a space. As it turns out, different circumstances (and sometimes just different companies) would require a slightly different standard for sending serial data. connectors and voltage levels for mark and space wouldn't be the same, but the protocol (the way of encoding the characters in pulses) used would carry over. In particular, the use of transistors made it easy to create a universal system that could be understood by any computer or device, as long as each device had something to convert the transistor logic (TTL) signals into whatever standard they expected. The protocol was changed as well, using ASCII to encode the data into digital information. Thus was born the Universal Asynchronous Receiver-Transmitter. (Note that TTL uses positive voltage, be it 5 V, 3.3 V, or anything else, for "mark" and 0 V for "space".)

Asynchronous
Now that it's clear what makes the UART universal, let's look at what is meant by asynchronous. In radio, you can send a message (by voice, digital code, morse code, or whatever), but the message cannot be received unless someone is listening. For serial communication, it requires more than just a signal saying data is ready to be transmitted, unfortunately. Imagine a system where I'm going to send a message to you by holding up a giant sign. We agree before hand that at 1:32 PM I will put the sign up, and at the designated time you look in my direction, see the sign, and read the message. This would constitute a parallel type of transmission--each letter was visible all at once. Now let's say I just don't have access to a big enough piece of paper to write the whole message, but I can send you one letter at a time. So we agree that every 10 seconds, I'll hold up a new letter. You come at the specified time and see me hold up the first letter, which you record on a piece of paper. Every 10 seconds you look back, and I'm holding a new letter up and you record it. This is serial communication. But what happens if one of us has a bad clock, and it's saying 10 seconds are up when, say, 12 seconds have passed. Eventually the mismatched timing causes you to either record the same letter twice or miss a letter completely, depending on whose clock is faster. In order to ensure the message gets through, our clocks need to be synchronized.

There are synchronous methods of serial communication, including both SPI and I2C, which we'll address in the future. These methods have synchronized clocks by using the same clock for the sender and the receiver. The disadvantage is that sharing a clock means another wire. It's clear from the history that developed the UART why a clock signal was not included along with the message; instead, both the transmitter and receiver agree before hand at what rate the data will be sent. This allows sender and receiver to have their own clocks, which don't have to be synchronized in terms of when the second hand ticks, but it does require that each person's clock is accurate. Asynchronous communication simplifies the connection by not needing a second signal in parallel with the data, at the cost of needing an accurate way to time intervals between data.

Receiver-Transmitter
Enough history; let's look at how the UART actually transmits information. Whatever protocol we may be using, we are able to encode data as a series of 1's and 0's. We can encode a number as its binary representation, or we can encode a character as a particular binary number. In any case, we have a certain number of 1's and 0's to send. In a UART, we also add on at least two extra bits: one to designate the start of a new set of data, and one to designate the end. These start and stop bits with the data bits in between constitute what we call one "frame" of data. Using ASCII encoding, often 7 bits of data are sent. In addition, a 10th bit would be sent between the data and the stop to help determine if the data received was correct or not. If the sender and receiver agree that every frame will have an even number of 1's in it, then this "parity bit" would be 1 or 0, depending on the number of 1's in the rest of the message. The receiver could then look at the 7 data bits and parity bit, add up the number of 1's, and if the total number is even be confident that they received the right message. In 8 and 16 bit systems like a microcontroller, it could also make sense to send data in 8 bit segments instead. Often times no parity bit is included in this case, to keep the total data length of each frame to 10 bits. The compromise is that there is no way to check for errors in the transmission, but generally error checking is only necessary under particular circumstances.

Let's say we want to encode the letter "D" using 7-bit ASCII encoding and odd parity. The ASCII code for the letter "D" is 0x44, or 0b1000100 in 7-bit binary. Now we face a choice: do we send the least significant bit first, or the most significant bit first? The typical protocol used in UART is what we call "little-endian", meaning we start with the least significant bit. (This makes sense when you think in terms of a shift-register; the SR in a UART pushes bits from high to low, so you send the lowest bit first.)

Representation of the ASCII character "D" in UART TTL.

UART uses logic high as the default (or idle) state. So to start a message, we want to change from high to low. Thus, our start bit will be a 0. Likewise, to stop we want to go back to the default state, so the stop bit is 1. So far, our total encoding is now "00010001x1", where x represents our parity bit. We want odd parity, and there are two 1's in the representation for "D", so we set this bit to 1 to ensure an odd number in the whole message. Our final message is the 10 bit stream "0001000111". (If we do this with 8-bit data and no parity, we would have "0001000101", this time the 2nd to last bit being the most significant bit in the 8-bit code 0b01000100.)

Hopefully this gives you a clear picture on how UART works. There are really no limitations on the protocol you use, so long as you have a start and stop bit. As long as the sender and receiver agree on what goes in the middle and at what rate the information comes, it will work. The standard protocols such as those illustrated here are convenient as it's very simple to use a computer to read the data coming from the microcontroller. In addition, keep in mind that there are standard speeds for transmitting bits (bits per second (bps) or baud), which are leftover from the old teletype days. In any case, many systems are limited to using these rates, so it's often a good idea to standardize to them. If you have your own internal system, use what ever baud rate is convenient, but do remember that a lot of computers and devices may expect one of the more conventional rates, like 300, 1200, 4800, 9600, or 115200 baud.

We've identified one of the key things we'll need for a successful UART: a good clock. Next time we'll look at some options, their limitations, and how to implement them.

Reader Exercises: Using 7 bit encoding with even parity, what would the bit stream look like to send the character "j"? How about the character "k"?
Using 8 bit encoding with no parity, what would the bit stream look like to send the newline character, "\n"? How about the character "&"?

Tutorial 16a: Getting Serial

2011-10-17T17:37:00.000-04:00

In order to do an actual scientific experiment using the MSP430, we need one more tool. To be fair, we could do with what we've covered so far, but it requires constant (or at least regular periodic) monitoring of the equipment, and manual recording of the data displayed on the LCM. No, what we need is a way to automatically record the data when it is taken.

There are two different paths open to us at this point: the MSP430 has on-board flash memory. We could use it to record multiple measurements. The other, more complicated path is to learn how to communicate between the LaunchPad and a computer via USB. There's some elegance in starting with the former, as our focus to this point has been on the LaunchPad itself, but unfortunately we'd need a way to transfer the data from the flash memory to a useable location anyway, which more or less requires connection to a computer. So even though it will delay getting to some of the cooler things we can do with the MSP430, it's time we tackle serial communication. Once we have this piece mastered, we'll start a little science experiment that will take me a few days/weeks to complete. During that time, we'll begin looking at recording to flash, communicating with external peripherals, and how to put all the pieces together for remote data collection. We'll also start looking at alternative power systems, system control, and other great things that will completely open the field of what's possible with a microcontroller. The future looks bright; but first we'll have to tackle this difficult task.

Well, things aren't really so bleak... serial communication isn't that complicated. In fact, most MSP430 devices have peripherals built in already for that very purpose, making it simple to do. However, of the two devices that come with the LaunchPad, only the G2231 has one of these peripherals, and it only has two modes of operation, conspicuously missing the one we really need first: the Universal Asynchronous Reciever/Transmitter, or UART. So, instead, we are going to turn to learning to implement this functionality in software.

Fortunately, there's some real advantage to this; a solid understanding of how serial communication works helps us understand how to process and record scientific data. In fact, when we get to the USI/USCI peripherals, looking at other modes of communication such as SPI and I2C, we'll take the time to understand how these methods send data. (The particular implementation of a serial communication system is called a protocol. There are even more protocols available, including Bluetooth, Wi-Fi, and ZigBee, which are cool things we'll tackle some day!)

You might be asking, "Why are we going to rehash software UART? Lots of people have published articles about it already, and lots of code and examples are available." Well, I'd respond that there are two reasons. The more philosophical reason is that you become a better scientist when you understand how the tools you're using work; Einstein once said you don't really understand anything until you can explain it to your Grandmother. The more practical reason is that none of the articles I've perused give much explanation to why the code is set up the way it is. That's our goal here: by completely dissecting the software UART, we learn how serial communication works, and get a thorough example of using the MSP430 peripherals to our advantage in getting jobs done. We'll also do a very thorough job, starting with just transmission (I guess technically it would be UAT), then moving to just reception (likewise UAR), then designing a full-on UART transceiver. Along the way, we'll talk a bit about crystals as well as learn about calibrating our DCO. We'll even talk about saving DCO calibration to the flash memory, and introduce the concept of a checksum. (So we'll see a little bit about writing to flash memory soon after all!)

If that sounds like a lot to cover, it is. I'll do my best to keep the posts coming regularly and quickly, so that we can move on to more advanced ideas soon. There is motivation for approaching this topic in this way at this time, however. These tutorials have always been designed as notes from my own learning. As a result, sometimes the methods/styles have been a little disjointed, but one of the goals of this blog was to put together a curriculum that could be used to teach science students in a one-semester course on microcontrollers. (After graduation, I'll gather, edit, and format these tutorials into a book that can be downloaded for just such a purpose.) I think the material we've covered to this point fits about a one semester course very well, so think of this tutorial as the final project for the course. It's a bigger concept that will take a while, but will draw on our knowledge from the other peripherals and skills we've learned. The fact that we'll introduce some new ideas along the way will add to the sum total of knowledge taken away from this course. So strap in; we're going to start the final for MSP430 101!

Question for Readers

2011-10-16T23:59:00.002-04:00

We're fast approaching the end of what I would call the 'basic tutorials', and the point where I'll move on to interfacing with the real world and other cool toys and devices. Unfortunately, that means I need some cool toys and devices. In brainstorming ways to help fund this little hobby, a friend suggested to me that I might consider using Google AdSense on this blog. If I were to do so, I would want it to be unobtrusive, as my intent is not to sell things for other people. How would you feel if I were to do this? Would I be better off thinking of another way to raise a little hobby revenue?

Tutorial 15b: Using ADC10

2011-10-16T23:46:00.001-04:00

Like the Comparator_A+ peripheral, ADC10 has a wide range of operating modes and features. It can also integrate with other peripherals (such as Timer_A, of course), making it a very powerful tool in scientific measurements. Today we'll look at basic configuration of ADC10 in preparation to do a full scientific experiment using the MSP430. Keep in mind that this tutorial requires a device with the ADC10 peripheral, such as the G2231. The G2211 chip that comes with the LaunchPad will not work in this tutorial.

First, let's examine some of the features of the ADC10 peripheral. ADC10 of course requires a clock, and can source from any of the three clocks in the MSP430 (and subsequently from a crystal, DCO, or VLO). In addition, ADC10 comes with its own internal clock that can be used independently of the system clocks. This clock is typically in the 5 MHz range, but is uncalibrated and thus varies from chip to chip, as well as with operating voltage and temperature. A major advantage to the internal oscillator is that it can remain in operation even when other clocks are powered down in an LPM.

ADC 10 can connect to up to 16 different inputs. Typically, 8 of these are external inputs, 4 are internal inputs, and 4 are other references (on some devices, they are extra external inputs for a total of 12). The G2231 device has 8 external inputs (on each of the pins in P1), and also has a temperature sensor built into the chip as an internal input (in addition to the other three internal inputs, which have to do with voltage reference comparisons).

Like the Comparator_A+, ADC10 requires a reference voltage for operation. In fact, it can operate with two reference voltages for the upper and lower bounds of conversion. The upper reference can be anywhere between 1.4 V and Vcc (up to 3.6 V). The lower reference can be between 0 and 1.2 V. There are two references available inside ADC10 at 1.5 V and 2.5 V, and it can also use Vcc in addition to an external reference.

Finally, the ADC10 also has 4 operating modes. Two of these modes sample only a single channel. The other two modes cycle through a specified set of the 16 possible inputs. Each single/sequence type can be done only once, or repeated. (Note: in a sequence mode, you must use the inputs in order. If you want to sample 3 inputs, you must use A0, A1, and A2. Unfortunately, the only way to sample arbitrary inputs is to use single channel mode and change channels in software.)

That covers the bulk of the dizzying ways to configure the ADC10; it's a lot to sort through, so keep in mind that we're only going over it to have the different things you can do in the back of your mind. The best way to learn how to use all of the features is by example, so let's look at a simple example by modifying the capacitance meter project to a voltage meter. This meter will be restrictively useful, as it will only be able to measure voltages between 0 and 3.3 V, but it will illustrate the idea. We'll display the output on the LCD as before, but the code can easily be modified to pause in the debugger to find the result as was done at first with Comp_A+ if you don't have an LCD. For the LCD display, we'll use the single-channel mode and repeat the measurement in software, which makes it easier to use the debugger to see the result.

The x2xx User's Guide gives a set of diagrams to explain the process used in each of the four modes. For example, in the repeat single-channel mode, the peripheral is turned on and enabled. The ADC10 is triggered to start a conversion, which is stored upon completion. If interrupts are being used, the flag is set, and the ADC10 returns to on of three steps, depending on just how we set it up. Keep in mind this all happens within the ADC10 module itself, leaving the MSP430 free to perform any other actions it needs to. You can use the ADC10 interrupts to do something with the code after samples are taken.

Our code will instead use single-channel mode, which is very similar to the repeat single-channel mode, but without the repeat part. =) I've chosen this mode because I won't be using a low power mode, and it's easier to coordinate timing so that a sample isn't taken and finished while waiting for the LCD to update. While a new conversion is occurring, the code will trap in a loop before writing the measured sample to the LCD for display. Once that's finished, a new conversion will be started to update the measurement.

There are 8 registers associated with ADC10; of these, 4 are used to configure the peripheral. One is used to store the individual samples, and three are used to control transferring the sample data for storage. (More on this later; for now we're going to keep it simple and only worry about 5 registers!)

While this sounds like a lot of configuration, fortunately two of the registers are used solely for configuring the inputs. ADC10AE0 enables the ADC function of the external pins being used. (This is necessary, because P1SEL changes the operation of those pins to a function other than ADC; since it's a binary value, P1SEL can only configure two different operations. This register frees up those pins for uses other than just ADC!) ADC10AE1 performs a similar function, but only for devices with more than 8 analog inputs.

We'll look at the other two configuration registers in more detail. ADC10CTL0 handles some of the base configurations of the peripheral-- the voltage references, sampling time and rate, and handling power and interrupts for the ADC. ADC10CTL1 controls the inputs, clock, mode, and data formatting. Here are the essential pieces for each register (we won't cover all of them today):
ADC10CTL0

SREFx (Bits 15-13): These select one of 8 different configurations for the upper and lower references for the ADC.
SHTx (Bits 12-11): These select 4 different sampling times for the ADC. The voltage is held constant during conversion by charging a capacitor; these control the amount of time you allow for charging. Obviously more time ensures a more accurate sample, but limits the sampling rate achievable by the device and risks having the voltage being measured change during the sampling time. You can select 4, 8, 16, or 64 clock cycles (of ADC10CLK).
REF2_5V, REFON (Bits 6,5): Selects between 1.5 V and 2.5 V references and turns the reference on/off.
ADC10ON, ENC,ADC10SC (Bits 4,1,0): Turns on the ADC, Enables Conversion, and Starts Conversion respectively.
ADC10IE, ADC10IFG (Bits 3,2): Interrupt enable and flag.

ADC10CTL1

INCHx (Bits 15-12): In single channel mode, selects the channel to sample. In sequence mode, selects the highest channel to sample.
ADC10DF (Bit 9): change between straight binary data and 2's complement data.
SSELx, DIVx (Bits 4-3,7-5): chose the clock source and divide the clock frequency by 1-8.
CONSEQx (Bits 2-1): Select the sequence mode.
BUSY (Bit 0): a read-only flag that indicates when the ADC is in the middle of a sample/conversion cycle.

That's a very brief overview; we can't cover all of the features in detail in a reasonable introductory tutorial, so we'll examine more advanced features in the future as they come up. In the mean time, read the User's Guide and documentation to understand more of what all of these do.

Last of all, we'll mention the ADC10MEM register. When conversion takes place, the value is stored and read from here. If ADC10DF is cleared (value 0), we can read this straight away: 0x00 is equivalent to the lower reference, 0xFF is equivalent to the upper reference, and the intermediate values are a line between the two points. If ADC10DF is set (value 1), the value is stored in 2's complement. This can be useful for transferring data in some configurations, but we'll not need it today.

That does it for a brief (but long!) summary of the basics. Let's look at the simple volt meter now. The code for this project can be seen in VMeterG2231.c. It will require the simple_LCM library from the previous tutorial. There's very little that's new here, and the code should be clear by itself. It uses input A1 on P1.1. You can test the code by using a potentiometer connected between Vcc and ground and connecting the wiper to P1.1. When you turn the potentiometer, you should see the corresponding value change on the LCD.

So much for the basics; next time we'll look at how to store the data for later analysis and start working on an actual experiment.

Reader Exercise: How can you use this same code to measure a larger voltage range? Hint: a simple way to do it uses only two passive components. A trickier task is to be able to measure positive and negative voltages; can you think of a way to do this even though the MSP430 can't use a negative voltage reference? Hint: an op amp might help.

Tutorial 15a: Analog Signal Conversion

2011-09-29T12:31:00.000-04:00

Looking back on the past tutorials, we really only have two more major peripherals to learn. Today, we'll start taking a look at the Analog to Digital Converter (ADC), then learn about serial communication methods in preparation for an actual scientific experiment.

A corrolary to the Analog to Digital Converter is the Digital to Analog Converter. Unfortunately, it's very difficult to fully understand either of these without understanding the other, but we can learn a great deal about each to start. To understand the actual inner-workings of an ADC or DAC system, we can start with the basic ideas and then learn how they are implemented. So first, let's examine what it is that's different between an analog and a digital signal.

An example of an analog signal

An analog signal is what we're most likely to experience in the physical world. An incandescent light bulb can be put on a circuit where by rotating a knob the brightness can be adjusted. The oven in your kitchen can adjust its internal temperature to any value between about 170 and 500 deg F. The music you listen to pulls the membrane of a speaker in and out to create pressure waves that our ears interpret as sound. For the most part, the universe around us is analog: any measurement can take any value within a continuous range. As a visual example, consider the sine wave. No matter how closely you look at this function, it's always smooth--each of the infinite number of values between -1 and 1 is found in the curve.

While there are digital equivalents in the universe, for the most part our common encounters with digital signals reside in the realm of computers and electronics. The key difference is that measurements can only take discrete values; it's like saying the value can be 1, 2, or 3, but not 1.3 or 2.14. Consider the discrete version of the sine wave shown here.

A digital representation of the analog signal

The red lines represent the digital values that approximate the sine curve (shown in cyan for reference). While this example may not look so great, picture what would happen if we can have more than the 9 possible values available in this example---you can probably imagine that more values in the discretization would give us a better approximation. The simplest ADC peripheral in the MSP430 is a 10 bit system, which gives us 2**10 (or 1024) values. The sine approximation looks quite good with this set:

10-bit digital approximation of the analog signal

Obviously more bits gives a better representation, but it does come at a cost, in both complexity and speed. The reasons for that are more apparent when we understand how an ADC comes up with its values, so let's take a look at the ADC itself.

In reality, we've already looked at elementary ADC by using the comparator. When we convert an analog value (in this case a voltage) to a digital value (a number), the result tells us something about the magnitude of the analog signal. For the comparator, a particular voltage threshold is set for the analog value, and the number is either 0 or 1, depending on if the signal is greater than or less than the threshold. This makes a 1-bit ADC; the number is expressed in a single bit.

While very useful for more applications than you might expect from a single bit, the comparator is limited in how much it can say about the analog signal coming in. If the signal changes about the threshold, we see the bit change between 0 and 1. But if the signal is changing above or below the threshold without crossing it, we have no way of seeing that occur.

The simple-minded solution would be to add another comparator with a different threshold. If we set the threshold on the first comparator to 1 V, and the second to 2 V, with both returning 1 when Vin is greater than the threshold, we would have the following possible results:

0,0: both comparators are below threshold, so the voltage must be less than 1 V.
0,1: the first comparator is above threshold, but the second is below, so the voltage must be greater than 1 V, but less than 2 V.
1,1: both comparators are above threshold, so the voltage must be greater than 2 V.

This setup would work, but notice that it's not completely efficient. Particularly, it is impossible to get a result of 1,0, because the voltage cannot be greater than 2 V but less than 1 V. So adding comparators can give you a broader view of the analog signal, but it's not the best way to do it.

The MSP430 ADC10 peripheral uses a Successive-Approximation-Register ADC, or SAR ADC. This fancy name is simply a description of how the ADC makes its measurement. Have you ever played the number guessing game? Say I ask you to guess the number I'm thinking of between 1 and 100, and I'll tell you if you're low or high. What's the most efficient way of getting there? If you guess 90, and I say you're low, then you've narrowed it down to 10 possible values in just one guess! On the other hand, if I say you're high, then you've only eliminated 10 possible values. When you consider that compromise, it's clear the best starting guess would be 50-- you're guaranteed to eliminate half of the possibilities. What next? Well, it would make sense to cut the remaining possibilities in half-- if 50 was low, guess 75; if high, guess 25. If you continue on with this algorithm, it won't take you too long to come up with the number I'm thinking of. (It will take you at most 7 guesses.)

SAR works in the same way; note that in any binary representation, a 1 followed by zeros is half the total possible range in the same number of bits. (Eg. 0b1000 is 8, while the upper limit 0b1111 is 15.) If we take a single comparator and use half of our reference voltage, we get our first bit-- if it's above 1/2 Vref, set it to 1; if below, set it to 0. Then we set the comparator reference to either 1/4 or 3/4 Vref (depending on the value we just got), and compare again to get the next bit. Using this method, you can come up with the digital value in as many measurements as you have bits-- in the case of ADC10, it takes 10 measurements.

Note that instead of adding another fixed comparator, we use only one as opposed to the 1,024 we would have needed to get the same resolution. The compromise is that now we have to change the comparison voltage and make multiple measurements. These two factors lead to a limit on how quickly we can make a measurement; to get very fast measurements, we need fast settling times on both the reference divider and the recording to the data register (which depends on the number and frequency of clock cycles in the CPU, of course). The ADC10 is rated to measurements up to about 200,000 samples per second (or 200 ksps, in the nomenclature used for the datasheets).

The actual mechanism used to make the measurement is pretty simple; you use a DAC of some sort to set the reference according to the bits we've already set. The details are fascinating, but beyond the scope of this particular tutorial. Feel free to read in the Family User's Guide or in a copy of MSP430 Microntroller Basics to get more information. Search online as well. That concludes our introduction to ADC. This is only a basic introduction, of course, and the ADC10 has a wealth of powerful operating modes. Next time we'll look at how to configure the ADC10 peripheral.

Tutorial 14b: Adding a New Library

2011-09-13T23:54:00.003-04:00

Before I start this tutorial, let me add a caveat: I have a feeling this is not the best way to build a library in CCS. It is, however, the only way I could get it to work reliably short of copying the code into every project I use it in. If anyone has some experience with this in CCS, please send a comment and let me know!

We have code that will let us easily send text to the LCM, which would be very useful to have in a library that can be called up as needed, without having to rewrite (or copy-paste) the code every time. The C language makes doing this fairly easy, and so we'll look now at moving the LCM code into a library and go through how to configure a project in CCS to use the library. You should be able to add any code you'd like to reuse to this library and be able to call it up whenever needed.

First: choose a location to keep your library. It's not important where this library resides (from the compiler's point of view), but it's best to have it somewhere easy to get to when you add/change code in your library. At the same time, it should be somewhere safe, where it won't be accidentally deleted, moved, or changed in any unintentional way. I chose to create a folder in my workspace directory called 'library'.

Second: copy any #include, #define, function prototypes and global variables into a new header file. For this library, I've called it simple_LCM.h. If you're going to use definitions specific to the MSP430, you will need to include the MSP430 header as well. To keep your library general, rather than including the header file for a specific device, just #include <msp430.h>.

Third: copy the remaining code (the encapsulated functions) into a new .c file with the same name (ie. simple_LCM.c in this case). At the top of the file, you should add #include <filename.h> (replacing filename with the name of your library file). Note that this file should not have a main function in it.

Fourth: in your new project, right click the project folder and select new → folder. Click the [Advanced >>] button, and select "Link to folder in the filesystem". You can then browse to your library folder and finish adding the folder.

Any files in your library directory are now available for use in your code; the compiler, however, needs to be aware of the path to this folder to find it. (This is the part I don't like; this has to be done for every project, and I'm unable to find a way to make this path be a default in CCS for every new project.)

Fifth: right click your project folder and select properties. Open the C/C++ Build window, and in the Tool Settings, look for MSP430 Compiler → Include Options as well as MSP430 Linker → File Search Path. Both of these need to have your library folder added to the list in order to compile your code.

One shortcut I've found: In CCS, go to the menu Window → Preferences, then navigate to General → Workspace → Linked Resources. Here you can define a path variable (eg. My_Library) that links to your library directory. When you add a new folder to a project, instead of browsing to the folder location, you can click [Variables...] and select it from the list; it's much quicker that way. Unfortunately, I can't seem to get the project properties changes to recognize the path variable, though it seems it's supposed to.

Now we should be ready to build our capacitance meter using the LCM. The code I've written in CMeterLCMG2211.c demonstrates a number of new ideas using the LCM. Browse the code and examine the comments to see how it works. Note the use of MoveCursor(row,col); and the particular commands sent to configure the LCM.

While the simple_LCM library has a routine for printing strings, what happens when we want to print an integer value like the recorded value in the time variable? One intuitive option (at least if you're accustomed to programming in C) would be to use the stdio library and the function sprintf();. All we would need to do is set up a character array such as print_time[10], and use sprintf(print_time, "%d", time); to put the integer into the print_time string and pass it to PrintStr(). Unfortunately, this method has some serious problems for microcontroller use. First of all, even with the heavy streamlining done in CCS to reduce its size, any code using a printf function will be large. In this program, it would exceed the 2 kB of size available in this device. Second, the streamlining makes it difficult to format correctly; ideally, we'd use a %10d format specifier to put time into exactly 10 places to fit the print_time size. We can't do this with the streamlining implemented. We can change the printf assumptions in the project properties, but that makes the function use even more of our severely limited code space.

Fortunately, there are some ways around this problem. For an integer, we can pick off the individual digits by using the mod operator and integer division. x%10; will return the last digit of the number stored in x. x/=10; will remove the last digit and leave up to the second to last. By running a loop over the number until we reach a condition of x == 0 (no more digits), we can pick off each digit to print one by one. The ASCII codes (and the codes for the LCM) are arranged in a way such that the lower nibble corresponds exactly to the digit's value, so 0x30 + 0 is "0", 0x30 + 7 is "7", and so on.

The disadvantage to this loop technique is that the digits are picked off in reverse order--from right to left. The LCM has a mode that allows you to decrement the cursor position when you send characters, however, so it's possible to print from right to left in this way. (In fact, this ability is used in many hand-held calculators.) See the code for the exact code needed to configure the LCM for this mode.

And there's our first complete scientific instrument using the MSP430. We use a combination of the timer and comparator with a calibrated clock to measure the decay time in an RC circuit. The LCM displays the measured time in microseconds. Knowing the value of R and the reported time, we can calculate the actual value of C measured by the meter.

Reader Exercise: This works fine, but wouldn't it be nice to have the LCM display the capacitance rather than the time? You can do floating point operations in the MSP430 (albeit inefficiently), but how would you display a floating point number on the LCM? If sprintf was to big for the program above, it will definitely be too large in this case. Can you come up with a way to display the capacitance without exceeding the 2 kB limit for the G2211 device? If you get stuck, one way is demonstrated in CMeterLCMFull.c. It also has the benefit of being auto-ranging. This code takes up 1934 bytes of space-- just barely enough to squeeze into the G2211!

Tutorial 14a: The Alphanumeric LCD

2011-09-10T15:51:00.000-04:00

We're almost at a point where we have built a complete scientific instrument. The one thing the capacitance meter lacks is a way to provide the measurement outside of the debugging environment-- not very convenient for working in the field. There are a number of ways we can transfer the data somewhere usable. One way that is useful for single measurements is by displaying the result on an LCD display, much as consumer meters do. We're now going to look at using a standard alphanumeric LCD module with the LaunchPad. This project will also introduce the concept of building a custom library; by the end of this tutorial, you will have a library that you can import into future projects to add an LCD display without having to re-code the entire thing.

The LCD Module (LCM)

One disadvantage to this tutorial is that it require having an LCD display, which you might not have. If not, and are willing to purchase one, I would recommend doing so. These displays can be very useful, and are not very expensive. They come in a variety of sizes and styles-- for this tutorial we will use a standard 16x2 character alphanumeric display modules, such as those found at SparkFun.com. SparkFun carries a variety of these modules; feel free to pick one to your liking, but be certain of a few things: it needs to be configured to run on 3.3 V and should not have been modified to accept serial input. If you'd like a larger module (such as a 20x4 display), it's up to you, as they all work the same way. Get whatever color you'd like.

The SparkFun LCM's utilize an ST7066 chip as the interface to the display, which is based on the ubiquitous HD44780 interface. (If the names make this sound technical, don't worry too much about them-- the important thing here is that we have an interface that translates data from the MSP430 into the commands and characters needed to control the LCM.) This interface uses an 8-bit parallel transmission for sending data to/from the display. As you can imagine, with 8 bits for data, plus another 3 bits for control, you can very quickly run out of GIO pins on your MSP430. In fact, even if we use the G2211 device without a crystal so that P2.5 and P2.6 are available, we only have 10 GIO pins available in total, so we're short 3 pins to control the LCM (needing 11 pins) and the comparator interface (needing 2 pins) for our meter. Fortunately, the HD44780 interface (and thus the ST7066) provides a means of sending data in two 4-bit chunks, and as long as we have no need for reading data from the LCM, we can get by with 6 pins for LCM control, allowing us to just fit the comparator and the LCM into the 8 GIO pins for P1 on our G2211. We're stretching the limits of this chip at this point, which is excellent motivation for expanding to other MSP430 devices in the future!

Connecting to the LCM

The standard LCM module has 16 pin connections (14 without a backlight). The first few connections are for power (possibly in two places, if the LCD is also backlit) and contrast adjustment. Pin 1 (labeled as Vss) should be connected to your LaunchPad ground. Pin 2 (Vdd) is connected to the LaunchPad Vcc. If you are using the backlight, pin 15 (LED+) is also connected to Vcc and pin 16 (LED-) to ground. (This is most easily done on a breadboard. If you find yourself losing track of this description, a good guide to follow is one written by LadyAda.) Pin 3 (Vo) controls the contrast of the screen. If you have a 10k potentiometer available, tie it to the wiper and tie the two ends to Vcc and ground for an adjustable contrast. If not, you can just ground this pin; it probably won't look as good as it could, but it will work.

That leaves 11 pins for the control and data lines. The three control lines are pins 4 (RS), 5 (R/W), and 6 (E). The read/write (R/W) pin is not necessary here, and by tying it to ground we keep the LCM always in write mode. We won't be able to read anything from the LCM (such as the address of the cursor, the busy state flag, etc.), but it saves us a pin on the MSP430. The Register Select (RS) and Enable (E) pins are what we'll use to control the LCM. Finally, pins 7-14 are the data lines D0-D7 respectively. You can consider these pins much like the P1 pins on the MSP430-- D0 is the first bit, D1 the second, and so on. If we used an entire GIO port on an MSP430 to control the data lines, we could connect Px.n to Dn, and by writing a value to Px, we can write the same value to D (conveniently saving us from any strange coding to accommodate changing the order). Since the G2211 doesn't provide enough ports to do this, we'll use the 4-bit mode instead. This mode uses only D4-D7. Leave D0-D3 unconnected for now. (Doing so prevents accidentally writing commands we don't intend.)

For the capacitance meter, we're going to change some of the pin arrangements to accommodate the LCM. We'll use P1.1 as TA0.0 rather than CA1, and use P1.2/CA2 as the input to V+ on the comparator. P1.0 will control RS, P1.3 will control E, and P1.4-7 will control D4-7.

Note: P1.3 is also connected to the button-- this shouldn't affect the code, but since there is a pull-up resistor on P1.3, there will be excess current whenever we drive E low. Unfortunately, the LaunchPad is not designed with a jumper like on P1.0 and P1.6 for the LEDs, so we'll just have to live with this. While we're on the topic, be sure to remove the jumpers for the two LEDs and on the TXD/RXD pins.

Sending Commands to the LCM

Once we're wired up, sending commands or characters to the LCM is a straightforward task. In fact, it can even be done by hand, without a microcontroller at all! (If you're interested in this, or would like to know more about what's going on, see the Reader Exercise below.) The basic idea is that we write an instruction to the data pins and pulse E. The instruction is sent on the falling edge of E, which is why it's pulsed. The instruction issues a command if RS is low, and sends a character if RS is high.

As an example, let's look at the commands we need to set the LCM in 4-bit mode. The 8-bit binary instruction 0b001nnnxx is the "Function Set" instruction. (Here, the n's represent values we choose for the configuration, and the x's imply an unused bit-- these can have either 0's or 1's and not affect the instruction.) Bit 4 in this instruction sets the interface mode: a 1 sets the LCM to accept 8-bit instructions, and a 0 sets it to accept 4-bit instructions. So by sending the instruction 0b00100000 (or 0x20), we configure the LCM to accept commands and characters in two 4-bit chunks instead of one 8-bit chunk. This command must be issued first in order to do anything with our 6-wire setup. We first set the data lines with P1OUT |= 0x20; (which also sets RS low (command mode) and E low in this wiring scheme) and then send the command by pulsing E.

The LCM does not respond instantly to the command, and there are some strict timing requirements in order for it to work correctly. Specifically, RS must be set low a certain amount of time before beginning the pulse on E. The data lines must be set a certain amount of time before the falling edge on the pulse, and must be held at that value a certain amount of time after the pulse. Then a certain amount of time must elapse before we can pulse E again. Fortunately for us, the only timing value of major concern is the time between command pulses. The other times are on the order of a few hundred nanoseconds, and at the processing speeds of the MSP430 there is enough latency to accommodate them. The amount of time needed to complete a command before accepting another can be on the order of 150 milliseconds, however, and so delays must be incorporated to handle them.

So, to recap, here's the set of instructions needed to set the LCM in 4-bit instruction mode:

__delay_cycles(10000); // wait for the LCM to settle on power-up
P1OUT |= 0x20; // set to 4-bit instructions
P1OUT |= BIT3; // E high
__delay_cycles(200);
P1OUT &= ~BIT3; // E low
__delay_cycles(200);
P1OUT &= 0x0F; // clear the upper 4 bits

Though E can be set high before setting the data lines, it's convenient to switch the order to prevent any timing mismatches. Note that if you use different pin connections, or especially if you use multiple GIO ports, this code won't work exactly as is; it's convenient to use P1.4-7 for D4-7 to be able to assign directly to P1OUT, but this is not general. If we were to swap the order, for example, to P1.4-7 as D7-4, then we would be writing 0b0100 instead of 0b0010 on the data line with this code. So be careful; either use the pin connections I've suggested here, or assign the data line bits individually as needed. The final line clears the data line bits to make it easier to set the next command properly.

Other Initializations: Sending Commands in 4-bit Mode

Now we have our LCM ready to accept 4-bit commands. This mode works by sending the upper 4-bits (or nibble) with a pulse on E, and then sending the lower nibble with a second pulse. With our wiring scheme, we can do this easily by the following code:

P1OUT |= ( & 0xF0); // send upper nibble
pulse();
P1OUT &= 0x0F; // clear
P1OUT |= (( & 0x0F;) << 4); // send lower nibble
pulse();
P1OUT &= 0x0F; // clear

I'm assuming here that I've lumped the commands to pulse E with the incorporated delays into a function void pulse(void). refers, of course, to whatever 8-bit command or character we're sending to the LCM. If we encapsulate this set of commands into a function void SendByte(char), then we can issue the next initialization commands as follows:

SendByte(0x28); // Function Set 4-bit, 2-line mode (for 2-line displays, of course)
SendByte(0x0E); // Display on, underline cursor on, non-blinking
SendByte(0x06); // Character entry mode: increment address, no display shift

After sending these commands, our LCM is ready to display whatever characters/text we want to send it. Note that to send characters, the commands are similar to above, but P1OUT must also set BIT0 (RS) to tell the LCM to receive character instructions rather than commands. In lcddemoG2211.c, I demonstrate this with a more generalized version of SendByte that lets you send commands and characters. It also demonstrates other commands, such as clearing the display and moving the cursor. If you have an LCM, try out the code yourself. I wouldn't use a DCO faster than about 2 MHz with the selected delays, so if you play around with the code keep that in mind. In the next tutorial, we'll look at how to encapsulate all of this into a custom library that we can keep on hand and how to import it into our capacitance meter project.

Reader Exercise: Not really an exercise-- more suggested reading. If you'd like to know more about how the modules work and the specific commands and characters that can be sent, I suggest reading the following two articles from Everyday Practical Electronics:
How To Use Intelligent LCDs: Part One
How To Use Intelligent LCDs: Part Two
These articles are very easy to understand, and do a great job of explaining how to use the LCM.

Return of the Blog

2011-09-09T18:14:00.002-04:00

To all those who have been so patiently waiting: thank you for coming back. As you can see, another tutorial has been posted, and more are on their way. I've not yet finished my dissertation, but I'm making substantial progress, and in a few months I'll finally be a free man!

In the mean time, as I'm coming back to this blog, I've decided it's in desperate need of an interface overhaul. So I'm posing a question to my readers: what would you like to see in the interface? How would you like to have the tutorials presented so as to make them more accessible?

I will likely go back through the past tutorials and clean things up, clarify specifics, and generally improve the quality of information in them as well as bring back some consistency in style and presentation. What else can I do to help this community effectively?

Tutorial 13b: Interfacing the Comparator A+ and Timer A Modules

2011-09-09T18:11:00.001-04:00

The idea behind the capacitance meter is simple, but (as may be evidenced in part by the time it took me to get to this) there are some particulars that need to be resolved.

First: how do we minimize any delay in the timing due to delays from carrying out instructions? If we're not careful, a non-negligible amount of time can pass between when we start the capacitor discharge and the timer, or between the comparator trigger and the timer capture.

Second: how do we determine what capacitances can be measured for a given configuration? Smaller capacitors will discharge more quickly, leading to shorter measurement times (meaning more error due to the digital nature of the timer). Larger capacitors take more time to charge up, and may not be fully charged when we start discharging.

The first issue is easily resolved by using features built into the Timer_A module. The second is less easily resolved, but easily understood, so we will know in advance the limitations of our code. There are a couple of things we'll be able to do to improve it generally, but for our purposes here we won't be too concerned about it.

New Feature of the Timer_A Module: Output

Let's introduce here two features in Timer_A we haven't used yet. First off, let's look at how we can use the timer to change an output. Recall that the Timer_A module has a certain number of "capture/compare" registers built into each MSP430 device. (The G2211 and G2231 have two.) Each of these registers can drive their own output; we can program the MSP430 to adjust the output every time the timer reaches the value stored in the register. For example, we can set the output TA0.1 to set the output (to 1, that is) every time the timer reaches the value set in TACCR1. Or we can toggle the output TA0.0 every time the timer reaches the value set in TACCR0. We also have modes that allow us to use both registers on the same output, giving one result at TACCR1 and another at TACCR0. (This ability is used for pulse width modulation, or PWM. We'll talk about that in an upcoming tutorial!)

Take a look at table 12-2 in you x2xx Family User's Guide:

This table lists all of the possible modes we can use to work with the timer outputs.

New Feature of the Timer_A Module: Capture

So far we have only discussed uses of the timer in compare mode. The other mode, capturing, can be used to do precise timing of events. In capture mode, the timer records the value in TAR into TACCRx at the moment when the capture is triggered. This trigger can come externally, or it can come from internal connections to other modules, including the comparator. By configuring the timer in this way, we can record the timer value when the comparator output provides either a rising edge (going from 0 to 1) or a falling edge (from 1 to 0).

Putting It All Together

Here's the general concept used in the capacitance meter. Note that accurate timing requires a calibrated clock, so we'll use the calibrated 1 MHz DCO for this project. First, we connect the resistor to a timer output. (For this purpose, we'll use the TA0.0 output.) The junction between the resistor and capacitor is tied to a comparator input, and the other end of the capacitor is connected to ground. We start charging the capacitor by setting TA0.0, and wait some specified amount of time for the capacitor to charge. The output is then reset (grounded) at the time specified in TACCR0. While the capacitor's voltage is above the reference voltage, the output is set at 1 (assuming we tied the RC circuit to V+ and the reference to V-). When it drops below that value, the comparator output falls, triggering a capture in the timer, recorded in TACCR1. The difference in time between TACCR1 and TACCR0 is an accurate measurement of the decay time of the RC circuit from Vcc to Vref. (Note that if TACCR0 is 0, no subtraction is needed.)

Obviously the longer the time it takes to fall, the more accurate our timing measurement will be overall. But what happens if the time is longer than 2^16 microseconds? TAR rolls over, and starts counting over again; so in our code, we'll need to account for any rollovers that may occur.

Let's examine the comparator configuration used in the code:

void CAinit(void) {
CACTL1 = CARSEL + CAREF_1; // 0.25 Vcc ref on - pin.
CACTL2 = P2CA4 + CAF; // Input CA1 on + pin, filter output.
CAPD = AIN1; // disable digital I/O on P1.7 (technically
// this step is redundant)
} // CAinit

This sets up the comparator to use CA1 on the V+ input. If you check the MSP430G2211 datasheet, CA1 is connected to P1.1. Looking up the register description in the Family User's Guide, we configure for CA1 on V+ by setting P2CA4. (P2CA0 also controls V+, and for CA1 should be clear.)

Now let's look at the timer configuration:

void TAinit(void) {

TACTL = TASSEL_2 + ID_0 + MC_0; // Use SMCLK (1 MHz Calibrated), no division,

// stopped mode

TACCTL0 = OUTMOD_1 + CCIE; // TA0 sets VCTL at TACCR0

TACCTL1 = CCIS_1 + SCS + CAP + CCIE; // Use CAOUT for input, synchronize, set to

// capture mode, enable interrupt for TA1.

// NOTE: Capturing mode not started.

} // TAinit

The timer is set up without starting. Setting TACCTL0 to OUTMOD_1 sets the output TA0.0 when TAR reaches TACCR0, which is 0 by default. Enabling the interrupt lets us keep track of overflows. In TACCTL1, we change to capture mode by setting CAP. To know how to connect the comparator, we need to check the device datasheet. Find the table called "TIMER_A2 SIGNAL CONNECTIONS" and make sure you're looking at the one specific to devices with COMP_A+. In the Device Input Signal column, find CAOUT (internal), and note the Module Input Name in the column next to it: CCI1B. The CCISx bits in TACCTLx select the input, and in the Family User's Guide, we see that these two bits should be set to 0b01 to select CCIxB. In the device's header file, we find that we can set these bits with CCIS_1.

Also note that by setting SCS, we synchronize the capture to the timer clock. We haven't started capturing yet, just as we haven't started the timer. The code is set up to wait for the user to push the button connected to P1.3. Doing so exits LPM0, and continues the main code. The following then happens:

First, the timer is turned on. When the timer rolls over the first time, TA0.0 (on P1.5 in this code) is set, charging the capacitor. We want to wait long enough for the capacitor to charge. The code is set to wait for 10 overflows, which corresponds to about 655 ms. At this point, the comparator is turned on, and the timer is configured to reset TA0.0 at the next overflow (so we've actually charged for 11 overflows at this point). We let the timer capture the next event, or when the voltage at the capacitor (on P1.1/CA1) drops to the value at Vref, or 1/4 Vcc. At this point, an interrupt is triggered. The interrupt routine turns off the captures and the timer and returns to the main code. The code loops back, and starts the process again, waiting for the user to press the button to start a measurement.

Note: Before running the code as set up, keep in mind we're using P1.1; what else is this pin used for? You'll want to remove the TXD jumper to get the project to work properly. Thanks to RobG over at www.43oh.com for pointing this out to me... I was really puzzled by it for an embarrassingly long time!

Try running the code found in CMeterG2211.c. To do this, you'll need a resistor and a capacitor. Use a 10 kO resistor and a 100 nF capacitor (it will have a label that says 104 on it) if you can. In the debugger, set the code to run freely, and push the button. The led should switch from green to red, then back to green, indicating the measurement is done. The timer has captured the event and recorded the time in TACCR1. Unfortunately, there's no way to see this as is yet! Pause the debugger, and examine the timer_a2 registers. The time is recorded in TACCR1. For the suggests RC combination, you should have a value somewhere around 1400. (You can change from the default hex format to decimal by right-clicking the register and selecting decimal in the format menu.)

Try increasing R to 100 kO. You should see the time increase by a factor of 10. Try using a 1 uF capacitor. (You might need to increase the number of overflows to wait while charging to get something accurate here.) In the watch window, we can view the value in the overflows variable. To do this, click where the window says , and type in the variable name. With such a large capacitor, you should see the number of times the timer wrapped around before stopping. With the measured time and the known resistor value, you should be able to use the formula provided in the previous tutorial to calculate the value of the capacitor. Feel free to experiment with this program. In particular, how consistent are your timing measurements?

Aside from the lack of ability to see the timer value without using the debugger, there are a few issues to work out still in this meter. We'll take a careful look at some of these in the future, and bring back this code to demonstrate ways we can see data and ways we can improve the timer.

Reader Exercise: Given the discussion in the previous tutorial about the accuracy of the meter, and from your own experimentation with the program, where are the major sources of error in the measurement? How consistent is the timing? What might cause the inconsistency? What assumptions have we made in the way we measure the capacitance? Once you've built an instrument to make any kind of scientific measurement, it's important to identify all of these aspects. By doing so, we identify the limitations of the instrument, both those we can fix and those we have to live with.

Tutorial 13a: Combining Peripherals

2011-02-18T12:13:00.001-05:00

The MSP430 peripherals are very useful tools in their own right, but when we're able to use two or more peripherals together, they become much more powerful for instrumentation. This tutorial will go through one way that we can combine the Comparator_A+ and Timer_A peripherals. In the next post, we'll use this combination to build a capacitance meter.

Background
Capacitors are one of the three fundamental, passive components that are used in nearly every electronic device out there. When a voltage is applied to a capacitor, it will store a charge proportional to the applied voltage. This proportion is called the capacitance. These factors are all connected by the simple relationship Q = C V. (Q is the charge, C the capacitance, and V the voltage.) When the applied voltage is removed, the charge doesn't disappear immediately, but rather decays gradually by running a current through whatever resistance is present between the capacitor's two leads.

The Discharging Capacitor Equation
V_0 is the starting voltage. In SI units, V is in volts, t in seconds,
R in ohms (Ω), and C in Farads. Equivalently, you can use t in μs and C in μF,
or t in ms, R in kΩ, and C in μF. These are more useful in formulating
the calculation portion of the instrument.

The way in which a capacitor's charge dissipates is simple to describe, but might not be what you expect if you haven't seen it before. Right when we disconnect the charging voltage V, the voltage across the capacitor is still V because no charge has moved yet. In that first moment, a little chunk of charge will flow as a current through the resistance, according to the well-known Ohm's Law: V = I R. (Again, V is the voltage, I is the current, and R is the resistance.) After that first moment, how much charge will move in the next moment? A simple picture would be to guess that the same amount will move, however that's not what happens. Since a little charge has already left the capacitor (Q is now smaller), the voltage across it now must be a little smaller too! Since we have a slightly lower voltage, the next moment will have a little less current. The following moment a little less still, and the next a little less, and so on. This picture describes not a linear drop in the voltage, but rather an exponential change. If you watch the voltage on the capacitor carefully (with an oscilloscope or some other device) you'll see that this is exactly what happens.

While it's not a linear change, it's still a simple description, and we can exploit this characteristic to find the value of the capacitance, C. Assuming we know the resistance, all we need is to apply a voltage and time how long it takes for the voltage to decay to another known value.

Formulating the Capacitance Meter
The idea behind the instrument we are going to build is simple: we charge up a capacitor, then start the timer at the moment we start discharging. We stop the timer when the capacitor has discharged to a known point, then plug in the values into the formula.

Formula needed to calculate C from the MSP430
C is in μF if t is in μs and R in Ω. Alternatively, C is in nF if t is in μs and R is in kΩ

The formula is easy to find. When we invert the Discharging Capacitor Equation, we find that our measured value of C depends on the time for discharge, the resistance, and the fraction of the starting voltage to the ending voltage. We can use Comparator_A+ to trigger the timer when we reach our chosen reference. For this tutorial, we'll discharge the capacitor until it reaches 1/4 Vcc, so that we use f = 4. This value is convenient, and minimizes any external components.

In the next tutorial, I'll show you how to set up the peripherals and suggest a few ways that you can read the obtained result with the MSP430. You may wonder how accurate this setup will be. The short answer is that it will be as accurate as you know the value of the resistor; if you use a 5% resistor, you'll be able to measure C to 5%. A 1% resistor tolerance will give you close to 1% for C, but at that point some of the other factors become more important. If you are interested, take a look at this description I've written on finding the error in the measurement.

New Devices!

2010-12-29T21:36:00.000-05:00

If you haven't already seen from some of the other websites in the LaunchPad community, TI is gearing up to release more MSP430 devices that are compatible with the LaunchPad. Some of these will be 20-pin chips, and will make use of the entire board. You can see details of the new devices on TI's website.

In regards to the new devices, some will include more of the MSP430 peripherals, most notably a hardware UART for serial communication. The UART uses the same two pins that TI chose to use on the LaunchPad for the timer-based UART used in the demo program that comes with the G2231 chip. Unfortunately, it swaps the transmit and receive functions on these pins. TI is working on potentially re-designing the LaunchPad, and has asked for the community's views on how to approach this issue. If you haven't already, go to the post on the E2E Community site, review the proposals they've given, and vote for the solution you think is best!

Tutorial 12: Making Comparisons

2010-12-27T15:39:00.019-05:00

As we've seen, microcontrollers have great usefulness in digital electronics. In the real world, and for scientific applications, however, digital is not always adequate. In this tutorial, we begin working with analog signals using a 1 bit analog to digital converter: the comparator.

Some MSP430 devices have a built-in comparator (called the Comparator_A+ module in the technical documentation, I'll refer to it as CA+ here), including the MSP430G2211 that comes with the LaunchPad kit. (See TI's website for other LaunchPad-compatible devices that include the CA+ module.) Up to this point, all of the tutorials could be used on both the G2211 and the G2231 chips in the LaunchPad kit by changing the #include header appropriately. For this tutorial, you will need to use the G2211.

Overview of the Comparator_A+ Module

Simplified diagram of the Comparator_A+ module. Taken from the book
MSP430 Microcontroller Basics; I highly recommend getting a copy of this book!

The CA+ module is very flexible, allowing multiple GIO pins to be connected to its inputs and including a variety of useful internal voltage references. As you may recall, a comparator has two inputs, called inverting and non-inverting (often labeled V+ and V- respectively). The V+ input can be connected to three different pins for external signals, or any of three different internal reference signals. The V- input can be connected to seven different pins (two overlap with the V+ inputs) and any of the internal references. CA+ has an output that can be read in software, trigger the CA+ interrupt, and trigger a timer interrupt. All of these options give the CA+ module its flexibility and usefulness to us in developing instrumentation.

Take a look at the datasheet for the G2211, and find the page that shows the pinout diagram for the chip. The pins that can be connected to the CA+ inputs are labeled as CAx. Note that CA0-2 can be connected to V+, while CA1-7 can be connected to V-. Note also that in addition to providing the CA7 input, P1.7 can be configured to provide the output value CAOUT externally.

Configuring the Comparator_A+ module

The CA+ module has three different registers for its configuration: CACTL1, CACTL2, and CAPD. These registers are described on pages 19-10 to 19-13 of the x2xx Family Guide. We'll look at the basic pieces here.

CACTL1

The CAREFx and CARSEL bits (4-5 and 6) control the internal references for the comparator. Bits 4 and 5 select the reference value, while bit 6 selects which input is connected to the reference. There are three references provided in the module. Two of them are a fractional value of the voltage powering the MSP430: 1/2 Vcc and 1/4 Vcc. If you are powered from the USB (3.6 V), these references are 1.8 V and 0.9 V respectively. (These are accurate to about 1%.) A third reference is provided by the forward voltage of a transistor. This voltage is typically 0.55 V, but is less accurate and susceptible to temperature changes.
The CAIFG, CAIE, and CAIES bits (0-2) control the interrupt for the comparator. Bit 0 is the interrupt flag, which clears automatically when the interrupt is serviced. Bit 1 turns on the interrupt, and bit 2 selects whether an interrupt is triggered on a rising edge (low to high transition) or a falling edge (high to low transition).
The CAON bit (3) turns the comparator on when set, and off when cleared.
The CAEX bit (7) is used to exchange the two inputs; ie. the pins/references connected to V+ and V- are swapped. (In addition, the output is inverted to compensate for the change.) This ability is useful in examining values close together, but for basic functionality is not necessary.

CACTL2

The P2CAx bits (2-6) are used to select the pins connected to the comparator inputs. V+ is selected with P2CA0 and P2CA4. V- is selected with P2CA1-P2CA3. The x2xx Family Guide provides a table on page 19-12 that explains which bit configuration selects the various pins.
The CAF bit (1) puts the output through an RC filter to smooth out any rapid oscillations that might occur if the comparator inputs are very close together. It's not always necessary, but is a good idea to enable if you're using slowly-varying signals.
The CAOUT bit (0) is the output value only; you cannot write to this bit, but reading it will give you the current value of the comparator output.
The CASHORT bit (7) shorts the two comparator inputs together. While this might sound like an odd thing to do, it is useful under certain circumstances. Basic use of CA+ will not use this function.

CAPD

The CAPD register is analogous to the Port registers; each bit corresponds to the input pins CA0-CA7. The purpose of this register is to disconnect the digital circuitry for the GIO ports from the pins that are being used with analog signals. If an analog signal close to the transition voltage for the digital circuit is applied to the pin, the digital portion could oscillate between high and low fairly rapidly. This effect can cause degradation of the circuitry in the chip, and so it's best to disconnect it completely when analog signals are used. In fact, when a pin is connected to the comparator, it is automatically disconnected. The purpose of this register is to manually control the disconnect. Sometimes you may want to use the comparator on multiple signals; only one pin can be connected to the comparator at a time, but you can switch the input connection in the software. While the CAPD method of disconnecting the digital circuit is redundant when only one pin is used, enabling the CAPD bit for a pin connected to an analog signal prevents it from being reconnected to the digital circuit when the software causes the comparator to switch input pins.

Programming Example

To demonstrate the CA+ module, look at a basic comparison program in bcompG221.c. The idea in this program is to measure an analog voltage, and flash an LED if the voltage is above a particular reference, in this case 1/2 Vcc (1.8 V when running off the USB power). To do this, the program uses the Timer_A module to flash the LED, while the Comparator_A+ uses an interrupt to turn the flashing on and off.

The portion of the code that configures the CA+ module is as follows:

CACTL1 = CAREF1 + CARSEL + CAIE; // 0.5 Vcc ref on - pin, enable
// interrupts on rising edge.

CACTL2 = P2CA4 + CAF; // Input CA1 on + pin, filter output.

CAPD = AIN1; // disable digital I/O on P1.1 (technically

// this step is redundant)

The values used here can be found in the header file for the G2211. Setting CAREF1 alone selects 1/2 Vcc as the reference voltage and setting CARSEL connects the reference to the V- input. Setting P2CA4 alone selects CA1 (same pin as P1.1 for the G2211) as the V+ input. AIN1 was defined to be BIT1, so we permanently disable the digital circuit on P1.1 for this program. This step wasn't essential, since we don't change the inputs on the comparator in this program.

After all the peripherals are configured, the comparator is turned on with CACTL1 |= CAON (the |= operator is used to prevent changing any of the other configurations we put in at first) and the chip enters LPM0.

TimerA periodically triggers an interrupt and toggles the P1.0 output with the value stored in flash. When CAOUT is 0, flash is 0 and so the LED never turns on. When CAOUT is 1, however, flash is set to LED1 (defined to be BIT0) and the LED toggles on and off.

Now let's look at the Interrupt Service Routine for CA+:

#pragma vector = COMPARATORA_VECTOR

__interrupt void COMPA_ISR(void) {

if ((CACTL2 & CAOUT)==0x01) {

CACTL1 |= CAIES; // value high, so watch for

// falling edge

flash = LED1; // let LED flash

}

else {

CACTL1 &= ~CAIES; // value low, so watch for

// rising edge

flash = 0; // turn LED off

P1OUT = 0;

}

} // COMPA_ISR

None of the examples that TI provides on their website demonstrate how to use the Comparator_A+ interrupt. To find the proper syntax, I located the vector name in the msp430g221.h header file. (Remember, the vector name must be what the compiler expects (in this case, COMPARATORA_VECTOR). The header file is the safest place to locate the proper name.) The interrupt routine name, of course, can be named anything. Something descriptive is always helpful, though. For this program, I chose COMPA_ISR(). The service routine first examines the value of CAOUT. If it is 1, then the voltage on V+ is higher than the reference on V-. The next interrupt should be when the value drops below the reference again, so it sets the edge select to a falling edge. It then sets flash to a non-zero value so the LED will blink. If CAOUT is 0, then V+ is lower than the reference. The edge select is set to a rising edge, flash is set to zero so the LED won't blink, and the P1OUT is cleared to ensure the LED is off.

To test the program, you can connect a potentiometer (anything above 1 kΩ should work) between Vcc and ground, and connect the wiper to the P1.1 pin on the LaunchPad. Adjust the potentiometer to see the LED start blinking (indicating the voltage on the pin is above 1.8 V) and back again to see it turn off (indicating the voltage is below 1.8 V). If you don't have a potentiometer, you can try two resistors of different values. Connect one resistor between Vcc and P1.1, and the other between P1.1 and ground. If the smaller resistor is between Vcc and P1.1, the voltage should be more than 1/2 Vcc, and the LED blinks. If the larger is in that place, the voltage is less than 1/2 Vcc, and the LED turns off. (Caution: If you use two resistors to try this, be wary of removing the resistors while the LaunchPad is powered. You might not do any damage, but it's safer to power off a circuit before pulling pieces out.)

Reader Exercise: Change the program so that the LED doesn't blink, but is set on/off constantly for high/low values of CAOUT. Then use TimerA to periodically change the reference voltage between 1/2 Vcc and 1/4 Vcc. When comparing to 1/2 Vcc, it should turn the red LED on P1.0 on if the analog signal is above the reference. When comparing to 1/4 Vcc, it should turn the green LED on P1.6 on if the signal is above the reference. Turning the knob on the potentiometer, you should see the green LED light when the signal is above 1/4 Vcc, then the red LED light when above 1/2 Vcc.

New Tutorials Coming Soon

2010-12-12T07:31:00.002-05:00

I just wanted to put a quick post up letting people know that more tutorials are on their way. I've been in Norway for the past long while doing my research for my Ph.D. We launched our sounding rocket today, and I will be coming home in a few days. At that point, I can get my hands on some hardware to do the tutorial I've been anxiously planning. Should be a lot of fun; hope you're looking forward to it!

This post written from Longyearbyen, Svalbard; 78 degrees, 13 minutes North latitude!

Design Note: Op-Amps

2010-11-15T13:31:00.002-05:00

This quick note is less for design in an MSP430 circuit, but a quick tutorial on Op-Amps that will help those less familiar with electronic components to understand the next tutorial.

The Operational Amplifier, or Op-Amp is an extremely useful piece of hardware. (Some MSP430 devices come with Op-Amp peripherals built in!) The name reflects two very important functions of the device; it can be used to effect the equivalent of a mathematical operation to one or more electrical signals, or it can be used to amplify a signal.

While the details of how an op-amp works physically are a little complicated, visualizing what happens from a practical viewpoint is not so difficult. There are two inputs, labeled V+ and V- in the above schematic. The + and - labels next to the V+ and V- pins help you remember which pin is which. While both are inputs, they don't necessarily behave the same way, which gives the op-amp some of its flexibility. There is one output (Vout). Vs+ and Vs- are the positive and negative sides of a power supply. (Note that Vs- does not necessarily have to be a negative value--some circuit designs use ground on this pin.)

When you analyze an op-amp design, the simplest way to view the chip is to recognize that the output will be an amplification of the potential difference between the V+ and V- pins. Usually the gain on an op-amp is very high (1-10s of thousands) and so a very small difference can be enough to drive the output all the way up to Vs+ (if V+ > V-) or down to Vs- (if V+ < V-). (This is the behavior of what's called a differential amplifier.)

Since the gain is so high, we can use the op-amp in this configuration to compare two voltages. If voltage 1 on V+ is greater than voltage 2 on V-, we get a high output from the op-amp. If we have the reverse situation, we get a low output from the op-amp. In reality, general purpose op-amps are not the best choices to make this comparison, so a special chip called a comparator was designed to do this job. We'll examine it more closely in the coming tutorial.

The true power of the op-amp comes in the ability to tie the output to one of the inputs, providing a feedback that drives the output one direction or another. With feedback in place, the output will change until one of three conditions is reached: the output has increased to Vs+ and cannot increase further, the output has decreased to Vs- and cannot decrease further, or the output has found a state where the two inputs are the same potential. Whenever feedback is used, the output will drive up or down seeking to make the potential difference on the inputs zero.

Op-amps are a very important component for electronic designs. If you're not familiar with them, I'd highly recommend doing some reading to understand them better. (See for example the page on Wikipedia.) My purpose in this note was to mention the comparison operation so that readers have at least been introduced to the comparator before I write up the next tutorial.

This post was prepared while in Andenes, Norway.

Design Note: Power

2010-11-01T17:02:00.001-04:00

A number of comments in the community lately have suggested a note on powering the MSP430 outside of the launchpad would be helpful; to that end I'm writing up this design note to help explain the options and requirements for powering the MSP device.

Chip Configuration

The MSP430 has two pins for power that correspond to the high and low states for the digital logic: Vcc and Vss respectively. For the MSP430, Vss is typically ground and Vcc is usually in the 1.5-3.6 V range, depending on the application. (On the value line devices, these are labeled as DVCC and DVSS, with the D referring to the digital circuitry. Some devices also have a separate AVCC and AVSS for analog signals and peripherals. On these devices, you can tie the A and D supply pins to each other, but the ability to use separate supplies is there.)

Regardless of your chosen power source, there is one thing that must absolutely be done in all designs. Every MSP430 device has a RST/NMI pin. This pin allows you to reset the chip externally by grounding that pin. (The non-maskable interrupt feature is something we'll look at in a more advanced tutorial sometime in the future; for now, only the default operation of the pin is considered.) The LaunchPad is designed with a button that does just that.

In the button tutorial that for a button to behave as an input, the pin needs a definite default state (either grounded for active-high buttons or Vcc for active-low buttons). In order for a chip to be powered, the RST pin must be tied to Vcc. Note that a direct wire is not a safe method of doing this; if a reset is triggered and the pin is grounded, it would short out your power supply. A pull-up resistor is required, and a careful look at the LaunchPad schematic (it's on page 15) shows that TI uses a 47 kΩ resistor, and that seems a reasonable choice for the typical supply voltages one would use for any MSP430 design.

Note in the schematic one other aspect: on the Vcc pin, there are two capacitors. One of these is a 0.1 μF capacitor (100 nF if you're unfamiliar with SI prefixes) and the other a 10 μF capacitor. These capacitors are used to filter the power input, by which we mean keep any fluctuations in the power supply from affecting the value of Vcc. You will see below that many suggested designs for regulated power supplies use a 10 μF capacitor or similar on their output, and you may be able to get away with not using another on the MSP430 if you use one of these power sources. (You might have also noticed a small 1 nF capacitor connecting RST to ground. While not absolutely necessary, if you find your design has sporadic resets that you can't explain, add this capacitor. A TI support technician tells me that for SBW programming to work properly, it should be a capacitor of about 1 nF in size.)

Unlike the larger filtering capacitor, the 0.1 μF should always be included unless you have good reason not to. Digital circuits, especially when run at higher frequencies, can be susceptible to noise from pins switching between high and low. This capacitor is used specifically to filter out that noise, and works best if it can be physically located close to the Vcc pin on the MSP430. If you plan on making your own board designs rather than relying solely on the LaunchPad, get a number of this size of capacitor, as it will be used a lot!

Power Options

There are a huge number of possibilities for powering your circuit: solar panels, large super-capacitors, even various fruits will supply enough electrical power to run your MSP430 designs! For most hobbiest work, however, there are three major places from which to draw power: batteries (consumer type, like you'd buy at the grocery store), the wall AC, and the USB port of a computer.

Batteries are sometimes the easiest choice, but there are some caveats to consider. For the most part, a typical battery holder with a couple of wires can be connected to Vcc and Vss. On the LaunchPad, there are pins for this purpose; soldering female header pins to the wires or using jumpers make battery use simple. Before just connecting up, however, remember that the MSP430 can't handle voltages higher than about 4 V. A 9V battery might sound like a good idea, but alone is not safe to use on the microcontroller.

Good combinations of batteries: 1 or 2 alkaline AAA, AA, C, or D cells would give 1.5 V or 3 V, both good supply voltage values. If you switch to a rechargeable battery, double check the type. Many rechargeable cells are nominally 1.2 V rather than 1.5 V. If you use the 1.2 V cell types, you can use up to three of these in series (a total of 3.6 V) without trouble. Coin cell batteries also work well if you have a holder for them. In general, batteries need no other external parts, though it may be a good idea to have both filtering capacitors on the MSP430 in this case.

If you use a higher voltage battery or battery combination, or if you want to use the USB power (5 V), you will need to step down the voltage to an acceptable level. While there are a number of ways to do this, perhaps the simplest and most effective is to use a voltage regulator. (The LaunchPad is powered from USB; the portion of the board dedicated to the SBW programmer includes a voltage regulator to drop the USB line voltage to 3.6 V.) These components are cheap, robust, and work very well when used properly. Some can even handle such a wide range of inputs that you could connect most any common power source to it and have the output you need. If you've never used a voltage regulator before, read up about it and learn how to use them. An excellent tutorial can be found at SparkFun, and is a good place to start. For my designs, I like to use Linear Technologies regulators, such as the LT1763. (Note that the suggested design on the LT1763 page includes a 10 μF capacitor on its output.) This particular regulator is only available in surface mount packages, but Linear makes a number of other varieties that are comparable in through-hole packages (as an example, the LT1965). There are plenty of options out there that fall into the voltage ranges useful for the MSP430.

If you want to use a wall outlet, you will also need a transformer with a rectifier. Plenty of stores carry such power supplies in a variety of voltages. Anything in the 1.5-3.6 V range will work directly, but I've found most wall-wart supplies are 5 V or higher, and will require a regulator to operate the MSP430.

There are many, many more ways to power your circuit, but these will give you a few reliable sources to start from. Remember to tie the RST pin to Vcc with a resistor, add a 0.1 μF capacitor near the Vcc pin, and keep your voltage within the usable range for the MSP430. Don't forget to connect ground (or the negative side of the battery as the case may be) to the Vss pin, and have fun exploring your power options!

Tutorial 11-b: Using the Auxiliary Clock

2010-10-03T22:32:00.000-04:00

If you did the exercise at the end of the last tutorial, you probably noticed that the program stopped working if you tried using any of the LPMs other than LPM0 or LPM1. The reason for this has to do with the clock that is chosen to power the timer. So let's take a careful look at just what's happening in the limboG2211.c program.

First of all, we set the DCO to the calibrated 1 MHz frequency. Pretty straight-forward here; the MSP430 MCLK timing the CPU will operate at very close to 1 MHz. What isn't as obvious is that the sub-main clock (SMCLK) is also driven by the DCO, and so also operates at 1 MHz.

The timer is then configured to run with the SMCLK divided by 8, or at 125 kHz. The timer counts to TACCR0 and then triggers an interrupt, wherein the current through the speaker (or current to the LEDs if you changed it to that mode) is switched. The frequency of the switching drives the speaker to create a particular tone.

In between switches, the MSP430 enters LPM0. We can see what happens to the chip when entering this mode by looking again at the diagram and table on page 2-15 of the x2xx Family Guide: the CPUOFF bit in the Status Register is set to 1. The CPU turns off, as does MCLK, leaving SMCLK and ACLK running. If we run LPM1, then the CPUOFF bit is set as in LPM0, and in addition SCG0 is set to 1. We can see that this mode has the added benefit of turning off the DCO if the SMCLK is not being used. In our case, we're using SMCLK to drive Timer A, so the DCO is not turned off for LPM1. Essentially, for this program, there is no difference between LPMs 0 and 1.

If we move to LPM2, however, we set CPUOFF and SCG1, which has a much different effect: in addition to the CPU and MCLK, SMCLK is disabled, allowing the DCO to also be disabled. In our program, then, when we enter LPM2 we turn off the clock driving Timer A; Timer A never reaches TACCR0, and an interrupt is never triggered to cause the MSP430 to exit the LPM. In LPM2, however, ACLK is allowed to continue running. If we drive Timer A with ACLK, then, we could use deeper modes and consume less power overall! Less power means more battery life and more efficient use of the resources in the MSP430 design.

ACLK is typically driven at low frequencies (comparatively), and so draws less power than does DCO, further improving our goal of reducing power consumption. By default, it is set to use a 32,768 Hz quartz crystal. Your LaunchPad kit came with a crystal that you can solder onto the board to use here. Alternatively, you can configure the LFXT1 clock source to run from an internal oscillator, similar to the DCO, that operates at a very low frequency (typically 12 kHz). This oscillator is referred to simply as the VLO.

Configuring LFXT1 and ACLK
If you're planning to use the crystal oscillator on LFXT1, there's likely little that needs to be done. The crystal that comes with the LaunchPad needs 12.5 pF capacitors for stability, and you might notice the SMD solder pads near the crystal location for capacitors. You can use discrete capacitors if you like, but the MSP430 is also configured with a few capacitances internally, and 12.5 pF is one of the choices. Using the crystal is a simple matter of soldering it onto the board and configuring the BCS+ module correctly. There are a lot of switches and controls involved here, so we'll save crystal control for a later tutorial, and assume for now that we're going to use the VLO to source the Auxiliary Clock.

Section 5.3 in the x2xx Family Guide (starting on page 5-13) holds the necessary information for configuring the BCS+ module. The registers we need for now are BCSCTL1 and BCSCTL3. In terms of setting up the VLO, we need the XTS bit in BCSCTL1 (bit 6) and the LFXT1Sx bits in BCSCTL3 (bits 5 and 4). The XTS bit sets the LFXT1 clock source to low or high frequency. Many MSP430s in the x2xx family let you use a high frequency crystal for this source; the value line devices, however, only support low frequency (ie. 32,768 Hz) crystals. When this bit is cleared to 0 we have configured the chip for low frequency ranges. Some devices, including the value line chips that come with the LaunchPad, allow us to use the VLO. This mode is selected by setting the LFXT1Sx bits to 0b10, as described on page 5-16. To do this in C, we again make use of a header file definition:

BCSCTL3 |= LFXT1S1; // sets LFXT1Sx to 0b10, VLO mode

We don't need to explicitly change the XTS bit, as it defaults to the low frequency setting. This line is sufficient for setting up the VLO.

With LFXT1 now oscillating at 12 kHz, ACLK can be used for the peripherals. You may recall from Tutorial 08-a that ACLK only sources from LFXT1, using either a crystal or the VLO. We can, however, alter the frequency for ACLK by dividing the VLO by 2, 4, or 8. This is done in BCSCTL1 with the DIVAx bits (5 and 4) with the configurations given on page 5-14. For our purposes, we'll set ACLK to run at about 3 kHz by dividing the VLO by 4. We do this with the following code:

BCSCTL1 |= DIVA_2; // ACLK divide by 4

Keep in mind that you can also divide the clock in the peripheral itself, or further divide inside the peripheral. For example, we can run Timer A at 750 Hz by dividing by an additional factor of 4:

TACTL = TASSEL_1 + ID_2 + MC_1 + TACLR; // use ACLK, div 4, up mode, clear

To summarize, we can modify the limboG2211.c code to use the following:

BCSCTL1 = CALBC1_1MHZ; // Running at 1 MHz
DCOCTL = CALDCO_1MHZ;
BCSCTL3 |= LFXT1S1; // VLO mode

TACCR0 = 14; // With the Timer using ACLK (12 kHz), this
// value gives a frequency of 12000/(TACCR0+1) Hz.
// For TACCR0 = 14, that's 800 Hz.

TACCTL0 = CCIE; // Enable interrupts for CCR0.
TACTL = TASSEL_1 + MC_1 + TACLR; // ACLK, up mode, clear timer.

_BIS_SR(LPM3_bits + GIE); // Enter LPM3 and enable interrupts

This code sets ACLK to run from the VLO (at ~12 kHz) and then uses Timer A to switch the speaker at ~800 Hz. Most importantly, since we are now sourcing the timer which causes interrupts from ACLK, we can use LPM2 and 3 in our program. Note that LPM4 would turn off the ACLK; using LPM4 is only feasible if we have some external interrupt source, such as watching for a signal on one of the GIO pins.

We'll return to looking at the low power modes soon; the first real scientific project we'll do will analyze and compare the power consumption of a simple MSP430 design using the various LPM settings. To do this, however, we're going to need to measure an analog signal and record data. The next tutorial will start us in this direction by looking at analog to digital conversion.

Reader Exercise: Suppose your LaunchPad has the crystal soldered onto it, and is being used in a project that does not use ACLK at all. The crystal will continue to oscillate, and use power (albeit a very small amount) that is not contributing to the overall design. Note that none of the standard LPMs disable ACLK and the crystal oscillator except LPM4. Write up the needed line(s) of code that would create a new LPM that keeps MCLK, SMCLK, and the DCO running, but disables ACLK and the crystal oscillator.

Yes, the blog is officially back!

2010-10-01T23:01:00.000-04:00

Thanks, everyone, for your patience. My research has been moving quite a bit lately and occupied the majority of my time. Fortunately the 16 hour work-days are over, and I have some spare time and motivation to play with the LaunchPad some more. I've posted the first part of a multi-part tutorial on Low Power Modes (by popular demand!) and have a bunch of great ideas coming up. We'll be working toward being able to make your own LaunchPad circuit board (minus the SBW programmer, of course) and communicating with a computer among many other fun things. Send me a note if you have any particular topics you're aching to learn about. We'll keep on with LPMs and start ADC soon as I wait for the boards I've designed to arrive. Watch for some design notes and other posts to come soon!

Tutorial 11-a: Going Low Power

2010-10-01T22:53:00.004-04:00

Now that we have some degree of control over the MSP430, it's a good opportunity to introduce the low power mode. This feature is arguably one of the most important for the MSP430, and is an excellent reason for choosing this microcontroller over many others. Let's look at how the modes work.

The operating mode of the MSP430 is controlled with four different bits in the status register. These bits are called CPUOFF, OSCOFF, SCG0, and SCG1. The first two are fairly self-evident; the first of these controls the power to the CPU of the MSP430. The second controls the power to the external oscillator (ie. crystal usually). In addition, these bits turn on/off MCLK and ACLK respectively, since those are associated with the CPU and LFXTL. The other two bits add more control over SMCLK, the DCO, and the DC generator.

Page from the x2xx Family Guide describing
the low power modes.

In the x2xx Family Guide, page 2-15 shows a diagram and table explaining how the operating modes work. For our convenience, TI has defined 6 different modes that are easily accessible to us via the header files. The MSP430 starts off in Active Mode, where the CPU and all clocks are up and running. This is the mode in which we've been running up until now. Any time the MSP430 needs to do something, it will be in Active Mode. That's not to say that peripherals can't operate in the other modes. There are 5 low power modes, labeled LPM0 through LPM4. These are the commonly used configurations, and only rarely will you need one of the other 10 possible modes available with a 4-bit configuration. (One exception to that would be turning off an unused crystal oscillator that's soldered to your LaunchPad, but not being used in your current project. More on that later.)

the _BIS_SR() function we saw earlier is perhaps the easiest method of using the LPMs. The header files define a set of names called LPMx_bits to help with the bit management. To enter a low power mode, simply issue the command _BIS_SR(LPMx_bits); with x replaced by the LPM number you've chosen. Keep in mind that if you want to use interrupts, you will also have to add GIE to the argument, or at least _enable_interrupt(); before going into the LPM.

Another good thing to keep in mind is that the LPMs are distinct; you don't need to include LPM0 to use LPM1. In fact, doing so (eg. using a command such as _BIS_SR(LPM0_bits + LPM1_bits + GIE);) would have undesirable side effects by adding the binary values that the header file definitions provide together.

One of the features of the MSP430 architecture is that you don't need to tell the CPU to wake up on the interrupt, nor do you need to put it back in the LPM manually. All of this is done automatically; when an interrupt is triggered, the Status Register is saved to memory (pushed onto the stack) and reset, waking up the CPU. Once the ISR has been satisfied, the original Status Register (including the LPM setting) is popped off the stack back into its place, and the MSP430 returns to the low power state. If you require your program to wake up the chip and stay awake, you will need to include a line in your ISR to do so:

_BIC_SR(LPMx_bits); // clears the bits corresponding to LPMx and exits the low power mode

Note the different function name; _BIS_SR() is Bit Set Status Register (ie. set to 1) while _BIC_SR() is Bit Clear Status Register (ie. clear to 0).

Example using the Low Power Modes
As an example, I've coded up a simple program that plays a tone on an 8Ω speaker. The speaker I have has two pins with 0.2" separation, and so it plugs right into the headers on the LaunchPad. To accommodate the spacing, I'm using P1.0 and P1.2 to drive the speaker. If you don't have a speaker available, you can simulate the same idea using the two LEDs on the LaunchPad; just follow the instructions in the code and change SOUT to BIT6 and adjust the frequency accordingly.

The idea is simple; we start with P1.0 high, P1.2 low, and switch each at a given frequency. This method provides a square wave, not a pure tone, but it does work. Keep in mind that audible frequencies are generally in the 100's and 1000's of Hz. It might be interesting to see how low of a frequency you can hear (clicking doesn't count; listen for an actual tone) and how high you can hear. Also, you can keep one pin constantly low and switch only the other if you want to reduce the volume.

There's more to explore with the low power modes, and next time we'll start playing with the low frequency oscillator to drop into the deeper sleep modes.

Reader Exercise: This tutorial's code uses LPM0. Try out the other low power modes by using LPMx_bits in place of LPM0_bits. What happens if you try to use LPM1? LPM2? LPM3? LPM4? Can you explain why some of these work and others don't? Those that work, is there any actual difference between the modes as implemented for this program? As you answer these questions, think about what clock is sourcing the timer and what oscillator is used for the clock.

A Great Example of an MSP430 Based Instrument

2010-09-16T14:46:00.001-04:00

I ran across an interesting article in reading the news during my lunch break today. A group at the University of Washington has been doing research in smart sensors that communicate through the established power lines in a house. The page doesn't say specifically, but given the power consumption they mention I wondered if this was based on an MSP430. A close up of the photo of the board looks like it might be, and you can just make out the TI logo on the chip. Digging a little deeper, I confirmed that yes, this instrument is based on the MSP430. The team is using a surface mount variation of the MSP430F2013. This chip is also available in a 14 pin DIP package that is compatible with the TI LaunchPad. Very cool idea.

In other news, my project is now at integration, and I have some extra time on my hands. Watch for a couple new tutorials coming this week!

Still Alive

2010-08-21T08:59:00.000-04:00

I've had a number of people ask about the long delay since my last post, so I thought I'd put a quick note up to give you an update. My deadline to deliver the instrument I'm building for my Ph.D. research is coming up in a couple of weeks. As such, I'm spending 10-14 hours a day in the lab, and haven't had a moment to think about the blog in a while. Once the instrument is delivered, however, there will be lots of time opening up. I have had lots of ideas and do have lots of plans for this site, so thanks for your interest and patience! I'm really encouraged by the good reviews I've gotten for what I've written up so far. I do really think the MSP430 can be a very important tool in developing instruments for use in or out of a laboratory, and we'll get to try some out soon.

Tutorial 10-b: Interrupt Examples

2010-08-03T18:58:00.004-04:00

GPIO Interrupt Example
The first example we'll do uses the Port 1 interrupts; this code is easily changed for any port number used in your particular device. This code will show how to do the DCO example we did in Tutorial 08-b, which demonstrates changing the DCO, using interrupts.

First, we need to configure the port to use interrupts. The LaunchPad button is on P1.3, so all of our concern will be on that pin. The pin needs to be configured as an input. Since the default state of the pin is logic 1, a high-low transition (a drop from 1 to 0) should be used to signal the interrupt. We can code this using:
P1IES |= BIT3; // high -> low is selected with IES.x = 1.
P1IFG &= ~BIT3; // To prevent an immediate interrupt, clear the flag for
     // P1.3 before enabling the interrupt.
P1IE |= BIT3; // Enable interrupts for P1.3

We've enabled the interrupt for P1 now, and a high-low transition caused by the button press will set the interrupt flag in P1IFG. The processor, however, isn't set to recognize maskable interrupts like P1IFG. We can turn on the interrupts with:
_BIS_SR(GIE);

or equivalently:
_enable_interrupt(); // Note the singular name here! It's not interrupts.

The first method parallels the bis.w instruction in assembly used for this command, and can be used to configure the SR in one step with other options, such as low power modes. The second method is a little more human readable, and works well enough if you don't need to enable any LPM's.

Next we need to write the ISR. Something like this will work:
#pragma vector = PORT1_VECTOR
__interrupt void P1_ISR(void) {
   switch(P1IFG&BIT3) {
   case BIT3:
   P1IFG &= ~BIT3; // clear the interrupt flag
   BCSCTL1 = bcs_vals[i];
   DCOCTL = dco_vals[i];
   if (++i == 3)
   i = 0;
   return;
   default:
   P1IFG = 0; // probably unnecessary, but if another flag occurs
   // in P1, this will clear it. No error handling is
   // provided this way, though.
   return;
   }
} // P1_ISR

The port interrupts can be sourced from 8 port pins, and so the ISR needs to decide what to do with each possible interrupt. The switch statement in C is ideal for this task, and is used here to single out a BIT3 flag. If, for some reason, the MSP430 is flagged with a different Port 1 interrupt, it simply clears the flag and moves on. Since none of the other flags are enabled, this should never happen, but it's good coding practice to include something like this. Error handling would be ideal, but it's not done here.

Note that since the P1 interrupt has 8 sources and individual flags, you need to clear the flag manually. Don't forget to do this, or your code will continually keep interrupting! This code makes use of three pre-stored values for BCSCTL1 and DCOCTL and increments through them each time the interrupt is called. These values, as well as the counter i, need to be global for the ISR to see them, and so they are declared outside of the main() function. See the whole code put together in interrupted-1_G2211.c.

Timer_A Example
As a second example, we'll do something similar to a project I'm working on and turn a light on and off using a relay switch. I've coded this using a switch on P1.6 so that you can observe its behavior on a LaunchPad using the green LED instead of the actual relay. If you have a relay, be sure to connect it correctly to prevent too much current draw from your MSP430. Using the 1 MHz calibrated DCO divided by 8, Timer_A will count up to 62,500 in 0.5 s. In my actual application, I'd like to turn the light on for a few hours, then turn it off for a few hours. That's easier to do with a slower clock, and an ideal application for the LFXT1 clock source. But, since we haven't covered that yet and many people likely do not have the crystal soldered to their LaunchPad's, we'll do more frequent on/off cycles to simulate the actual process. We'll use the DCO to turn the light on and off in 1 minute intervals. To do this, we'll make use of the Timer_A up mode and interrupt using the CCR0 registers. (Yes, this is essentially a fancy version of blinky. Turns out "Hello, world!" is actually useful in microcontrollers!)

We configure the timer with the following:
TACCR0 = 62500 - 1; // a period of 62,500 cycles is 0 to 62,499.
TACCTL0 = CCIE; // Enable interrupts for CCR0.
TACTL = TASSEL_2 + ID_3 + MC_1 + TACLR;

The long string of assignments to TACTL are, in order, select SMCLK as the clock for Timer_A (runs off the DCO by default), select input divider of 8 (1 MHz SMCLK becomes 125 kHz), select up mode, and clear the count in TAR. These values are defined in the device header file so that you don't have to constantly manipulate bits by hand. The mnemonics are easier to use most of the time. (For other configuration options, see the Timer_A section in your device's header file.)

The ISR may look something like this:
#pragma vector = TIMERA0_VECTOR
__interrupt void CCR0_ISR(void) {
   // no flag clearing necessary; CCR0 has only one source, so it's automatic.
   if (++i == 120) {
   P1OUT ^= RLY1;
   i = 0;
   }
} // CCR0_ISR

Again, we're using a global variable i as a counter, and presumably have defined RLY1 to be BIT6 in the program header. Every time a flag occurs (twice a second) the counter is incremented. If we've reached 120 (60 s at 2 Hz) the relay control is toggled and the counter resets.

The complete code for this example is in interrupted-2_G2211.c. For you impatient folks, feel free to adjust the timer period to whatever value preserves your sanity.

These two examples should get you started with interrupts. As always, feel free to ask questions or suggest other helpful tips!

Tutorial 10-a: Something Completely Different (Interrupts)

2010-08-03T16:53:00.005-04:00

I realized half way through the last tutorial that we need to take an aside for now. One of the unfortunate aspects in microcontrollers, especially for those with no prior experience, is that you run into chicken-egg dilemmas all the time. How can you teach timers without interrupts? How can you teach interrupts without something to cause interrupts, like timers? It takes some patience, but with some experience (and lots of examples!) things start to settle into place. In the mean time, I apologize for the occasional jump in topic. For that matter, we're not entirely done with previous topics either, and will revisit some of the more advanced concepts of GPIO, Clocks, and so forth in the future.

So what exactly is an interrupt? Hopefully you're familiar enough with C programming (if not, I highly recommend spending some time with a good book; I suggest the C Primer Plus (5th Edition)) to have a good handle on function calls. Microcontrollers use function calls as we've seen before, just as your personal computer does. But microcontrollers also interface with the outside world, and sometimes you need to perform a specific task based on what happens outside the circuit. One option would be to continuously poll an input (or sequentially poll a set of inputs) to see if anything needs to happen and call the appropriate function accordingly. Unfortunately, this ties up the processor so that it can't do anything useful in the mean time. Perhaps worse, the processor keeps chugging along, using up power doing nothing but waiting to see if it's got a job to do. The better option is to have the outside signal interrupt the processor (from its current task or its nap) to get a task done and then allow the processor to go back to what it was doing. This ability is implemented in the aptly named interrupt service routine (ISR).

The Interrupt Handling Procedure
In order to control multiple sources at once, the MSP430 needs to have some definite organization; who gets priority over the other peripherals? How do we keep track of where we were before? To do this, the MSP430 is designed with a clean and efficient procedure to handle interrupts.

If a peripheral's interrupt is enabled, the appropriate signal sets the interrupt flag in one of the peripheral's registers.
If the processor is allowing interrupts, the presence of a peripheral interrupt flag sets a general flag to the processor.
The processor finishes any instruction it's currently doing.
The processor saves it place by copying the address where it's currently executing instructions (the value in the Program Counter (PC) register) to the memory stack (this is called "pushing onto the stack").
The processor saves its current status by pushing the Status Register (SR) onto the stack.
The interrupt that currently has the highest priority is selected if there are multiple flags set. Check your device's datasheet for a list that shows the priority of the possible interrupts.
The interrupt flag is cleared, unless the peripheral has more than one type of interrupt. In that case, you have to clear the flags manually.
The SR is cleared, which disables any further interrupts during the ISR handling and wakes up the processor from any low power mode (LPM). Note that only "maskable" interrupts are disabled by the SR clear; this means "non-maskable" interrupts, such as a reset, are still possible during an ISR.
The address of the interrupt vector is copied to the PC, directing the processor to start executing code from that address on.

From the start of an interrupt signal to the start of ISR execution can take anywhere from 6-12 clock cycles of the processor, depending on exactly what's going on when the interrupt is flagged. (This latency isn't much, but must be handled differently for time-critical event handling.) If the chip is operating at 1 MHz, that's anywhere from 6-12 μs for the processor to respond to an event.

When the ISR finishes, the processor executes the return from interrupt sequence, which consists of just two steps:

Move the original SR value from the stack to the SR (this is called "popping" from the stack).
Pop the original PC value from the stack to the PC.

This sequence takes another 5 cycles to complete, after which the processor returns to what it was doing. Note that if the MSP430 was in an LPM before the interrupt, it returns to the same LPM after the ISR handling with no further instruction from the code necessary. You only need to give a different instruction if you don't want the MSP430 to reenter the LPM. We'll see how to do that soon, when we discuss the low power modes.

Coding Interrupts

Writing an ISR is very similar to writing encapsulated functions in C, but requires some special syntax that you may not have seen before. Every ISR has this structure:

#pragma vector = <VECTOR_NAME>

__interrupt void <ISR_NAME> (void) {

ISR code here

}

The keyword #pragma is used in C to signify a special operation peculiar to a compiler. (If you were to compile your MSP430 code with another compiler, such as gcc, it would simply ignore this line, leading to potentially unexpected errors.) In this case, it tells the MSP430 compilers that the following code is to be referenced for the particular interrupt named. VECTOR_NAME is essential, and must follow the conventions for the particular peripheral interrupt being written used in your device's header file; the address of the start of the ISR in the code memory is recorded in the address defined by the header as VECTOR_NAME. Take careful note that the #pragma line does not have a semi-colon at the end.

__interrupt signifies the start of the ISR. You can name the ISR anything you'd like, but conventionally coders use something descriptive, such as P1_ISR for a Port1 interrupt, or TA0_ISR for a Timer_A interrupt.

Beyond that, everything remains the same as we're used to seeing. There's no special code needed in C to start the return sequence, but in assembler you need to manage this using the reti instrunction.

Unused Interrupts

What happens if an interrupt is called and you don't have an ISR written for it? The results are unpredictable, depending on what value is inside the interrupt vector. The safest method to protect from this is to write an ISR for every interrupt, doing nothing, or perhaps entering an infinite loop, for interrupts not used. (The infinite loop method makes debugging clearer; it's obvious where you get stuck that way!) This convention doesn't take much code space in the MSP430, but can make your simpler projects a little more complicated to the outside viewer. Another way to handle this problem is to be certain that unused interrupts are disabled so that they can't ever flag the processor. Not controlling interrupts can cause serious problems, however, so be sure to try to use good coding practices whatever you do.

This part of the tutorial on interrupts is long enough, so the following post will give a couple of examples to get you started using what we've learned here.

Tutorial 09: Timers

2010-08-01T23:55:00.001-04:00

Now that we can configure the clocks in the MSP430, we can use them to drive peripherals. Peripherals are hardware that may be built into the chip itself or added on by us. Controlling peripherals is where the microcontroller really comes to its own, and is likely the reason you're learning about the MSP430. The first peripheral we'll examine is the Timer_A system.

First, note that there is also a Timer_B system available in some devices, which in most respects is just like Timer_A. None of the value line devices have this system, so if you're eager to use this peripheral in another device, learn about Timer_A and then refer to the Family User's Guide for more information.

A timer is really nothing more than a counting mechanism that is tied to some type of regular interval provided by a clock. The Timer_A peripheral is what we call a 16-bit timer. This definition simply means that the timer counts from 0 in binary to 0b1111111111111111, or 0xFFFF in hex, 65,535 in decimal. Simple enough, and very useful when we know how to manipulate the behavior of the timer.

Timer Modes

There are three modes to operate Timer_A. Which one we use depends entirely on the application. The first mode is what we call the continuous mode: Timer_A acts just like a 16-digit, binary odometer; it counts from 0 to 0xFFFF and then "rolls over" to 0 again. The second mode is called up mode; here, just like in continuous mode, it counts up and rolls over to 0. This mode, however, lets you choose how high up the timer counts before rolling over. The third mode, up/down mode, is similar to up mode in that you can program the upper limit. It differs in that rather than rolling over to 0, it turns around and counts down to 0. When you would choose to use the different modes may or may not be immediately obvious, so as you peruse articles on this and other sites, take note of how each mode is used when you see them in examples.

In addition to the three ways of counting in Timer_A, there are also a few ways we can make use of the counter. Timer_A has the ability to set "checkpoints" in its counting (Value Line devices only have two, but other devices have a third). TI calls these checkpoints Capture/Compare Registers. The most basic use of these registers is to set values at which the counter flags the processor to do something special. In fact, one of these registers is what is used to set the upper limit in up and up/down mode. The other register only flags the processor and allows the timer to keep on counting. (This is also the behavior of the first register in continuous mode.)

This type of use is the Compare mode of the register; we set a value that is compared to the current count in Timer_A. If the values are equal, it signals that's the case to the processor. Capture mode behaves a little differently; the timer waits for some type of signal (often from some sort of input) and then records the current value of the timer in the register without stopping the timer, somewhat like the lap time function of a stopwatch.

Registers

With so many ways to use Timer_A, you can probably imagine it corresponds to a lot of registers in the MSP430 to use and control the timer. There are, in fact, at least seven registers used in any device with the Timer_A peripheral. Let's take a look at each of these in more detail. In your Family User's Guide, turn to pages 12-20 through 12-23 to see the register maps.

TACTL -- The Timer_A Control Register is used to set up the link between the timer and a clock and select the mode used.

The TASSELx bits (8 and 9) tell the timer which clock to use as its source.
The clock frequency can be divided by a further factor of 2, 4, or 8 using the IDx bits (6 and 7). (Note that this is further division to any divisions done from the clock source for the clock itself; you could potentially have a total division of up to 64 from your clock source for this peripheral.)
The MCx bits (4 and 5) select the particular mode for the timer to use. Note particularly that setting these bits to 0 (the default setting on POR) halts the timer completely.
TACLR is bit 2. If you write a 1 to this bit, it resets the timer. The MSP430 will automatically reset this bit to zero after resetting the timer.
TAIE and TAIFG (bits 0 and 1) control the ability of the timer to trigger interrupts; more on this soon!

TAR -- The Timer_A Register is the actual counter; reading this register reports the current value of the counter.
TACCRx -- The Timer_A Capture/Compare Registers, of which there are two in the value line devices (TACCR0 and TACCR1) are where particular values we want to use are stored. In compare mode, we write values here where we want the timer to signal an event. Particularly, TACCR0 is used to store the value to which we want Timer_A to count in up and up/down mode. In capture mode, the processor will record the value of TAR when the MSP430 is signaled to do so.
TACCTLx -- The Timer_A Capture/Compare Control Registers correspond to the TACCRx registers. These set the behavior of how the CCR's are used.

CMx (bits 14 and 15) change what type(s) of signals tell the timer to perform a capture.
CCISx (bits 12 and 13) select where the input signals are taken.
SCS and SCCI (bits 11 and 10 respectively) change the synchronicity; the timer normally operates asynchronously to the input signals. (Yeah, I don't entirely understand this yet either. Watch for a future post to explain this further.)
CAP (bit 8) changes whether capture mode (1) or compare mode (0) is used.
OUTMODx (bits 5-7) select various output modes for the CCR's signal when the timer flags a capture or compare event.
CCIE and CCIFG (bits 4 and 0) are more interrupts associated with the CCR's.
CCI and OUT (bits 3 and 2) are the input and output for the CCR.
COV (bit 1) is the capture overflow; this bit is set to 1 if two captures are signaled before the first capture value is able to be read.

TAIV -- The Timer_A Interrupt Vector Register; since there are multiple types of interrupts that can be flagged by Timer_A, this register holds details on what interrupts have been flagged.

The only bits used here are bits 1-3 (TAIVx), which show the type of interrupt that has happened, allowing us to take different actions to resolve the different types of interrupts.

There's an awful lot of information to cover to fully explain these registers, unfortunately, so we'll look at some examples of how to use the Timer_A as a means to illustrate what many of these bits do and how to use them. Before getting to that, though, we'll need to take a look at these interrupts, and that will be the topic of the next post. Hopefully we've been able to learn a little about the overall function of the Timer_A peripheral. Shortly we'll be able to put it to use in our MSP430 designs.

Design Note: Using Outputs to Control Loads

2010-07-30T19:25:00.003-04:00

In my plant-watering project, I need to control a relay switch to turn a water pump on and off. I chose this nice, inexpensive relay to do the job, and confirmed that 3V does indeed close the switch in the relay. If I connect the coil to the output of the MSP430 and set a high value on the pin, however, nothing happens.

The reason is that the MSP430 GPIO pins are limited in the amount of current they can source/sink. According to the G2x11 datasheet, the total output for P1 should not exceed +/- 48 mA. (This is also true for any of the Value Line devices.) Omron's datasheet for the G5LE shows that the power consumption of its coil is 400 mW, which means at 3.6 V provided by the LaunchPad, it draws 111 mA, well above what the MSP430 can do!

Fortunately, there's an easy way around this that requires just a few inexpensive components. A fellow ham, N1HFX, has an excellent write up on transistor switches that includes an example for a relay switch. I've borrowed his schematic image and changed the values to what I've used for my relay. Some external parts won't need the diode, but it's cheap insurance for any inductive circuits like a mechanical relay. I'm using the same power source as for the chip (from the USB port via the LaunchPad for testing, but eventually a couple of AA batteries), but it's also possible to use a different supply, and even (with some careful design) use a different voltage. Just be certain that your current draw from the MSP430 does not exceed its limits.

One thing to keep in mind with this circuit is that rather than the switch being on with logic high, it's on with logic low. Since I want the switch off by default, I need to be sure that I've initialized the output pin to a high value before setting it as an output.

(Thanks N1HFX, de KE7BFA!)

Tutorial 08-b: Configuring the DCO

2010-07-29T16:57:00.007-04:00

The MSP430's Digitally Controlled Oscillator is one of the most important peripherals to be able to manage. It's the easiest of the clock sources to configure, as it requires no external parts and is controlled completely by software. The DCO (within the BCS+) is configured with two registers: DCOCTL and BCSCTL1. Look up the maps of these two registers in the x2xx Family User's Guide, page 5-14.

This image comes directly from the User's Guide, and explains how to select the different possible frequencies for the DCO. The total range of frequencies is divided into 16 overlapping ranges. So Range 7's low end overlaps Range 6's high end, and Range 7's high end overlaps Range 8's low end. Make sense? Ok, each range is further subdivided into 8 possible frequencies. If you plot all of these out, you get something similar to the above image, but with 16 lines instead of the three representative lines shown here. There are then 128 distinct frequencies available to the DCO, with some overlap of course.

Registers
We are able to select the frequency we use with the RSELx bits in BCSCTL1 (select range 0 to 15) and the DCOx bits in DCOCTL (select step 0 to 7). How do we know which pair we want? The device-specific datasheet should give you some help in that regard. For the G2x11, we see the DCO frequency table on page 26. For any device, this table will either list the typical value for a sample of selections, or a set of min/max values for the selection set. (Note: As of this writing, the current revision of the G2x11 datasheet (SLAS695B) is printed incorrectly, giving typical values for some selections and min/max values for others. In future revisions of the document it will likely be changed to only one or the other.) TI uses an ordered pair notation to describe the DCO setting, such as (8,2) for Range 8, Step 2 (or DCO 2 to use their term). We'll use that notation from now on to describe DCO settings with the convention DCO(r, s) where r is the range value and s is the step value.

As an example, note that DCO(6,3) is typically 0.80 MHz (or 800 kHz), while DCO(13,3) is 7.8 MHz. Note that the table only lists DCO(r,3) pairs for each range, and also values for DCO(0,0) and DCO(15,7), the low and high end of the DCO values. What about all the others? At the bottom of the table, there are two values called SRSEL and SDCO. These values give the ratio of subsequent ranges and steps as SRSEL = (r+1,s)/(r,s) and SDCO = (r,s+1)/r(s), allowing you to get a value for any of the possible combinations. For example, DCO(6,4) would be SDCO * DCO(6,3), or in the case of the G2211, 1.08*0.80 Mhz = 0.864 MHz. DCO(6,7) would be SDCO * DCO(6,6) = SDCO * (SDCO * DCO(6,5)) and so on, so a general formula would be DCO(r,s+n) = SDCO^n * DCO(r,s). (Note that you can get the lower step values with negative n, eg. DCO(6,1) = DCO(6,3-2) = SDCO ^ (-2) * DCO(6,3).)

One final topic before getting to the code; each MSP430 device comes with at least one calibrated value for the DCO. These values are found for each individual chip at the fabrication facility and programed into the information memory section of the flash memory. The values are not necessarily the same for my G2211 as it is for yours, but if you ever accidentally (or intentionally) erase the calibration values, TI does provide a program that will recalibrate the DCO and write the values to the memory for later use. (You should be able to find this program in the code examples you can download for your device. The G2xx code can be obtained here, and the program is called msp430x20xx_dco_flashcal.c.) The G2x11 devices only have one calibrated frequency at 1 MHz.

Example
Now for the practical part. Fire up CCS with your launchpad, and enter the debugging mode with any program you have. We're not going to actually run the program, just look at some of the registers as they come up by default. The MSP430 x2xx devices supposedly default to a 1.1 MHz DCO. What value actually comes up? In the debugger, open up a view of the registers, and find the BCS+ registers under System_Clock. For the G2211, the registers start with values of 0x60 for DCOCTL and 0x87 for BCSCTL1. Expand the registers to look at the individual bits, and we can see that RSEL is 0b0111, or 7, and DCO is 0b011, or 3. The default setting for the DCO is DCO(7,3), which according to the datasheet is between 0.80 MHz and 1.50 MHz. The actual value depends on your unit, the temperature, pressure, phase of the moon... ok, not really the moon phase, but you get the idea. If you happen to have an oscilloscope, we can actually look at the frequency by using the alternate function for P1.4-- the SMCLK can be driven by the DCO and put on this pin for external use.

Let's write up some code to actually change the DCO now. We're mostly interested in manipulating the DCOx and RSELx bits, which are bits 5-7 in DCOCTL and 0-3 in BCSCTL1 respectively. When we've selected the pair of values we want, we can change those bits in code. For example, if we want to change to DCO(12,2), we want 0b1100 for RSELx and 0b010 for DCOx. We can set these values in our code with the following:
BCSCTL1 &= ~(BIT0 + BIT1); // set bits 0 and 1 to 0

BCSCTL1 |= BIT2 + BIT3; // set bits 2 and 3 to 1

DCOCTL &= ~(BIT5 + BIT7); // set bits 5 and 7 to 0
DCOCTL |= BIT6; // set bit 6 to 1

Does the order matter? Well, keep in mind the frequency will change with every step. So after the first line, assuming we have the default configuration found above, the bits have changed to 0b0100, putting us in DCO(4,3). The second line moves us to DCO(12,3). The third line moves us to DCO(12,2), making the last step redundant. If we had started by setting bits 2 and 3 in RSELx, we would have stepped from DCO(7,3) to DCO(15,3), putting a really high frequency on everything. That may not be an issue, but if you have any sensitive components you might consider stepping rather than jumping up to higher frequencies. If MCLK is driven by DCO (it is by default) you may find some problems as the higher frequencies may be above the 16 MHz limit for the processor. Going the other direction, jumping down puts the DCO at a really low frequency, which slows down the operation of the subsequent steps, but shouldn't cause any serious trouble.

Setting to calibrated values is much easier, since CCS provides us with shortcuts to those values:
BCSCTL1 = CALBC1_1MHZ;
DCOCTL = CALDCO_1MHZ;

Those two lines are all that's needed to set the DCO at exactly 1 MHz! (Within 3%, anyway.)

I've written some code in dcodemo_g2211.c that gives an example of how to use the DCO in a program. Browse through it and try running it on your launchpad to see how it works. The program simply flashes the LED with a delay loop and waits for the user to press the button. The program then changes the DCO frequency, and re-flashes the LED. Since the frequency increases, however, the LED flash is much faster, even though it uses the same delay loop! The DCO is controlling the operating speed of the processor, and so the for loop steps through much more quickly. Another button press slows down the DCO and re-flashes the LED, this time at a slow rate. Another button press returns the LaunchPad to the original state, and the program runs through again.

We haven't covered all the features of the DCO yet, and will discuss them as we progress further. Next we'll talk about the use of timers in the MSP430. As always, feel free to discuss and ask questions about what you've read here!

Reader Exercise: My G2211 unit that came with my LaunchPad uses DCO(6,5) for the calibrated 1 MHz frequency on the DCO, and sets the MODx bits to 0b00101 (which is also 5). What does yours use? Write a program that uses the calibrated value and use the debugger to find out what the register settings are for the 1 MHz calibration on your unit. Supposedly, these are set individually to the chip, so I'd be interested to hear if anyone actually has a different value than mine!

Tutorial 08-a: The Beating Heart (BCS+ Part I)

2010-07-20T18:20:00.002-04:00

With the basics behind us, we can jump into some of the more advanced (and far more interesting!) topics to learn how to use the MSP430 microcontroller. The goal of this tutorial series is to examine the various peripherals available on the MSP430 devices and how to use them. Along the way, we'll look at the concepts of interrupts and low power modes as well. To follow this tutorial, it is extremely helpful to have a copy of the Family User's Guide and Datasheets for the specific device you are using. I printed these out (including the 600+ page User's Guide) and had them bound for easy access, but an electronic copy will work fine. The first peripheral we'll look at is the Basic Clock System + (BCS+) used in the MSP430x2xx Family, including the Value Line chips compatible with the LaunchPad platform. This system is detailed in Chapter 5 of the x2xx Family User's Guide.

We've seen in our analogy to a town that we can issue different commands and control different things easily in the MSP430. Just as in any town, if the parts aren't working in conjunction then everything winds up in a big mess. When does this switch get flipped? Does it happen before or after that event? What order do I do things, and when? Every town needs a clock, and a microcontroller depends on one.

The 3 Clocks
Each family of MSP430 has a slightly different clock system, though many of the principles are the same for each. The x2xx family uses the BCS+ system, which provides the MSP430 with three separate clocks that can run as quickly as 16 MHz in particular conditions. The reason we have three clocks instead of just one or even two is to compromise between systems that need speed and the ability to minimize power consumption, one of the real hallmarks of the MSP430. Faster clocks consume more power, so to really reduce the power used we need slower clocks. But some functions need to respond and conclude quickly, so we also need fast clocks. You can design around the use of a single clock, but having the flexibility of three is powerful. Let's look at the three clocks available in BCS+:

MCLK: This is the Master Clock, the one that drives the processor and times the commands in your program. This is typically a high frequency clock, but can be configured for low frequencies if needed.
SMCLK: The Sub-Main Clock is a secondary clock that is often used by other peripherals. It can be the same frequency as MCLK or different, depending on the application.
ACLK: The Auxilliary Clock is usually timed outside the MSP430 and is typically used for peripherals. Often, this is a low frequency clock, but can also be used at high frequencies when desired.

The 4 Sources
There are also up to four sources available in BCS+ to drive each of the three clocks:

LFXT1CLK: The name of this source implies its use with a low-frequency crystal, and this is often the case. A 32,768 Hz crystal can be connected to your MSP430 for low-power, high-accuracy timing. In some x2xx devices, this source also has a high frequency mode that can use crystals from 400 kHz to 16 MHz, assuming the chip is powered with a large enough voltage to handle the frequency. In addition, other resonators and external signals can be used for this source.
XT2CLK: Again, this source is named for its implied use with a second crystal, but in this case only a high frequency crystal. It can also use other resonators and external signals. This source is not available on every x2xx device. (See page 5-2 of the x2xx Family User's Guide to see which devices use XT2.)
DCOCLK: The internal source is the digitally controlled oscillator. Though not as accurate and stable as crystal sources, the DCO is still quite good and can be configured to operate at a wide range of frequencies.
VLOCLK: The MSP430 includes a second internal oscillator for very-low power, very-low frequency applications. The VLO can run slower than the LFXT1 watch crystal, and typically is used at about 12 kHz. This source is not available in all x2xx devices. (Refer to 5-2 in the User's Guide.)

Each clock can also divide the frequency by which it's sourced by a factor of 2, 4, or 8. In addition, many peripherals can further divide their clock by the same factors, giving a large number of possible frequencies available from just one source. While MCLK and SMCLK can use any of the four sources, ACLK uses only LFXT1 or VLO. The default configuration for MCLK and SMCLK is to use the DCO at about 1.1 MHz, and for ACLK is to use LFXT1. In the coming parts for Tutorial 08, we'll look at each source and how to configure them properly. Because it's in every MSP430 device, we'll start with the DCO before taking a look at using crystals.

So the BCS+ provides us three separate clocks with 32 possible ways of sourcing them. The clocks can be divided for operation of different peripherals individually. These varied combinations provide for nearly any conditions needed for an MSP430 project. We should not neglect, however, to note that TI has gone to great effort to make the clock system very reliable; even the VLO and DCO are very well made, accurate, and stable. For precision timing, nothing can surpass well-designed crystal control, but the internal clocks do a great job, and can even change configuration in the middle of a program. Such power available without much sacrifice for quality is one of the real benefits of the MSP430 design.

Look forward to the next post, where we'll examine how we configure the DCO for different operating modes in the MSP430!

Disclaimer on Changing Chips

2010-07-19T23:37:00.000-04:00

Just a word of caution; the MSP430G2231 in my LaunchPad was seated pretty firmly. I've written my tutorial code for the G2211, and so following it exactly requires changing the chips out. If you're not careful about it, you can really mangle the pins on the G2231 when you try to pull it out. Get yourself an IC extractor, or pry at it carefully and evenly from underneath. If you do end up bending some of the pins, you should be able to bend them back into place if you're careful. If you break off a pin... well, consider yourself warned.

Anyone have some good tips on pulling out DIPs?

Tutorial 07: Pushing Buttons

2010-07-19T23:24:00.008-04:00

We've gotten to the point now where we can program the MSP430 and make it respond by flashing an LED or two. While being able to change pins to outputs is useful, it's the combination of input and output that make the microcontroller so powerful. The pushbutton is one of the simplest types of inputs, and will be very helpful for learning more about the peripherals.

There are all kinds of switches available on the market, and there are some differences in the ways they need to be attached to the MSP430. For now we'll look at single-pole, single-throw (SPST) types, such as the momentary push-button. The LaunchPad platform includes two of these types of buttons; one is connected to P1.3 (that's the button on the lower left of the board) and the other to the RST/SBWTDIO pin (pin 16 on the DIP).

Connecting Buttons
If you are following the tutorial using the LaunchPad, then open up a copy of the LaunchPad User's Guide and turn to page 15 to see a circuit schematic of the target section of the board. You can see here that the two buttons are connected between their respective pins and ground. Note also that the same pins have 47 kΩ resistors connecting them to Vcc. To use pushbuttons in digital logic, they need to be able to provide a 1 in one state and a 0 in the other. When the button is up, the resistor ties the pins to Vcc, pulling up the voltage to whatever level the board is powered at (in the case of the LaunchPad, it's 3.6V). When you press the button, it closes the short to ground. So unpressed is logic 1, and depressed is logic 0.

You can use the opposite convention as well, reversing the positions of the button and the resistor. For obvious reasons, we call the first configuration a "pull-up resistor" and the second a "pull-down resistor". Without these resistors, the input pin would be floating, and could take on any value between ground and Vcc, which gives inconsistent behavior for your design. Whichever case makes more sense for your design, always remember to use the resistors to pull the open state up or down. A larger resistor (such as the 47 kΩ used on the LaunchPad) keeps the current draw from the button low. Ideally we only want to change the potential on the input pin and not use any power to do so.

You might recall that there are internal resistors on each of the GPIO pins for the MSP430 that can act as pull-up and pull-down resistors. The resistance value quoted for these in the MSP430 datasheets is large enough that the current draw would not be too high, but as readers have pointed out it may not be the best practice to use these for your push-buttons, especially while prototyping and testing.

Example
With the resistors in place, using buttons in an MSP430 design is quite simple. Let's illustrate them by writing a program that flashes the red LED on P1.0 a few times, then flashes the green LED on P1.6 a few times after the button is pressed. Pressing the button again should return to the red LED, and so on. For this program, we'll need to configure the two LED pins as outputs and be sure the button pin (P1.3) is configured as an input. We'll use the technique from the Blinky program to take care of the LED delay again, so we'll need a counter as well. A second counter will keep track of the number of times the LED flashes.

The new thing needed is an ability to tell the MSP430 to check the state of the button periodically; we call this polling. When the program reaches the point where it is waiting for the user to push the button, it should check and recheck the button until it sees that it has been pressed. We can do this by using a logic operation to check the value on P1IN. Since the button is attached to P1.3, bit 3 of P1IN tells us if the button is pressed (logic 0) or unpressed (logic 1). The other bits of P1IN could, in principle, be anything, so how can we extract just the value of bit 3? A simple way is to use the & operator-- since x & 0 = 0 and x & 1 = x, then P1IN & BIT3 (0b00001000) will return 0b0000x000, where x is the current value of bit 3 in P1IN. Note that the result is not either 0 or 1, but rather 0 or 0b00001000, which is also the value BIT3. Since 0 corresponds to the pressed state, we can poll P1IN in a loop that continues while (P1IN & BIT3) == BIT3, or equivalently while (P1IN & BIT3) != 0.

I've written my own version of a program that uses this in pushy_G2211.c. Try coding the program up yourself first, and then compare it to mine. A couple of new techniques used in the code are the #define command in the header, and encapsulation of a re-used command in a function call. If you're not familiar with either of these techniques, brush up on them in your favorite, reliable book on C programming. Essentially, #define lets me rename the value BIT0 to something more descriptive-- in this case, red_LED. Since this doesn't change the value of BIT0, it can still be used in the code, or you can even define two things to be BIT0, as you would if you had LEDs on P1.0 and P2.0 of a larger MSP430 device. The delay() function also makes the code more readable, and illustrates the power of encapsulation. Since a delay function is so common, I could put this into a library, and then recall it whenever I want without having to retype the same thing over and over. I encourage you to use these and any other good coding practices as much as possible to help make your code easier to understand and reuse!

This code isn't perfect, as it can't account for all situations. What happens if you press the button while an LED is flashing? Since the input value only matters during the while loop, nothing. If you have ninja reflexes and push the button in a way where the MSP430 polls it before and after the pressing, then it never sees the button press. And what happens if you just hold the button down? The solution here is to use interrupts, which is a topic beyond this tutorial. But for now, you have a rudimentary way to use buttons.

Reader Exercise 1: Copy the code into a new CCS project and try loading Pushy into your G2211. Step through the code with the debugger to be sure it works. (Change the limit on count to save clicks. Change the limit on flash too, if you're not feeling particularly patient.) Note that to get the debugger to work with the button you need to be holding it down as you step into the next line. Try watching the P1IN register as you step through to see the input value change.

Reader Exercise 2: We didn't discuss the RST button on the LaunchPad; try letting the red LED blink, then push this button instead of the button on P1.3. (You'll have to terminate the debugger to get this to work.) What does it do? While the LaunchPad is configured in a way where this is the only function this button can have, it's a very useful tool to have, especially if you ever need to restart you program!

Question for Readers

2010-07-19T12:27:00.004-04:00

I just received my two LaunchPads this morning; I'm excited they're finally here! One of the things I mentioned in an early post was that, with my PW28 target board, I put female headers in for the breakout section. These are my reasons for having used that convention:

A socket can connect to a plain solid wire for quick connections to breadboards, etc.
In rockets, the rule of thumb is if something is disconnected, the side that remains powered should not be an exposed pin to prevent an accidental short when wires are jostled around.
Looks cleaner than the bare pins; no concern of something outside the circuit (eg. a meter) brushing up against a pair of pins and accidentally shorting them.

It seems many others use the opposite convention, such as in the Arduino case. (Reader Plazma points out that other photos of the Arduino show the female convention being used.) Ultimately, it would be nice to use the convention that is common to most users, making use of other people's designs, "shields", expansion boards and what not easy.

So what does everyone think? Which convention would be the better one to use, male or female headers on the LaunchPad? Why?

Comments

2010-07-17T15:05:00.002-04:00

For those who have put comments on, I apologize for not having moderated them promptly. The blog is now set so that anyone can post without signing in, and it will notify me when I need to moderate them. I'd like to moderate them just so I'm aware when someone says something-- I trust everyone, but I don't trust myself to go back and look. This way I get to learn from y'all!

Also, while I've posted up the initial tutorials, they may change and edit a bit more as I read through them again and find errors. Thanks for your patience! My LaunchPads should be arriving on Monday, so look forward to a little more then!

Tutorial 06: Getting the Bugs Out

2010-07-17T13:34:00.009-04:00

The debugging features of the MSP430 are one of the most helpful tools you'll have in developing your projects. Let's take a look at how to use some of the basic features here. Load up your Blinky program and start the debugger, but this time don't push the 'Run' button, just leave it in a hold state. Your screen should look something like the image here. Note a few things to start. There are six windows opened here by default. The one on the far right, the 'Cheat Sheets', gives tips and help if you need it. You can also just close this window. (If you really get annoyed with it, just choose Disable All Cheatsheets on that window.)

The five remaining windows are Debug, Variables (labeled Local in this screenshot), the code, Dissasembly, and a Console. The console, again, shows results and errors that come from compiling, loading, and in some cases the code itself. The code window should be self-explaning, but note that the void main(void) { line is highlighted and has an arrow next to it. This shows where in the code the debugger is sitting. When you first load code into the flash memory of the chip, it turns on and holds everything right at the start. The variables window shows current values of code variables and (we'll see in a little while) of registers in the MSP430. The Debug window shows where we are in the hierarchy of the project itself. (Ours is simple, only one source file, so this window isn't as helpful right now.)

Note the collection of icons in the Debug window. You can see the 'Run' button there. The other important ones for this tutorial follow the 'Run' button. There's 'Halt' (looks like a pause button, should be grayed out when the debugger holds, lights up while 'Run' grays out when the chip is running), then 'Terminate All'. These control the debugger, like a play, pause, and start button. Next come a series of arrows, the first of which is 'Step Into'. We'll use that button today. A little farther, there's an icon that looks like a chip with two cycling arrows. This button resets the CPU in the MSP430 and sends the debugger back to the beginning.

Example
Before we start debugging our code, let's change the number of loops in our delay to 6. You'll see why in a bit. Scroll through the code in the code window until you find the right line, and change the count to end at 6 rather than 60000. Up at the top of the CCS window, you'll see icons similar to what we had in the compiler environment. Next to the 'Build Active Project' icon, there's a 'Rebuild Active Project' icon. After you make simple changes in the code here, click that button to recompile and reload the updated code to the MSP430. (If you need to make significant changes to the code, it's easier to terminate the debugger and work in the compiler environment.) Go ahead and tell CCS to reload the code into your MSP430, and the debugger will start over again.

Now we'll use the 'Step Into' button of the debugger to step through the code line by line. One click of the button, and you should see the arrow move down two lines, to WDTCTL. You may have noticed that the count variable already appeared in the Local Variables window; CCS loads that information automatically before debugging. The value of count is probably just some random value that we won't be using. We'll get back to that window soon.

Before we 'Step Into' the WDTCTL line, let's open up another useful window. Go to View → Registers, and you'll see another variable window pop up with all the registers in your device. (This feature is so useful for learning from! We'll make extensive use of this as we learn about the MSP430 peripherals, so remember how to do this part.) To the bottom of the list, you'll find Watchdog_Timer. Open up this section, and you'll find the WDTCTL register. The debugger is showing that the register currently has the hex value 0x6900. Opening the WDTCTL register shows the individual bits. Note that all of them are set to 0 when you power up the MSP430. This setting uses the watchdog timer normally, and running like this would reset the CPU periodically. Now step into the next line of our code and see what happens.

Stepping into the next line, you see the WDTHOLD turns to 1 (and turns red, signifying something changed in this clock cycle) and the value of WDTCTL is now 0x6980. You may recall that setting the WDT requires a password of 0x5a. When you read the password byte of WDTCTL, however, it returns 0x69.

(Want to force a reset in your code? Try writing WDTCTL = WDTCTL. Reading WDTCTL returns a value that is not the right password and you give the incorrect key to be able to write to the register; the MSP430 resets if this happens.)

See if you can find the P1 registers and then step into the next two lines to see what happens there. The debugger should now be on the LED toggle line in the infinite loop. Before we go further, change the variable window back to the local variables. Note that count still has some random value in it. Now, stepping into the LED toggle line, we should change P1OUT to light up the LED! We are now at the for loop for the delay. Step once into this; the debugger goes right back to the same line, but note the change in the value of count in the variable window. Count increments by 1 each time you press 'Step Into'. When it reaches count==6, the debugger moves on to the next line. One more step brings you back to the LED toggle. (Glad I had you change the delay to 6 instead of 60000?) You can then step through the code to turn off the LED, delay again, then repeat as much as you wish. At any time you can hit 'Run' and set the MSP430 off on its own. If you want to show someone that your LaunchPad is working, don't forget to increase the value in the delay loop. The MSP430 is fast enough that your eye won't pick up the frequency with counting up to 6. =)

The debugger is a very useful tool, though keep in mind it won't always work for what we want it to do. The MSP430 is designed to interface with the outside world. While the debugger can pause the clock inside the MSP430, it can't pause the clock in our world. Later on we'll look at what to do when you're debugging code that relies on outside timings. But I hope you can see just how helpful the debugger can be in your project. If you know of or discover any other features of the CCS debugger that you find very helpful, send a comment and let us know!

This post concludes the initial collection of tutorials on the MSP430. You now have enough knowledge to be able to write a program, download the code into an MSP430, and create some basic projects. Good luck on your next project, and join in our growing community to let people know what you're able to do and learn with the MSP430! Come back often as I'll be posting new tutorials on the peripherals of the MSP430 soon.

Reader Exercise: Try out the code you wrote in Tutorial 04. Does it behave how you expected? Use the debugger to step through it (change any delay loops to something manageable) and be sure everything runs as it should.

Tutorial 05: Loading the Program

2010-07-17T13:02:00.001-04:00

Note: I just received word that my LaunchPad has been shipped, and so I should have it soon. I figured it'd be good to make some forward progress anyway, so I'm going to go ahead and do this post using my 28-pin TSSOP target board with the F2132, but talk in terms of the G2211 and the LaunchPad. I'll change any discrepancies as soon as I have a LaunchPad with which to program and take pictures.

This post will describe a little of what you need to use TI's Code Composer Studio. This programming environment, or Interactive Development Environment (IDE) is based on the open-source project Eclipse. Eclipse is a great editing environment, and you should find it fairly easy to use for programming your MSP430. The TI LaunchPad wiki has a link from which you can download the software; it does require registration with TI, but with your account you are also able to request free samples of other products (including MSP430's) to try out. CCS can be used free of charge, but limits you to 16 kb of code. While that may not sound like much, keep in mind the MSP430's that come with the LaunchPad have no more than 2 kb of programming space! Code used to program the MSP430 turns out to be very efficient and dense, and won't take up much space. We'll be able to see how much space our code takes up when we start using the debugger included with CCS.

Once you've installed CCS, start it up and it will ask for a workspace. The workspace is just the directory where you will keep your projects; you can always change it later if you need to with the 'Change Workspace' option in the file menu. For now, use something simple, like ~/My Documents/MSP430 LaunchPad. Once that's done, you should have a welcome screen come up, that looks like this image. You can enter the IDE itself by clicking on the cube in the upper right corner; but first, take note of the Getting Started icon. Clicking on this will bring you to a few links with lots of helpful information on how to use CCS. I would recommend looking through these before getting started, especially if you've never used an IDE before.

Assuming you've now done that, or are comfortable already with this type of interface, close the welcome screen (you can come back to it with the 'Welcome' option in the help menu) and bring up the interactive editor. There's not too much here at first, so let's go ahead and start a new project. Select File → New → CCS Project, and name your project something descriptive. I like to give the program a name, and include a suffix to specify which MSP430 the program is targeting. For blinky, I name the project something like blinky_G2211. Click Next, and make sure that the Project Type is selected as MSP430 (should be the only option if you installed the CCS version with only MSP430 support.) Click Next. There's nothing to do on the next page for now, so click Next again. On the final screen, we need to choose the device we're programming. Make sure the Output Type is selected as Executable, and then choose the MSP430G2XXX in the filter for the Device Variant. The filter allows you to select subfamilies of the MSP430 to reduce the number of devices you have to sort through to find yours. Once you've filtered the results, choose MSP430G2211 for the Device Variant. For now, the other options should be fine with their default settings. A quick word before continuing; be sure you choose the correct device variant here; different linkers are needed for different MSP430 devices, so be sure to choose the one that matches your target device.

Click next one last time, and you should see your new project come up in the left-most window. The project creates a sub-directory in your workspace that holds all the files and information needed for downloading the code into your chip. But first, we need to make some code to download. Go to File → New → Source File, and enter a name for the source file that ends with .c; something descriptive is helpful, but for larger projects with multiple source files, something like main.c is a good choice. Note that CCS will give you a warning until your filename has a .c extension on it. Go ahead and click Finish, and a new window opens up in which you can type your code. Go ahead and fill in your code for blinky, and be sure to give it some good comments to explain how it works. Make sure you have one blank line at the end. CCS defaults to issuing a warning if there is any text on the last line of the code. If someone knows how to change this behavior, let me know. Otherwise, just live with the quirk.

Note that I've changed the size of my windows. I like to have my editor show 80 columns (a standard for terminal windows) so that I can avoid overly-long lines of code if possible. Feel free to adjust the window sizes to whatever is useful to you. Ok, we have code, now we need to compile it. Technically we don't have to compile before loading it into our MSP430, but I think it's a good idea to get all compile-time bugs sorted out first. The 'Build Active Project' button to the right of the print button will compile your code for you. Alternatively, you can select Project → Build Active Project. If you didn't make any typographical errors, your code should compile without any errors. The compiler brings up two new windows at the bottom: a Console showing the compiler commands and results, and a Problems list that would show any compiler errors or warnings. The code given in the previous post should compile error-free.

Alright, now that we're confident our code should work, let's load it into the MSP430! Plug your LaunchPad into your USB port. If you've installed the drivers correctly, then click the Debug button (looks like a little beetle) or alternatively select Target → Debug Active Project. The debugger will change the windows, make sure your code has been compiled since any changes were made, then check to be sure your MSP430 is connected. If your chip isn't powered properly, it won't detect the device at all. If everything is powered and installed right, it should just load the code and give you the debugging environment windows. Note that at the bottom window, it shows you the size of the code loaded into the MSP430. Blinky (as I wrote it) shows Text: 86 bytes Data: 2 bytes. Blinky is by no means a complicated program, but as you can see the size of our programs won't be very high. the 2 kb that comes with each of your G2211 and G2231 is more than enough for what you are able to do with those chips.

If you were expecting right away to see your LED blinking away merrily, you'll be disappointed. The debugger actually holds the chip in a state just after a Power Up Reset (abbreviated PUC). In the middle window, you should see your code with the line at void main(void) { highlighted. This window shows the position in the code the chip is currently looking. We'll look at using this feature to our advantage shortly, but for now just click the green 'Run' arrow at the left side of the debug window. This turns off the debugging control of the clock, and lets the MSP430 run normally. The LED should be blinking about once a second or so. If, however, you run your program and the LED stays on, check to make sure you fixed the problem in my original code; if you declare int count; you won't ever count up to 60,000. You should be declaring unisgned int count; in your code instead.

If after all of this you see your LED blinking, then congratulations, you've just finished your first MSP430 project! Otherwise, move on to the next tutorial anyway. If you can't get your code to work, then the debugger may be able to show where the error is occurring. To leave the debugger, click the 'Terminate All' icon near the 'Run' icon.

Tutorial 04: Stuck in a Loop

2010-07-13T00:08:00.018-04:00

We now have enough to be able to write programs for the MSP430, so before we go into the peripherals that make the microcontroller useful, let's get started programming and debugging. We'll start using the MSP430G2211 that comes with the LaunchPad. If you're not using LaunchPad, it's easy to change this first program for whatever device you're using. All it needs is an LED connected to one of the GPIO (General Purpose I/O) pins. (Connect it with a resistor to prevent too much current draw out of the MSP. A couple hundred ohms should be sufficient.)

In the previous tutorial, we mentioned the useful BITx definitions in the device-specific header file. These were at one time variation specific (eg. msp430x2x01 as opposed to msp430g2001), but with the most recent version of Code Composer Studio, TI appears to be moving to device specific header files. Whenever you write software for your MSP device, be sure to include the appropriate header file. For this tutorial, if you're not using a LaunchPad or the G2211, change the header file to whatever device you're using.

So the start of any MSP430 program will have a line similar to this:
#include <msp430g2211.h>

For simple programs, this is often all that is needed before coding the main function, and that is certainly the case for the "Hello, world!" program of microcontrollers, blinky. Blinky is a simple program that toggles an LED at a given period. It's best to use timers, interrupts, and such to do this type of function, but you'll have to wait until we look at those types of peripherals and functions before we can do that. The simplest way to get the program to work is with some type of delay loop. The LaunchPad has a green LED connected to P1.0 and a red LED connected to P1.6. We'll use the green LED for now. Let's get started!

The beginning of our code looks like this:

#include <msp430g2211.h>

void main(void) {

} // main

Unfortunately, we do need one step that we can't explain completely yet before we do anything else. The MSP430 includes a special timer called the Watchdog Timer (WDT). Its function is to reset the CPU if it gets stuck (ie. the watchdog timer runs out). This timer is on by default when the chip powers up. Though we could use this timer to give us our delay, for now we don't want our program to reset on us, so we need to first turn this timer off. (We'll look at using the WDT later.)

The WDT has a 16 bit register called WDTCTL, but only the first 8 bits have any control. The upper byte is used as a security measure; to prevent your code from accidentally changing the WDT, you must provide a password. The password turns out to be 0x5a (in the upper byte, so actually 0x5a00), but the header file helps you out by defining that value as the much easier to remember WDTPW. Add this value to the 1-byte configuration value you want to assign to WDTCTL. To turn off the WDT, we can use the header-defined value WDTHOLD:
WDTCTL = WDTPW + WDTHOLD;

You'll get into the habit of starting all of your first programs with this line, but keep in mind the WDT has a lot of useful functions. We'll discuss those when we talk about the WDT in depth.

Ok, now that we've disabled the watchdog, we can continue writing the code. We want to light an LED on P1.0, so we can use the last tutorial to set that up:
P1OUT = 0;
P1DIR = BIT0;

Now we want to toggle the LED and delay for some given amount of time. I'm using a for loop, though a while or do-while loop would be just as effective. We'll need a counter for the loop, so remember to define it at the start of the code:

#include <msp430g2211.h>

void main(void) {
   unsigned int count;
   WDTCTL = WDTPW + WDTHOLD;

   P1OUT = 0;
   P1DIR = BIT0;

   P1OUT |= BIT0;
   for (count = 0; count < 60000; count++);
   P1OUT &= ~BIT0;
   for (count = 0; count < 60000; count++);
} // main

What happens when we get to the end of the code? In a computer, it would just exit. In a microcontroller, however, it would just move on to the next address to read its next "instruction". There could be just about anything in there, from random noise to leftover code from older (larger) programs. In any case, it would just continue stepping merrily through the address space until it gets to the end and then... well, I don't know what happens. It's not what is intended to happen in any case, so we need to prevent the processor from ever moving beyond the actual code. We'll do this now by putting the code into an infinite loop. That's usually a bad idea in computer code, but essential here.

#include <msp430g2211.h>

void main(void) {

unsigned int count;

   WDTCTL = WDTPW + WDTHOLD;

   P1OUT = 0;
   P1DIR = BIT0;

for (;;) {

P1OUT |= BIT0;

for (count = 0; count < 60000; count++);

P1OUT &= ~BIT0;

for (count = 0; count < 60000; count++);

}

} // main

Again, you could easily do the same thing with a while(1) loop or something similar instead.

So there's blinky. The light turns on, it waits, turns off the light, waits again, then goes back to the beginning to do it all over ad nauseum.

Note there's a cleaner way to accomplish this task:

#include <msp430g2211.h>

void main(void) {

unsigned int count; // loop counter

   WDTCTL = WDTPW + WDTHOLD; // disable watchdog

   P1OUT = 0; // initialize LED off
   P1DIR = BIT0; // P1.0 output

for (;;) {

P1OUT ^= BIT0; // toggle LED on P1.0

for (count = 0; count < 60000; count++); //delay

}

} // main

Now you only have to change one loop length to adjust the frequency of the blink. (Though if you want to play with different duty cycles, the first method works well.) I've also added some comments to the code. Programming teachers seem to always stress the importance of good commenting habits; it'll save your hairline in microcontrollers. Comments don't add to the code size at all, so be sure to document everything you do well.

Next time we'll put this into our G2211 and learn how to use CCS to load programs onto the LaunchPad.

Reader Exercise: Write a program like blinky that alternates the green and red LEDs on the LaunchPad (the red LED is on P1.6). Then modify the program so that it alternates flashing the green LED, then the red LED, with short pulses and a delay between the individual flashes.

Disclaimer: I don't have my LaunchPad yet, so I haven't technically tested this code. After doing similar programs for three or four other MSP430's, I'm confident it works, but until I can get a video posted of my LaunchPad blinking its LED with this code, I reserve the right to have made mistakes. =)

Disclaimer 2: When I first typed up this post, I declared the count variable as just int count;. In the MSP430 compiler, a 16-bit plain int cannot count up as high as 60,000; it reaches its highest value then wraps around to a negative value. Using a plain int for this code will never leave the delay loop. An unsigned int, rather, is non-negative. Using an unsigned int allows us to count up higher. Longer delays may require an unsigned long. An alternative would be to use a hex notation; 0xFFFF is the highest value an int can count to. In plain int decimal, this corresponds to 32,767. In unsigned int decimal, it's 65,535.

Tutorial 03: Flipping Bits

2010-07-12T17:15:00.010-04:00

Now that we have access to the registers, how do we actually flip the switches (change the bits)? We'll examine the ways to do this using the following example: we'll use a G2001 with an LED connected from P1.4 to ground. If P1.4 is at 0 V, nothing happens, but if P1.4 is at Vcc, the LED will turn on. Since we've connected to P1.4, we should be able to control it by fiddling with bit 4 in the P1 registers. (Keep in mind that we're not changing the 4th bit, at least not in the way we normally think of it. The 1st bit is bit 0, so bit 4 is technically the 5th bit, but who's counting?)

Before we look at setting bit values, we should take a look at the ways we can represent the values in 8-bit registers. We could always use regular decimal notation, but unfortunately it has little advantage to counter the confusion caused by having to use 8-bit numbers in a non-multiple base (the decimal base is, of course, 10).

The clearest way to represent the value is in binary notation, or base 2. The register has 8 digits, each is a 0 or 1, corresponding to the value in each bit. To make a binary 2 clear from a decimal 10, we can preface the number with the notation 0b (first character is a zero), such as 0b10.

Another common notation used is hexadecimal (base 16). This notation is convenient because each 8-bit value is represented by exactly two digits, each a value from 0-9 or a-f. The preface for hexadecimal is 0x, so the number 2 in hex is 0x02. The number 12 would be 0x0c, since the digits a-f correspond to the numbers 10-15. 16-bit numbers are represented with 4 digits, such as 0x14da. Many values in the MSP430 are 16-bit, so hexadecimal is very convenient here. (I apologize for the change in notation from the previous tutorial; in the TI documentation they use the notation 14DAh for hex values, but here we're using 0x14da instead. The 0x notation is used in the programming, and I will stick to that notation unless I'm citing from a TI document directly that uses the h notation.)

We could also use an octal notation (base 8), with the preface 0o. I've not seen this in practice, however.

We'll start using some actual code in this post, so I want to establish a convention. Anything written in the Courier font is a code snippet or example. The coloring in the code matches the color scheme I usually see when I look at a .c file in a text editor, and for now doesn't make a difference. You may have other color schemes that you see. I'll try to use the colors that are used in CCS as best I can.

Binary notation is obviously the one that makes it clear what bits we're using and what they're set to. Unfortunately, it also takes lots of characters to write them out. When we write C programs for the MSP430, we can include a header file with information and shortcuts specific to the device we're using (such as #include <msp430g2001.h>). These header files include some shortcut names for the binary values where each digit is 0 except for a specific bit; the header file allows us to use the name BIT2 to represent 0b00000100. There is a BIT0 through BIT7 included in each header file, which makes for a nice shortcut and less typing. In the discussion below, however, I'll try to keep it to the full 8 digit binary values to make it clear what is happening in the operations described. Now, on to the fiddling!

For our LED example, we'll need to first make P1.4 an output so that we can control the voltage above the LED. We do this by changing bit 4 in P1DIR to 1, for output mode.

1. Direct Assignment

If we know exactly what the binary (or hex, or even decimal) value corresponding to the configuration we need is, we can just set it directly: P1DIR = 0b00010000; would set all of the bits in P1DIR to 0 except bit 4. This method works pretty well for initializing the processor, but later in the program can be problematic when we might not know for certain what state bits we don't want to change are in. Turning off the bit is easy, just set it to the value with bit 4 set at 0: P1DIR = 0b00000000, or just as easily for this particular case, P1DIR = 0. (Using the BITx notation, we would write P1DIR = BIT4.)

2. Addition and Subtraction

If we don't know exactly the value needed for the configuration, or if we're just trying to turn on one bit, we could just add the bit's value to P1DIR (I'm using the colon character : to represent unknown digit values): 0b:::0:::: + 0b:::1:::: = 0b:::1::::, so we could turn on bit 4 by doing P1DIR += 0b00010000. *(Confused by the +=? See the footnote below!) The problem with this method is if we accidentally turn it on twice: 0b:::1:::: + 0b00010000 is going to cause a carry over into the next bits, changing I/O directions where we don't want to! This method should be used with caution. Note that the equivalent to turn the bit off would be to subtract the value, of course. (BITx notation: P1DIR += BIT4 or P1DIR -= BIT4.)

3. Logic Operators & and |

To avoid the problems with addition and subtraction, we can use logic operations. Let's say we have a bit with the value x. (x could be 0 or 1, we'll just look at this generally.) The operations and (&) and or (|) can be used to change the value of the bit to be specifically 1 or 0. Note that x & 0 = 0 no matter what value x is. Similarly, x | 1 = 1 regardless of the value of x. Also, x & 1 = x and x | 0 = x, so the value of x is unchanged. for these operations. So what would be the result of the operation P1DIR | 0b00010000? Bits 0-3 and 5-7 would be unchanged (remember, | 0 doesn't change the value) while bit 4 is set to 1. (It may have been 1 before, but is definitely 1 after the operation!) On the other hand, P1DIR &= 0b11101111 would have the effect of setting bit 4 to zero and leaving the others unchanged. Note that 0b11101111 is the not operation (~) applied to the original 0b00010000, so we could write this as P1DIR &= ~0b00010000. (In BITx notation: P1DIR |= BIT4 turns bit 4 on, and P1DIR &= ~BIT4 turns it off.)

Reader Exercise: Sometimes you'll see example code that uses the notation a + b; and sometimes a | b; to do the same thing. Convince yourself that these are equivalent in particular circumstances; when would you not want to use one or the other?

4. Toggling with ^

Ok, I said there were three choices, and there really are only three. This fourth option is similar to the third choice, but is an effective way if we just want to toggle the value, not set it to be specifically 0 or 1. The exclusive or operator (^) has this effect: x^0 = 1 if x is 1, and 0 if x is 0. x^1 = 1 if x is 0, and 0 if x is 1. So x^0 leaves the bit unchanged, and x^1 changes the value of x to its opposite. P1DIR ^= 0b00010000 flips bit 4 (to 1 if it was 0, to 0 if it was 1) just like toggling a switch. (In BITx notation: P1DIR ^= BIT4.)

Now, in our program we need to initialize the pin to be an output:

P1DIR = BIT4;
(An equivalent way to do this is to use a logic operator rather than an assignment: P1DIR |= BIT4;)

The value in P1OUT could be either 0 or 1, so if we care what state the LED starts in we should set that:

P1OUT = 0;

(A better practice is to initialize the output state before we change the pin to an output.)

Now we have an output pin set at 0, keeping the LED off. To turn it on, we give the command:

P1OUT |= BIT4;

To turn it off, we give:

P1OUT &= ~BIT4;

To toggle its state (off if on, on if off):

P1OUT ^= BIT4;

As a final example, demonstrating some power in the other assignment methods, let's put another LED on P1.6.

First, let's configure the two pins as outputs with an initial state off:

P1OUT = 0;

P1DIR = BIT4 + BIT6;

(adding the two values together is easily verified to be 0b01010000).

We can turn each one on and off individually:

P1OUT |= BIT4; // P1.4 on

P1OUT &= ~BIT4; // P1.4 off

P1OUT |= BIT6; // P1.6 on

P1OUT &= ~BIT6; // P1.6 off

Or we can turn them on and off together:

P1OUT |= BIT4 + BIT6; // both on

P1OUT &= ~(BIT4 + BIT6); // both off

And finally, toggle them simultaneously:

P1OUT ^= BIT4 + BIT6; // toggle both

Reader Exercise: Write down the necessary code to use LEDs on pins 3 and 7 of port 1, with pin 3 initially off and pin 7 initially on. Then toggle the LEDs so that 3 is on and 7 is off.

* += is a shorthand operator in C. If I say x += 1;, the command adds one to x and reassigns the result to x. In other words, it's the same as saying x = x + 1;. While algebraically that statement makes no sense, in programming it's very common. Don't think of = as meaning the two sides are equal, read it as "x is now equal to the value currently in x plus 1".

Tutorial 02: The MSP430 Township and Registers

2010-07-12T16:29:00.006-04:00

Most places I've found to learn how an MSP430 actually works inevitably start talking about architecture, addressing, buses, and varied other technical ideas. Unfortunately, they all seem to require some electrical engineering experience as well. Today we're going to attempt to explain what's needed to be able to use the MSP430 without having to understand the physical properties of bipolar junctions or anything else like that. The technical knowledge is very helpful in fine-tuning a design or in programming in assembly, but a rudimentary knowledge is sufficient to start working in C.

One of the distinguishing characteristics of the MSP430 over other microcontrollers is its von Neumann architecture; all of the memory and information available to the processor is available in one place. Other mcu's will treat different types of memory separately, which makes for some nice efficiencies, but complicates the design somewhat. A simple way to view this is to picture an mcu as a town (or in the case of the Harvard architecture, a collection of towns). For von Neumann systems like the MSP430, everybody lives together in the same town, each with their own unique address. For Harvard systems, addresses may be duplicated, and so the particular town must also be specified.

Memory

The memory space in an MSP430 includes room for the program, room to store data, memory (RAM), and other important information that we'll get to later. Today our primary interest is in a particular collection of addresses called registers. These addresses essentially are the community services in our MSP430 town; things like the post office, power company, and so forth. For the MSP430, the registers control the functions of various parts of the processor and its peripherals. You can think of them as houses with switches and circuit breakers in them. The setting of the switches determines if a particular event happens, what job a particular pin takes, how a particular peripheral behaves, and so on. The registers are grouped into three sections: the special function registers (SFR), 8-bit peripherals (parts that need only 8-bits to read instructions), and 16-bit peripherals (obviously those needing a full 16-bits to read instructions). As an example, lets look at the smallest of the MSP430's: the MSP430G2001. Open up copies of the x2xx family guide and the G2x01 datasheet.

Please note that the above links may break on occasion, if TI updates either of these documents to a new revision. The easiest way to find these is to go to TI's website, and use the "Search by Part Number" box. For a G2x01 device, search for anything that falls in that category, such as the msp430g2001. The family guide can be found on the pages for any of the x2xx family of devices.

Page 1-4 of the family guide shows a map of the x2xx family "towns". You can see that the addresses for the SFRs are anywhere from 0h to Fh (the h denotes the value is in hexadecimal; in decimal you'd see these addresses as 0 to 15). Next come the 8-bit peripherals; from 10h to FFh (16 to 255). Note there is a large gap in the addresses between the RAM and the Flash memory. The family guide shows a map for the entire x2xx family-- to see the values for our particular chip, we need to look at the datasheet.

Page 13 in the datasheet gives a table for all of the G2x01 and G2x11 device memory maps. For the G2001, we have the peripheral registers, then 128B of RAM. Addresses from 0201h to 10FEh are empty, and then we see a 256 byte portion called "information memory". (This region stores calibration values and other important numbers that needed to be held when the power is gone. Usually these won't be available to write to, but could be if necessary; but that's another post.) Finally, we have the 512B for code, including at the very top of everything the interrupt vectors (again, that's another post).

Registers

Now that we can see what the G2001 town looks like, let's turn to how to use the switch houses we discussed. The registers of the MSP430 are special sections of memory that configure the device and tell us when something important happens. Page 12 of the datasheet shows the SFRs available in the G2001. This device only lists 4 of them, in addresses 0h to 3h: Interrupt Enable 1 (IE1) and 2 (IE2), and Interrupt Flag Register 1 (IFG1) and 2 (IFG2). Each address points to 1 byte of memory, so there are 8 bits (switches/breakers/etc.) in each register. Page 12 shows which ones are usable for the G2001.

In this case, IE1 only has bits 0, 1, 4, and 5 available. Likewise, IFG1 has bits 0-4. The datasheet tells you the name of each of those bits and describes what they do. For example, bit 0 in IE1 is named WDTIE, or the Watchdog Timer Interrupt Enable. This bit is normally a 0, but if we configure the device to use the watchdog timer as an interval timer, then setting this bit to 1 allows the watchdog timer to raise a flag (IFG1 bit 0 to be precise) causing an interrupt (we'll get to that later too) under particular circumstances. Essentially, this bit tells the MSP430 if the watchdog timer can signal the processor to do something special or not when it's used in a particular mode.

Now turn to page 17 of the datasheet. This table gives the peripheral file map, or the addresses and names of the registers that affect the various peripherals in the device. Note at the bottom it lists the SFRs we just discussed. Any time you need to use a peripheral, this page will give you a starting point for knowing which switch houses you need to visit to be certain everything is configured properly. We'll look at the registers for each peripheral specifically in their own posts. Today, let's look at the registers for Port P1 and Port P2, as these are the most straight-forward.

The ports are the general input/output pins available on the device. The pinout diagram on page 3 shows that the G2001 has all 8 pins for P1 (P1.0 through P1.7), and 2 pins for P2 (P2.6 and P2.7). Each register for a port has bits that correspond to each of the pins; for example, P1.4 is controlled by bit 4 in each of the registers. Let's go through each of the registers available for a port now.

PxIN

The input register for a port is a read-only value. When a pin is selected to be an input, reading the value of the bit tells you the voltage currently on that pin. The entire byte PxIN reads the value of all of the inputs on that port at once. Keep in mind this is a digital system, so there are only two values that can be read; a 0 or a 1. These values correspond to the voltages on Vss (0) and Vcc (1), which are generaly 0 V and between 1.8 and 3.6 V respectively. There is a particular threshold built into the device such that any voltage over that value is read as a 1 and any voltage read below is read as a 0. To prevent any damage to the chip, you should certainly never try to read any voltages outside the range between Vss and Vcc directly.

PxOUT

The output register for a port is writeable. When a pin is selected to be an output, we can change the voltage on that pin by writing a 0 or a 1 to its corresponding bit in PxOUT. Like the input, a 0 corresponds to the voltage on Vss, and a 1 corresponds to the voltage on Vcc.

PxDIR

The direction register determines whether a pin is an input (bit is low, or 0) or an output (bit is high, or 1). At the beginning of your program, you should configure the port pins to their values as inputs or outputs. That's not to say you can't change a pin's behavior in the middle of your program, of course.

PxIE, PxIES, and PxIFG

These three registers are the interrupt enable, interrupt edge select, and interrupt flag registers for the ports. We'll look at these three registers together, as they work together. You can use the port pins as a way to flag special circumstances to the processor and trigger an interrupt. For now, think of an interrupt as a message to the CPU to hold on what it's currently doing and take care of the special circumstance. Once the interrupt has been satisfied, the CPU returns to where it was before. You enable this behavior by setting the PxIE bit for the pin being used to 1. PxIES bits determine if the flag is triggered by the pin going from 0 to 1 (IES bit set to 0) or from 1 to 0 (IES bit set to 1). In other words, a flag is triggered when it detects a positively sloped, rising edge or a negatively sloped, falling edge. When the interrupt is triggered, it sets the corresponding bit in PxIFG.

PxSEL

Looking back at the pinout diagram on page 3, you can see that most of the port pins have multiple functions. The selection register determines what function a pin takes on. The default function is listed first, so P1 defaults to general I/O pins, whereas the P2 pins default to connections to a crystal oscillator. Changing the bits in PxSEL changes the behavior of the pins. We'll look at the particular settings later; for now, plan on using the default values in PxSEL.

PxREN

The resistor enable register is a very useful feature for the ports. Sometimes it is helpful to pull the voltage up to Vcc or down to Vss, such as when you attach a push button to a pin. The resistor enable register lets you turn on that ability. When a PxREN bit is enabled, you can select it as a pull-up or pull-down resistor by setting the corresponding bit in PxOUT, 1 for up, 0 for down.

Now that we've identified some of the switches we have to use, in the next post we'll take a look at how to actually set them in the software we write to the device.

Quick Explanation

2010-07-10T11:42:00.000-04:00

For those viewing the blog now, the recent tutorial post may seem disjointed from the previous posts. I'm in the process of transitioning the format to something more useable and accessible. For now the blog interface won't make that as clear, but in the near future it should make more sense. There will also be a Tutorial 00 that I haven't written yet.

Tutorial 01: Getting Started

2010-07-10T11:40:00.006-04:00

Surprisingly, only a few things are needed to start working with microcontrollers. Using an MSP430 requires a target board with a chip, a programmer, a compiler, and a power source. Power can be as simple as a couple of AA batteries, or come directly from your computer. There are different options for the compiler, some free and some not, and target boards can be made by hand if necessary. Until recently, however, there were few options available for the programmer, and the better ones were fairly expensive. TI's recent release of the LaunchPad has changed all of that. Let's take a look at some of the options available for the needed pieces for MSP430 design.

Target Boards
The MSP430 can be programmed while inside its final circuit, if the proper electrical connections are available, or outside of its intended place by using a target board. These boards are built in a way that the chip can be inserted temporarily, programmed, and then removed and mounted into the circuit in which it's intended to be used. A well built target board will also make it possible to prototype, or connect to other circuits so that the chip can be used while still in its target board. TI makes nice target boards for some of the form factors used for their MSP430's, such as the MSP-TS430PW28. While a little costly, most of the expense comes in the fancy, spring-loaded, zero insertion force (ZIF) socket for holding the chips. For a little more, you can even get bundles that include a full programmer. Target boards are not too difficult to design, either; we'll look at how to do just that in a later tutorial.

A fancier type of board is the experimenter's board (also may be called a development board). This board can be similar to a target board and use a socket to make the chip placement temporary, or it can have the MSP430 soldered in place. Experimenter's boards come with other parts like LED's, buttons, and perhaps speakers, serial or ethernet ports, and a wide variety of devices or connections that interface with the outside world. TI makes a few of these, such as the MSP-EXP430F5438. Other vendors like Olimex also make this type of board, usually at a lower price tag, but sometimes with older families of the MSP430.

If you've looked at the above links and decided the price is way too high, then let's look at the new LaunchPad! This board is a target board for 14 and 20 pin DIP components that also includes a programmer (see below) built into it. The best part of this option is that it comes at a price tag of a whopping $4.30! Though a new product, an online community has already started to develop around this development platform, and this option may be the easiest way to get started using the MSP430, especially for those with no experience in microcontrollers. The tutorial articles will use the LaunchPad to teach the basic uses and concepts of MSP430's.

Programmers
The MSP430 programmer is officially referred to as a Flash Emulation Tool (FET). These tools serve a dual purpose; they write programs to the MSP430, and they also can control the chip manually to allow for debugging of the program (see the discussion on debugging in the compiler section).

TI has two types of programming connections. You can use a 4-wire JTAG connection, which needs four pins of the MSP430 to write the program to the chip's memory, or you can use a 2-wire (Spy-bi-wire, or SBW) connection, which obviously needs only two pins to write the program. The 4-wire JTAG can be used to program any of the MSP430's, but the SBW only works with some of them. While you might think the SBW interface only works on some of the smaller, lower end chips, it's not the case; in fact it seems TI is including SBW capability in all of its new designs, including some of the new and powerful MSP430x5xx family. (A list of compatible parts can be found in slau157n. Look for Table 2-1.) The real trade-off for using SBW is the programming speed; SBW runs about ten times slower than JTAG. However, MSP430 programs tend to be quite small, often less than 2 kb in size. Unless you're really impatient, programming and debugging speed shouldn't be much of an issue, unless you're working in time critical environments.

The standard TI FET comes in a USB interface, though an older serial-port interface is also available. This FET can program by either JTAG or SBW through a 14 pin (2x7) header pin connector. Other companies have made their own equivalents to the TI programmer, often at a lower price.

If you are satisfied with SBW programming, there are some cheaper options available. The TI eZ430 system has an FET interface in a USB stick form factor (picture here). Unfortunately, the pins are very close to the computer, so your board must also be close, or you'll need to make your own cable to connect your board to the stick. (Remember that SBW is a 2-wire interface; you might notice the connection to the USB portion has 4 pins. The MSP430 also needs power, and most FET's can provide power directly. Two more pins are needed for Vcc and ground. The minimum needed for JTAG would be 6 pins.)

The LaunchPad comes with its own SBW FET built in. The emulation portion of the board can also be used to program MSP430's externally. A set of 6 pins are available for this, giving power, the SBW interface, and two extra pins for communicating through the USB controller on the board.

Compilers
Two professional compilers for the MSP430 also make free versions available; IAR Systems and Code Composer Studio. The free versions limit the code size you can create (4 kb for IAR, 16 kb for CCS), but many of the MSP430 variations have less memory than this anyway. For larger programs, you can either purchase the full compilers, or use the mspgcc open source compiler. Information on using mspgcc will be given at some point on this blog, but for the purposes of the tutorial we'll use TI's Code Composer Studio. Those who prefer IAR's compiler should be able to do so without much difficulty from the tutorial here.

One of the most important tools for a development environment is a debugging interface. IAR and CCS both come with one built in to the IDE, but mspgcc users will need mspdbg to do debugging. The debugging feature allows you to step through the code and see how it changes the settings and configurations of the MSP430 step by step, helping you to verify that the system is working the way it should and to view the contents of the registers and variables in memory. Early on in the tutorial posts we'll look at using the debugger effectively.

Power
The LaunchPad is powered through the USB interface, and whenever an FET is used this option is available. If you want to implement your design in a stand-alone system, however, you'll need to provide power to the circuit in some way.

The MSP430 is an ultra-low power device, and performs very well using standard consumer batteries. The MSP430 will run with anywhere between 1.8 V and 3.6 V, though at least 2.2 V is needed to do any programming to the chip. Keep in mind that the speed at which the chip is able to run also depends on the voltage; though it's capable of running up to 16 MHz, at 1.8 V an MSP430F2001 cannot run any faster than 6 MHz. This image is an excerpt from the MSP430F2001 datasheet, showing how the supply voltage affects the operating frequency.

Check the datasheet for your particular MSP430 device for a similar plot to see what frequencies are available at the voltage you choose to power your design.

Aside from consumer batteries, you can also power your design from the wall if you use a transformer and voltage regulator. Later on we'll look at the ideas to consider in using a voltage regulator. You may be interested in looking into using a solar cell to power your design, or other creative ways to get power.

Following the Tutorial

This tutorial will use the TI LaunchPad with its SBW emulator to explain how many of the features of the MSP430 work and how to use them effectively. Examples will be done using CCS v4 as the development environment. If you have these two pieces (for a total price of $4.30!), you'll have enough to get started. If you happen to have another emulation tool or target/experimenter's board, feel free to use what you already have; everything done in the tutorial is easy to modify to whatever MSP430 platform you're using. When we move on to interfacing outside of the LaunchPad system, we'll provide some good ideas on how to do that cheaply and cleanly. Once you have the basics down, you should be able to design any system in which you can put in and program an MSP430.

Crystal Timers

2010-06-08T13:26:00.008-04:00

The MSP430 has great internal clocks, but for time-critical applications we need something more stable. Crystals are one of the best oscillators available, and are quite stable if they are handled correctly. While it would make more sense to look at timers starting with the internal clocks, I have an immediate need to work toward USB communication, which requires the use of crystals for timing.

MSP430's can have up to two crystals to set clocks externally. XT1 is typically a low frequency (< 1 MHz), which is why it is usually referred to as LFXT1 (low frequency crystal 1). All of TI's MCU's have pins that can be used with one of these low frequency crystals. The chips can also be configured to use a high frequency crystal if needed. Many MCU's also have an XT2 built specifically for HF oscillators. The exact frequency chosen depends on the application, but a commonly used frequency is 32,768 Hz, often referred to as 32 kHz even though it is not a decimal kHz. It is, however, a binary kHz, which is why it is a convenient frequency for timing applications. In exactly 1 second, the crystal will go through 2**15 oscillations. When 15 bits roll over, the timer is reset to zero, and every reset happens at exactly 1 s intervals.

Connecting a crystal to an MSP430 is a little tricky. Fortunately, TI has provided some excellent documentation to help. Essentially, the crystal should be close to the chip and isolated from other signals in the circuit. Crystals have particular capacitances that need to be matched correctly in order to be accurate. The newer MSP430's (anything but the x1xx series, really) are able to set capacitors to a few values internally. The target board I received included a 32 kHz crystal with 12.5 pF capacitance. 12.5 pF is one of the values that can be set internally, so the crystal can be put on the board without needing external capacitors. It does require, however, setting the MCU software initially to have the right capacitance internally. This is done by setting the appropriate value to the XCAPx bits in BCSCTL3 (Basic Clock System Control 3). The header files include the values XCAP_x to help set the proper bits correctly. For my 12.5 pF crystal, XCAP_3 is the correct selection. Note in the code below rather than setting BCSCTL3 = XCAP_3, |= is used to only change the XCAPx bits in the register.

In the errata for the MSP430F2132, it mentions that the MCU sometimes has issues with crystals with an equivalent series resistance (ESR) less than 40 kΩ. The crystals I purchased have 30 kΩ ESR, but seem to work fine. I don't know if my fumbling soldering technique increased the resistance sufficiently or if it just appears to work and isn't perfectly accurate, but it seems close enough for now. Future workarounds are to pick a crystal with a higher ESR or to add a resistor into the circuit as explained in TI's application note about this particular erratum.

Once the crystal is in place, it should be checked to be certain it is oscillating. This post's program won't be able to prove accuracy of the crystal, but it at least shows that the crystal oscillates and can be used. The crystal's frequency is accessed with the auxiliary clock ACLK.

/* 32kcrystalF2132: quick program to test the functionality of a watch crystal

* soldered to the target board. Flashes an LED on P1.0 at 2 Hz.

#include <msp430f2132.h>

#define LED BIT0

void main(void) {

int i; // internal counter

WDTCTL = WDTPW + WDTHOLD; // turn WDT off

P1OUT = 0x00;

P1DIR = LED;

BCSCTL3 |= XCAP_3; // xtal has 12.5 pF caps

TACCR0 = 16383; // f_xtal / 2 - 1 gives 2 Hz

TACTL = TASSEL_1 + MC_1 + TACLR; // ACLK + Up Mode + Clear timer

for (;;) {

while ((TACTL & BIT0) == 0) { // wait for timer to reach TACCR0

}

TACTL &= ~BIT0; // reset TAIFG

P1OUT |= LED; // LED on

for (i=0; i<0x314; i++) { // short delay

}

P1OUT &= ~LED; // LED off

}

} // main

The comments in the code should help explain how the program works, but it's worth taking some time to explain some of the features of Timer A.

Any of the timers in an MSP430 can be configured to run off of any of the clocks (MCLK, SMCLK, ACLK) by setting the TASSELx bits in TACTL. TASSEL_1 in the header file configures the timer to run off the auxiliary clock connected to the crystal.
The MCx bits set the mode of the timer. These are initialized to 0 when the MCU is powered, keeping the timers turned off and conserving power. MC_1 in the header file configures the timer in "Up Mode", which counts upward until it reaches a value set in TACCR0. MC_2 sets the timer in "Continuous" mode, which counts upward until the counter rolls over (from 0x0000 to 0xFFFF). This code could use continuous mode, but would then only be able to flash the LED at exactly 1 Hz. Using up mode allows you to set the flash to exact values at frequencies higher than 1 Hz and up to 32 kHz.
The TACLR bit clears the timer so that it starts at 0 from wherever the bit is set. This is useful because the timer continues to run even when the code is not using it or looking at it. If an exact time is needed, the timer should be cleared to be certain it counts the right number of times before reaching TACCR0.
The TAIFG bit (this is bit 0 in TACTL) is set when the timer rolls over, either at the top in continuous mode or at TACCR0 in up mode. The code watches this bit to know when to flash the LED. Note that the flag must be reset manually. The timer continues to run while the code is turning on the LED, waiting briefly (0x314 is just a random value I picked for a short flash), and turning off the LED, so when the loop starts again, the timer has already been running. This feature is very useful for exact timing applications, because we don't need to be concerned about accounting for the processing time between loops. As long as the program takes less time to run than intervals between TAIFG being set, the program will execute at exactly the time we require.

One final note about the value set to TACCR0--Since the timer starts at 0, and 0xFFFF coresponds to 65,535, the timer can only trigger at integer values between these two. For this crystal, 32,768 counts would correspond to 1 s, so by setting TACCR0 to 32767 we would trigger every second. The correct way to get the exact timing is to count to f/n - 1 (using whole fractions of the oscillation frequency, i.e. 1/2 s., 1/3 s., 1/4 s., etc as the period between flashes), so 1/3 s would be TACCR0 = (1/3) / 32,768 - 1 = 10,922. As long as this value is less than 65,536, nothing other than setting this register needs to be done.

Configuring Inputs & Outputs

2010-06-07T16:45:00.000-04:00

The MSP430 becomes especially useful in the laboratory environment when it is used to collect information and send information in conjunction with equipment and measuring instruments. To do this, the chip needs an electrical connection with the transducers, or motors, or whatever other devices are being used. These connections are made through input and output ports.

All MSP430 microcontrollers have general input/output ports. The larger chips, of course, have more ports available, but even the smallest chips have pins for input and output. One of the nice features of these microcontrollers is that the pins can be used as an input or as an output; each port is normally associated with up to 8 pins, and each can individually be an input or an output, and can even change function in the middle of a program. The MSP430F2132 has 3 ports (24 pins) available that can be configured for general I/O.

Keep in mind that,while for low power systems the MSP430 is able to drive devices directly (assuming they run well at 3.3V), many devices will need to be controlled/sampled with transistors and amplifiers, or other intermediate components, to prevent damaging the MSP430 with high voltages or currents.
Part of the memory space in the MSP430 is set aside as specific registers, which are used to store information on how the chip should behave. The behavior of each pin on a port is controlled with the register P#DIR, where the # corresponds to the particular port being used. P#DIR is a 1 byte value with each bit corresponding to one pin for the port. For example, the 3rd bit on P1DIR controls P1.3. (Remember that the bits are numbered 0-7, not 1-8, so the 3rd bit is actually the 4th least significant digit.) When a bit in P#DIR is set to 0, the pin is configured as an input. When it is set to 1, the pin works as an output. As an example, if P3DIR = 0b01100101, then P3.0, P3.2, P3.5, and P3.6 are set to be outputs, while P3.1, P3.3, P3.4, and P3.7 are set to be inputs.

Setting the value on an output is done through the P#OUT register. This register is again a 1 byte value, each bit corresponding to each pin on a port. In the previous post, the LED connected to P1.0 was turned on and off by writing a value to the 0th bit of P1OUT. P1OUT = 0x01 (which corresponds to 0b00000001) turns on the LED by applying Vcc to the pin. P1OUT = 0x00 turns off the LED by grounding the pin. If we had set P1OUT = 0x03 (0b00000011), the LED would have turned on since bit 0 is set to be high. What about P1.1, since the second bit is high? In this case, since P1DIR was configured to have P1.1 an input, no voltage is applied to the pin, but the number is rather stored in a buffer. If we reconfigure P1.1 to be an output after setting P1OUT as above, then it starts with Vcc applied to the pin when switched. It is a good idea to always set P#OUT to the desired initial values before setting P#DIR to be certain the buffer values match what we want the pin behavior to be when the device is turned on. (It wouldn't be so good to turn on the controller and immediately start moving a motor before setting the output to keep the motor from turning.)

Reading inputs is done with the P#IN register. The values in this register correspond to the current voltage level on each pin in the port. Thus, for pins configured as outputs, the bits in P#IN and P#OUT are the same. When an MSP430 of any kind restarts, it defaults to setting the port pins as inputs. (There are exceptions for some pins, such as those intended to connect to a crystal oscillator. See your chips datasheet for details.)

The following program makes use of I/O ideas to turn the LED on P1.0 on and off by using a push-button switch on P3.3. The push button used is connected with a resistor to ground so that when unpressed the output doesn't float, but is tied to ground. When pressed, the output is connected to Vcc. This connection also causes a small current to flow through this "pull-down" resistor. A push button can also reverse this behavior by having the output tied with a "pull-up" resistor to Vcc and grounding the output when pressed. The output of the button can be connected to an input on the MSP430 in either case. For the pull-down setup, the input reads 0 when unpressed and 1 when pressed. I've done this with an external circuit, connecting my push buttons to Vcc and ground with external resistors enclosed in a small box. In the video below, the red button is tied to a pull-up resistor, and the black button to a pull-down resistor. (The black is used in the program below.) The MSP430 actually is built with resistors inside the chip, and each input pin can be set with pull-up or pull-down resistors individually without external pieces. We'll examine how to do that in another post soon.

A quick comment on some parts of the program: the header files include definitions for each individual bit. BIT0 is defined as 0b00000001, BIT1 as 0b00000010, and so on. I've used two definitions to make the program even more clear. I use LED to refer to bit 0 and BTN to refer to bit 3, since those are the bits used in the circuit design for the led and the button. The program also makes a function call. The purpose of the short delay function is to deal with switch bounce. Most mechanical switches will flip on and off a few times when pressed or released. To make certain the led doesn't rapidly turn on and off with the bouncing, a delay is used. The program constantly checks the current state of the button. Each check delays for a brief moment so that any bouncing occurs while the program is in the delay loop.

The method used for switching the output values is also very useful. Any bit and 0 returns 0, while any bit and 1 returns the original bit. ~LED gives the value 0b11111110, in this case, so bits 1-7 remain unchanged while bit 0 is set to 0 when you set P1OUT to P1OUT & ~LED. Any bit or 0 returns the original bit, while any bit or 1 returns 1. Setting P1OUT to P1OUT | LED has the opposite effect of setting bit 0 to 1.

/* buttonF2132: I/O configuration test that lights an LED when a push button is
* pressed. The LED is connected to P1.0, active high. BTN is connected to
* P3.3, active high (ie. when pushed gives a positive voltage, normally gnd.)
*
* Also demonstrates bit manipulation and function calling. The delay function
* accommodates switch bouncing.
*/

#include <msp430f2132.h>

#define LED BIT0 // P1.0
#define BTN BIT3 // P3.3

void delay(void);

void main(void) {

WDTCTL = WDTPW + WDTHOLD;
P1OUT &= ~LED; // initialize output by ensuring bit 0 is 0.
P1DIR = LED; // set bit 0 to output
P3DIR = 0x00; // unnecessary, but explicitly states P3 is all inputs.

for (;;) {

if ((P3IN & BTN) == 8) {
P1OUT |= LED; // set bit 0 to 1, turn on LED
delay(); // delay to prevent switch bounce
}
else {
P1OUT &= ~LED; // set bit 0 to 0, turn off LED
delay();
}
} // infinite loop
} // main

void delay(void) {
int i;
for (i=0; i<0xFF; i++) {
}
} // delay

Reader Exercise: Write a program that controls two LEDs as in the previous exercise. Use two other pins in port 1 as inputs for two buttons, one with a pull-up resistor and one with a pull-down resistor. Have each button control one of the two LEDs. Set one LED to be off unless its button is pressed, and set the other LED to be on unless its button is pressed.

Writing a first program

2010-05-17T22:35:00.022-04:00

The typical "Hello, World!" of microcontrollers is a blinking LED. The F2132 target board has an LED connected to one of the pins on port 1 (P1.0, pin 21) by a jumper. Here's what a typical C program for this looks like:

/* blinkyF2132: test program toggling an LED connected to P1.0 on the
* MSP430F2132.
*/

#include <msp430x21x2.h>

void main(void) {

int i;

WDTCTL = WDTPW + WDTHOLD;
P1DIR = 0x01;
P1OUT = 0x00;

for (;;) {
P1OUT ^= 0x01;

for (i=0; i<0xFFFF; i++) {
} // delay
} // infinite loop

} // main

The first thing to note is the included header file; all msp430 compilers come with a collection of these files that define specific tools and behavior for the various families of the controllers. In this case, since I am using an F2132, I use the x21x2 family header. (Edit: looking at the header file included in CCS4, this format for the header file is considered legacy. The preferred usage would be specific to the chip itself, so in this case you would include the msp430f2132.h header file.)
WDTCTL, P1DIR, P1OUT and the like are all convenient keywords defined in the header file.

WDTCTL points to the word (2 bytes) controlling the watchdog timer. This timer resets the chip after a certain amount of time has passed. To keep our program running, it needs to be disabled. The 8 least significant bits (0 through 7) of WDTCTL control the behavior of the watchdog timer. Bit 7 specifically puts the timer on hold if set to 1. In the header file, WDTHOLD is defined to be a 2 byte value with only the 7th bit set to 1 (ie. 0b0000000010000000, or in hex, 0x0080). By writing WDTHOLD to WDTCTL, we turn off the timer.
WDTCTL only uses 1 byte for its control; the 8 most significant bits are set up as a key to prevent a program from inadvertently changing the configuration. Hence, to write to WDTCTL you need to include a password of sorts. This password is the value 0x5a, and the header defines WDTPW to be 0x5a00. By adding this value to WDTHOLD you end up writing the value 0x5a80 to WDTCTL--which satisfies the necessary key and sets the hold bit to 1. (Note that you could also use WDTPW | WDTHOLD instead of adding them. They have the same effect in this case, but the TI examples use +, so I chose to use that convention.)
Each port can configure each of its 8 pins to be inputs or outputs individually. On the target board, the LED is on P1.0, so P1DIR is set to have bit 0 to be the value 1 (output) and each of the other bits 0 (input). Writing 0x01 (0b00000001) to P1DIR configures it this way.
P1OUT controls the digital values on the output pins of P1. In this program, 0x00 sets the outputs all to zero, and 0x01 sets all but pin 0 to zero with pin 0 at 1. The LED is connected with its cathode at ground, so a high value on P1.0 turns on the LED. Thus 0x00 is off, 0x01 is on.

After setting up the configuration of the MCU, the program then enters the infinite loop: for (;;) { }. This step may seem odd at first, but since we want our controller to keep working, we can't have a program that terminates. Practically, without the loop the MCU would then continue trying to execute statements in the next memory spaces, eventually reading well beyond the actual program to unpredictable results.
Inside the infinite loop, the program changes the value on P1.0. The ^, which is the C symbol for the exclusive or operation, turns the LED on if it is off, and off if it is on. Another for loop causes a delay between toggles on the LED. The length of the delay depends on how far the iterator i has to count. (It also depends on the frequency at which the MCU is operating; a faster clock speed makes the iteration count faster.)

This program is very simple, and not really useful for much other than to reassure you that everything works right and that you can actually program the msp430. Below is a short video of my target board running the program. There are certainly more elegant ways to do this trivial task, but this method is a good way to start and doesn't require much understanding of the MCU itself.

Reader Exercise: Write a similar MSP430 program using the MSP430F2001 to alternate blinking LEDs on ports P1.2 and P1.7 (ie. LED 1 is on, LED 2 is off. After some time, they switch to LED 1 off, LED 2 on. The F2001 is a 14 pin MSP430 that comes in PDIP, TSSOP, and QFN packages. P1.2 is pin 4, P1.7 is pin 9.)

Software

2010-05-17T21:59:00.000-04:00

A few options exist for programming the MSP430. A number of professional compilers are available, but for easy home and hobby use there are also free versions.

IAR Embedded Workbench Kickstart (Referred to as EW430 in MSP430 Microcontroller Basics by John H. Davies)

The free version is limited to 4 kb code size
Works in Windows (32 and 64 bit versions)

Code Composer Studio v.4 (CCS4)

Free version is limited to 16 kb code size
Works in Windows (32 and 64 bit versions)

MSPGCC

Unlimited code size, as it's open source software
Works in Linux or Windows under Cygwin (32 bit)

I'll be working with CCS4, at least to start. On a Mac system, the MSP430 is programmable by using any of the windows software through a virtual windows installation using VMWare Fusion. Unfortunately, VMWare requires a license, and the free, open source VirtualBox does not work with the USB FET. MSPGCC has been ported to Mac, though.

While I would prefer working in a linux environment, it seems mspgcc is difficult to use because of the state of msp430-gdbproxy, the software that communicates through the FET. It does not yet support some of the newer families of MCUs, and takes a good deal of effort to get working properly. It also does not seem to support 64 bit systems yet.

For now, CCS4 works quite well and so will be the IDE I use. Very little of what will be documented here depends specifically on the environment, however, and so the choice is pretty arbitrary. The 16 kb limit might sound small, but typical MCU programming is actually quite dense, and so a lot of projects can easily fit into that limit.