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 
41 /** @name Supported hardware platforms
42  * This library supports the following hardware platforms.
43  * More can easily be added.
44  */
45 //@{
46 /** The Microchip Explorer 16 Development Board
47  * with a 100-pin plug-in module, part number DM240001.
48  */
49 #define EXPLORER16_100P 0
50 
51 /** The Dangerous Prototypes web platform.
52  * See http://dangerousprototypes.com/docs/Web_platform_hardware_design
53  */
54 #define DANGEROUS_WEB 1
55 
56 /** The Microchip 16-bit 28-pin Starter Board,
57  * Part number DM300027. Thanks to István for contributing this!
58  *
59  * Note: When you use a Microchip 16-bit 28-pin Starter Board with this
60  * library collection or just try out the example programs of the
61  * texbook, the SW2 switch shoud be set in the USB/debug state.
62  */
63 #define STARTER_BOARD_28P 2
64 
65 /** Any of three targets, which share the same hardware configuration:
66  * 1. The schematic on pg. 255 of the book
67  * "Microcontrollers: From Assembly Language to C Using the PIC24 Family"
68  * 2. The Microchip Microstik for dsPIC33F and PIC24H Development Board,
69  * part number DM330013.
70  * 3. The Sparkfun Breakout Board for PIC24HJ32 - mini-Bully
71  * sku: BOB-08787
72  */
73 #define DEFAULT_DESIGN 3
74 
75 
76 /** Select one of the hardware platform above to compile for. */
77 #ifndef HARDWARE_PLATFORM
78 #define HARDWARE_PLATFORM DEFAULT_DESIGN
79 #endif
80 // Verify that a valid hardware platform is selectd
81 #if (HARDWARE_PLATFORM != EXPLORER16_100P) && \
82  (HARDWARE_PLATFORM != DANGEROUS_WEB) && \
83  (HARDWARE_PLATFORM != STARTER_BOARD_28P) && \
84  (HARDWARE_PLATFORM != DEFAULT_DESIGN)
85 #error Invalid hardware platform selected.
86 #endif
87 //@}
88 
89 /** @{
90  * \name Defines configuring pic24_clockfreq.h
91  */
92 
93 /** Clock configuration for the PIC24 - set \ref CLOCK_CONFIG
94  * to one of the following. Naming convention is
95  * OSCTYPE_[PRIFREQ]_FCYFREQ where OSCTYPE gives the
96  * oscillator type (see \ref FNOSC_SEL for details),
97  * the optional PRIFREQ specifies primary oscillator frequency,
98  * and FCYFREQ determiens the processor clock
99  * (F<sub>CY</sub>) frequency. The "#defines for CLOCK_CONFIG"
100  * section gives the definition of the values below.
101  *
102  * \code
103  * Name uP
104  * --------------- ---
105  * SIM_CLOCK (simulator) any
106  * FRCPLL_FCY16MHz 24F
107  * FRC_FCY4MHz 24F
108  * PRIPLL_8MHzCrystal_16MHzFCY 24F
109  * PRI_NO_PLL_7372KHzCrystal 24F, 24H
110  * FRC_FCY3685KHz 24H
111  * FRCPLL_FCY40MHz 24H
112  * PRIPLL_7372KHzCrystal_40MHzFCY 24H
113  * PRIPLL_8MHzCrystal_40MHzFCY 24H
114  * \endcode
115  */
116 // Uncomment one of the #defines below to make
117 // a clock choice. If all the #defines below
118 // are commentend, code below
119 // will pick a default clock choice.
120 #ifndef CLOCK_CONFIG
121 //#define CLOCK_CONFIG SIM_CLOCK
122 //#define CLOCK_CONFIG FRCPLL_FCY16MHz
123 //#define CLOCK_CONFIG FRC_FCY4MHz
124 //#define CLOCK_CONFIG PRIPLL_8MHzCrystal_16MHzFCY
125 //#define CLOCK_CONFIG PRI_NO_PLL_7372KHzCrystal
126 //#define CLOCK_CONFIG FRC_FCY3685KHz
127 //#define CLOCK_CONFIG FRCPLL_FCY40MHz
128 //#define CLOCK_CONFIG PRIPLL_7372KHzCrystal_40MHzFCY
129 //#define CLOCK_CONFIG PRIPLL_8MHzCrystal_40MHzFCY
130 #endif
131 
132 // For convenience, choose the fastest
133 // possible clock depending on which
134 // processor we're using. If simulation mode is
135 // selected, then use the simulation clock.
136 #ifndef CLOCK_CONFIG
137 #if defined(SIM)
138 #define CLOCK_CONFIG SIM_CLOCK
139 #elif (HARDWARE_PLATFORM == EXPLORER16_100P) && defined(__PIC24H__)
140 #define CLOCK_CONFIG PRIPLL_8MHzCrystal_40MHzFCY
141 #elif (HARDWARE_PLATFORM == EXPLORER16_100P) && defined(__PIC24F__)
142 #define CLOCK_CONFIG PRIPLL_8MHzCrystal_16MHzFCY
143 #elif defined(__PIC24H__) || defined(__DOXYGEN__)
144 #define CLOCK_CONFIG FRCPLL_FCY40MHz
145 #elif defined(__PIC24F__) || defined(__PIC24FK__)
146 #define CLOCK_CONFIG FRCPLL_FCY16MHz
147 #elif defined(__dsPIC33F__)
148 #define CLOCK_CONFIG FRCPLL_FCY40MHz
149 //60MHz clock is conservative max choice for PIC24E, 70MHz has a more limited temp. range.
150 #elif defined(__PIC24E__)
151 #define CLOCK_CONFIG FRCPLL_FCY60MHz
152 #elif defined(__dsPIC33E__)
153 #define CLOCK_CONFIG FRCPLL_FCY60MHz
154 #else
155 #error Unknown processor
156 #endif
157 #endif
158 
159 /// @}
160 
161 /** \name Defines configuring pic24_delay.h
162  * @{
163  */
164 
165 /** Define a debounce delay for use in reading pushbutton
166  * switches. The value is specified in milliseconds.
167  */
168 #ifndef DEBOUNCE_DLY
169 #define DEBOUNCE_DLY 15 //in milliseconds
170 #endif
171 
172 /// @}
173 
174 
175 
176 /** \name outString() end-of-line behavior in pic24_serial.h
177  * @{
178  */
179 
180 /** Set \ref SERIAL_EOL_DEFAULT to this value to
181  * send a CR with every LF in outString.
182  * PuTTY uses this, expects "\n\r".
183  */
184 #define SERIAL_EOL_CR_LF 0
185 
186 /** Set \ref SERIAL_EOL_DEFAULT to this value to
187  * send a carriage return only ("\r") to end a line.
188  */
189 #define SERIAL_EOL_CR 1
190 
191 /** Set \ref SERIAL_EOL_DEFAULT to this value to
192  * sends a new line only ("\n"). This
193  * works for Bully Bootloader, MPLAB SIM, TeraTerm,
194  * RealTerm.
195  */
196 #define SERIAL_EOL_LF 2
197 
198 /** This macro defines end-of-line output behavior
199  * when the \ref outString() function is passed a new line ("\n").
200  * Set this to either \ref SERIAL_EOL_CR_LF, \ref SERIAL_EOL_CR, or
201  * \ref SERIAL_EOL_LF.
202  */
203 #ifndef SERIAL_EOL_DEFAULT //can be overridden in project file
204 #define SERIAL_EOL_DEFAULT SERIAL_EOL_LF
205 #endif
206 
207 #if (SERIAL_EOL_DEFAULT != SERIAL_EOL_CR_LF) && \
208  (SERIAL_EOL_DEFAULT != SERIAL_EOL_CR) && \
209  (SERIAL_EOL_DEFAULT != SERIAL_EOL_LF)
210 #error Invalid choice for SERIAL_EOF_DEFAULT
211 #endif
212 
213 /// @}
214 
215 /** \name Defines from pic24_serial.h
216  * @{
217  */
218 /** Defines the default UART which the configUART() function
219  * initializes and which serial I/O is directed to
220  * until the _C30_UART variable is changed.
221  */
222 #ifndef DEFAULT_UART
223 #if (HARDWARE_PLATFORM == EXPLORER16_100P)
224 #define DEFAULT_UART 2
225 #else
226 #define DEFAULT_UART 1
227 #endif
228 #endif
229 
230 
231 
232 /** Default baud rate used by \ref configBasic() to
233  * configure the \ref DEFAULT_UART.
234  */
235 #ifndef DEFAULT_BAUDRATE
236 // For convenience, common baud rates (uncomment one):
237 #define DEFAULT_BAUDRATE 230400
238 //#define DEFAULT_BAUDRATE 115200
239 //#define DEFAULT_BAUDRATE 57600
240 //#define DEFAULT_BAUDRATE 38400
241 //#define DEFAULT_BAUDRATE 19200
242 //#define DEFAULT_BAUDRATE 9600
243 #endif
244 
245 /** Default BRGH value used by \ref configUART1 to 4
246  * when configurating a UART. This value may be
247  * overridden on a per-UART basis by \#defineing
248  * \ref DEFAULT_BRGH1 to 4. Allowed values:
249  * - BRGH = 0 - the baud rate divisor is 16
250  * - BRGH = 1 - the baud rate divisor is 4
251  */
252 #ifndef DEFAULT_BRGH
253 #define DEFAULT_BRGH 0
254 #endif
255 
256 #if (DEFAULT_BRGH != 0) && (DEFAULT_BRGH != 1)
257 #error Invalid value for DEFAULT_BRGH
258 #endif
259 
260 /// @}
261 
262 /** \name Defines configuring pic24_util.h
263  * @{
264  */
265 
266 /** When set to 1, verify that calls to switchClock() do
267  * successfully switch the clock, reporting an error
268  * message on failure. See also checkClockTimeout().
269  */
270 #ifndef USE_CLOCK_TIMEOUT
271 #ifdef BUILT_ON_ESOS
272 #define USE_CLOCK_TIMEOUT 0
273 #else
274 #define USE_CLOCK_TIMEOUT 1
275 #endif
276 #endif
277 
278 /* \name Heartbeat
279  * These routines provide heartbeat support by blinking a LED
280  * on a regular basis. See doHeartbeat() for more information.
281  */
282 //@{
283 
284 #ifndef USE_HEARTBEAT
285 /** If this macro is true, heartbeat functionality is enabled.
286  * If false, heartbeat is disabled.
287  */
288 #define USE_HEARTBEAT 1
289 #endif
290 
291 
292 #ifndef HB_LED
293 #if (HARDWARE_PLATFORM == EXPLORER16_100P)
294 #define HB_LED _LATA7
295 #define CONFIG_HB_LED() CONFIG_RA7_AS_DIG_OUTPUT()
296 #elif (HARDWARE_PLATFORM == DANGEROUS_WEB)
297 #define HB_LED _LATA8
298 #define CONFIG_HB_LED() CONFIG_RA8_AS_DIG_OUTPUT()
299 #else // All other hardware platforms
300 /** Choose a pin for the heartbeat.
301  * If \ref USE_HEARTBEAT is false, the heartbeat is disabled.
302  */
303 #define HB_LED _LATB15
304 /** Define a config function for the heartbeat pin. */
305 #if (defined(_ODCB15) || defined(_ODB15))
306 #define CONFIG_HB_LED() CONFIG_RB15_AS_DIG_OD_OUTPUT()
307 #else
308 #warning "Heartbeat pin not open drain."
309 #define CONFIG_HB_LED() CONFIG_RB15_AS_DIG_OUTPUT()
310 #endif
311 
312 #endif //if (HARDWARE_PLATFORM..
313 #endif // #ifndef HB_LED
314 
315 
316 #if (defined(__PIC24HJ12GP202__) || \
317 defined(__PIC24HJ12GP201__) || \
318 defined(__PIC24HJ32GP202__) || \
319 defined(__PIC24HJ32GP202__) || \
320 defined(__dsPIC33FJ32GP202__) || \
321 defined(__PIC24HJ16GP304__) )
322 #define SMALLRAM
323 #endif
324 
325 
326 /// @}