PIC24 Support Libraries
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
dataXfer_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  * \page dataXfer The uC/PC data transfer protocol
30  * \section dataXferIntro The uC/PC data transfer protocol
31  *
32  * The uC/PC data transfer protocol is a simple protocol to exchange data between
33  * a PC and a PIC over the UART. The example given below and implemented in
34  * this library applies to the PIC24/dsPIC33 series, though porting it to other
35  * microcontrollers is straightforward.
36  *
37  * \htmlonly
38  * <object width="640" height="505"><param name="movie" value="http://www.youtube.com/v/3B60xpMLoFg&hl=en_US&fs=1&"></param><param name="allowFullScreen" value="true"></param><param name="allowscriptaccess" value="always"></param><embed src="http://www.youtube.com/v/3B60xpMLoFg&hl=en_US&fs=1&" type="application/x-shockwave-flash" allowscriptaccess="always" allowfullscreen="true" width="640" height="505"></embed></object>
39  * \endhtmlonly
40  *
41  * \section usageSketch Usage sketch
42  * \code
43 #include "pic24_all.h"
44 #include "dataXfer.h"
45 
46 // Indexes of all the variables to be transferred.
47 enum { U16_NUMCHARS_NDX, C_NDX };
48 
49 // Number of characters to print on each line.
50 #define CHARS_PER_LINE 10
51 
52 int main(void) {
53  char c;
54  uint16_t u16_numChars = 0;
55 
56  // Initialize
57  configBasic(HELLO_MSG);
58  initDataXfer();
59 
60  // All variables received by the PIC must be specified.
61  // Params: Index Variable PC can change Format Description
62  SPECIFY_VAR(U16_NUMCHARS_NDX, u16_numChars, TRUE, "%hu", "Number of characters received");
63  SPECIFY_VAR(C_NDX, c, FALSE, "%c", "Character entered");
64 
65  while (1) {
66  // For debug support, send the index and char received.
67  sendVar(U16_NUMCHARS_NDX);
68  sendVar(C_NDX);
69 
70  // Echo a character
71  c = inCharXfer();
72  outChar(c);
73 
74  // Add a CR every CHARS_PER_LINE
75  if ((u16_numChars++ % CHARS_PER_LINE) == 0)
76  outChar('\n');
77  }
78 }
79  * \endcode
80  *
81  * \section dataXferExamples Examples
82  * See the bottom of the <a href="sphinx/textbook_examples.html">example directory</a> page.
83  *
84  * \section designGoals Design goals
85  * - Easy to use: no setup required to send variables; integrates with
86  * ISRs seamlessly by using getch/putch rather than direct assignment
87  * to UxRXREG/UxTXREG. Receive requires setup and returns a non-protocol
88  * character read or a variable read.
89  * - Excellent error reporting: PIC defines the protocol, pushing most
90  * errors onto the PC. Timeouts on the PIC and PC help spot errors. The
91  * PIC reports errors via text messages, which flow through to the PC.
92  * - Reasonably efficient (> 100 Hz). Two bytes of overhead per variable (start, type).
93  * - Minimal PIC memory requirements: one pointer, one uint8_t, one bit per variable.
94  * - Can send/receive data in any order (not a fixed sequence): sendVar
95  * in any order, receiveVar receives any var (or even a non-protocol
96  * character, to make interaction via a menu work)
97  *
98  * \section errorCases Error cases
99  * - Timeout during received of a variable. In this case, the variable
100  * is only partially assigned; the PIC is reset, while the PC reports an error.
101  * - Sending in an ISR, which could cause timing problems. Fixing this
102  * really needs a trace buffer implementation.
103  * - Index of variable not the same between PIC and PC. The PIC names
104  * variables; the PC likewise only allows access to variables of the same
105  * name. However, the PC code will enforce variable name to number mapping,
106  * making this fairly uncommon (if the same name occurs twice, there's a problem).
107  *
108  * \section protocol Protocol
109  * - \ref CMD_TOKEN varBits data
110  * - varBits = { v v v v v v l l} bitfield
111  * - v = variable number (0-\ref NUM_XFER_VARS, 63 = special)
112  * - l = length (1-4 bytes, encoded as 0-3)/special code. Special codes:
113  * - code = 0: escaped \ref CMD_TOKEN : this is the value \ref CMD_TOKEN,
114  * not the start of a command.
115  * - code = 1: long var
116  * - code = 2-3: Variable specification: data is size (1 byte),
117  * format string, name, description (all
118  * zero-terminated). Code 2: send only var (PC may not modify);
119  * code 3: send/receive var.
120  * - Only the PIC can send codes 2-3.
121  * - For all but code 0, data = varNum (1 byte), length (1 byte),
122  * data (of length bytes). varNum must be between 1 and
123  * \ref NUM_XFER_VARS.
124  * - For non-special, data is len bytes. For special: see above. All
125  * lengths are len + 1, e.g. len = 0 is 1 byte, etc.
126  * - Sending a \ref CMD_TOKEN, whether inside a protocol packet or as a
127  * character not in a packet, must always be escaped with a
128  * \ref CMD_TOKEN \ref ESCAPED_CMD.
129  */