Timex Datalink library for Ruby

Here is a fully-tested, feature-complete, and byte-for-byte perfect reimplementation of all the various Timex Datalink client software as a Ruby library! This library supports every Datalink device manufactured, which includes protocols 1, 3, 4, 6, 7, and 9!

These devices have been tested to work with this library:

• Timex Datalink 50 (protocol 1)
• Timex Datalink 70 (protocol 1)
• Timex Datalink 150 (protocol 3)
• Timex Datalink 150s (protocol 4)
• Timex Ironman Triathlon (protocol 9)
• Motorola Beepwear Pro (protocol 6)
• Franklin Rolodex Flash PC Companion RFLS-8 (protocol 1)
• Royal FL95 PC Organizer (protocol 1)
• DSI e-BRAIN (protocol 7)

The Timex Datalink is a watch that was introduced in 1994 that is essentially a small PDA on your wrist. The early models (supported by this software) have an optical sensor on the top of the face that receives data via visible light.

The original data transfer method involves drawing patterns of lines on a CRT monitor for the watch to receive with its optical sensor. CRTs use electron guns that draw scan lines one-by-one from top to bottom, then they return to the top in preparation for the next frame. This means that the electron guns turn on when they're drawing a white line, and and turn off when they're drawing the black background. This produces flashing light as the graphics are drawn, which is ultimately received by the optical sensor and decoded by the Timex Datalink device.

Have a CRT monitor? Use this library with timex_datalink_crt to transfer data with your CRT!

For laptop users, Timex also offered the Datalink Notebook Adapter. Instead of using a CRT monitor, the Notebook Adapter simply flashed a single LED light. This adapter is fully supported by the Timex Datalink software, and sends the same data as a CRT.

This library communicates with the Datalink Notebook Adapter to emit data to your Timex Datalink watch. Don't have a Notebook Adapter? Use a Teensy LC instead!

As a fun tidbit, these watches are flight certified by NASA and is one of four watches qualified by NASA for space travel! Here's a shot of James H. Newman wearing a Datalink watch on the Space Shuttle for STS-88!

In addition, the Datalink protocol is also used in some other watches, organizers, and toys, i.e. the Motorola Beepwear Pro, Royal FL95, Tiger PDA2000, Franklin Rolodex Flash PC Companion RFLS-8, and DSI e-BRAIN 69006.

If you need to install Ruby, follow the Ruby installation instructions first. The oldest supported version is 3.1.0, so make sure to have Ruby 3.1.0 or greater installed.

Then, with Ruby installed, run this command to install the timex_datalink_client gem:

gem install timex_datalink_client

You're done! From here, continue reading the documentation for which protocol to use and follow the code examples below.

On Timex Datalink watches, press the MODE button until "COMM MODE" is displayed. "COMM READY" will appear. This is sometimes accompanied by a version number. Use the table below to identify the protocol.

Watch display	Protocol compatibility
	Use protocol 1 models in TimexDatalinkClient::Protocol1
	Use protocol 3 models in TimexDatalinkClient::Protocol3
	Use protocol 4 models in TimexDatalinkClient::Protocol4
	Use protocol 9 models in TimexDatalinkClient::Protocol9
	Use protocol 6 models in TimexDatalinkClient::Protocol6

During data transmission, the "start" packet of each protocol will announce the protocol number to the device. If the protocol doesn't match the device, the screen will display "PC-WATCH MISMATCH" and safely abort the data transmission.

Most non-Timex devices use protocol 1, so start with protocol 1 if the protocol can't be identified.

Each protocol is individually documented with their own code examples:

• Using TimexDatalinkClient with Protocol 1 (Timex Datalink 50 & 70, various PDAs)
• Using TimexDatalinkClient with Protocol 3 (Timex Datalink 150)
• Using TimexDatalinkClient with Protocol 4 (Timex Datalink 150s)
• Using TimexDatalinkClient with Protocol 6 (Motorola Beepwear Pro)
• Using TimexDatalinkClient with Protocol 7 (DSI e-BRAIN)
• Using TimexDatalinkClient with Protocol 9 (Timex Ironman Triathlon)

After every byte is sent to the watch, a small delay is necessary before advancing to the next byte. This gives the watch time to decode and store the incoming data. In addition, an additional delay is necessary after sending a packet of data (bytes that represent a piece of data, i.e. an alarm).

The byte and packet sleep time defaults to the same rate of the Timex Datalink software for parity. This is 0.025 seconds per byte, and 0.25 seconds per packet. These two sleep times can be tuned with the byte_sleep and packet_sleep keywords when creating a TimexDatalinkClient instance.

In practice, much smaller values can be used for a much higher data rate. In testing, these values seem to work reliably with the Teensy LC Notebook Adapter:

timex_datalink_client = TimexDatalinkClient.new(
  serial_device: "/dev/ttyACM0",
  models: models,
  byte_sleep: 0.008,
  packet_sleep: 0.06,
  verbose: true
)