PIC24 Support Libraries
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
pic24_libconfig.h
Go to the documentation of this file.
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 for this file. If the \file tag isn't present,
31 // this file won't be documented.
32 /** \file
33  * This file consolidates all the user-configurable \#defines
34  * scattered throughout the \ref PIC24_support
35  * "PIC24 support library". These may be changed by
36  * editing the \#defines below, or by defining them via passing
37  * a <code>-Dname=value</code> flag to the compiler.
38  */
39 
40 #pragma once
41 
42 // Needed by HB_LED config.
43 #include <xc.h>
44 
45 
46 /** @name Supported hardware platforms
47  * This library supports the following hardware platforms.
48  * More can easily be added.
49  */
50 //@{
51 /** The Microchip Explorer 16 Development Board
52  * with a 100-pin plug-in module, part number DM240001.
53  */
54 #define EXPLORER16_100P 0
55 
56 /** The Dangerous Prototypes web platform.
57  * See http://dangerousprototypes.com/docs/Web_platform_hardware_design
58  */
59 #define DANGEROUS_WEB 1
60 
61 /** The Microchip 16-bit 28-pin Starter Board,
62  * Part number DM300027. Thanks to István for contributing this!
63  *
64  * Note: When you use a Microchip 16-bit 28-pin Starter Board with this
65  * library collection or just try out the example programs of the
66  * texbook, the SW2 switch shoud be set in the USB/debug state.
67  */
68 #define STARTER_BOARD_28P 2
69 
70 /** Any of three targets, which share the same hardware configuration:
71  * 1. The schematic on pg. 255 of the book
72  * "Microcontrollers: From Assembly Language to C Using the PIC24 Family"
73  * 2. The Microchip Microstik for dsPIC33F and PIC24H Development Board,
74  * part number DM330013.
75  * 3. The Sparkfun Breakout Board for PIC24HJ32 - mini-Bully
76  * sku: BOB-08787
77  */
78 #define DEFAULT_DESIGN 3
79 
80 /** A device with hard-mapped pins for UART TX and RX. */
81 #define HARDMAPPED_UART 4
82 
83 /**
84  * Microchip part number: dm330013-2
85  *
86  * Microstick II delivers a complete development hardware platform for Microchip’s 16-bit and 32-bit
87  * microcontrollers and digital signal controllers. It’s the perfect solution to those looking for a
88  * low-cost, easy-to-use development platform.
89  * The USB-powered kit includes an on-board debugger/programmer, a DUT socket for easy device swapping,
90  * a user LED and reset button. It is designed for insertion into a standard prototyping board for easy
91  * connection to additional circuitry. The kit is extremely portable as well and is still about the size
92  * of a stick of gum!
93  *
94  * Supported Parts: All 3.3V PIC24FJ, PIC24E, PIC24H, dsPIC33, and PIC32 28-pin SPDIP packaged devices.
95  */
96 #define MICROSTICK2 5
97 
98 /** The CAN2 rev C1 board used for Embedded Systems, ECE 4723, at Mississippi State University (Fall 2013) */
99 #define EMBEDDED_C1 472313
100 
101 /** The CAN2 rev C1 board used for Embedded Systems, ECE 4723, at Mississippi State University (Fall 2014) */
102 #define EMBEDDED_F14 472314
103 
104 /** Select one of the hardware platform above to compile for. */
105 #ifndef HARDWARE_PLATFORM
106 # define HARDWARE_PLATFORM DEFAULT_DESIGN
107 #endif
108 // Verify that a valid hardware platform is selectd
109 #if (HARDWARE_PLATFORM != EXPLORER16_100P) && \
110  (HARDWARE_PLATFORM != DANGEROUS_WEB) && \
111  (HARDWARE_PLATFORM != STARTER_BOARD_28P) && \
112  (HARDWARE_PLATFORM != MICROSTICK2) && \
113  (HARDWARE_PLATFORM != DEFAULT_DESIGN) && \
114  (HARDWARE_PLATFORM != HARDMAPPED_UART) && \
115  (HARDWARE_PLATFORM != EMBEDDED_C1) && \
116  (HARDWARE_PLATFORM != EMBEDDED_F14)
117 # error "Invalid hardware platform selected."
118 #endif
119 //@}
120 
121 // Defines for compiling the bootloader
122 #ifdef BOOTLOADER
123 # define USE_HEARTBEAT 0
124 # define USE_CLOCK_TIMEOUT 0
125 # define _NOASSERT
126 # define _NOFLOAT
127 #endif
128 
129 // Defines for compiling ESOS.
130 #ifdef BUILT_ON_ESOS
131 # define USE_HEARTBEAT 0
132 # define _NOASSERT
133 # define _NOFLOAT
134 #endif
135 
136 /** @{
137  * \name Defines configuring pic24_clockfreq.h
138  */
139 
140 /** Clock configuration for the PIC24 - set CLOCK_CONFIG
141  * to one of the following. Naming convention is
142  * OSCTYPE_[PRIFREQ]_FCYFREQ where OSCTYPE gives the
143  * oscillator type (see \ref FNOSC_SEL for details),
144  * the optional PRIFREQ specifies primary oscillator frequency,
145  * and FCYFREQ determiens the processor clock
146  * (F<sub>CY</sub>) frequency. The "#defines for CLOCK_CONFIG"
147  * section gives the definition of the values below.
148  *
149  * Name | uP
150  * --------------- | ---
151  * SIM_CLOCK (simulator) | any
152  * FRCPLL_FCY16MHz | PIC24F, PIC24FK
153  * FRC_FCY4MHz | PIC24F, PIC24FK
154  * PRI_NO_PLL_7372KHzCrystal | PIC24F, PIC24FK, PIC24H, dsPIC33F
155  * FRC_FCY3685KHz | PIC24H, dsPIC33F, PIC24E, dsPIC33E
156  * FRCPLL_FCY40MHz | PIC24H, dsPIC33F
157  * PRIPLL_7372KHzCrystal_40MHzFCY | PIC24H, dsPIC33F
158  * PRIPLL_8MHzCrystal_40MHzFCY | PIC24H, dsPIC33F, PIC24E, dsPIC33E
159  * PRIPLL_8MHzCrystal_16MHzFCY | PIC24F, PIC24FK
160  * PRI_8MHzCrystal_4MHzFCY | PIC24F, PIC24FK, PIC24H, dsPIC33F
161  * FRCPLL_FCY60MHz | PIC24E, dsPIC33E
162  * FRCPLL_FCY70MHz | PIC24E, dsPIC33E (limited temp. range)
163  */
164 // Uncomment one of the #defines below to make
165 // a clock choice. If all the #defines below
166 // are commented out, code in below
167 // will pick a default clock choice.
168 #ifndef CLOCK_CONFIG
169 //#define CLOCK_CONFIG SIM_CLOCK
170 //#define CLOCK_CONFIG FRCPLL_FCY16MHz
171 //#define CLOCK_CONFIG FRC_FCY4MHz
172 //#define CLOCK_CONFIG PRI_NO_PLL_7372KHzCrystal
173 //#define CLOCK_CONFIG FRC_FCY3685KHz
174 //#define CLOCK_CONFIG FRCPLL_FCY40MHz
175 //#define CLOCK_CONFIG PRIPLL_7372KHzCrystal_40MHzFCY
176 //#define CLOCK_CONFIG PRIPLL_8MHzCrystal_40MHzFCY
177 //#define CLOCK_CONFIG PRIPLL_8MHzCrystal_16MHzFCY
178 //#define CLOCK_CONFIG PRI_8MHzCrystal_4MHzFCY
179 //#define CLOCK_CONFIG FRCPLL_FCY60MHz
180 //#define CLOCK_CONFIG FRCPLL_FCY70MHz
181 #endif
182 
183 // If no clock was selected, pick a default: choose the fastest
184 // possible clock depending on which
185 // processor we're using. If simulation mode is
186 // selected, then use the simulation clock.
187 #ifndef CLOCK_CONFIG
188 # if defined(SIM)
189 # define CLOCK_CONFIG SIM_CLOCK
190 # elif (HARDWARE_PLATFORM == EXPLORER16_100P) && defined(__PIC24H__)
191 # define CLOCK_CONFIG PRIPLL_8MHzCrystal_40MHzFCY
192 # elif (HARDWARE_PLATFORM == EXPLORER16_100P) && defined(__PIC24F__)
193 # define CLOCK_CONFIG PRIPLL_8MHzCrystal_16MHzFCY
194 # elif defined(__PIC24H__) || defined(__DOXYGEN__)
195 # define CLOCK_CONFIG FRCPLL_FCY40MHz
196 # elif defined(__PIC24F__) || defined(__PIC24FK__)
197 # define CLOCK_CONFIG FRCPLL_FCY16MHz
198 # elif defined(__dsPIC33F__)
199 # define CLOCK_CONFIG FRCPLL_FCY40MHz
200 # elif defined(__PIC24E__) || defined(__dsPIC33E__)
201 // 60MHz clock is a conservative max choice for PIC24E, 70MHz has a more limited temp. range.
202 # define CLOCK_CONFIG FRCPLL_FCY60MHz
203 # else
204 # error "Unknown processor."
205 # endif
206 #endif
207 
208 /// @}
209 
210 /** \name Defines configuring pic24_delay.h
211  * @{
212  */
213 
214 /** Define a debounce delay for use in reading pushbutton
215  * switches. The value is specified in milliseconds.
216  */
217 #ifndef DEBOUNCE_DLY
218 # define DEBOUNCE_DLY 15 //in milliseconds
219 #endif
220 
221 /// @}
222 
223 
224 
225 /** \name outString() end-of-line behavior in pic24_serial.h
226  * @{
227  */
228 
229 /** Set \ref SERIAL_EOL_DEFAULT to this value to
230  * send a CR with every LF in outString.
231  * PuTTY uses this, expects "\n\r".
232  */
233 #define SERIAL_EOL_CR_LF 0
234 
235 /** Set \ref SERIAL_EOL_DEFAULT to this value to
236  * send a carriage return only ("\r") to end a line.
237  */
238 #define SERIAL_EOL_CR 1
239 
240 /** Set \ref SERIAL_EOL_DEFAULT to this value to
241  * sends a new line only ("\n"). This
242  * works for Bully Bootloader, MPLAB SIM, TeraTerm,
243  * RealTerm.
244  */
245 #define SERIAL_EOL_LF 2
246 
247 /** This macro defines end-of-line output behavior
248  * when the \ref outString() function is passed a new line ("\n").
249  * Set this to either \ref SERIAL_EOL_CR_LF, \ref SERIAL_EOL_CR, or
250  * \ref SERIAL_EOL_LF.
251  */
252 #ifndef SERIAL_EOL_DEFAULT //can be overridden in project file
253 # define SERIAL_EOL_DEFAULT SERIAL_EOL_LF
254 #endif
255 
256 #if (SERIAL_EOL_DEFAULT != SERIAL_EOL_CR_LF) && \
257  (SERIAL_EOL_DEFAULT != SERIAL_EOL_CR) && \
258  (SERIAL_EOL_DEFAULT != SERIAL_EOL_LF)
259 # error "Invalid choice for SERIAL_EOF_DEFAULT."
260 #endif
261 
262 /// @}
263 
264 /** \name Defines from pic24_serial.h
265  * @{
266  */
267 /** Defines the default UART which the configUART() function
268  * initializes and which serial I/O is directed to
269  * until the _C30_UART variable is changed.
270  */
271 #ifndef DEFAULT_UART
272 # if (HARDWARE_PLATFORM == EXPLORER16_100P)
273 # define DEFAULT_UART 2
274 # else
275 # define DEFAULT_UART 1
276 # endif
277 #endif
278 
279 
280 
281 /** Default baud rate used by \ref configBasic() to
282  * configure the \ref DEFAULT_UART.
283  */
284 #ifndef DEFAULT_BAUDRATE
285 // For convenience, common baud rates (uncomment one):
286 // If none are select, a default will be chosen below.
287 //# define DEFAULT_BAUDRATE 230400
288 //# define DEFAULT_BAUDRATE 115200
289 //# define DEFAULT_BAUDRATE 57600
290 //# define DEFAULT_BAUDRATE 38400
291 //# define DEFAULT_BAUDRATE 19200
292 //# define DEFAULT_BAUDRATE 9600
293 #endif
294 
295 #ifndef DEFAULT_BAUDRATE
296 # if defined(__PIC24F__) || defined(__PIC24FK__)
297 // The PIC24F/FK's 16 MHz max frequency using the inaccurate FRC means a lower default baud rate is a safer choice.
298 # define DEFAULT_BAUDRATE 57600
299 # else
300 # define DEFAULT_BAUDRATE 230400
301 # endif
302 #endif
303 
304 /** Default BRGH value used by \ref configUART1 to 4
305  * when configuring a UART. This value may be
306  * overridden on a per-UART basis by \#defineing
307  * DEFAULT_BRGHn (where n = the UART to override)
308  * to the values given below. Allowed values:
309  * - BRGH = 0 - the baud rate divisor is 16
310  * - BRGH = 1 - the baud rate divisor is 4
311  */
312 #ifndef DEFAULT_BRGH
313 # define DEFAULT_BRGH 0
314 #endif
315 
316 #if (DEFAULT_BRGH != 0) && (DEFAULT_BRGH != 1)
317 # error "Invalid value for DEFAULT_BRGH."
318 #endif
319 
320 /// @}
321 
322 /** \name Defines configuring pic24_util.h
323  * @{
324  */
325 
326 /** When set to 1, verify that calls to switchClock() do
327  * successfully switch the clock, reporting an error
328  * message on failure. See also checkClockTimeout().
329  */
330 #ifndef USE_CLOCK_TIMEOUT
331 # ifdef BUILT_ON_ESOS
332 # define USE_CLOCK_TIMEOUT 0
333 # else
334 # define USE_CLOCK_TIMEOUT 1
335 # endif
336 #endif
337 
338 /* \name Heartbeat
339  * These routines provide heartbeat support by blinking a LED
340  * on a regular basis. See doHeartbeat() for more information.
341  */
342 //@{
343 
344 #ifndef USE_HEARTBEAT
345 /** If this macro is true, heartbeat functionality is enabled.
346  * If false, heartbeat is disabled.
347  */
348 # define USE_HEARTBEAT 1
349 #endif
350 
351 
352 #ifndef HB_LED
353 # if (HARDWARE_PLATFORM == EXPLORER16_100P)
354 # define HB_LED _LATA7
355 # define CONFIG_HB_LED() CONFIG_RA7_AS_DIG_OUTPUT()
356 # elif (HARDWARE_PLATFORM == DANGEROUS_WEB)
357 # define HB_LED _LATA8
358 # define CONFIG_HB_LED() CONFIG_RA8_AS_DIG_OUTPUT()
359 # elif (HARDWARE_PLATFORM == MICROSTICK2)
360 # define HB_LED _LATA0
361 # define CONFIG_HB_LED() CONFIG_RA0_AS_DIG_OUTPUT()
362 # else // All other hardware platforms
363 /** Choose a pin for the heartbeat.
364  * If \ref USE_HEARTBEAT is false, the heartbeat is disabled.
365  */
366 # define HB_LED _LATB15
367 /** Define a config function for the heartbeat pin. */
368 # if (defined(_ODCB15) || defined(_ODB15))
369 # define CONFIG_HB_LED() \
370  do { \
371  CONFIG_RB15_AS_DIG_OUTPUT(); \
372  ENABLE_RB15_OPENDRAIN(); \
373  } while (0)
374 # else
375 # define CONFIG_HB_LED() CONFIG_RB15_AS_DIG_OUTPUT()
376 # endif
377 # endif //if (HARDWARE_PLATFORM == EXPLORER16_100P)
378 #endif // #ifndef HB_LED
379 
380 /// @}