tashtalk/documentation/protocol.md
2021-09-13 15:33:30 -06:00

64 lines
4.9 KiB
Markdown

TashTalk UART Protocol
======================
Host to TashTalk
----------------
### Flow Control
The firmware accepts bytes over its UART receiver at all times, including while actively transmitting or receiving LocalTalk frames. When its 128-byte buffer is half-full, it deasserts the CTS (Clear To Send) line to request that the host suspend transmission of data. When the buffer falls below half-full, it reasserts CTS to request that the host resume transmission of data. The host must stop transmission soon after the CTS line is deasserted to prevent overflow of the queue. Because the firmware does not keep an entire frame to transmit in memory at once, the host must also promptly resume transmission once the CTS line is reasserted to prevent underflow of the queue. Overflow or underflow of the queue will result in undefined behavior.
### Commands
#### 0x00 - No Operation
This command byte does nothing. As such, the host can send it as many times as it likes to no ill effect. A sequence of 1024 0x00 bytes will be certain to return the chip's UART receiver to the state where it awaits a command byte.
#### 0x01 - Transmit Frame
This command byte prepares the firmware to accept a frame to transmit over LocalTalk. It is simply followed by the frame to be transmitted, byte for byte with no escape sequences.
* The host must calculate and provide the two-byte CRC sequence for the payload frame.
* The end of the frame is not explicitly marked and will be inferred from the frame data.
* Control frames, where the high bit of the third (LLAP type) byte is set, consist of five bytes.
* Data frames, where the high bit of the third (LLAP type) byte is clear, are variable length.
* The length of a data frame is defined in its fifth byte and the two least significant bits of its fourth byte.
* This number includes the length field, but not the three LLAP header bytes or the two CRC bytes.
* LocalTalk specifies that this number may not exceed 600, but the firmware does not enforce this limit.
* Data frames will be preceded by an RTS frame (generated by the firmware) and non-broadcast data frames will be transmitted in response to a CTS frame, following the algorithm as detailed in *Inside AppleTalk*.
* The firmware will await the next command byte after the transmission completes or after 32 failed attempts at transmission.
#### 0x02 - Set Node IDs
This command byte determines on which node IDs' behalf the firmware will respond to ENQ and RTS frames. It is followed by a 256-bit (32-byte) bit field, with each bit corresponding to one of the 256 possible node IDs on the LocalTalk network.
The first byte following the 0x02 command byte determines whether the firmware will respond on behalf of node IDs 0 through 7, with a 1 in the least significant bit causing the firmware to respond on behalf of node ID 0, and a 1 in the most significant bit causing it to respond on behalf of node ID 7. Likewise, the next byte determines whether the firmware will respond on behalf of node IDs 8 through 15, with the least significant bit corresponding to 8 and the most significant bit corresponding to 15, and so on up to the 32nd byte following the 0x02 command byte.
Note that 0x00 and 0xFF are not valid for use as node IDs on a LocalTalk network; the bits corresponding to these node IDs should never be set. The former may not cause any problems, but the latter will prevent any broadcast data frames from being transmitted.
TashTalk to Host
----------------
The firmware retransmits over its UART all frames going over the LocalTalk bus, regardless of source, type, or destination, excepting those that it transmits itself. It will also transmit frames that it responds to itself; it is important to bear this in mind so that, for example, duplicate responses to ENQ frames are not transmitted.
### Escape Sequences
In order to accomplish in-band signalling, the firmware uses an 0x00 byte as the first half of an escape sequence. The character following the 0x00 byte determines its meaning.
#### 0x00 0xFF - Literal 0x00
This sequence signifies a literal 0x00 byte in the frame being received.
#### 0x00 0xFD - Frame Done
This sequence signifies the end of a frame where no exceptional conditions occurred. The host should regard the data preceding it as an incoming frame, process it if its CRC is correct, and await the start of a new frame.
#### 0x00 0xFE - Framing Error
This sequence signifies a framing error - a condition in which six consecutive '1' bits are received but cannot be interpreted as a flag byte. The host should discard the data preceding it and await the start of a new frame.
#### 0x00 0xFA - Frame Aborted
This sequence signifies an aborted frame - a condition where a host had been transmitting a frame but unexpectedly stopped without a concluding flag byte. The host should discard the data preceding it and await the start of a new frame.