A port message is a message that gets sent out from or received by one of the Slink-e's ports. Sending and receiving messages is the fundamental purpose of a port. A port message takes the form of electrical signals or pulses of infrared light, and its exact form differs according to the type of port.
The serial port deserves special explanation, because this port's primary purpose is not to send and receive arbitrary messages, but to implement the programming interface. The Slink-e considers any port message it receives on the serial interface to be a programming interface command. The Slink-e generates programming interface reports as port messages from the serial port.
Whereas when the Slink-e receives a port message on any other port, it turns it opaquely into a report, when the Slink-e receives a port message on the serial port, it executes it as a command. (Of course, executing the command often involves generating a report!)
But you can send an arbitrary port message from the serial port, the same as you would from any other port (by sending Send Port Message and Send Port Message End commands). The only reason you could possibly want to do this is for some weird diagnostic purpose. You could use this facility to fake a normal Slink-e report and test your program. It might also be a good way to test the integrity of the RS-232 channel.
On the IR port, a port message can be either infrared light or electrical signals. In IR Zone 0, it is infrared light -- either sent from an attached infrared emitter or received by the Slink-e's infrared sensor. In the other zones, it is an electrical wave form on the IR zone connectors, which is meant to represent infrared light. In zones 1-6, the signal follows the Xantech protocol. In Zone 7, it follows the S-link Control-S protocol.
Port message data is the description of a port message that exists in the Slink-e programming interface. It consists of an arbitrary number of bytes and the relationship between port message data and the actual port message depends on the port type. For the parallel, serial, and s-link ports, the relationship is trivial. A port message on these ports is normally considered to be a sequence of bytes, and the port message data is simply those same bytes. On the infrared port, the relationship, like the form of an IR message itself, is quite a bit more complex. See IR Port Messages. For additional information about port messages on the S-link ports, see S-link Port Messages.
One important fact about port message data is that it is an arbitrary number of bytes, but at least one byte.
To send a port message, you send the Slink-e an arbitrary number of Send Port Message commands followed by a Send Port Message End command. See Commands. The Send Port Message End command is what determines the end of the message.
You must send the Send Port Message commands in timely fashion because the Slink-e begins sending the port message as soon as it gets the first port message data. If you don't send Send Port Message commands, and the ultimate Send Port Message End command, fast enough for the Slink-e to meet its timing obligations on the port, a transmission timeout error occurs. You may know this condition as a "data underflow."
On the other hand, you may send Send Port Message commands as fast as you like. The Slink-e buffers the port message data and uses it to generate the port message with the proper timing.
A Send Port Message command contains from 1 to 30 bytes of port message data. The number of bytes is determined by the Command Type field of the first byte of the Send Port Message command. Remember that there are 30 different values of Port Type that all mean Send Port Message. Simply interpret the value as a pure binary number to get the number of bytes of port message data in the command (e.g. Command Type=00010 means the command contains 2 bytes of port message data). The order in which you send the Send Port Message commands determines the order in which the Slink-e assembles the port message data they contain.
So the in the simplest case, you can send a short port message with one Send Port Message command followed by a Send Port Message End command. But if you want to send a port message with more than 30 bytes of port message data, you must use multiple Send Port Message commands.
There is no such thing as a port message with no port message data. There is no way to specify zero data length in a Send Port Message message. Sending a Send Port Message End command when no port message send is in progress is a no-op. It does not cause the Slink-e to send a port message.
The Slink-e cannot send port messages on multiple ports at once. If a port message send is in progress when you send a Send Port Message command for a different port, the Slink-e waits until the in-progress port message is finished before sending the new port message. Bear in mind that the Slink-e cannot finish sending a port message until either you send a Send Port Message End command or an error occurs and the message send fails.
On the S-Link ports, Slink-e will not send a port message while it is receiving a port message on the same port. If you send a Send Port Message command while the Slink-e is receiving a port message on the same port, the Slink-e waits until it is no longer receiving the message and then begins sending your port message.
For S-Link ports, there is a special feature that lets you send a port message which is not a multiple of 8 bits. A Send Port Message command can specify only whole bytes of port message data, and S-link port messages correspond bit-for-bit to port message data, so you can't use that. But a control command with the Send S-Link Odd Bits action functions exactly like a Send Port Message command, but lets you send 1 to 7 bits of port message data, and consequently 1 to 7 bits of port message.
Send Port Message and Send Port Message End commands do not cause the Slink-e to generate a report. Not directly, anyway. Bear in mind that sometimes when you send a port message, it causes the Slink-e to receive a port message, and the Slink-e generates a report saying that it received the port message. For example, if you send an IR message, light fills the room and an IR sensor might sense the message and deliver it back to the Slink-e.
Let's say you want to send the two byte S-link Control-A1(II) message A1A1 (hex) from the S-link Port 2. You could do that by sending the following 4 bytes to the Slink-e on its serial port:
42 1A 1A 40These 4 bytes compose two programming interface commands. The first one is 42 1A 1A and is a Port Send Message command. The second one is 40 and is a Port Send End command. In the Port Send Message command, the first byte (42) says that it is a Port Send Message for S-link Port 2 and has two bytes of port message data. The 2nd and 3rd bytes are the two bytes of port message data. Because it is an S-link port, the port message data is equal to the S-link Control-A1(II) message. In the Port Send End message, the first and only byte (40) says that it is a Port Send End message for S-link Port 2.
When the Slink-e receives a port message on any port except the serial port, it generates one or more Port Message Received reports, followed by a Port Message End Received report.
The Port Message Received / Port Message End Received report sequence is analogous to the Send Port Message / Send Port Message End command sequence for sending a port message. The format of the reports is even identical to that of the commands.
The Slink-e sends full 30-byte Port Message Received reports until there is less than 30 bytes of port message data left to report, then sends one Port Message Received report containing the remaining port message data.
A port message is always at least one byte, so there is always at least one Port Message Received report.
Note that it is possible for a port message to arrive at a port without the Slink-e receiving it. This would be the case if you configured the Slink-e to ignore certain port messages.
The Slink-e is capable of receiving messages on multiple ports simultaneously. That means you could see Port Message Received and Port Message End Received reports pertaining to multiple port messages interleaved. But for any one port, port messages are strictly ordered in time and so are the Slink-e's corresponding reports. This means that your program should maintain a separate buffer for each Slink-e port and be prepared at all times to receive a Port Message Received or Port Message End Received report from any port.
The IR port, on Slink-e Version 2.0 and later, is special. For that port only, the Slink-e immediately follows every Port Message End Received report with a Last Received Port Is report. That report tells the IR zone with which the port message in question is associated.
The example of sending a message is directly analogous to receiving a message. In this case, the Slink-e receives a 1A1A message on S-link Port 2 and sends the four bytes 42 1A 1A 40 from the serial port.