PIC24 Support Libraries
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
textbook_examples_dox.h
1 /*
2  * "Copyright (c) 2008 Robert B. Reese, Bryan A. Jones, J. W. Bruce ("AUTHORS")"
3  * All rights reserved.
4  * (R. Reese, reese_AT_ece.msstate.edu, Mississippi State University)
5  * (B. A. Jones, bjones_AT_ece.msstate.edu, Mississippi State University)
6  * (J. W. Bruce, jwbruce_AT_ece.msstate.edu, Mississippi State University)
7  *
8  * Permission to use, copy, modify, and distribute this software and its
9  * documentation for any purpose, without fee, and without written agreement is
10  * hereby granted, provided that the above copyright notice, the following
11  * two paragraphs and the authors appear in all copies of this software.
12  *
13  * IN NO EVENT SHALL THE "AUTHORS" BE LIABLE TO ANY PARTY FOR
14  * DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT
15  * OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF THE "AUTHORS"
16  * HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
17  *
18  * THE "AUTHORS" SPECIFICALLY DISCLAIMS ANY WARRANTIES,
19  * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
20  * AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS
21  * ON AN "AS IS" BASIS, AND THE "AUTHORS" HAS NO OBLIGATION TO
22  * PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS."
23  *
24  * Please maintain this header in its entirety when copying/modifying
25  * these files.
26  *
27  *
28  */
29 
30 // Documentation placed on the textbook examples page. This file only
31 // include comments for Doxygen; it does not contain any
32 // code.
33 /**
34  * \page textbookExamples Example code from the textbook
35  *
36  * This page gives example PIC24 code accompanying the textbook titled
37  * <a href="http://www.reesemicro.com">"Microcontrollers:
38  * From Assembly to C with the PIC24 Family"</a> by R. Reese,
39  * B. Jones and J.W. Bruce published by Cengage Learning
40  * in December 2008.
41  *
42  * The next section discussing using the example code, while the
43  * \ref exampleDirectory "example directory" lists all available
44  * examples.
45  *
46  * \section usingExamples Using the example code
47  *
48  * First, make sure you've read the
49  * <a href="http://www.reesemicro.com/Home/pic24-software-library-collection/getting-started">getting
50  * started guide</a>, insuring that your hardware and software are
51  * correctly configured.
52  *
53  * You can place this directory anywhere that you wish; the project
54  * files use relative path names.
55  *
56  * Documentation starts at \ref index "docs/index.html". These examples have
57  * minimal reliance on the libraries shipped with the PIC24 compiler,
58  * and instead use libraries that have been developed by the authors.
59  * The new libraries are meant to be more friendly to programmers
60  * who are new to the PIC24 Family, as this material and code examples
61  * are used in an introductory microprocessors class at Mississippi
62  * State University.
63  *
64  * Most of the examples are meant for a reference
65  * PIC24HJ32GP202 system (some examples in Chapter 13 use the PIC24HJ64GP502, which is
66  * pin compatible with the PIC24HJ32GP202 but has additional on-chip peripherals).
67  * The projects all have a custom linker
68  * file intended for use with a serial bootloader - if you want generated
69  * hex files to be compatible with the PICKIT2 programmer then
70  * delete the linker file from the MPLAB project.
71  * The MPLAB project files do not have workspace files associated with
72  * them - this means that double-clicking on a MPLAB project file opens
73  * a blank workspace, and you do not see the project files. Instead of double-clicking
74  * on a project file, start MPLAB manually, and use 'Project->Open' to open
75  * one of the example projects. This creates a new workspace for that project,
76  * which you can save when you close the project.
77  *
78  * If you have a different PIC24 Family member, simply change the
79  * target device in the MPLAB to that device.
80  * When you compile the files, you will get warnings that the internal
81  * oscillator with PLL is being used, and that the default configuration
82  * bit settings are being used.
83  *
84  * To change clock options, see the documentation on
85  * common/pic24_clockfreq.c and include/pic24_clockfreq.h.
86  * To change config bits, see the documentation on common/pic24_configbits.c
87  *
88  * All of the examples assume a serial port using UART1; our reference system
89  * uses pins RP10 (RX) and RP11 (TX) with a default baudRate of 57600.
90  * To change these assignments, edit the function called configUART1() in
91  * common/pic24_uart.c. To change the default baudrate, edit
92  * the <code>\#define DEFAULT_BAUDRATE</code> in include/pic24_libconfig.h
93  * (The file include/pic24_libconfig.h includes all of the macros for configuring
94  * user-defineable behavior for library functions).
95  *
96  * If the end-of-line (EOL) output behavior is not correct for the serial terminal
97  * program that you are using (i.e, printed new lines do not return to the left
98  * edge of the screen), then you can change this by selecting an appropriate
99  * value for the SERIAL_EOL_DEFAULT macro contained in include/pic24_libconfig.h.
100  * The three choices are <code>SERIAL_EOL_CR_LF</code>,
101  * <code>SERIAL_EOL_CR</code>, or <code>SERIAL_EOL_LF</code>. By default, the
102  * library uses <code>SERIAL_EOL_LF</code> (an EOL is a LF only).
103  *
104  * Our examples also assume an LED tied to port RB15 - this is used as
105  * a 'heartbeat' and is blinked by our examples when waiting for input.
106  * You can reassign this to another port (see \ref HB_LED) or remove it
107  * entirely (see \ref USE_HEARTBEAT) by editing pic24_libconfig.h.
108  *
109  * The best project to start with is chap8/reset.mcp - this just assumes
110  * serial port functionality. Chapter 8 examples are parallel port I/O,
111  * while Chapter 9 gives some interrupt examples. See the following listing
112  * for descriptions of individual code examples.
113  *
114  * \section exampleDirectory Example code directory
115  * Example code includes:
116  * - Chapter 8 (initial startup, parallel port examples)
117  * - chap8/asm_echo.s - Demonstrates calling C from assembly.
118  * - chap8/echo.c - inputs chararacter from UART RX1, echos back +1.
119  * - chap8/lcd4bit.c - Character LCD interface example
120  * - chap8/ledflash.c - Flashes an LED, uses I/O macros.
121  * - chap8/ledflash_nomacros.c - Flashes an LED, does not use I/O macros.
122  * - chap8/ledsw1.c - Demonstrates using a FSM approach for a LED/switch IO problem.
123  * - chap8/ledtoggle.c - Uses an FSM approach to toggle an LED whenever a pushbutton input is pressed and released.
124  * - chap8/ledtoggle_nofsm.c - Toggles an LED whenever a pushbutton input is pressed and released, does not use an FSM approach.
125  * - chap8/reset.c - Demonstrates software reset, idle, sleep, watchdog timer operation.
126  * - Chapter 9 (interrupts, simple timer usage)
127  * - chap9/trap_test.c - Code which causes a math error (divide by zero) trap
128  * - chap9/trap_test_handled.c - contains an ISR which handles the math error (divide by zero)
129  * - chap9/button_semaphore.c - has a periodic timer ISR that creates a semaphore for a complete button press/release
130  * - chap9/change_bounce.c - uses a change notification interrupt to detect switch bounce
131  * - chap9/change_latency.c - measures ISR latency using a change notification interrupt
132  * - chap9/change_test.c - demos a change notification interrupt using an input pushbutton
133  * - chap9/change_wakeup.c - wake from sleep using a change notification interrupt
134  * - chap9/change_wakeup_noint.c - attempt to wake from sleep using a priority 0 CN interrupt
135  * - chap9/filt_test.c - test an extern low-pass RC filter effectiveness by generating a pulse train that is read by another port
136  * - chap9/int0_bounce.c - use the INT0 interrupt to detect switch bounce.
137  * - chap9/int0_wakeup.c - uses INT0 to wake from sleep mode.
138  * - chap9/int1_bounce.c - use the INT1 interrupt to detect switch bounce.
139  * - chap9/int1_wakeup.c - uses INT1 to wake from sleep mode.
140  * - chap9/keypad.c - Implements a 4x3 key scanned keypad interface.
141  * - chap9/ledflash_timer.c - uses a periodic timer interrupt to flash an LED.
142  * - chap9/ledsw1_timer.c - uses a periodic Timer3 interrupt for a LED/SW IO problem, uses a button semaphore in the ISR.
143  * - chap9/ledsw1_timer2.c - same problem as ledsw1_timer.c, except ISR implements the entire FSM for the LED/SW IO problem.
144  * - chap9/ledtoggle_timer.c - toggle an LED using a periodic interrupt to poll the switch input
145  * - chap9/rot_enc.c - A 2-bit incremental Gray code rotary encoder example
146  * - chap9/rot_enc_trace.c - Demonstrates use of an ISR trace buffer for capturing the states of a rotary encoder.
147  * - chap9/softfilt_test.c - Implements a software filter for input pulses less than a specified duration.
148  * - chap9/squarewave.c - Generates a square wave using timer 2 and an ISR.
149  * - Chapter 10 (UART, SPI, I2C)
150  * - chap10/soft_uart.c - Demonstrates a software driven UART TX/RX using PIO pins
151  * - chap10/reverse_string.c - Used in three different projects to illustrate polled UART RX/TX (reverse_string.mcp),
152  * interrupt driven RX/polled TX (uartrx_fifo.mcp), interrupt driven RX/TX (uartrxtx_fifo.mcp)
153  * - chap10/mcp41xxx_spi_pot.c - PIC24 uC in Master mode to Microchip MCP41xxx Digital Potentiometer
154  * - chap10/ds1722_spi_tempsense.c - PIC24 uC in Master mode to Maxim DS1722 Digital Thermometer using SPI
155  * - chap10/spi_master_revstring.c, spi_slave_revstring.c - uses SPI for PIC24 uC to PIC24 uC communication, master uses slave to
156  * reverse strings
157  * - chap10/ds1621_i2c.c - PIC24 uC in Master mode to Maxim DS1621 Digital Thermometer using I2C
158  * - chap10/ds1631_i2c.c - PIC24 uC in Master mode to Maxim DS1631 Digital Thermometer using I2C
159  * - chap10/mcp24lc515_i2c_eeprom.c - PIC24 uC in Master mode to Microchip 24LC515 EEPROM using I2C
160  * - Chapter 11: Data Conversion (ADC, DAC) subdirectory
161  * - chap11/adc2pots1.c - Demonstrates 2-channel manual sampling with the ADC
162  * - chap11/adc7scan1.c - Samples 7 channels sequentially with automatic channel scanning (only for PIC24 CPUs without DMA).
163  * - chap11/adc7scan2.c - Above plus uses double buffering (only for PIC24 CPUs without DMA).
164  * - chap11/adc4simul.c - Simultaneous sampling of 4 channels (only for PIC24 CPUs without DMA).
165  * - chap11/adc_spidac_test.c - Demonstrates reading the internal ADC in 12-bit mode and then sending the upper
166  * 8-bits to an external 8-bit SPI DAC (MAXIM 548A)
167  * - Chapter 12 (Timer coverage - PWM, input capture, output compare, time keeping)
168  * - chap12/incap_freqmeasure.c - Measures the square wave frequency using input capture and Timer2
169  * - chap12/incap_switch_pulse_measure.c - Measures the pulse width of pushbutton switching using input capture and Timer2
170  * - chap12/ir_biphase_decode.c - Decodes bi-phase bitstream from IR remote control as output by an IR receiver.
171  * The protocol is Phillips VCR control, 13 bit command (start bit, toggle bit, 5-bit address, 6-bit data).
172  * The Timer2 divider must be set such that one bit time does not exceed the timer period.
173  * - chap12/manual_switch_pulse_measure.c - Measures the pulse width of a pushbutton switch using Timer2 without input capture.
174  * - chap12/timer32bit_switch_pulse_measure.c - Measures the pulse width of pushbutton switch using Timer2/3 in 32-bit mode with INT1 for edge detection.
175  * - chap12/outcompare_contpulse.c - Generate an asymmetric square wave using output compare (OC1), continuous pulse mode.
176  * - chap12/outcompare_squarewave.c - Generate a squarewave using output compare (OC1).
177  * - chap12/outputcompare_oneservo.c - Demonstrates pulse width modulation using the OC1 output to control a hobby servo.
178  * The ADC input value on AN0 is used to vary the pulse width between its min and maximum values.
179  * - chap12/outputcompare_multiservo.c - Demonstrates pulse width modulation using four digital outputs
180  * and the OC1 module to create four PWM outputs for hobby servos. A table is used to control the pulse widths of the four servos.
181  * - chap12/ledpwm.c - Demonstrates pulse width modulation by controlling the intensity of an LED.
182  * The ADC input value on AN0 is used to vary the PWM period.
183  * - chap12/pwm_dac.c - Demonstrates a PWM DAC - connect an RC filter on the OC1 output and vary the pulse
184  * width of the PWM signal, and monitor the DC value on the capacitor. The RC time constant should
185  * be at least 10x greater than the PWM period. Examples values used for testing were R=6.8k, C = 1.0u, PWM period= 500 us
186  * - chap12/rtcc.c - Demonstrates the Real Time clock module
187  * - Chapter 13 Advanced topics (DMA, ECAN, I2C slave, flash programming, comparator)
188  * - chap13/comparator_example.c - Illustrates a simple use of the comparator module
189  * - chap13/dma_example.c - Uses DMA in ping-pong mode to capture data from the UART, write it to the 24LC515 EEPROM.
190  * - chap13/ecan_example_nofifo.c - Illustrate CAN transmit, receive. Uses only one buffer for RX receive, and
191  * uses a standard data frame.
192  * - chap13/ecan_example_fifo.c - Illustrate CAN transmit, receive. Uses a FIFO for RX receive, and
193  * uses a standard data frame.
194  * - chap13/ecan_example_fifo_eid.c - Illustrate CAN transmit, receive. Uses a FIFO for RX receive, and
195  * uses an extended data frame.
196  * - chap13/flash_example.c - Illustrates run time self programming of the flash memory
197  * - chap13/i2c_master_reverse_string.c, chap13/i2c_slave_reverse_string.c - pair of files that shows a PIC24 I2C master
198  * talking to a PIC24 I2C slave
199  * - chap13/i2c_multmaster_rstring.c - Two PIC24 uCs communicate with each other over I2C, acting both as master
200  * and slave devices.
201  * - Chapter 14 ESOS examples (also see the \ref ESOS section)
202  * - chap14/esos_skel.c - basic ESOS template
203  * - chap14/app_flashled.c - flash an LED
204  * - chap14/app_echo1.c - ESOS version of the echo.c program
205  * - chap14/app_reverse.c - demonstrates a user task that reverses a string
206  * - chap14/app_timerLEDecho.c - flash an LED using a software timer
207  * - chap14/app_semaphore1.c - demonstrates use of semaphores for signaling synchronization
208  * - chap14/app_semaphore1.c - demonstrates rendezvous synchronization with semaphores
209  * - chap14/app_childtask.c - demonstrates child tasks
210  * - chap14/app_irqs.c - demostrates IRQ handling in ESOS
211  * - chap14/app_ds1631.c - I2C example using the DS1631
212  * - chap14/app_ds1722.c - SPI example using the DS1722
213  * - Chapter 15 Capstone examples
214  * - chap15/audio.c, chap15/audio_adpcm.c - audio record/playback to/from Serial EEPROM with adpcm compression.
215  * - chap15/reflow_oven.c, chap15/reflow_debug.c, chap15/reflow_flash.c, chap15/reflow_operate.c - Use a toaster oven as a reflow oven,
216  * demonstrates AC power control and high temperature monitoring.
217  * - chap15/robot.c, chap15/robot_ir_decode.c - code for a small three-wheeled robot with IR control and collision avoidance.
218  *
219  * Examples converted to be compatible with the Explorer-16, 100-pin demo board:
220  * - explorer16_100p/reset.c example (see Chapter 8); Demonstrates software reset, idle, sleep, watchdog timer operation
221  * - explorer16_100p/lcd4bit.c example (see Chapter 8); Character LCD interface example
222  * - explorer16_100p/adc_test.c example (see Chapter 11); Demonstrates reading the internal ADC in 10-bit mode and converting it to a voltage.
223  * - explorer16_100p/timer1_sosc.c example (see Chapter 12); Demonstrates using the secondary oscillator with a 32768 Hz oscillator.
224  * - explorer16_100p/mcp25lc256_spi_eeprom.c example (see Chapter 10); Demonstrates using the 25lc256 SPI EEPROM on the explorer-16 board. This is not tied
225  * to a particular textbook example, but has a similar structure to the Chapter 10 mcp24lc515_i2c_eeprom.c example that uses I2C.
226  *
227  * Other examples not tied to textbook figures:
228  * - chap11/adc_test.c - Demonstrates reading the internal ADC in 10-bit mode and converting it to a voltage.
229  * - chap11/adc_test_12bit.c - Demonstrates reading the internal ADC in 12-bit mode and converting it to a voltage.
230  * - chap11/adc7scan1_dma_scatter_gather_1.c - Samples 7 channels sequentially with automatic channel scanning in scatter/gather mode; uses DMA (only for PIC24 CPUs with DMA) - see the Appendix H online-supplement.
231  * - chap11/adc7scan1_dma_conv_order.c - Samples 7 channels sequentially with automatic channel scanning in ordered mode; uses DMA (only for PIC24 CPUs with DMA) - see the Appendix H online-supplement.
232  * - chap11/adc4simul_dma.c - Simultaneous sampling of 4 channels (only for PIC24 CPUs DMA) - see the Appendix H online-supplement.
233  *
234  * Examples using the \ref dataXfer "data transfer protocol":
235  * see the data transfer protocol \ref dataXferExamples "example listing".
236  */