PIC24 Support Libraries
Main Page
Related Pages
Modules
Data Structures
Files
File List
Globals
All
Data Structures
Files
Functions
Variables
Typedefs
Enumerations
Enumerator
Macros
Groups
Pages
lib
include
doxygen
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
*/
Generated by
1.8.4