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