SoundOptions currently uses hourly_chimes:

This is inconsistent with the Timex Datalink software:

Update this to use hourly_chime instead.

Here's some example data:

Bytes from above:

11 43 01 00 14 00 00 01 1C 1D 24 1A 1D 1B 24 8C 22
11 43 02 00 14 00 00 02 17 0D 24 1A 1D 1B 24 0A DF
11 43 03 00 14 00 00 11 0A 15 0F 1D 12 16 0E 75 C2
11 43 04 00 14 00 00 03 1B 0D 24 1A 1D 1B 24 00 DB
11 43 05 00 14 00 00 04 1D 11 24 1A 1D 1B 24 3B FC

Mention that protocol 9 is supported, and include Timex 78701 Ironman Triathlon as a tested device.

Add Protocol1::Time to sync time data for protocol 1. This will support syncing time for Datalink 50 and Datalink 70 watches.

This can be pulled out:

The time zone that is visible on the watch is currently hard-coded to follow whatever is set on the time param passed to the Time model:

The time zone name is simply arbitrary text of 3 characters, and there isn't any reason why this needs to be a time zone name.

Allow the time zone name to be a user-issued field.

This explicitly truncates the phone number to 12 places:

However, phone_chars_for does this already, so there's no need to truncate this value.

Remove the needless truncate logic from Eeprom::PhoneNumber

As of now, SoundTheme only accepts data from SPC files, which prefixes the sound data with a file header.

Allow the user to submit raw sound data in addition to the entire file contents of a sound file.

Add EEPROM data in protocol 1 format.

There's a good chance that the EEPROM data will be very similar if not identical to the EEPROM data from protocol 3: lib/timex_datalink_client/eeprom

Every string in the Datalink 150 has a maximum length, but many strings in the lib are not truncated, like so:

(the above uses these methods)

It's possible to pass strings that are longer than the possible limit and write invalid data.

Truncate these strings to their allowed limits to prevent writing invalid data.

As of now, Eeprom's appointment_notification parameter is not very clear:

The Timex Datalink software uses set values from a drop-down list that appear to be multiples of 15 minute values, and 0xff is used for no notification. Determine exactly what these are, and possibly add some constants that the user can use instead of what's ultimately a magic number.

This is the documentation for increasing data performance in README.md as of this writing:

On the Timex 70301 (Datalink 50) and Franklin Rolodex Flash PC Companion RFLS-8 (which are both protocol 1 devices), the 0.006 byte_sleep option is a little too aggressive and doesn't seem to work most of the time. I haven't seen 0.008 fail with these devices yet with any device, and this difference is hardly noticeable.

Update README.md to use a byte_sleep value of 0.008 in the performance tuning section.

Here are CHARS and EEPROM_TERMINATOR:

chars_for will happily convert ] in strings to value 63, which is the last value of CHARS:

This is fine, except when packing strings in eeprom_chars_for, 63 (which is 0x3f) is expected to be the terminator. This means that this method will add EEPROM string terminators in place of ]:

On the Timex Datalink 150, strings with this value simply end whenever this value is seen (as opposed to displaying the "small square" special character).

It's impossible to display the "small square" character in EEPROM strings, and its value produces unpredictable results. Make eeprom_chars_for replace ] with some other placeholder character (i.e. an empty space).

If a model uses a mixture of uppercase and lowercase characters in their strings, i.e.

TimexDatalinkClient::Eeprom::PhoneNumber.new(
  name: "Marty McFly",
  number: "1112223333",
  type: "h"
)

...then the char_for helper will not match some of the uppercase characters:

The Datalink 150 has no lowercase characters, and is case-insensitive. Make all strings case-insensitive so that uppercase and lowercase characters transfer correctly to the watch.

Now that protocol 9 is feature-complete, update README.md to include usage examples for protocol 9.

This spec ensures that an uppercase "H" type will produce a correct packet. This is currently being tested with "h":

The current models only support the Datalink protocol 3. Protocol 1 (on the Timex Datalink 50 and 70) has different packet formats for most models, so it'd be best to namespace the protocols explicitly.

This is the current model pattern that exists now:

time1 = Time.now
time2 = time1.dup.utc

models = [
  TimexDatalinkClient::Sync.new(length: 200),
  TimexDatalinkClient::Start.new,
  TimexDatalinkClient::Time.new(zone: 1, is_24h: false, date_format: 2, time: time1),
  TimexDatalinkClient::Time.new(zone: 2, is_24h: true, date_format: 2, time: time2),
  TimexDatalinkClient::End.new
]

client = TimexDatalinkClient.new(
  serial_device: "/dev/ttyACM0",
  models: models
)

client.write

Here is what I propose:

time1 = Time.now
time2 = time1.dup.utc

models = [
  TimexDatalinkClient::Protocol3::Sync.new(length: 200),
  TimexDatalinkClient::Protocol3::Start.new,
  TimexDatalinkClient::Protocol3::Time.new(zone: 1, is_24h: false, date_format: 2, time: time1),
  TimexDatalinkClient::Protocol3::Time.new(zone: 2, is_24h: true, date_format: 2, time: time2),
  TimexDatalinkClient::Protocol3::End.new
]

client = TimexDatalinkClient.new(
  serial_device: "/dev/ttyACM0",
  models: models
)

client.write

Then, for protocol 1 devices, a pattern like this could be used. Of course, it would be tweaked to accommodate whatever differences there are between protocol 3 and protocol 1.

time1 = Time.now
time2 = time1.dup.utc

models = [
  TimexDatalinkClient::Protocol1::Sync.new(length: 200),
  TimexDatalinkClient::Protocol1::Start.new,
  TimexDatalinkClient::Protocol1::Time.new(zone: 1, is_24h: false, date_format: 2, time: time1),
  TimexDatalinkClient::Protocol1::Time.new(zone: 2, is_24h: true, date_format: 2, time: time2),
  TimexDatalinkClient::Protocol1::End.new
]

client = TimexDatalinkClient.new(
  serial_device: "/dev/ttyACM0",
  models: models
)

client.write

Add SoundOptions model for protocol 9. It looks like this in the Ironman software:

From a logic analyzer, here are the packets for start, options, and end with no sounds on:

07 20 00 00 09 06 7E
05 32 01 A1 C4
04 21 D8 C2

...with hourly chime on:

07 20 00 00 09 06 7E
05 32 02 A0 84
04 21 D8 C2

...and button beep on:

07 20 00 00 09 06 7E
05 32 03 60 45
04 21 D8 C2

It looks like the first "data" byte for packet with command 0x32 contains bitmask values for the two options. The hourly chime appears to be 0b01 and the button keep appears to be 0b10.

With the discovery of the unique EEPROM data structure in protocol 9, and the addition of lib/timex_datalink_client/protocol_9/eeprom, it makes sense to move the shared EEPROM models in lib/timex_datalink_client/eeprom to the protocol 1 and 3 directories. Even though they would be copies, this adds consistency to the class layout 👌

Here are some alarms in the Ironman software:

Here's the data from the above, sans the sync bytes:

07 20 00 00 09 06 7E
1A 50 01 00 00 00 00 01 01 02 03 04 05 06 07 08 09 00 01 02 03 04 05 06 52 1B
1A 50 02 00 03 00 04 00 0A 15 0A 1B 16 24 24 02 24 24 24 24 24 24 24 24 7A DF
1A 50 03 03 00 04 05 00 0A 15 0A 1B 16 24 24 03 24 24 24 24 24 24 24 24 EA D5
1A 50 04 00 00 00 00 00 0A 15 0A 1B 16 24 24 04 24 24 24 24 24 24 24 24 F2 17
1A 50 05 00 00 00 00 00 0A 15 0A 1B 16 24 24 05 24 24 24 24 24 24 24 24 AE CA
1A 50 06 00 00 00 00 00 0A 15 0A 1B 16 24 24 06 24 24 24 24 24 24 24 24 4B AD
1A 50 07 00 00 00 00 00 0A 15 0A 1B 16 24 24 07 24 24 24 24 24 24 24 24 17 70
1A 50 08 00 00 00 00 00 0A 15 0A 1B 16 24 24 08 24 24 24 24 24 24 24 24 A7 8E
1A 50 09 00 00 00 00 00 0A 15 0A 1B 16 24 24 09 24 24 24 24 24 24 24 24 FB 53
1A 50 0A 00 00 00 00 00 0A 15 0A 1B 16 24 01 00 24 24 24 24 24 24 24 24 C4 5B
04 21 D8 C2

While working on #57, I discovered that the EEPROM models between protocol 1 and protocol 3 are identical.

To do this, these things need to be done:

• Move lib/timex_datalink_client/protocol_3/eeprom to lib/timex_datalink_client/eeprom
• Move all classes in Protocol3::Eeprom to Eeprom
• Move tests and update them to use Eeprom from the base TimexDatalinkClient class

There's a common Sync class and a common End class. There are also Sync and End classes that inherit these classes, i.e. this file.

While this reduces duplicate code a bit, it would make more sense to have copies of these classes in each of the protocol classes. It's cleaner, and makes the collection of classes make more sense.

TimexDatalinkClient#initialize models param doesn't include Protocol1 model types in YARDoc:

Add the Protocol1 classes as accepted types to #initialize.

The Ironman software seems to have shared EEPROM storage like protocols 1 and 3:

It's more limited: it only contains a single chrono option and phone book entries, but this probably means that an Eeprom class needs to be added for protocol 9, too.

This is the character map for most strings:

The uppercase characters are problematic because they actually map to special characters on the Datalink 150. This is a smell, because a user might submit a string with uppercase characters with the intent of having readable text on the watch.

Change the map of uppercase characters to special characters that are not [A-Za-z].

Add Sync, Start, and End classes for protocol 9. This is for the Timex 78701 Ironman Triathlon watch.

After some testing, I discovered that the original Timex Notebook Adapter requires a "ping" byte (0x78, or "x") for the adapter to work. Without it, the LED blinks once in response to received packets, but it does not emit the sequence of flashes used in the Datalink protocols.

In the gemspec, there's a short description that doesn't really have much useful information in it.

The gemspec requires a summary but not a description, so this can just be removed 👍

There are a few trailing commas:

There are quite a few places where it's possible to submit bad data. Sometimes the program will raise uncaught exceptions, and other times, it will render packets with invalid data in it.

Convert invalid data to similar acceptable data when possible. Where it isn't, validate the data and raise custom exceptions classes.

There are a few contexts that look like this that are missing the escaped quote at the end of the description:

Add the escaped quotes to these spec descriptions.

Related to #49.

After picking at time data on protocol 1 a bit, I discovered that time is synced differently than protocol 3.

Protocol 3 syncs everything related to a time:

However, it looks like protocol 1 syncs time data and time name data (typically for time zones) separately. Here is UART-decoded data from the Timex Datalink software sending time data only (with sync bytes omitted):

07 20 00 00 01 C0 7F                    # start protocol 1 data
0D 30 02 14 23 09 0B 16 06 03 01 2F B0  # zone 1 time
0D 30 01 12 23 09 0B 16 06 03 01 F5 24  # zone 2 time
08 31 01 19 0D 1D 2E 68                 # zone 1 time name
08 31 02 0C 0D 1D AE 79                 # zone 2 time name
04 21 D8 C2                             # end data

Add a TimeName model to accommodate for this separate packet type.

Add sync, start, and stop models for protocol 1. This will be the foundation of transferring data to Timex Datalink 50 and Datalink 70 watches that use protocol 1.

The library takes a little while to write the serial data due to the required sleep statements. It'd be great to have an option to enable verbose output to show the data being sent 👌

Alarm currently expects explicit 1 or a 0 as values for audible. These should be true and false instead.

Add Alarm model for protocol 1!

In the Timex Datalink software, it looks like this:

The protcol 1 format also supports daily, monthly, and yearly alarms (protocol 3 only supports daily alarms):

With the data above, this is what comes out of the Datalink software (taken from a logic analyzer, sync bytes omitted):

07 20 00 00 01 C0 7F
12 50 01 00 00 09 15 0A 15 0A 1B 16 24 01 24 01 02 3D
12 50 02 00 00 00 0B 0A 15 0A 1B 16 24 02 24 01 FD 80
12 50 03 00 00 00 00 0A 15 0A 1B 16 24 03 24 01 19 A0
12 50 04 00 00 00 00 0A 15 0A 1B 16 24 04 24 01 1F 17
12 50 05 00 00 00 00 0A 15 0A 1B 16 24 05 24 01 1E 46
04 21 D8 C2

Example data (selected text only):

Bytes from above:

20 70 02 40 05 A9 22 5F E6 B2 E8 BB E7 B2 E8 BB E7 BB E8 B2 E7 B2 5C A3 09 26 ED 15 A9 01 32 CD
14 70 02 5A A9 02 14 A9 B6 A9 A4 07 47 B7 A9 CC 74 6F C6 FC
06 23 02 40 D2 F1
05 60 01 C1 F9
13 61 01 00 0E 00 D6 32 00 0A 0A 0A 0A 0A 0A 0A 0A D4 C3
04 62 29 83

NotebookAdapter is hard-coded to use these values:

They are used here:

These values were set to match the Timex Datalink software. However, after some experimenting, these sleep values can be much, much shorter and still reliably transfer data to a Datalink 150.

Add support to allow user-tunable values.

Here's some example data (two screenshots due to scrolled content:

Bytes from above:

20 70 02 40 05 A9 22 5F E6 B2 E8 BB E7 B2 E8 BB E7 BB E8 B2 E7 B2 5C A3 09 26 ED 15 A9 01 32 CD
14 70 02 5A A9 02 14 A9 B6 A9 A4 07 47 B7 A9 CC 74 6F C6 FC
06 23 02 40 D2 F1
05 60 06 03 B8
20 61 01 00 0E 00 16 02 08 24 0C 11 1B 18 17 18 24 0E 21 43 65 87 09 BC 99 B3 71 D8 45 06 EB DD
20 61 02 3F 0E 21 43 65 87 09 CF 99 B3 71 D8 45 06 3F 13 21 43 65 87 09 21 F1 40 14 C6 81 0B 44
20 61 03 24 40 20 0C 44 61 FC 13 21 43 65 87 09 21 F1 40 14 C6 81 24 40 20 0C 44 61 FC 13 F1 B2
20 61 04 99 99 99 99 99 99 71 92 24 49 92 24 49 92 24 49 92 FC 13 99 99 99 99 99 99 71 92 BB 84
20 61 05 24 49 92 24 49 92 24 49 92 FC 13 99 99 99 99 99 99 71 92 24 49 92 24 49 92 24 49 E3 27
1A 61 06 92 FC 13 99 99 99 99 99 99 71 92 24 49 92 24 49 92 24 49 92 FC 1E 32
04 62 29 83

As of this writing, protocol 1 is fully supported by this library! It's time to update README.md to reflect how protocol 1 devices are supported 🎉

SoundOptions currently expects explicit 1 or a 0 as values for hourly_chimes and button_beep. These should be true and false instead.

The .gemspec has this value for #homepage:

This makes GitHub display the files and README.md of the default "main" branch, which may include unshipped changes.

Change this to use the URL to show the files from the latest tag instead.

Add Time and TimeName models for protocol 9. This should work with the Timex 78701 Ironman Triathlon watch.

It'd be great to add YARDoc documentation for public methods: https://yardoc.org/

This would allow the public documentation to be clearer, also: https://www.rubydoc.info/gems/timex_datalink_client/0.1.0

It'd also be great to add a yard-junk CI check: https://github.com/zverok/yard-junk

While working on #57, I discovered that the Timex Datalink software paginates at 27 bytes for protocol 1 EEPROM data. The paginate_cpackets helper method from the CpacketPaginator module is hard-coded to paginate at 32 bytes:

Add packet length parameter to this helper method so it can be consumed in the models its shipped with now, and also be used with future protocol 1 EEPROM models.

This is Time for protocol 3:

It accepts an integer as a date_format param, but the values of this parameter is undocumented.

Until this gets added to the code, these are the date formats that the date_format values produce on the Datalink 150. The "C" in the values are correct: these formats actually make a "C" displayed in place of the date on the watch. I'm not sure what this is for, so I'm documenting it as-is.

Update documentation and possibly add some code to make it more clear what Time's date_format param does.

WristApp currently expects the entire ZAP file data to be issued. This file follows a little "package" format that has an app name, description, etc., which is read by the original Timex Datalink software and presented to the user:

Only the binary data in this file is sent to the watch, though. For ease of development of WristApps, it would be useful to issue the raw binary data to the WristApp model instead of wrapping everything in the ZAP format.

The CI listens to push and pull_request events:

This makes the CI run twice in PRs:

Remove the pull_request event from CI to only run CI on push events.

Here's the spec:

The time value is not 2015-10-21 19:28:32 NZDT, which is what's in the spec description.

This should use "lib/timex_datalink_client/protocol_1/time.rb":