PC Documation M200 μC Serial Communication Protocol

Punched Paper Project – December 2009
Author: Sven Köppel – $Id: protocol.htm 59 2010-01-22 18:44:34Z sven $


This file describes the communication design via RS232 to the microcontroller driver software that was written for controlling the Documation M200 punch card reader.

This protocol is mainly ASCII based and designed with the target for a lightweight microcontroller implementation (using the C programming language) and a client application, running on a computer. Alternatively, it is supposed to be human readable at a terminal, so an human shall be able to replace the client program on a PC.


Version 1.0.0
First write down from some scratch paper


  1. Motivation
  2. Definitions
  3. Hardware wiring and RS232 settings
  4. General protocol layout
  5. Client request codes
  6. Server response code
  7. Punch card representations

1. Motivation

In 2009 I've programed a microcontroller control and read out the data from a punch card reader. It was supposed that the microcontroller software translates the data and prints them out to the connected computer.

Since punch cards, having 80 columns with 12 bit each, are a bit weird to handle on modern computer platforms (all talking in 8 bit wide bytes), the question of how to represent such a punch card on a computer arised soon. Furthermore, this Documation M200 punch card reader device isn't complex at all, but there are nevertheless some status and error signals that would be nice to be transfered to the computer, too. After all, it's supposed that humans could use that device with their computers without being freaks. So there must be some running some cient program on the computer that actually accepts the data from the microcontroller. For processing this workflow, there's a need of a standarized protocol.

Well, we're in 2009, today there are many, many protocols outside to use. But there's another point: Users should be able to use the microcontroller without the client program, because I don't want to bind the microcontroller to one special client program.

Since we are using RS232 as transportation layer between computer and microcontroller, we already have some sort of flow control and handshaking, so we need only some data model. Using ASCII is quite the only choice if humans should be able to handle it directly from terminals.

Summing up, we need a protocol with these features:

The proposed protocol in the present document is intended to cover all these issues.

2. Definitions

At first I want to introduce some simple abbreviations:

refers commonly to the punch card reader Documation M200
This is the Microcontroller (with the software running on it)
This is the PC in general or some application running on it, like a terminal or a graphical frontend.

3. Hardware wiring and RS232 settings

This is a rather unimportant chapter concerning how to get a RS232 communication line to the microcontroller.

Discussion about RS232 male and female sockets are too specific at this point, since they only cover our needs. Our microcontroller board is equipped with a RS232 female socket. Since computers are using typically RS232 male sockets, you will need an ordinary RS232 connection cable. The connection is not crossed.

We will use hardware flow control with 8bit bytes and no parity bits. Currently we are using 36400 baud.

4. General protocol layout

This is a typical communication:

100 foo bar bar barz...

5. Client request codes

List of codes:

char signification
h Order μC to print out a help of client request codes
c Connect: Will print out version and internally reset
0 Ping (microcontroller will print out pong if not hung up)
1 Start punching
2 Stop punching
3 Set output to hexadecimal output
4 Set output to debug output
5 Set output to binary jones output
6 Reset internal buffers and stop punchingou
7 Toggle very verbose output (experts only)

6. Server response codes

Range Typical numbers and comments/data signification
100 100 pong The answer to a ping request
101 help output Commenting and help output on any other [101; 199] line
200 200 v1.0 Welcome to M200 Card Reader Answer to Connect request: Print out version (in v[Major].[Minor] format) and welcome message
201 Going to start soon... Acknowledgements to request code, code [x] will produce 20[x] as answer (See table above)
202 Stopping as soon as possible...
203 Set output to HEX
204 Set output to DEBUG
205 Set output to JONES
206 Performing a soft RESET...
207 Verbose output ON
300 301 ERROR rising Scheme: 3[x][y], where [x] = Signal line, [y] = 1 or 0, depending on state
300 ERROR falling
32- BUSY
33- HCK (Hopper Check)
34- MOCK (Motion Check)
400 4-- Any debug output Specific debug output, can be completely ignored
500 500 illegal character at input: 'd' Bad input, see table above for correct request codes
600 600 0x12 0x85 Hexadecimal output. Scheme: 6[xy] where xy is the column number, going from 00 to 79
601 0x00 0xA5 Data scheme: low octett, high octett...
602 0x72 0x42
679 0xBE 0xEF
700 470 /123456789 012| Debug output. Displays the complete punch card as ASCII art. The first line
700 000000010 000 (470) may occur to make some nice column heading
700 000000010 000
779 111011011 101
800 800 BINARY Binary Jones output (123 bytes) starting after newline. See next chapter for format
808 FINISHED Binary Jones output finished (maybe... we'll look)
900 900 Bad card! Stopping reader Bad device behaviour, possibility of data loss! Stop everything immediately.
905 Printer Buffer Full Ugly code design caused status output information loss (no data loss)

7. Punch card representations

As you can already extract from the response code table, there are three punch card formats:

The only real world data format is the binary format, named after the inventor, Douglas Jones. He proposed a format for complete card decks, as excepted in APPENDIX A. We do not use the fully featured syntax (which defines some bytes as meta data) but only the basic idea of encoding an 80 columns punch card to exactly 120 octetts. So a typical card data transportation following this protocol will look like:

    800 BINARY DATA\r\n.........................................808 FINISHED\r\n
	                   ^         120 bytes payload             |
	     start of data exactly at caret, end after 120 bytes

This is an example for the first six bytes in the payload:

         column 1                column 2                column 3                 column 4
|_ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _|
|               |               |               |               |               |               |
      byte 1          byte 2          byte 3         byte 4          byte 5          byte 6

For the exact decoding of one column (three nibbles) see APPENDIX A.

APPENDIX A: Binary Punch Card Representation (Douglas Jones)

This appendix is a copy of Emulated Punch Card Decks by Douglas W. Jones, Part of the Punched Card Collection.

The purpose of this file is to document the card formats I hope will be used by developers of emulators for antique computers, so that card "decks" punched on one emulator will be readable by others, and so that a standard suite of utility software can be used to support "card" processing on all such emulators.

The following file format is proposed for use on such emulators:

One column of a card holds 12 bits; in the file, we lay them out as follows, with ones representing punched holes:

      Top                  Bottom
        _ _ _ _ _ _ _ _ _ _ _ _
      12 11 0 1 2 3 4 5 6 7 8 9
       |     |                 |
       |Zone |     Numeric     |
Note that there are multiple mappings from ASCII to card codes, reflecting different keypunches and reflecting different interpretations of non-ASCII graphics such as cent-sign and logical-not.

A design dilemma presents itself: There are two rational ways to map card columns to byte sequences, highbyter (or bigendian) and lowbyter (or littleendian). The choice is arbitrary. Here, we will be bigendian as follows:

               column 1                column 2
       |_ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _|
       |               |               |               |
             byte 1          byte 2          byte 3
Card files need a distinguished magic number or prefix to prevent accidental interpretation of random files as virtual card decks. Here, we will use the ASCII prefix "H80", in honor of the FORTRAN Hollerith format used to read one card image as uninterpreted text.

This prefix allows extension to H82, where both columns 0 and 81 are represented -- note that some verifiers punched in column 0, and that IBM 026 keypunches could generally punch column 81. Emulators should generally accept H82 files and ignore the extra leading and trailing columns! Similarly H51 can be used to represent the 51 column cards used for some business forms, and H53 can be used to represent these cards with data punched in columns 0 or 52. Mixing multiple card sizes in one deck was never practical, so emulators need not support it, and most emulators need only support H80 (and H82, but ignoring columns 0 and 81).

To support keypunch emulators and card deck display and editing programs, a 3 byte prefix is needed on each card. Emulators that read the holes on a card should ignore this prefix (other than using it to verify that a card-file is indeed being read). The prefix format is as follows:

             byte 1          byte 2         byte 3
       |_ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _|
       | | Color | |cut| | |     |form | |    logo     |
                  |       |   |
                corner    | punch
Cards came in many colors, and cream cards (the default) came with pale colored stripes coarsely printed across the top margin. The following color selection should be more than sufficient:
      Color:  cream (unbleached)      0000 default!
              white                   0001
              yellow                  0010
              pink                    0011
              pale blue               0100
              pale green              0101
              pale orange             0110
              pale brown              0111 rare
              yellow stripe           1010 very common!
              pink stripe             1011
              pale-blue stripe        1100
              pale-green stripe       1101
              pale-orange stripe      1110
              pale-brown stripe       1111
Most cards had rounded corners to prevent fraying, but you could save a bit of money by ordering square cornered cards. One of the top corners of each card was usually cut off diagonally. Cards with no cut and with both top corners cut were made!
      Corner: round   0  default
              square  1

      Cut:    neither 00 rare
              right   01 common
              left    10 default
              both    11 rarest

Keypunches usually printed on the top edge of the card as they punched. Each model of keypunch printed its own interpretation of the character codes used, and if a card was punched by a high speed computer-driven punch, it was not usually printed. Any deck of cards could be run through an interpreter which overprinted the card with a somewhat eccentric interpretation of the data on the card. Accurate emulation of the particular character sets used by different interpreters is probably not necessary (most programmers got used to the fact that interpreters hardly ever printed in the character set that they wanted!)
      Interp: no      0  default
              yes     1

      Punch:  none            000 punch didn't print
              026 Commercial  001 older, with "&-#@.¤$*,%"
              026 FORTRAN     010 older, with "+-='.)$*,("
              029             100 default
Cards could be printed with a number of forms and logos. Most corporate logo cards were based on a standard form, with the logo added in light grey in the center of the card. The set of available forms was open ended, and of course, the set of logos was open ended. This virtual card format allows only a few of them (and far too many logos).

      Forms:  no printing  000
              IBM 5081     001 all numeric rows marked (default)
              IBM 507536   010 only colmns 1, 80 and row 0 marked
              IBM 5280     011 8 fields, 3-3-3-1 subfields
              DSI 327      100 8 fields, 5-5 subfields
              IBM 733727   101 20 fields, 4 chars each
              IBM 888157   110 FORTRAN column layout

      Logo:   none                                  0000000 \ default may
              (your institution's logo here)        0000001 / vary!
              IBM 821924 (701 binary)
              IBM 821162 (701 assembly)
              IBM 874266 (7090 assembly)
              Rechenzentrum RWTH Aachen 
              University of Alaska
              University of Arizona Computer Center
              Battelle Laboratories
              Bell Labs (old style)
              Bell Labs (GE 600, new style)
A matter of philosophy: The forms listed in the forms category above are those which served as the basis for large numbers of institutional overprints! There were huge numbers of other standard forms, some of which should be probably be assigned as logos and overprinted on the blank form. As a result, these forms cannot have custom logos, but this should not cause great problems with users of the full-blown emulator package envisioned. Please, if you ever come up with keypunch emulators that support custom logos, inform me of the logos you use and reserve their numbers!