The uC/PC data transfer protocol

The uC/PC data transfer protocol

The uC/PC data transfer protocol is a simple protocol to exchange data between a PC and a PIC over the UART. The example given below and implemented in this library applies to the PIC24/dsPIC33 series, though porting it to other microcontrollers is straightforward.

Usage sketch

#include "pic24_all.h"
#include "dataXfer.h"

// Indexes of all the variables to be transferred.
enum { U16_NUMCHARS_NDX, C_NDX };

// Number of characters to print on each line.
#define CHARS_PER_LINE 10

int main(void) {
  char c;
  uint16_t u16_numChars = 0;

  // Initialize
  configBasic(HELLO_MSG);
  initDataXfer();

  // All variables received by the PIC must be specified.
  // Params:  Index             Variable      PC can change  Format  Description
  SPECIFY_VAR(U16_NUMCHARS_NDX, u16_numChars, TRUE,          "%hu",  "Number of characters received");
  SPECIFY_VAR(C_NDX,            c,            FALSE,         "%c",   "Character entered");

  while (1) {
    // For debug support, send the index and char received.
    sendVar(U16_NUMCHARS_NDX);
    sendVar(C_NDX);

    // Echo a character
    c = inCharXfer();
    outChar(c);

    // Add a CR every CHARS_PER_LINE
    if ((u16_numChars++ % CHARS_PER_LINE) == 0)
      outChar('\n');
  }
}

Examples

See the bottom of the example directory page.

Design goals

• Easy to use: no setup required to send variables; integrates with ISRs seamlessly by using getch/putch rather than direct assignment to UxRXREG/UxTXREG. Receive requires setup and returns a non-protocol character read or a variable read.
• Excellent error reporting: PIC defines the protocol, pushing most errors onto the PC. Timeouts on the PIC and PC help spot errors. The PIC reports errors via text messages, which flow through to the PC.
• Reasonably efficient (> 100 Hz). Two bytes of overhead per variable (start, type).
• Minimal PIC memory requirements: one pointer, one uint8_t, one bit per variable.
• Can send/receive data in any order (not a fixed sequence): sendVar in any order, receiveVar receives any var (or even a non-protocol character, to make interaction via a menu work)

Error cases

• Timeout during received of a variable. In this case, the variable is only partially assigned; the PIC is reset, while the PC reports an error.
• Sending in an ISR, which could cause timing problems. Fixing this really needs a trace buffer implementation.
• Index of variable not the same between PIC and PC. The PIC names variables; the PC likewise only allows access to variables of the same name. However, the PC code will enforce variable name to number mapping, making this fairly uncommon (if the same name occurs twice, there's a problem).

Protocol

• CMD_TOKEN varBits data
  • varBits = { v v v v v v l l} bitfield
    • v = variable number (0-NUM_XFER_VARS, 63 = special)
    • l = length (1-4 bytes, encoded as 0-3)/special code. Special codes:
      • code = 0: escaped CMD_TOKEN : this is the value CMD_TOKEN, not the start of a command.
      • code = 1: long var
      • code = 2-3: Variable specification: data is size (1 byte), format string, name, description (all zero-terminated). Code 2: send only var (PC may not modify); code 3: send/receive var.
        • Only the PIC can send codes 2-3.
      • For all but code 0, data = varNum (1 byte), length (1 byte), data (of length bytes). varNum must be between 1 and NUM_XFER_VARS.
  • For non-special, data is len bytes. For special: see above. All lengths are len + 1, e.g. len = 0 is 1 byte, etc.
• Sending a CMD_TOKEN, whether inside a protocol packet or as a character not in a packet, must always be escaped with a CMD_TOKEN ESCAPED_CMD.