,ll 78
,lm 0
,nj
,mmc %
,pl 66
,hd
,ll 78
,lm 0
,ce 2
PC Share Data Interface Protocol
Author: J.Bird

Issue    : 12
Date     : %date%
Version  : 4.0


,,
,ft

PAGE: ##
,,

,pg


,ce
PC Share Data Interface Protocol

1. Introduction

Message protocol descriptions/capabilities of system  between Host computer and PC Sharer software. 

This document is for use with Version 4.0 Software only. This software release is only available for Windows platforms (Win16 & Win32) and is not applicable to any DOS release.

1.1 Changes to this document since Issue 1

- updated Mode Change Message (2.1.2.1) to include status response
- included graphic mode descriptions (2.1.1.2.1.1)
- clarified File transfer status messages
- included recognized & actioned VT100 sequences.

1.2 Changes to this document since Issue 2

- updated all status responses to single byte
- included all PC capable graphics modes and Dragon hi-res emulation (2.1.1.2.1.1)
- redefine file transfer protocol in line with OS9
- maximise VT100 emulation
- include Dragon OS9 GO51 emulation codes
- moved all transfers to single I/O port, define HDISK messages
- implement miscellaneous command structure

1.3 Changes to this document since Issue 3

- baselined document for PCShare V2.X
- restore message header to all status responses
- remove status byte from graphics mode change for V2.X (2.1.1.2)
- remove remaining TBD's (palette data 2.1.1.2.3.1)
- modify file read operations to return status info prior to transferring data (2.1.1.3.7, 2.1.1.3.8)
- update file status bytes to remove obsolete codes and add new codes (2.1.1.3.14)
- remove references to deleted functions
- clarify VT100 codes (2.1.2.2)
- include missing Dragon OS9 GO51 codes (2.1.2.3)

1.4 Changes to this document since Issue 4

- initial spec for PCShare V2.1
- add text attributes (colours) message (2.1.1.4.3)
- extended text mode selection (2.1.1.2.1.1)
- removal of GETSTAT & SETSTAT messages, replaced with unique messages for each GetStat and SetStat function code (2.1.1.3.12 - 2.1.1.3.15)
- add messages for transferal of DOS directory information (2.1.1.3.17).
- 'Change Directory' message returns current directory to host computer (2.1.1.3.3).
- new 'delete directory' message. (2.1.1.3.16)

1.5 Changes to this document since Issue 5

- baseline issue for PCShare V2.1
- move text mode selection from Graphics Mode (2.1.2.1.1) to a new message (2.1.1.4.3)
- add support for multiple hard drives (2.1.3.1, 2.1.3.2)
- colour attribute change in VT100 codes

1.6 Changes to this document since Issue 6

- update for new V2.2 release
- new 'device ready' message (2.1.1.3.18)
- PC COM Port configuration message (2.1.1.3.19)
- Extended usage for 'Get File Size' message for serial devices (2.1.1.3.12)
- Additional error code/status byte 'device not ready' (2.1.1.3.20)
- new 'Read Clock' message (2.1.1.4.5)

1.7 Changes to this document since Issue 7

- prelim issue for PCShare V3.0 MS-Windows release
- MS-Windows interface (2.1.4)
- remove obsolete messages with this release (Execute DOS Command, and Set Text Mode messages)
- graphical interface changes for Windows (2.1.1.2)

1.8 Changes to this document since Issue 8

- baseline issue for PCShare V3.0 DOS and Windows
- include details of both DOS and Windows releases

1.9 Changes to this document since Issue 9

- change to read directory protocol ready for Win95 version:
- issued with PCShare v3.1x

 File Open (2.1.1.3.2) used to open a directory
 File Close (2.1.1.3.4) used to close a directory
 Read Directory Entry (2.1.1.3.17) message structure changed

1.10 Changes to this document since Issue 10

- issue for PCShare v3.2x

 Read PC Clock (2.1.1.4.5) year field extended to 4 digits for Y2K

1.11 Changes to this document since Issue 11

- issue for PCShare v4.0x
- remove obsolete DOS sections

 Draw Line (2.1.1.2.7) & Draw Circle (2.1.1.2.8) messages extended to include line styles.

 New message Define Colour Palette Entry (2.1.1.2.10) added

2. PC Remote Sharer System Interface Definition

The PCRSS has one external interface, comprising a single 8 bit wide input and  output port. Each interface is defined as follows: Data is passed in the form of either textual data to be displayed, or supervisor messages which request special functions to be performed. 

2.1 Data Interface

Data arriving at the input Port is interpreted as textual or message data.

2.1.1 Message Data

Messages issued across the interface are prefaced by a 3 byte header identifying them. The following data packet will then define the actions to be performed. If a partial or incomplete message header is received, the received part of the message header is deemed to be text to be displayed. Messages comprising integer (2 byte) or long integer (4 byte) words are transmitted most significant byte (MSB) first. Messages which require a response packet will be prefaced by the 3 byte message header prior to the packet info to be transferred in order to allow the host computer to syncronise up the i/o interface. Note that this response header message may not include the command byte or packet length. See individual messages for details.

2.1.1.1 Message Header

A message header is identified by the following 3 byte hexadecimal seqence arriving at the port.

MESSAGE HEADER: $AA, $FF, $FF
COMMAND BYTE  : $nn
PACKET LENGTH : $mm

The following byte identifies the command to be performed, and hence the structure of the remaining data packet. The next byte identifies the length of the data packet being transmitted. 

2.1.1.2 Graphics Messages

These messages affect the graphics operaton of a PC-Share window. Graphics commands are issued to the current host active window (see 2.1.4.3).

2.1.1.2.1 Set Graphics Mode Message

Byte 0 .. 2   : $AA,$FF,$FF      Message Header
Byte 3        : $00              Move cursor message
Byte 4        : $06              Byte count
Byte 5 .. 6   : X-co-ord         X pixel range
Byte 7 .. 8   : Y co-ord         Y pixel range
Byte 9        : X-Sign           Origin of X position
Byte 10       : Y-Sign           Origin of Y position

This message creates a graphics area of X-pixels by Y-pixels for the current window. All subsequent X and Y co-ordinates issued through graphics messages must fall within this range for the window. When the graphics area is displayed it is scaled to fit the current window size. A value of 0 in both ranges de-activates graphics mode. The origin values determine where all co-ordinates are drawn relative to:

        X, Y origin     Description

        0, 0            Origin is top left corner of window
        0, 1            Origin is bottom left corner
        1, 0            Origin is top right corner
        1, 1            Origin is bottom right corner

2.1.1.2.2 Obsolete in this release

2.1.1.2.3 Move Graphics Cursor Message

Byte 0 .. 2   : $AA,$FF,$FF      Message Header
Byte 3        : $01              Move cursor message
Byte 4        : $04              Byte count
Byte 5 .. 6   : X-co-ord         X co-ordinate of cursor
Byte 7 .. 8   : Y co-ord         Y co-ordinate of cursor

This message moves the current graphics cursor position to the specified X and Y co-ordinates. The Window/screen display is unaffected.

2.1.1.2.4 Colour Change Message

Byte 0 .. 2   : $AA,$FF,$FF      Message Header
Byte 3        : $02              Colour Change message
Byte 4        : $01              Byte count
Byte 5        : Colour           Colour id

This message changes the current colour to the requested colour id. The window display is unaffected.

2.1.1.2.4.1 Colour Palette Values

The following colours are available by default:

   Colour ID     Colour

        0        Black
        1        Blue
        2        Green
        3        Cyan
        4        Red
        5        Magenta
        6        Brown
        7        L/Grey
        8        D/Grey
        9        L/Blue
       10        L/Green
       11        L/Cyan
       12        L/Red
       13        L/Magenta
       14        Yellow
       15        White

Depending on the capabilities of your graphics card and video mode selected, some of these colours may not appear or may appear as hatched or shaded colours. This colour set aproximatly defines the standard VGA colours. 

The Colour Id parameter allows up to 256 colours to be selected, the remaining undefined values (16-255) or the first 16 may be redefined by use of the Define Colour Palette Entry message (2.1.1.2.10) which allows any custom colour to be defined. This colour can then be called up by any of the graphics functions. Custom colours are unique to each window that is active and are lost when a window is closed.

2.1.1.2.5 Set Point Message

Byte 0 .. 2   : $AA,$FF,$FF      Message Header
Byte 3        : $03              Set Point message id
Byte 4        : $05              Byte count
Byte 5 .. 6   : X co-ord         X co-ordinate of point
Byte 7 .. 8   : Y co-ord         Y co-ordinate of point
Byte 9        : Colour           Colour of point

This message sets the requested X & Y co-ordinate on the active window to the requested colour.

2.1.1.2.6 Clear Screen Message

Byte 0 .. 2   : $AA,$FF,$FF      Message Header
Byte 3        : $04              Clear screen message id
Byte 4        : $01              Byte count
Byte 5        : Colour           Colour of screen

This message clears the active window to the requested colour.

2.1.1.2.7 Draw Line Message

Byte 0 .. 2   : $AA,$FF,$FF      Message Header
Byte 3        : $05              Draw line message id
Byte 4        : $0B              Byte count
Byte 5 .. 6   : X1 co-ord        Starting X co-ordinate of line
Byte 7 .. 8   : Y1 co-ord        Starting Y co-ordinate of line
Byte 9 .. A   : X2 co-ord        Ending X co-ordinate of line
Byte B .. C   : Y2 co-ord        Ending Y co-ordinate of line
Byte D        : Colour           Colour of line
Byte E        : Width            Width of line in pixels
Byte F        : Style            Style of line

This message draws a line between the requested co-ordinates in the specified colour & width on the current active window. The defined styles are: 0 = Solid, 1=Dashed, 2=Dotted. Dashed & Dotted styles are only supported with a pixel width of 1.

2.1.1.2.8 Draw Circle Message

Byte 0 .. 2   : $AA,$FF,$FF      Message Header
Byte 3        : $06              Draw circle message id
Byte 4        : $09              Byte count
Byte 5 .. 6   : Radius           Radius of circle
Byte 7 .. 8   : X co-ord         Centre X co-ordinate of circle
Byte 9 .. A   : Y co-ord         Centre Y co-ordinate of circle
Byte B        : Colour           Colour of circle
Byte C        : Width            Width of circle in pixels
Byte D        : Style            Style of line

This message draws a circle of the specified radius at the request co-ordinates, of the specified colour & width on the current active window. The supported styles are 0=Solid, 1=Dashed, 2=Dotted. Dashed & Dotted styles are only supported with a pixel width of 1.

2.1.1.2.9 Read Pixel Colour Message

Byte 0 .. 2   : $AA,$FF,$FF      Message Header
Byte 3        : $07              Read Pixel Colour message id
Byte 4        : $04              Byte count
Byte 5 .. 6   : X co-ord         X co-ordinate of pixel to read
Byte 7 .. 8   : Y co-ord         Y co-ordinate of pixel to read

Status Response

Byte 0 .. 2   : $AA,$FF,$FF      Message header
Byte 3        : $01              Byte count
Byte 4        : Colour           Colour of requested pixel

This message requests the colour of the specified pixel. Upon receipt of this message, the PCRSS will send the colour of the pixel to the output port. See para 2.1.1.2.3.1 for the colour value returned.

2.1.1.2.11 Define Colour Palette Entry

Byte 0 .. 2   : $AA,$FF,$FF      Message Header
Byte 3        : $35              Define Colour Palette Entry message id
Byte 4        : $04              Byte count
Byte 5        : Pal Id           Entry in palette to define
Byte 6        : Red              Red intensity of colour
Byte 7        : Green            Green intensity of colour
Byte 8        : Blue             Blue intensity of colour

This message allows an entry in the colour palette (0-255) to be defined to a specified colour, given by the Red, Green & Blue intensities. This colour can then be used in subsequent graphics operations by specifiying the required Pal Id field in the colour entry. Colours 0-15 are preset to defaults so normally entries 16-255 are defined using this message although the first 16 may be altered if required.

2.1.1.2.11 Default/Current Settings

The software will maintain a current cursor and colour setting per window. These settings will be utilised whenever a graphics message sets a cursor co-ordinate to $FFFF or a colour to $FF. On power up, the current cursor & current colour will be set to 0. The current colour can only be set by the Colour Change Message, from which point on all colour bytes within messages which are set to $FF will utilise this colour.

The current graphics cursor position can be explicitly set by the Move Cursor Message, which simply updates the current position. The current cursor position is also updated by any other operation which specifies a cursor position, for example a request to draw a circle at co-ordinates 100,100 will set the current cursor position to 100,100.

An example sequence might be:

$AA,$FF,$FF       -- Message header
$05,$09           -- line command & byte count
$00,$04,$00,$04   -- starting X/Y is 4,4
$00,$10,$00,$10   -- ending at 16,16
$FF               -- using default colour

$AA,$FF,$FF       -- Message header
$05,$09           -- line command & byte count
$FF,$FF,$FF,$FF   -- starting at last posn (16,16)
$00,$60,$00,$60   -- ending at 140,140
$02               -- using colour 2

