USB Protocol

This article describes the protocol used for USB communication between the computer and the TI-Nspire. It has been documented from TI's official linking software Computer Link Software, an analysis of USB captures of data traffic, and results of tests with a custom host implementation. This documentation may be used to build a full-featured third-party implementation of the computer program, to use features provided by the link not available from Computer Link Software's GUI, to indirectly gather additional information on the TI-Nspire hardware and software, and to discover exploitable flaws of the TI-Nspire OS's implementation of the protocol.

The documentation is currently incomplete, sometimes vague or too restrictive, and may be wrong on some points. Feel free to contribute to its enhancement and refinement. Interrogations and information based on assumptions which needs to be confirmed by a deeper analysis, more tests with Computer Link Software or tests with a third-party host implementation are formatted in indian red. Once enough tests have been made to validate or correct these parts, please edit them and remove the highlighting.

The descriptions of the packets of the protocol let sometimes appear hard-coded value, for which it is not clear whether the corresponding field is constant or may vary under certain conditions. You may edit these descriptions to document additional logic found for them. Limit cases have not all been tested: most of the time the TI-Nspire's implementation of the protocol handles them and make use of error codes. These error codes have not all been documented yet.

Overview

We will call host the participant of the communication which is the USB host, i.e. the computer for a transfer between a computer and a TI-Nspire. The host of a transfer between two TI-Nspires is probably also the USB host, determined with the Host Negotiation Protocol of USB On-The-Go. The communication model of the TI-Nspire seems to allow multiple devices to communicate simultaneously with the same host, through not yet released USB hubs, similar to TI-Navigator available for former calculator models. The TI-Nspire and the computer thus have each a dynamically assigned address used to identify the source and destination of a packet. A message sent from a source host/device to a destination host/device will be called a packet in the rest of this documentation. It is actually a protocol packet which may be transparently split into several USB packets by the USB device and host stacks if its length is greater or equal than the maximum USB packet size supported by the TI-Nspire (64 bytes).

Packets are exchanged between services of the host and the device. A service is a software module which produce and interpret a subset of packet types. A service is identified by a two bytes identifier. Each packet contains both the source and destination service identifiers. A service of a participant sending a packet choose the target service it wants to talk with. Service ids are similar to TCP ports, except that multiple source and destination services are used during the same session (more specifically for acknowledgment) as we will see.

We will use further in the documentation notations of the form: 100.0:8001->100.1:4060 where 100.0 is here the source address, 8001 the source service, 100.1 the destination address and 4060 the destination service.

After a connection reset (described further) and once a device has been declared to the host, transfers are initiated by the host and have this form (each line represents a packet):

Host: Request
Device: ACK (acknowledgment)
Device: Response
Host: ACK (acknowledgment)

What could be called a "functional request" (for example "transfer a file") may use serveral exchanges of this type. The host and the device have stateful sessions and can keep track of the current state between these exchanges (for example when listing the content of a directory, which requires one pair of request/response for each file, the device keeps track of the current file).

Packet format

Packets send by a host or a device have the same format. A packet has a 16 bytes header and may have an optional data part of variable length. A packet is at most 270 bytes long, so the data part is at most 254 bytes long.

54 FD SA SA SS SS DA DA DS DS DC DC SZ AK SQ CK [data part]

The different fields of the header part are:

• 54 FD: constant
• SA SA: source address
• SS SS: source service id
• DA DA: destination address
• DS DS: destination service id
• DC DC: checksum of the data part
• SZ: size of the data part
• AK: used for acknowledgment packets, 00 for other packets.
• SQ: sequence number
• CK: checksum of the header: the sum of the preceding bytes modulo 256

Here is additional information for the fields not obvious and not described before.

Service identifiers

The host which always initiate the transfers (except address assignment during described further) choose the service id it uses for standard (not acknowledgment) packets. It will be the source service id that appears in the packets sent to the device, and the destination service id of the responses of the device. Any non-standard service id may be chosen. Computer link Software uses service id greater or equal than 0x8001. The service id must be chosen before starting to exchange packets with a new service of the device. When using another service of the device, the host must disconnect itself from the previous service (this process is described further), and choose a new local service id for the subsequent packets for the new target service. Each time a new host service id is chosen, it must be different that the previous ones. The device won't answer to packets with a source service id which matches a host service which has previously asked to disconnect itself. The same service ids can be reused only once the connection with the device is reset. At each generation Computer Link Software increments by one the service id to ensures unique generation, but this is actually not mandatory.

The identifiers (in hexadecimal) of the currently known standard services on the device side are:

• 00FF: packet reception acknowledgment
• 4003: device address request
• 4004: service tuning (?)
• 4020: device information
• 4021: screen capture
• 4041: service activity (?)
• 4050: authentification (?)
• 4054: hub connection (?)
• 4060: file management
• 4080: OS installation
• To be completed

The identifiers of the services on the host side are:

• 00FF: packet reception acknowledgment
• 4003: device address assignment
• 40DE: service deconnection
• To be completed

Sequence number

Sequence numbers are solely used for proper acknowledgment of packets. Each participant manages itself the generation of the sequence numbers for the packets it sends (a communication between a computer and a TI-Nspire brings into play two sequences). Each packet (except acknowledgment packets, see further, and except in the case of an overflow) has it own sequence number. The number is incremented each time a packet is sent (do they really need to be consecutive?). The generation is common for all the services of a participant, i.e. two consecutive packets sent by/to different services will have consecutive sequence numbers. The sequence number is reinitialized to 1 after a connection reset (does the host really have to make it start from 1?). The sequence number which follows 255 is 1, 0 is never used (is there really a reason for this are does it still work with 0?).

Acknowledgment

Whether send by the host or a device, an acknowledgment packet always have 0x00FF as source service id. The destination service id must be the source service id of the previously received packet the participant acknowledges. The sequence number must be the same as the one of the packet acknowledged. The field AK of the header must contain 0x0A (is there a special value for NACK packets? Do NACK packets really exist?). The 2 byte-long data part must contain the destination service id of the packet acknowledged (i.e. a local service id). Here is an example of an acknowledgment packet sent by a TI-Nspire to a computer:

64.1:00FF->64.0:8001 AK=0A SQ=02 
data part: 40 60

Here the device acknowledges the reception of a packet sent by the service 8001 of the host, which had 02 as sequence number, and was sent to the service 4060 of the TI-Nspire.

The TI-Nspire will acknowledge the reception of invalid packets with minor errors (for instance with a bad header or data checksum, or with a duplicate sequence number), but the target service won't take the packet into account.

Data part checksum

The 2 byte-long checksum is more or less a CRC checksum. The checksum is 00 00 if there is no data part in the packet. Here is an implementation in Python of the algorithm:

def checksum(data):
    acc = 0
    for byte in data:
        first = (ord(byte) << 8) | acc >> 8
        acc = acc & 0xFF
         second = (((acc & 0xF) << 4) ^ acc) << 8
       third = second >> 5
        acc = third >> 7
        acc = (acc ^ first ^ second ^ third) & 0xFFFF
    return acc

# A few examples
assert checksum('\x00\xFF') == 0xFF00
assert checksum('\x05\x00\x00') == 0x57AD
assert checksum('\x20\x00\x00\x00\x00\x00\x00\x00\x05\x01\x00') == 0xA095

Data part

The format and interpretation of the data part depends on the source and destination services for the packet, and on the current state of the exchange. Multiple-bytes integers that appear in the data part (for example sizes are service identifiers) are in big endian (most significant byte first). Strings are terminated with a null byte.

Common packets with a data part are those which indicates the success or failure of the processing initiated by the previous request packet (or response packet in the case of a processing by the host). These packets should not be confused with packets acknowledging the reception: for example a request packet can be received successfully, but its data part can contain incorrect data - the device would here return an ACK packet and then a failure packet. These success and failure packets are 2 bytes long, starts with 0xFF and are followed by 0x00 in case of success, or an error code in case of failure. The error code is not specific to a type of request (but is it specific to a service?), some codes are reused when they have the same meaning (for example in the case of the file management service).

Testing

Computer Link Software

Computer Link Software's functions can be tested on the command line using the testing code embedded in the Java binding NavNet.jar for the low-level connector. TESTNUM is the number of the test to run (remove the echo at the beginning and the file redirection at the end the first time to understand how it works). The command line to use with Cygwin on Microsoft Windows is:

$ echo $TESTNUM | java -cp "C:\Program Files\TI Education\TI-Nspire Computer Link\lib\navnet.jar" com.ti.eps.navnet.main  >logs 2>&1

The logs of both the native NavNet connector and the Java testing program will be written to the output file. The verbosity of the native logs can be tuned in Main.class:

NavNet.init("-c X -d X -p connectors"); // X (initially 4) should be between 0 (no logs) and 5 (finest)

USB traffic analysis

Any suggestions of a free USB analyzer for Microsoft Windows?

TODO

• Move the section on USB descriptors here
• Find the differences between PC/TI-Nspire transfers and TI-Nspire/TI-Nspire transfers.
• Test and document the services available