WriteHere™ Protocol

Version 1.0, Last updated: August 30, 1999

The WriteHere Protocol is used by the WriteHere Server and the WriteHere handheld software to coordinate the transmission of text and commands between the desktop and handheld.

Those wishing to make use of the WriteHere protocol in their server and handwriting recognition software applications will find the WriteHere Protocol to be extremely simple to implement.

Overview

All transmissions in the WriteHere Protocol are a stream of ASCII characters.

Transmission Start

Every transmission from the handheld to the desktop is preceeded by a single character code. Currently there are only two codes being used:

Start of Command: ASCII Character 1 (SOH). The stream of data should be interpreted as a command key.
Start of Text: ASCII Character 2 (STX). The stream of data should be interpreted as text to be inputted at the cursor.

Please note that future versions of the WriteHere Protocol may include additional command codes. Your software should be written to support a variety of command codes.

Transmission End

Every transmission is terminated by the following character code:

End of Text: ASCII Character 3 (EOT). No more text is coming.

Sending & Handling Input

The next section deals with sending and handling text input and commands on the part of the WriteHere Server and Handheld software.

Handling Text Input

With this information, we can take a look at how text input is handled by the WriteHere Protocol. Every text stream is started with the STX character and ended by the EOT character. Let's look at an example, "Hello World!".

The stream of characters that your serial input code receives is presented below in ASCII and character format:


001 072 101 108 108 111 032 087 101 114 108 100 033 003

STX  H   E   L   L   O       W   O   R   L   D   !  EOT

If the data stream is too large for your serial device to take in all at once, the stream will be broken down into sections. This first piece of data will start with the SOT character but subsequent pieces will simply be the continuation of data and will not begin with the SOT character. The last portion of data will end with the EOT character. Usually, if the handheld is sending words at a time, you won't run into this situation. However, if the handheld is transferring entire paragraphs or documents at a time, your server code must be able to deal with this case.

After Receiving Text Input

If you are writing a port of the WriteHere Server, you must write now execute the code to handle inputting of this text stream wherever the cursor is located.

Handling Commands

Commands are relatively easy to send and parse. Every command begins with the Start of Command character code, ASCII 2 (SOH). It is followed by a single character code.

Start of Command: ASCII Character 1 (SOH).
Character: Single ASCII value for the character being sent.
Command Value: Either the '0' or '1' character. Determines whether the command key is depressed.
Option/Alt Value: Either the '0' or '1' character. Determines whether the option/alt key is depressed.
Control Value: Either the '0' or '1' character. Determines whether the control key is depressed.
Shift Value: Either the '0' or '1' character. Determines whether the shift key is depressed.

The following is an example of sending "command-shift-a". Below is the stream of ASCII characters that your handheld will send to the WriteHere Server on the desktop.


002 097 049 048 048 049 003

SOH  a   1   0   0   1  EOT

The command begins with the SOH character, followed by the 'a' character and then "1001" which corresponds to the command and shift modifier keys being depressed.

After Receiving Commands

If you are writing a port of the WriteHere Server, you must now execute the code to handle sending command keys to the frontmost application.

Note: Most commands characters are in lowercase. Most documentation writes these command characters in uppercase. For example, "Please press Command-A to select all the text in the document." What you are really sending is not Command-A but Command-a.

Sending Text & Commands From the Handheld

If you are adding WriteHere support to your handwriting recognition package, you need to be able to generate the data streams oulined above and be able to send them through your handhelds serial port.

Currently, all versions of WriteHere for handheld computers, for Palm OS and Newton OS, configure the serial port as follows:

Port Speed: 38400
Data Bits: 8
Parity: None
Stop Bits: 1
Flow Control: Varies. The Palm OS had no flow control enabled while the Newton OS has software flow control enabled (XON/XOFF).

Your software should have a WriteHere Mode in which your handwriting recognition software opens the serial port and sends inputted data out the serial port using the WriteHere protocol.

Sending Text From the Desktop

Some versions of WriteHere for Handhelds can receive text sent from the desktop to the handheld. All transmissions from the desktop should be standard C-style strings with the last character being a carriage return or linefeed character.

Carriage Return: ASCII Character 13
Linefeed: ASCII Character 10

Conclusion

The WriteHere Protocol is a very simple method to communicating between the handheld computer and the WriteHere Server. If you are adding WriteHere support for your favorite OS or for your handwriting recognition software package, you will find adding the WriteHere protocol to be a trivial matter.

For additional support or questions, please send us feedback.