TI-89 Link Protocol Guide - Silent Variable Transfers

##

Silent Variable Transfers

"Silent Linking" is a capability that Texas Instruments built into the TI-83, TI-83+, TI-92, TI-89, TI-92 and TI-92+. It enables the calculator to transfer data to and from a computer without any special preparation required on the calculator end. The only drawback to the silent linking method is that when using this protocol, the calculator will automatically overwrite any data in a variable that has the same name as one being sent to it. Any program that incorporates silent linking must check for this; otherwise data may be lost.

Because silent linking protocols are one-sided (i.e. the user interaction is solely on the computer), there are three different transfer sequences required. First a directory listing must be downloaded from the calculator in order to choose the variables to transfer or to check for duplicate names and out-of-memory conditions. Then, if variables are to be downloaded, a variable request action must be initiated by the computer. Finally, if variables are to be uploaded, a request-to-send action must be sent by the computer.

#### Directory Listing

A directory listing is a list of all user variables in the calculator's memory and a number specifying how many bytes of free memory are left.
On the TI89/92+/V200 calculator, the directory list is done in 2 phase:
- the first, the computer request a main directory list which lists only the folders (and the FLASH apps, too (see note))
- the second, the computer request a local directory list in each folder listed by the phase 1.

The protocol for requesting a directory listing is shown below. For information on packet formats, click here.

Step | Direction | Packet
--- | --- | ---
1 |  |  |  | REQ with data type=1Ah (see note under Type ID's for variable header format) and with a particular filter.
2 |  | ACK
3 |  | VAR - a variable information packet (see format below)
4 |  | ACK
5 |  | CTS
6 |  | ACK
7 |  | DATA - a variable entry (see format below).
8 |  | ACK
9 |  | CONT or EOT - if CONT, then go to step 4.
10 |  | ACK

The request has the following format according to the operation (global directory list or local directory list):

Offset | Length | Description
--- | --- | ---
0 | 4 bytes | Always {00h, 00h, 00h, Fl} where Fl is a vartype filter. This allow to only list variable of a given type. It is always 1Fh (directory type) when a global dirlist is required or 1Bh when a local directory list is required in a particular folder.
4 | 1 bytes | This byte always has a value of 1Ah (directory list request).
5 | 1 byte | The length, in characters, of the name field. Here, it is always 0.

The data in the variable information packet has the following format:

Offset | Length | Description
--- | --- | ---
0 | 4 bytes | Unknown.
4 | 1 bytes | This byte always has a value of 1Ah (directory list type).
5 | 1 byte | The length, in characters, of the name field. Always 04h.
6 | 4 bytes | The name of the current folder. Always "main".
10 | 1 byte | Unknown, always 03h.

The var section (data packet) is made up of several entries.

Offset | Length | Description
--- | --- | ---
0 | 4 bytes | These four bytes always have a value of 0.
4 | n bytes | Data section: variables, FLASH applications and folder entries are listed here.

Data section is made up of several blocks which take the following format (always 18 bytes long):

Offset | Length | Description
--- | --- | ---
0 | 8 bytes | Variable name padded with NULL chars if necessary.
8 | 1 byte | Variable type ID.
9 | 1 byte | Variable attribute: 00h = unlocked, 01h = locked, 03 = archived.
10 | 4 bytes | If folders are listed (phase 1), this field contains the number of variables in this folder. If variables are listed (phase 2), this field contains the length, in bytes, of the variable data for this variable without the extra four bytes at the beginning of the data packet.
14 | 8 bytes | (V200 only) These eight bytes always have a value of 0.

Note:
- with AMS < 2.08 : FLASH applications entries are listed both in phase 1 and phase 2,
- with AMS >=2.08: FLASH applications entries are listed only in phase 2.

Example:

PC: | `08 A2 06 00 00 00 00 1F 1A 00 39 00` | Global directory request (phase 1)
TI: | `98 56 00 00` | Acknowledgement of request
| `98 06 0B 00 7E 00 00 0E 1A 04 6D 61 69 6E 03 52 02` | Variable header - complete directory starting with "main".
PC: | `08 56 00 00` | Acknowledgement of header
| `08 09 FF FF` | Clear to send
TI: | `98 56 00 00` | Acknowledgement of clear to send
| `98 15 12 00 00 00 00 00 6D 61 69 6E 00 00 00 00 1F 00 00 00 00 03 66 13` | Variable entry - Unlocked folder "main" with threevariable
PC: | `08 56 00 00` | Acknowledgement of variable entry
TI: | `98 92 00 00` | Continue - more variables in directory
PC: | `08 56 00 00` | Acknowledgement of continue
PC: | `08 68 00 00` | Check if TI is ready
TI: | `98 92 00 00` | The calc is ready
PC: | `08 A2 0A 00 00 00 00 1B 1A 04 6D 61 69 6E DE 01` | Local dirlist request in folder 'main' (phase 2)
TI: | `98 56 00 00` | Acknowledgement of request
TI: | `98 06 0B 00 38 00 00 0E 1A 04 6D 61 69 6E 03 A6` | Variable entry - "main" folder
PC: | `08 56 00 00` | Acknowledgement of continue
| `08 09 FF FF` | Clear to send
TI: | `98 56 00 00` | Acknowledgement of clear to send
| `98 15 3C 00 00 00 00 00 6D 61 69 6E 00 00 00 00 1F 00 00 00 00 03 78 00 00 00 00 00 00 00 00 00 05 00 00 00 79 00 00 00 00 00 00 00 00 01 05 00 00 00 7A 00 00 00 00 00 00 00 00 03 05 00 00 00 45 03` | Folder entry - Folder "main" Variable entries - Normal variable "x", Locked variable "y" and Archiveded variable "z"
PC: | `08 56 00 00` | Acknowledgement of variable entry
TI: | `98 92 00 00` | End of transmission - no more variables
PC: | `08 56 00 00` | Acknowledgement of EOT

#### Requesting a Variable

The protocol for requesting and receiving a variable from the calculator is shown below.

Step | Direction | Packet
--- | --- | ---
1 |  |  |  | REQ with expected header including the folder name, if necessary
2 |  | ACK (see note below)
3 |  | VAR (specifing the size without the extra four bytes) with actual header and no folder name
4 |  | ACK
5 |  | CTS
6 |  | ACK
7 |  | DATA with an extra four bytes at the beginning of the packet
8 |  | ACK
9 |  | EOT
10 |  | ACK

Note: If the requested variable does not exist, step 2 will be the end of the transfer.

As with manual transfers, the data section contains the variable data. For information on variable formats, click here.

Example:

PC: | `08 A2 0C 00 00 00 00 00 00 06 6D 61 69 6E 5C 79 80 02` | Request Known Variable "x" in the "main folder
TI: | `98 56 00 00` | Acknowledgement of request
| `98 06 08 00 05 00 00 00 00 01 79 00 7F 00` | Variable Header: Real "x" (locked)
PC: | `08 56 00 00` | Acknowledgement of variable header
| `08 09 FF FF` | Clear to send variable
TI: | `98 56 00 00` | Acknowledgement of CTS
| `98 15 09 00 00 00 00 00 00 03 0D 01 1F 30 00` | Variable data: x=12
PC: | `08 56 00 00` | Acknowledgement of variable data
TI: | `98 92 00 00` | End Of Transmission
PC: | `08 56 00 00` | Acknowledgement of EOT

#### Sending a Variable

There are two ways to send a variable: with a folder name (such as 'main\str') or without a folder name (such as 'str'). If no folder is specified, the variable is sent to the current directory on the calculator.

The protocol for sending a variable to the calculator is shown below.

Step | Direction | Packet
--- | --- | ---
1 |  |  |  | RTS (specifing the size with the extra four bytes)
2 |  | ACK
3 |  | CTS or SKIP/EXIT (see note below)
4 |  | ACK
5 |  | DATA
6 |  | ACK
7 |  | EOT - if there are several variables to transmit, steps 7 and 8 can be skipped until the last variable.
8 |  | ACK

Note: If the calculator sends a MEM packet in step 3, it does not have enough free memory to accomodate the variable. In this case, step 3 will be the end of the transfer.

Again, the data section contains the variable data.

Example: (to do, my sample file is corrupted (strange, grrr!))

PC: | `09 C9 0D 00 05 00 00 00 00 06 6D 61 69 6E 5C 78 03 87 02` | Request to send Real "x" in the "main" folder
TI: | `89 56 00 00` | Acknowledgement of request
| `89 09 00 00` | Clear to send variable
PC: | `09 56 00 00` | Acknowledgement of CTS
| `09 15 0C 00 00 00 00 00 00 03 0C 01 1F 2F 00` | Variable data: 12
TI: | `89 56 00 00` | Acknowledgement of data
PC: | `09 92 00 00` | End Of Transmission
TI: | `89 56 00 00` | Acknowledgement of EOT

Manual Transfers | Table of Contents | Backups

Site maintained by Romain Liévin (roms@lpg.ticalc.org) and Tim Singer (tsinger@gladstone.uoregon.edu)