# Accessing Macintosh Serial Ports

Occasionally, it may be necessary to access the serial ports of the Macintosh PC directly in order to give commands to the motor controller, counter box or any device directly. Furthermore such a faclility is useful for coding environment device drivers in the SICS server macro language. The implementation of serial port access is highly SINQ specific and relies on the SINQ hardware concept. Besides, serial port access is realized in a different way then usual SICS objects. Usually SICS objects live in the SICS interpreter. Serial port access is implemented as an extension to the Tcl macro language. Essentially this is the same implementation as used in the psish. This section describes how to use serial port access. Several steps have to be performed:

1. Install the serialport command into the SICS server. This requires two lines to be added to the server startup script:
   - SerialInit
   - TclPublish serialport UserRights
   Where UserRights stands for one of the possible SICS user rights. See documentation for TclPublish above.
2. Each separate serial port will be represented by a name in the SICS server after it has been initialized. This name is also a command. These port names live in the Tcl interpreter and must be made accessible with TclPublish. For example for a port named p1 include this line in the server startup script:
   - TclPublish p1 User
   Replace User with the correct access code you want for a serial port. It is recommended to restrict serial port access to SICS managers only.
3. After starting the SICS server the command serialport is now available.
4. Now a serial port can be initialized with a command like this:
   - serialport name1 macintosh.name port channel force
   - Example: serialport p1 lnsp20.psi.ch 4000 5
   Such a command creates the command name1 and links it with serial port channel channel on the Macintosh-PC macintosh.name. Port is the port number on which the Macintosh serial port server is listening for connections (usually 4000). The last flag force is optional. If something is there, the connection to that port is done on a separate socket of its own. This has to do with some feature of the software interface to the Macintosh serial port server. This software interface tries to direct messages for multiple channels through one socket connection between the host and the Macintosh server. This is perfectly fine as long as none of the commands through this socket takes a long time to execute. However, if a RS-232 device takes a long time to respond, the whole socket is blocked. Fortunately, the Macintosh serial port server runs a separate thread of execution for each different socket. By forcing a new socket it can be achieved that such a slow device is decoupled from the rest. Exactly this is achieved with the force flag.
5. Once the port has been initialised (for example p1) it is ready to operate. The port object allows to send data to the serial port and receive data from it. Furthermore some configuration is possible. The syntax is like this:
   portname -tmo number
     Sets the timeout for the serial port. This is the maximum amount of time the Macintosh serial port server waits for data to arrive from the RS-232 device. Increase this if a lot of `_BAD_TMO` error messages creep up.
   portname -sendterm string
     Sets the terminator which will be automatically added to the string which is sent. Some RS-232 devices require special terminators in order to accept a command. The serial port implementation ensures that such a terminator is sent after each message. This command allows to configure this terminator. Please note, that the terminator string needs to be enclosed in quotes. An example:
     - `p1 -sendterm "\r\n"`
     This sets the terminator to carriage return - line feed.
   portname -replyterm string.
     The Macintosh terminal server expects the RS-232 device to send a terminator when it is done with sending answers. It even supports multiple lines to be sent as a reply. This expected reply terminator is set with this command. The string may may be four characters long. An example: `1\r\n` sets the expected terminator to one of `\r\n`. One of them is expected. Thus the first character is the count of terminators to expect, followed by the characters possible as terminators. This string must usually be quoted.
   portname blablalakjdl
     When none of the options -tmo, -replyterm, -sendterm, is found everything after portname is sent to the RS-232 device. The reply from the RS-232 device is printed.

The defaults set for the configuration parameters of the serial port connection are suited for the EL734, EL737 and ITC4 devices usually encountered at SINQ. For other RS-232 devices consult the manuals hopefully delivered with the device. The defaults are: 100 for timeout, `1\r\n` for the reply terminator and `\r\n`for the send terminator.

Please note, that the SICS server serial port access is a convenience feature for SICS managers and instrument scientists. It is needed for implementing environment device drivers in the Tcl macro language. If serial port connections must be debugged the Macintosh versaterm software or on a IBM-PC the kermit program are much better suited to the task.