Jaap's Psion II Page

Controlling the RS232 Port From Machine Code Programs

This document should be read in conjunction with :


1. Checking that COMMS LINK is installed 2. Opening and closing the RS232 port 3. RS232 Control signals 4. Examples using handshaking lines 5. Programming considerations

1. Checking that COMMS LINK is installed

First check that the COMMS LINK software has been loaded - i.e. COMMS is in the top-level menu. If COMMS LINK is not installed, any program which calls the machine code interface routines provided by COMMS LINK will crash.

This check can be performed in OPL as follows :

commsin%: rem return true if COMMS LINK installed onerr iserr:: xfeof: :rem try a harmless COMMS LINK function iserr:: return err<>203 : rem not installed if "missing proc" error

or in machine code :

bsr check_present bcs not_present bra is_present check_present: bsr 1$ ; PC relative LDX #XFEOF .ascic "XFEOF" ; leading count byte string 1$: pulx ; PC = address of "XFEOF" os dv$lkup ; if XFEOF not there, no COMMS LINK rts ; see tech. ref. manual

2. Opening and closing the RS232 port

Before accessing the RS232 port, the program must first call the COMMS LINK machine code interface routine RS$OPEN. This indicates that the RS232 port is now in use.

Example :

clrb ; Open for reading and writing jsr rst_entry_point .byte rs$open bcs error ; Deal with error ... ; Now free to access the port

RS$CLOSE should be called when the RS232 port is no longer needed.

; bit masks for rs$close turn_off_immed= 1 ; switch off immediately after close, else leave port on fail_if_busy= 2 ; fail with carry set if paused by XOFF, else ignore XOFF state, and close immediately

Example where port not closed while XOFF handshake:

close_type = fail_if_busy; don't close if busy handshaking, leave port switched on wait_busy: ldab,#close_type jsr rst_entry_point .byte rs$close bcs wait_busy; wait until XON

Straight close:

close_type = 0; ignore XOFF state, leave port switched on ldab,#close_type jsr rst_entry_point .byte rs$close

3. RS232 Control signals

The COMMS LINK hardware provides the following RS232 control signals on the port POB_PORT2 (address $0003) :-

NameTop slot pinDirectionPORT2 bit noSet if:
RTS5input2correspondent busy
CTS6output0ORGANISER II busy
DSR4input1correspondent busy
DTR-linked to DSR-DSR set

Note that DTR (normally an output) is merely linked to DSR and can not be driven by a program.

All bits are readable. See technical reference manual for details for POB_PORT2.

4. Examples using handshaking lines

; Bit masks cts= 1 dsr= 2 rts= 4 ;Set CTS to indicate ORGANISER II busy oim #cts,POB_PORT2:


;Clear CTS to indicate ORGANISER II ready for input aim #^C cts,POB_PORT2: ; note (1) = $FE


;Wait on both RTS and DSR wait: tim #rts!dsr,POB_PORT2: bne wait

Example: OPL/Machine code for controlling the RTS line directly:

global rtshigh%(2),rtslow%(2),a% rtshigh%(1)=$71fe rtshigh%(2)=$0339 rtslow%(1)=$7201 rtslow%(2)=$0339 rem to assert (raise) the rts line a%=usr%(addr(rtshigh%()),0) rem to de-assert (lower) the rts line a%=usr%(addr(rtslow%()),0)

5. Programming considerations

In between a call to RS$OPEN and a call to RS$CLOSE, programmers should look out for the following operating system routines :-

Routines which access packs :

These turn off the RS232 port, until the next call to COMMS LINK. This is normally no problem, unless a program tries to access POB_PORT2 after a call to one of the above routines but before another COMMS LINK call. The RS232 port should then be turned on by calling RS$OPEN again, as follows :

Example : no problem here

os FL$OPEN ...; RS232 now off jsr rst_entry_point .byte rs$getchar; or similar COMMS LINK function ... tim #cts,POB_PORT2; test the cts line

Example: this is a BUG

os PK$SETP ... ; RS232 now off tim #cts,POB_PORT2; test the cts line

Example: corrected version of above

os PK$SETP ;Re-open the RS232 port, to switch it on ldab,#opened_with ; use value originally supplied to RS$OPEN andb,#^XFE ; but with bit 0 clear to indicate that jsr rst_entry_point ; the handshaking state is not to be reset .byte rs$open ... tim #cts,POB_PORT2 ; now ok to access port

Other routines whose behaviour is altered while the RS232 port open:


The keyboard interrupt service routine is altered so that interrupts remain enabled while the keyboard is being scanned. This gives RS232 interrupts a higher priority than keyboard interrupts.