Protocol
Protocol version 0.3.2
DMX-84 uses a simple communication protocol wrapped in the TI graphing calculator two-wire link protocol. This communication protocol allows the calculator to communicate with the Arduino to send commands, update channel data, etc. It is designed with maximum transfer speed and data efficiency in mind to minimize the drawbacks of limited processing power and memory space.
Packets are sent over the standard TI graphing calculator 2-wire link cable. Other cable types are not currently supported; however, USB support may be added in the future. Details of the physical layer are available in the TI Link Guide.
The Data Link layer is implemented as the standard TI-83/84 link protocol. The TI-84 OS implementation is the reference implementation for the development of this project. See the TI Link Guide for details on the TI Link Protocol.
The TI Link Protocol does not provide networking capabilities because only two devices can be connected at once. It does, however, provide a method for identifying machine types. See the TI Link Guide for a list of machine IDs.
Having been wrapped by the TI Link Protocol for the lower layers, the DMX-84 protocol is exposed at the transport layer.
Each packet begins with a single byte specifying the message type. Depending on the type, data may follow. Each message type denotes the format of the data that follows (if any), including whether there must be a data length specified.
The DMX-84 protocol also handles initiation and termination of communication sessions. All calculator packets are rejected by the Arduino until it receives a ready check packet. All non-restricted commands are then accepted until it receives either a shutdown command, at which time it will stop listening for messages, or a no-op command, at which time it will allow executing restricted commands for 1 second.
Layers above the session layer are not in the scope of the DMX-84 protocol.
Packets are wrapped by the TI Link Protocol, documented in the TI Link Guide. Packets are generally sent as bulk data transfers, command ID 0x15, with the exception of the clear to send, ready check, acknowledge, negative acknowledge, and error packets.
If the received TI packet is marked as bulk data, then the bulk data it contains is a DMX-84 command. A command consists of a single command byte followed by data if specified by the command. There are three types of DMX-84 commands: single commands, fixed width commands, and variable width commands. Single commands naturally contain one byte: the command byte. Fixed width commands contain one command byte and a fixed number of data bytes or parameters. Variable width packets contain one command byte, one or more parameters if applicable, one length byte, and a number of data bytes specified by the length.
When the Arduino is finished booting, it sends a clear-to-send packet to the calculator. The calculator should attempt to receive and acknowledge this if it is known that the Arduino has started booting after the calculator program has started (for example, if the calculator is providing power to the Arduino).
Next, the calculator must send a ready check packet and receive acknowledgment before any further communication can occur.
The calculator can then send bulk data packets following the format specified below. Every bulk data packet is acknowledged by the Arduino. If a command byte will result in a reply from the Arduino, the calculator must be ready to receive that reply to prevent a link error. Note that the Arduino's reply always begins with the command byte it is responding to. This means that to receive a reply, the calculator must be listening for one byte more than the expected reply length. For example, the Uptime command replies with 4 bytes, but the calculator must receive 5 bytes to accommodate the extra command byte.
In order to initiate shut down or reset, the calculator must first
put the Arduino in restricted mode by sending 0x01. This will enable
access to the shut down and reset commands for one second before
reverting to regular mode. When shutting down or resetting, the Arduino
will send an end of transmission packet immediately before it enters
sleep mode or resets.
If no commands are received within 5 hours and 59 minutes, the Arduino will send a warning packet to the calculator. This is the only unsolicited message the Arduino can send. If the Arduino doesn't receive a command within 60 seconds, it will automatically shut down to save the calculator's batteries in case the calculator is powering the Arduino.