Programming Interface

This chapter is about the Slink-e's programming interface. That means the commands you send to and the reports you receive from the Slink-e's serial port.

We describe this interface in terms of an underlying channel that delivers a stream of bytes to and accepts a stream of bytes from the Slink-e. That channel happens to be an RS-232 serial line, but our description of the interface is independent of that fact. We do not discuss how the RS-232 lines transports those bytes or how you establish communications on the RS-232 line. We don't mention anything to do with RS-232 except incidentally.

We describe this interface in terms of the actual byte stream at the Slink-e connector. We do not describe how to get those bytes to and from a program running on a computer on the other end of the cable. To use this interface, you must know from some other source how to deliver bytes to the Slinke's serial port and get the bytes that the Slink-e sends from its serial port.

So to make use of this chapter to write a program to talk to the Slink-e, you must already know how to write a program to communicate on a serial line to an arbitrary device.

The interface consists of commands and reports. A command is a sequence of bytes sent to the Slink-e. A report is a sequence of bytes sent from the Slink-e. The Slink-e generates reports for three reasons: 1) in response to a command; 2) to indicate that it has received a port message; 3) to report an error condition. Responses to commands are synchronous with the commands, but reports of port messages received are not synchronous to anything -- they come when the come. Some commands do not cause Slink-e to generate a report.

Here are some examples, so you get the idea of what commands and reports are like:

Documentation Conventions

RS-232 delivers "characters". We call each of those characters (which in Slink-e's case are 8 bits) a "byte".

RS-232 defines the order of bits in a character as more and less "significant" (i.e. you send least significant bit first on the wire). Most of the bytes involved in the programming interface are not encodings of numbers, so "significance" of bits is meaningless. When referring to the order of bits in a byte, we consider RS-232's "most significant bit" to be the first bit. This is just what you would naturally assume, due to the way we normally write binary numbers and bit strings.

Port Naming Complication: IR, Control-S

If you think of a port as a place to physically connect something, you will be confused by the IR ports and S-link Control-S ports when you use the programming interface. In fact, there is only one IR port and no S-link Control-S port. The IR port is divided into 8 "zones" (following Xantech convention), which means there are 8 distinct physical places on the Slink-e where the Slink-e can send or receive port messages. Zone 0 is connected to the built-in IR emitter and built-in IR sensor. Zone 1 is connected to the IR Zone 1 connector. Zones 2-7 are connected to the "Expansion Connector" connector. And Zone 7 is also connected to the S-link Control S connector.

The programming interface does not distinguish in any way between IR and S-link Control-S. It doesn't have to, because the S-link Control-S protocol is designed to be identical to IR signalling except at the lowest physical level (S-link uses electrical signals instead of light, and doesn't use a carrier). Only the last stages of Slink-e hardware distinguish between IR signals and S-link Control-S signals.

(It's worth mentioning here that one of the controls that the programming interface gives you over the IR port is to turn off the carrier. You must do this to get true S-link Control-S protocol, but you must not do this to get conventional IR signalling).

But the Slink-e does have four separate S-link ports. These ports speak the S-link Control-A1(II) protocol. This protocol is considerably different from the IR signalling protocol, and these ports are unrelated to the IR port.

So in this document, the ports known as "S-link" ports are the S-link Control-A1(II) ports, and we don't normally mention the S-link Control-S capability -- our statements about IR signalling apply equally to Control-S.

You can make a simple hardware modification to the Slink-e to convert other IR zones from IR to S-link Control-S.

Slink-e before Version 2.0 doesn't have this confusion -- the IR port has only one zone and can't handle S-link Control-S.

Commands

A command is an instance of sending a sequence of bytes to the Slink-e. The value of those bytes is a command code. For example, the command code 0xFFFF means to reset the Slink-e. Every time you send 0xFFFF to the Slink-e, that's one reset command.

A command code is from 1 to 31 bytes. The first and sometimes second byte of the command code determine how many more bytes follow.

The first byte of a command code is composed of two parts:
Bits Meaning
0-2 Port
000
S-Link Port 0
001
S-Link Port 1
010
S-Link Port 2
011
S-Link Port 3
100
IR port
101
Parallel port
110
Serial port
111
no port
3-7 Command Type
00000
Send Port Message End
11111
Control
other
Send Port Message

In this case, the specific value of the Command Type field determines the data length. See the description of the Send Port Message command type.

Where a command code pertains to a particular Slink-e port, the port field tells which one. A command code that is not particular to a port has the 111 value for the port field.

Command Types

Send Port Message and Send Port Message End go together. Their job is to send a port message to a port. For details see Port Messages.

Control commands do everything else, both specific to a port and general. See Control Commands.

Reports

A report is a sequence of bytes received from the Slink-e.

Reports are highly analogous to commands -- the data just travels in the opposite direction. We will not fully specify reports, because saying they are analogous to commands pretty much covers it.

Reports come in the three types, analogous to the three command types: Port Message Received, Port Message End Received, and Control.

Port Message Received and Port Message End Received reports are unsolicited. The Slink-e generates these when it receives a port message. See Port Messages.

Control reports are either unsolicited or responses to Control commands. A Control report which is a response to a Control command is known simply as a "response." Most Control commands generate one response, which either confirms that the Slink-e processed the command, indicates a command failure, or supplies the information that the command requested. Some Control commands generate no response. No command generates multiple responses.

For details see Control Reports