Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/synthead/timex_datalink_client
Write data to Timex Datalink devices with an optical sensor
https://github.com/synthead/timex_datalink_client
150 150s beepwear data data-link datalink dsi e-brain fl90 fl95 ironman link pro royal ruby sync timex triathlon upload watch
Last synced: 3 days ago
JSON representation
Write data to Timex Datalink devices with an optical sensor
- Host: GitHub
- URL: https://github.com/synthead/timex_datalink_client
- Owner: synthead
- Created: 2022-09-01T17:35:03.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2023-08-13T01:58:16.000Z (about 1 year ago)
- Last Synced: 2024-10-18T22:04:20.913Z (20 days ago)
- Topics: 150, 150s, beepwear, data, data-link, datalink, dsi, e-brain, fl90, fl95, ironman, link, pro, royal, ruby, sync, timex, triathlon, upload, watch
- Language: Ruby
- Homepage: https://rubygems.org/gems/timex_datalink_client
- Size: 972 KB
- Stars: 36
- Watchers: 3
- Forks: 2
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# 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)
## What is the Timex Datalink?
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](https://www.youtube.com/watch?v=p3Pzxmq-JLM) 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](https://github.com/synthead/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](https://github.com/synthead/timex-datalink-arduino)!
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.
## Installing Ruby and the timex\_datalink\_client gem
If you need to install Ruby, follow the
[Ruby installation instructions](https://www.ruby-lang.org/en/documentation/installation) 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:
```shell
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.
## Determining the protocol to use
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.
## Protocol documentation
Each protocol is individually documented with their own code examples:
- [Using TimexDatalinkClient with Protocol 1](docs/timex_datalink_protocol_1.md) (Timex Datalink 50 & 70, various PDAs)
- [Using TimexDatalinkClient with Protocol 3](docs/timex_datalink_protocol_3.md) (Timex Datalink 150)
- [Using TimexDatalinkClient with Protocol 4](docs/timex_datalink_protocol_4.md) (Timex Datalink 150s)
- [Using TimexDatalinkClient with Protocol 6](docs/motorola_beepwear_pro_protocol_6.md) (Motorola Beepwear Pro)
- [Using TimexDatalinkClient with Protocol 7](docs/dsi_ebrain_protocol_7.md) (DSI e-BRAIN)
- [Using TimexDatalinkClient with Protocol 9](docs/timex_ironman_triathlon_protocol_9.md) (Timex Ironman Triathlon)
## Tuning data transfer performance
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](https://github.com/synthead/timex-datalink-arduino):
```ruby
timex_datalink_client = TimexDatalinkClient.new(
serial_device: "/dev/ttyACM0",
models: models,
byte_sleep: 0.008,
packet_sleep: 0.06,
verbose: true
)
```