ECE 2036 First Mbed C/C++ Assignment
Due Date: Wednesday, February 13
Introduction to
Embedded Devices and a Thermostat Example Product
Embedded devices account for 98% of the world’s microprocessors. For every desktop computer, there are over 100 embedded devices. A high-end car can contain up to 100 microprocessors. Embedded devices contain a computer with software that is typically not changed by the user (called Firmware). Most users are not aware that their cellphones, cameras, audio players, and TVs contain a computer with firmware. C/C++ is currently the most widely used language for embedded devices. ARM processors similar to the one found in the mbed module are used in about 80% of embedded devices including most cellphones.
Real-Time Systems
Many embedded devices are also real time systems. A real-time system needs to read in data from external sensors, perform computations based on new sensor data, and update the control outputs within a fixed period of time.
A Real-Time System reads in sensor data, processes the data, and
updates control outputs
Examples in cars include airbags, antilock brakes, and engine controls. Autopilots in airplanes and spacecraft are another example. In many of these systems, responding too slowly will cause system failure. Most real-time systems need a response time on the order of milliseconds or even microseconds.
The new Nest Thermostat
Programmable home heating and cooling thermostats are also embedded devices. Thermostats could perhaps also be considered a real-time system, but with a response in the minutes range that is several orders of magnitude slower than most applications. The new nest thermostat seen on the next page was designed by an engineer that previously designed Apple’s iPods. It uses a color LCD similar to those in cellphones and a rotating ring for user input. Menus are used to change settings and display data. This device is now available at your neighborhood Lowes, the Apple Store, and Amazon. Nest Labs is one of Silicon Valley’s newest startup success stories. It is an interesting example of how even common household devices are currently being re-engineered using new technology.
The Nest thermostat
As seen in the printed circuit board (PCB) image below, the nest contains an ARM Cortex A8 32-bit processor, temperature, light, motion, and humidity sensors and Wi Fi. The motion sensor senses when no one is home to save energy. A learning algorithm monitors your inputs to setup automatic scheduling. Wi Fi can be used for remote control via the web and for automatic firmware updates.
Hardware found in the Nest
Most home heating systems use 24V AC relays to turn the fan, heater, and cooling on and off. A driver circuit converts a digital logic output signal from the processor to the higher voltage and current levels required to trigger the relays.
Building a Thermostat
using mbed
For this assignment, we will use the ARM processor on the mbed module and develop C/C++ code to build a basic thermostat. Mbed’s I/O devices all have been setup with easy to use C++ Application Programming Interface (API) calls that are described in the mbed handbook. The API code provided with mbed uses C++ classes and methods to make them easier to use. These are similar to a simple device driver and it is not necessary to understand the hardware details of each I/O device to develop complex C/C++ applications on mbed. Follow the hyperlinks provided in this document for additional documentation and C/C++ code examples.
A TMP36 analog temperature sensor will be used to read the temperature. Using mbed’s built in analog to digital convertor and a C/C++ I/O Application Programming Interface (API) call, the voltage from the sensor will be converted from analog to a floating point value returned in a C/C++ variable. This temperature value is then checked to determine when to turn on and off the heating and cooling systems. Two of mbed’s built in LEDs will be used to indicate the value of the output signals that control the heating (LED4) and cooling (LED3). It will not be attached to an actual HVAC system or require a driver circuit to control the relays.
Thermostats and control systems must use hysteresis to avoid rapidly switching on and off. Mechanical systems take time to respond and wear out faster if they are constantly turned on and off. They need to run for a longer period of time to avoid excessive mechanical wear. They are also more energy efficient with longer run times. In the case of a thermostat for a heater, with hysteresis the heater would turn on at the temperature control point, but then not turn off until the temperature has increased a couple degrees. It would not turn back on until the temperature drops a couple degrees. This requires state information (i.e. heater is on or off) and then checking a different temperature threshold when turning the device on versus turning it off. The figure below shows a simple state transition diagram for a thermostat set at 75. The plus and minus 1s provide the hysteresis. It should start in the state where the heater is off.
State Diagram for a Thermostat set to 75
Modeling a State Machine in C/C++
Nested control structures are required to implement a complex state machine in software. As an example, a simple state machine is shown below in C/C++ that blinks an LED. When the program runs, LED1 changes every .33 seconds.
include "mbed.h"
DigitalOut myled(LED1);
int
main()
{
enum
Statetype { LED_off = 0, LED_on };
Statetype state =
LED_off;
while(1) {
switch (state)
{
case LED_off:
myled = 0;
state
= LED_on;
break;
case LED_on:
myled = 1;
state = LED_off;
break;
}
wait(0.33);
}
}
A
simple state machine in C/C++ that blinks an LED
An infinite while loop containing a switch() statement helps structure the code. The switch() statement selects one of several cases based on the current state. Each case (i.e., state) then checks the appropriate conditions to assign the next state. An enumerated type is used for state. Use this overall structure in your code for the thermostat’s state machine. It will be more structured, readable, and easier to understand. For just two unconditional states, an if..else statement could be used, but with a case statement adding more states and input conditions will be easier as the state machine gets more complex. A default case could be added to jump to the initial state just in case it ever entered an undefined state. Wait() actually slows down the state machine clock to around three clocks per second. Without the wait() the LED would change so fast it would only look a bit dimmer. Note that this simple state machine does not check inputs. For a more complex state machine with inputs, inside each case an if..else statement could be used to check inputs to determine the next state.
Reading the
Temperature Sensor
An TMP36 wiki page is provided that shows how to connect the TMP36 sensor and read the temperature using C/C++ on the mbed module. Be careful it looks just like the 2N3904 transistor in the kit, so check the tiny marks on the case’s flat area for the part number. Start by wiring up the TMP36 sensor to mbed and getting the demo code at the wiki page to work as shown. Use the compiler import code link (i.e., box after source code) on the TMP36 wiki page to copy over the complete project demo files for the TMP36. This will verify your hardware connections and sensor operation before trying your new code.
See the breadboard theory wiki, if you have not used a breadboard before and be very careful whenever inserting or removing the mbed module, as the pins can easily bend and break. If that happens, you will need a new mbed module. It is a good idea to put the mbed on your breadboard once and leave it there. A larger version of the TMP36 breadboard setup photograph is also available using the link under the image on the TMP36 wiki page. Device placement is often a critical first step in building a circuit on a breadboard and also in designing a printed circuit board. Typically placing devices with a large number of connections close together simplifies everything (i.e. shorter wires with less wires crossing). Looking ahead at the hardware needed for this laboratory assignment and consulting the mbed pin layout (colored card in kit), the LCD needs a number of GPIO connections. Since the SD card and Shiftbrite RGB LED need an SPI interface, it probably makes sense to put the LCD on the right side of the mbed using GPIO pins on the right side of the mbed module. The SD card and Shiftbrite could go on the left nearer the SPI pins. The TMP36 can use any AnalogIn pin, Pushbuttons can use any GPIO pin, and the speaker will need a PWM pin or the analog output pin, but these devices need only one pin and are not as critical. Pins are passed as arguments when the pin I/O functions are initially setup, so as long as the pin supports the hardware function needed they can be moved around with a one line change in your C/C++ code.
Suggested Parts
Layout
Details on pin assignment suggestions can be found in the Skeleton code provided for use with this assignment. Instructions on downloading this code are provided later near the end of this document. Check the card with pin functions first before moving pins. Using a pin for a non-supported hardware function does not cause a compile error; it generates a run time error which flashes the LEDs once the code runs. Be sure to setup the breadboard bus power strips. There is only one open pin on mbed for gnd and 3.3V (Vout) and power will be needed for several devices. Double check power pin connections before inserting the USB cable for power, if they are incorrect that is the easiest way to destroy an IC.
You will need to follow the instructions provided in your mbed box to setup a user account for access to the C/C++ compiler and space to save source files, if you have not already done so. You have to logon to use the compiler, but not the wiki pages.
The temperature sensor outputs a voltage that indicates the current temperature. An Analog to digital convertor inside the processor converts the analog voltage input to a 12-bit integer value at a maximum sample rate of 200Khz. The mbed C++ API AnalogIN reads a 3.3V max analog input and scales it to a float value between 0 and 1.0 (i.e., a 1.0 would be 3.3V and 0 would be 0V). DigitalOut can be used to control the LEDs. Use LED4 to indicate the state of the heater (i.e., LED4 on means the heater is on).
The mbed I/O APIs use C/C++ classes to enable users to work at a higher level of abstraction without dealing with the low-level hardware details. As example, here is what happens automatically when you use the AnalogIn API C++ class to read an analog input pin:
1. The pin is configured for analog input on initial use of AnalogIn. Most I/O pins can have one of several different
functions that are controlled by registers. I/O
registers on RISC processors are in memory addresses in a special range
reserved just for I/O devices . Pins are a critical
resource on an IC, so most I/O pins are configurable on new ICs. A pin can cost
as much as 100K transistors inside the chip.
2. Whenever the AnalogIn variable is read, the
eight input analog multiplexor is set to select the correct analog channel to
read the pin. This requires writing a value to another I/O control register
along with a small delay for the analog voltage to stabilize.
3. The A/D convertor is then started by writing a start A/D conversion
bit in the A/D control register.
4. The software then waits in a while loop for the A/D to report back
that the conversion is complete. The hardware sets a bit in an A/D status
register when this happens. The A/D can only read 200K samples per second. This is a lot slower than instruction
execution times, so code needs to wait for the A/D conversion complete bit.
5. The AnalogIn value is then read in from the
A/D data register, scaled from 0.0 to 1.0, and returned as the float value of
the AnalogIn variable.
A lot of development time is saved by using AnalogIn, there is no need to find and understand all of these hardware details in the LPC1768 User’s Manual to get the I/O device to work. This is why I/O device drivers are typically used in larger systems.
Since temperature changes slowly, it is engineering overkill to check the temperature as fast as possible in a tight while loop. In an actual system, running slower can save power or provide extra CPU time for other tasks. On mbed, a time delay can be added using wait(). Check the temperature sensor and update states no more than three times a second.
Printf() can be used to display data using the USB cable on a terminal application window running on a PC. In Windows, you need to install a USB virtual com port driver with your mbed attached before using printf() the first time. This driver is only used for printf() and not to download code. The driver needs to be re-installed, if you switch to another mbed as it locks to each mbed’s unique serial number. Printf() is a handy way to display additional data to debug your program. Spare LEDs can also be used to output a couple values as a debugging aid.
With the temperature sensor connected and the program running, you can simulate the effect of the heater turned on by pushing down on the sensor with your finger (being careful not to knock it loose from the protoboard). Your finger is typically a bit cooler than your core body temperature and it does not cover the entire sensor, but you should be able to warm the sensor up to the high 80s after a few seconds. So you can test the thermostat by setting the control point a bit higher than room temperature so that the heat comes on (LED4). Then by warming it up a couple degrees with your finger you should see the heat turn off after a couple seconds. Monitor the temperature using printf()s while this is happening. It is also possible to cool down the sensor using an ice cube in a small plastic bag (be careful not to get water on the breadboard or sensor leads). By spraying it with an aerosol can of dust off cleaner, it can be even be cooled below freezing.
The basic heater thermostat counts 50% (out of 100%). Demonstrate the thermostat to the TAs for checkoff using the checkoff sheet provided. It is possible to demo each part or you can wait until all parts are working. Turn in the checkoff sheet after getting the last signoff, so that the TA can record your grade.
Further Enhancements
Add Cooling (additional 10%) Build a thermostat that controls either heating (use LED4 for heat on) or cooling (use LED3 for cool on) with two different temperature thresholds (i.e., a heat and a cool setting) and three states (off, heat, cool). A DigitalIn pin should be used to switch the mode from heating to cooling by connecting a jumper wire to ground or 3.3V. Read this input pin when the program first starts up and set a global variable mode which indicates heating or cooling mode. There will now be two temperature control point settings, one for heating and one for cooling. To switch modes you will need to change the jumper wire form gnd to Vout and hit the mbed reset button, this will be improved later with the addition of pushbuttons. If you already understand pushbuttons and callbacks, a pushbutton could be added now instead of the jumper wire, but the callback function would need code to toggle mode. Use the enumerated type for mode (just like state in the earlier example state machine code). Use LED2=0 to indicate heating mode and LED2=1 for cooling. The cooling system also needs a couple degrees of hysteresis just like heating. Use printf()s in addition to the two LEDs to output status and temperature. It might be helpful to draw a new state diagram first. The value of mode can be checked in the state machine and used to determine next state along with temperature.
Add Sensor Data Logging (additional 10%) Once every 10 seconds, write the temperature, thermostat state, time and date to a file. The micro SD card or a USB flash drive (<2G FAT 16) can be used for storage. The micro SD card comes with a larger SD card adapter and it may be inside the adapter in your kit. Write out two minutes of data and stop (if you leave a file open and the program continues to write to it you might need to reset the file system on mbed by holding the reset switch down, so use LED1 to show when it is done logging two minutes of data). Fprintf writes to an open file and works just like printf. For time and date, mbed has a real-time clock calendar that is supported by C/C++ time functions. The date and time will power up to a default value, but it can be set using a time function API. Use the format date, time, year, temp, state all on one line and it is OK to just use the default value of the time in the real time clock. It is possible to automatically set it on mbed using a network connection to an NTP server, but that is a bit too much work for this project. Most laptop PCs have an SD card reader slot, if not the TA has some USB adapters in the lab. The micro SD can be put into the larger SD card adapter to read the data files on a PC.
If you can’t read the SD card in the adapter or the micro SD directly on your PC and don’t have a small flash drive around, the internal flash on the mbed can be used to initially develop and debug your code, but the final TA demo should be on SD or USB. Macs go a bit crazy and unmount mbed whenever you lock the flash files by writing to mbed’s internal flash in a program. An example showing local file I/O is in the handbook. The mbed has 2MB of file storage. It is also used to store your code, so be careful not to fill it up or erase the file system. The file system can be viewed on your PC just like any USB flash drive, so after the program runs view the datalog.txt file using the PC. You can also delete it from the PC. It is best not to leave the file system open while waiting, since if power is lost the directory or files may be in a strange state, so the file is closed each time a line is written before the time delay and then opened again for write with append (i.e., “a”). Here is a C/C++ example that logs a line with “Hello File World” very 10 seconds to a file on mbed’s internal flash (not SD or external USB) along with the number of seconds from the real time clock:
#include
"mbed.h"
LocalFileSystem local("local");
// Create the local filesystem under
the name "local"
DigitalOut myled(LED1);
int
main()
{
set_time(0);//Starts Real Time Clock
for(int i=0; i<5;
i++) {
FILE *fp = fopen("/local/datalog.txt",
"a");
//
Open "datalog.txt" on file system for writing with append
fprintf(fp, "Hello File World!
");
time_t
seconds = time(NULL);
fprintf(fp," %d seconds running
\n\r", seconds);
fclose(fp);
wait(10);
}
myled
= 1;
}
Seconds is actually the number of seconds since January 1, 1970 (Unix time). Here is an example that prints the time and date using printfs in a nicer human readable format that is more useful for the data log file using the ctime function:
#include "mbed.h"
int
main() {
set_time(0);//Starts
Real Time Clock
while(1) {
time_t seconds = time(NULL);
//points to time data from Real Time Clock
printf("Time
in seconds since January 1, 1970 = %d\n", seconds);
printf("Time
& Date as a human readable string = %s", ctime(&seconds));
wait(1);
}
}
Local
File System I/O and Time Example
The thermostat feature must still be operational while data logging is turned on.
Add LCD display (additional 10%) Instead of a standard printf directly to the terminal application window running on a PC, use the text LCD to display the current temperature, the temperature setting, and the current output state and mode (i.e., off, heat, cool). Power on pin 2 VCC on the text LCD in your parts kit uses 5V mbed pin VU (i.e., not 3.3V – mbed pin Vout as shown on the mbed LCD wiki page) and the 1K ohm contrast resistor is needed. See the Text LCD wiki page for additional help using the text LCD with mbed. More specific details on the text LCD in your kit are listed on the mbed inventor’s kit web page. The LCD requires several wires and if it is placed near the mbed pins used, the breadboard setup will be easier. It is probably a good idea to try the LCD demo program first to make sure the LCD is hooked up correctly – don’t forget that you probably want to move the pins and change the pin numbers in C++ to the right side of the mbed chip to leave breadboard room for the extra hardware added later. Be sure to check out the cls and locate LCD class member functions in addition to printf. Display the current temperature in two digits and the state on line 1 (i.e., “Temp XX Heat” or “Temp XX” or “Temp XX Cool” ). Put the temperature setting on line two and the mode (i.e., “Heating to XX” or “Cooling to XX”). The LCD can be updated using the same rate as the state machine.
Add User Input (additional 10%) Use two pushbuttons to change the temperature setting for the heater. One pushbutton to increase and the other to decrease a degree each time it is hit. A third pushbutton with a third callback can be used to toggle between heating and cooling modes (instead of the earlier jumper wire). Read the pushbutton wiki page and watch the videos for additional help using pushbuttons with mbed. The LCD printf() should output the temperature setting each time it changes after a small delay for the state machine clock. Small pushbuttons are available for use on your breadboard. The pushbutton callback option probably makes the most sense for this problem and the last example on the pushbutton wiki page shows two callbacks for two pushbuttons. The global variable count is similar to the raise and lower the temperature setting idea with two pushbuttons. The mode value could be used in the callbacks to determine which temperature setting (i.e., heating or cooling) the pushbuttons change.
Add Speaker pushbutton and state feedback (additional 5%) For user feedback, use the driver transistor and speaker to make a fast click whenever a pushbutton is hit and a short beep when a state changes (i.e., heater or AC goes from ON to OFF). All interrupt routines need to be fast, so don’t click (with a hidden wait ) directly inside an interrupt routine, if you write your own interrupt routine. Depending on the details of your implementation, one option might be a global flag might be set in the interrupt routine and used to click just a bit later outside of an interrupt routine. If callbacks are used as suggested earlier, it would be OK to do a fast speaker click in the pushbutton callback routine. See the speaker wiki page for additional hardware and software help using speakers with mbed. The PWM speaker PlayNote method is probably the best choice for this program.
Add RGB LED State Display (additional 5%) Use a shiftbrite to add a color display of the current state like the Nest ( i.e., off, heat-orange, cool-blue). For this portion, a new C++ class must be developed for a single shiftbrite and placed in a separate *.h file. It should function similar to the existing mbed APIs, it will call the SPI class (and Digital Out) but extend it for a shiftbrite. See the shiftbrite wiki page for additional help using shiftbrites with mbed and the mbed “making it a class” example. Reading the code in the classes developed in the speaker wiki page examples will also provide some more details. So in the main program, it would work something like this after an #include “Shiftbrite.h”
//
declare a new Shiftbrite connected to these pins
using a class
Shiftbrite myShiftbrite(penable,platch,pred,pgreen,pblue,);
…..
//
call the class member function to set the LED color
myShiftbrite.write(red, green, blue);
After studying the links with the example class code described earlier, for the new Shiftbrite class here is an additional hint. You will need a constructor and a member function (write) to write a new color to the Shiftbrite. The SPI API has three required pin arguments (one is not used but still needed) and the other examples only have one. So here is a line showing how three would work in the class constructor:
Shiftbrite::Shiftbrite(PinName pin_e,
PinName pin_l, PinName pin_do,
PinName pin_di, PinName pin_clk)
: _pin_e(pin_e),
_pin_l(pin_l), _spi(pin_do, pin_di,
pin_clk)
{
//setup SPI options and
initialize digital outs
}
With these also in the class definition:
private:
//class
sets up the 4 pins
DigitalOut _pin_e;
DigitalOut _pin_l;
SPI _spi;
};
When hooking up the Shiftbrite, the pins on the left side (see lettering on PCB) must be used. The pins on the right side go through a logic buffer so that you can connect long chains of Shiftbrites. Notice that if it is ever plugged into the breadboard upside down, the power pins get reversed, and if the supply does not shutdown from high current the chip burns out!
The Shiftbrite and the Speaker draw a bit more current from the power supply than the other devices. A power surge can cause a momentary voltage drop on the supply and this might cause a low temperature reading the instant that they turn on at a state change. If this is a problem, the TA has some 10uf capacitors that can be connected across the sensor’s power supply pins (right at the sensor pins). The longer lead on the electrolytic capacitor goes to the + supply pin. A small time delay (<1sec?) might also help after turning them on, if the problem persists.
Skeleton Project Code
to get started
Several steps are need to add all of the libraries and *.h files to a project and the required includes in main.cpp for all of the I/O devices that will be used. To save you time on the assignment, a sample project with all of these already added and the simple state machine code example that just blinks an LED has been provided for your use. The skeleton code project setup is available at:
http://mbed.org/users/4180_1/code/mymbedthermostat/
It is not required to use the skeleton code, but it will likely save you some time finding all of the *.h files and adding them one at a time. To use the skeleton code, plug in your mbed, logon to mbed.org, open a new tab in the browser window and go to the URL above. On the web page that appears click the Import this program box (upper right). It will open a compiler window and import all of the files into your project area and setup a new copy of the project.
It also has some sample I/O code just to show that things are setup OK for all of the new I/O devices. It should compile without errors after import (a warning or two is OK), but if you run it you will get a runtime error on SD file I/O (i.e., all four mbed LEDs will flash) until you delete the SD card I/O example code or attach the SD card breakout and insert and SD card. You will also see an error message on the PC if you have a terminal application program running hooked up to the virtual com port. Once that code is deleted, if you recompile and download the state machine will blink the LED.
You will still need to read the handout and wiki pages to figure out how to hookup the hardware and what needs to be done to finish the program to fill in the missing code in main.cpp. The code has pin assignments for the devices based on the earlier breadboard suggestions, but feel free to change them. Shiftbrite.h does not have all of the class code filled in, you will need to edit that file and add it for the final part of the project.
If you see some handy code on wiki pages or in the compiler and want to cut and paste it into your compiler source code, highlight it with the mouse, use “control C” to copy, move to the paste location, and use “control V” to paste. The format button in the compiler is also helpful to clean up nested control structures and auto indent.
Extra Credit
2 points extra credit for every day early the entire lab is checked off by the TAs. This is to encourage early check offs and minimize large last minute crowds. The first people that finish might also be the first to find minor problems or have suggestions to improve the lab. One attempt per student is allowed to checkoff all parts with the TA. The TA will answer questions about your setup prior to the final checkoff.
Late labs count off 20% per day.
Additional Sensor and I/O Devices for this and other Projects
For those that want to try additional projects with mbed on their own, most new ICs come in small surface mount packages that will not directly plug into a student breadboard. Devices similar to those used in the nest are available on small breakout boards that will plug directly into a breadboard for use with mbed. A large assortment of devices is available using this table of additional sensor ICs, LCD displays, and networking hardware. Many have code examples in the mbed cookbook.
A couple of devices that would be nice for this project, but are a bit too pricey for the students parts kit are a color graphics LCD and a WiFly Wi-Fi chip breakout board. Adding these with some more software would enable the thermostat to have a nice color graphics display like the Nest, and allow you to control it over the internet like the real Nest. It would be possible to add the network jack breakout in the kit and control the thermostat over the internet with a web page using a wired network connection by adding network driver and a simple web page server to the mbed. All of these examples are available in the cookbook, but a bit too advanced and too much work for an early C/C++ lab project.