REBOL SERIAL PORT SPECIFICATION

    REBOL Enhancement Proposal: REP004
    Version: 1.0.1
    Author: Jim Goodnow II

Contents:

1. PURPOSE
2. CREATION
3. OPERATION

1. PURPOSE

This specification describes the creation and operation of serial communication ports within REBOL.

2. CREATION

Serial ports are created in the same manner as other ports within REBOL. The scheme name for serial ports is "serial:". The specification of a serial port may include the device number, the communication speed, the number of data bits, the parity and number of stop bits. The specification information can be specified directly by setting the appropriate fields within the port specification object or by creating a URL which contains the same information. Any field not specified will be given a default value. The default values are:

    device: port1
    speed:  9600
    data bits:  8
    parity: none
    stop bits:  1

URL's are encoded with the different fields separated by slashes. For example,

    serial://port1/9600/8/none/1

The order of fields is not significant, as the type of field can be determined by the content.

Within a port specification, the various parameters are stored in the following object fields:

    host:           device
    speed:          speed
    data-bits:      data bits
    parity:         parity
    stop-bits:      stop bits

The portN specification is an indirect reference to the communication device. It refers to the Nth device defined in the System/ports/serial block. This block is initialized by default depending on the system being used and can be modified in user.r to reflect any local requirements.

For example, on Windows the block might be defined as:

    System/ports/serial: [ com1 com2 ]

or if COM1 is being used by the mouse, it might just be:

    System/ports/serial: [ com2 ]

On unix-style systems, the block might be defined as:

    System/ports/serial: [ ttyS0 ttyS1 ]

or if the first device should correspond to COM2:

    System/ports/serial: [ ttyS1 ttyS0 ]

Thus, the ports can be specified in a machine indpendent manner while the machine specific definition can be controlled using the serial definition block in System/ports/serial.

3. OPERATION

Serial ports are always opened as direct ports in much the same way as console and network ports. They may be opened as either /STRING or /BINARY with the default being /STRING. They are opened by default as asynchronous, but may be made synchronous by using the /WAIT refinement. When operating asynchronously, any attempts to copy data from the port will return NONE if no data is present. When operating synchronously, the copy will block until data is available.

Data can be written to the port using the INSERT native. Data can be read from the port using the PICK, FIRST or COPY natives with the usual ramifications. As usual with direct ports, the REMOVE, CLEAR, CHANGE and FIND functions are not supported.

The UPDATE function can be used to change port parameters. For example, to change the speed after an initial connection has been established, you could just do:

    ser-port: open serial://9600
    ser-port/speed: 2400
    update ser-port

Changing the device number or the System/ports/serial and calling UPDATE will have no effect. Once the port has been opened with a particular device, the device can't be changed.

There are two additional port fields that can't be set with a URL, but can be set in a port specification block or by manually changing them. The RTS-CTS field specifies whether hardware handshaking should be used on the port. The default is ON. To change the default, do:

    ser-port/rts-cts: off
    update ser-port

A timeout value can be specified by modifying the timeout field in the port structure. The timeout value only applies to serial ports that are opened with the /wait refinement. When the timeout expires, a serial port timeout error will be generated. To set the timeout value do:

    ser-port/timeout: 10        ; 10 second timeout

Serial ports work properly with the WAIT native.