About the Datalink
What is it?
Download Protocol
Display Segments
Memory Map
150 vs 150s
EEProms

Wristapp Programming
Reference
Creating Wristapps
[This Page] Wristapp Format
The State Table
Wristapp Routines
Wristapps

Wristapp Programming
Tutorials
1 - Hello World
2 - Getting Input
3 - Better Input
4 - Showing Selection
5 - PassWord
6 - Day Find
7 - Playing with Sound
8 - Using Callbacks
9 - Hex Dump
10 - EEPROM Dumper
11 - Spend Watch
12 - Sound Schemes
13 - Random Numbers
14 - Hourly Chimes
15 - Lottery Picker

Sound Schemes
Sound Hardware
Sound Scheme Format

Home Send Mail

The Basics

Unlike more complex operating systems and modern programming environments, the Datalink Wristapps are simply a series of bytes to be loaded into the watch.  They are always loaded at $0110 and there is no relocation whatsoever.  This means that if you want to have more than one Wristapp in the watch at a time, you can't.  However, you can get around this limitation by creating a Wristapp which performs more than one function.  The biggest issue with this will be the limited amount of ram ($0110 up $0436 minus however much you use for a sound scheme).  This works out to 804 bytes if you could have no sound scheme loaded.  Since the typical sound scheme is about 32 bytes, a more reasonable limit is 770 bytes for a wristapp - not a lot of room for sloppy code.

0110 WRIST_MAIN This is a JMP instruction to your primary initialization entry point for the wristapp. It is called immediately after the wristapp has been loaded for the first time and never again.
0113 WRIST_SUSPEND This is a JMP instruction to your suspend entry point.  It is called if your app is suspended because an alarm has gone off or your app has timed out because nothing has happened for 3 minutes.  If you don't care about this, the three bytes should be a RTS followed by two NOP instructions.
0116 WRIST_DOTIC This is a JMP instruction to your callback handling routine.  It is called in any situation where the app has requested a callback for timed events such as the normal TIC (1/10th second), Second change, Minute change, Hour Change, and Day change.  If you do not want to handle these events, the three bytes should be a RTS followed by two NOP instructions
0119 WRIST_INCOMM This is a JMP instruction to your COMM suspend routine.  It is called when the COMM app wants to suspend your Wristapp which has requested a callback for timed events.  This gives your app a chance to forget about timers for a while.  Note that it is possible that the app may never be reentered if the user downloads a new wristapp on top of it.  If you don't care about this, the three bytes should be a RTS followed by two NOP instructions.
011C WRIST_NEWDATA This is a JMP instruction to your new data handling routine.  It is called when the COMM app has downloaded new data to the watch.  This can be useful if you have an app that has to know about the data in the EEProm such as a password protect utility. If you don't care about this, the three bytes should be a RTS followed by two NOP instructions.
011F WRIST_GETSTATE This is always two instructions:
LDA STATETAB,X

RTS

Which are used to get an entry from The State Table.  The X register points to the entry that is to be retrieved.  You MUST supply this routine in order for the Wristapp to even function.

0123 WRIST_JMP_STATE0 This is a JMP to the state 0 handling routine.  
0126 WRIST_OFF_STATE0 This is the offset into the state table for the state data associated with state 0.  Unless you reorder the states, this will always be 0.
0127 WRIST_JMP_STATE1 This is a JMP to the state 1 handling routine (if any).  
012A WRIST_OFF_STATE1 This is the offset into the state table for the state data associated with state 1 (if any)

This sequence of JMP instructions follwed by the offset value repeats for all of the states that your Wristapp supports.  If you only have a single state, then your code can start at 0127.

Strings and Data

With any typical program, you want to be able to write to the display.  If you can get away with using strings from the ROM, then you don't have to worry about where to put the strings.  However, when you want to put your own strings there, you need to be aware that the BANNER8, PUT6TOP, and PUT6MID routines all take offsets from 0110 as the string to put on the display.  This effectively limits you to putting all of your strings at the start of the Wristapp. Since you also know that you can't put a string until 0127, those first bytes of addressability are lost, limiting you to a total of 233 bytes of strings that you can store.

.ZAP File Format

The Timex Datalink software on the PC stores all of the Wristapps in a .ZAP file.  The format of this file turns out to be pretty simple.  In fact, you can edit it using any standard text editor as long as you remember that the last line can not have a Carriage return after it.  This seems to make the Datalink software not always recognize the file.

Within the file, each section is terminated by a ¬ character ($AC).  You can optionally put a comment on the line immediately after the separator character.  For the V2.1 software, the .ZAP file contains the code for both the 150 and the 150s. For the earlier 2.0 software, the 150 code happens to be first and the 150s code is simply ignored.  This allows the same .zap file to work for both versions of the software.
Applet file header This is some sort of a version string associated with the creation time.  It is typically of the form "TDLmmddyyn" where mmddyy is the date that the applet was created and n is a sequence number.  The actual value of this string seems to be ignored.
Name 150 This is the name of the applet as it is to appear in the Wristapps list for the 150.  The name can be any number of characters (there may be an upper limit on it) and can contain spaces and other special characters.
Version 150 This is the version number of the 150 applet.  It should be up to 8 characters of alphanumeric characters.  It is not clear that this is actually used by the software.
Description150 This is the description for the 150 applet that is shown when you select it in the Wristapp panel.  The description can be pretty much any length and even include blank lines.  The software does its best to wrap this description when it displays it.
Help Filename 150 This is the name of the Windows .hlp file that is to be used when the user asks for help on the 150 applet. The default file that timex uses for all of its wristapps is WATCHAPP.HLP.  You should provide a .hlp file for any wristapp which tells the user how the Wristapp works on the watch.
Help Index 150 This is the index in the help file associated with the help for the 150 applet.  This is passed along with the Help Filename to the Windows Help system.
Config App 150 This is the configuration program (if any) that is to be invoked when the user selects the configure button  in the Wristapps software.  This program should be a standalone Windows program which modifies the applet as appropriate.  If the program is not configurable, the string should be "none"
Watch 150 This is the name of the watch that this applet is targeted at.  It should be "Timex Data Link 150 Watch"
Code 150 This is the hex code for the 150 applet.  It is simply the ASCII dump of the hex digits (0-9A-Z) of the code to be downloaded to the watch.  It really should be a single line of text with no spaces, but it does appear to allow the line to wrap.  Since the longest this line can ever be is 1608 characters, there really isn't any need to wrap the line.
CRC 150 This is the CRC-16 associated with the 150 applet. It is only a crc on the Code 150 string.
Data Indicator 150 This is the indicator of data for the 150 applet.  If there is no data, this should be a 0, otherwise it is a 1.
Data 150 (OPTIONAL) This is the data for the 150 applet. This entry is present ONLY if the Data Indicator 150 value is 1.
Name 150s This is the name of the applet as it is to appear in the Wristapps list for the 150s.  The name can be any number of characters (there may be an upper limit on it) and can contain spaces and other special characters.
Version 150s This is the version number of the 150s applet.  It should be up to 8 characters of alphanumeric characters.  It is not clear that this is actually used by the software.
Description150s This is the description for the 150s applet that is shown when you select it in the Wristapp panel.  The description can be pretty much any length and even include blank lines.  The software does its best to wrap this description when it displays it.
Help Filename 150s This is the name of the Windows .hlp file that is to be used when the user asks for help on the 150s applet. The default file that timex uses for all of its wristapps is WATCHAPP.HLP.  You should provide a .hlp file for any wristapp which tells the user how the Wristapp works on the watch.
Help Index 150s This is the index in the help file associated with the help for the 150 applet.  This is passed along with the Help Filename to the Windows Help system.
Config App 150s This is the configuration program (if any) that is to be invoked when the user selects the configure button  in the Wristapps software.  This program should be a standalone Windows program which modifies the applet as appropriate.  If the program is not configurable, the string should be "none"
Watch 150s This is the name of the watch that this applet is targeted at.  It should be "Timex Data Link 150s Watch"
Code 150s This is the hex code for the 150s applet.  It is simply the ASCII dump of the hex digits (0-9A-Z) of the code to be downloaded to the watch.  It really should be a single line of text with no spaces, but it does appear to allow the line to wrap.  Since the longest this line can ever be is 1608 characters, there really isn't any need to wrap the line.
CRC 150s This is the CRC-16 associated with the 150s applet. It is only a crc on the Code 150s string.
Data Indicator 150s This is the indicator of data for the 150s applet.  If there is no data, this should be a 0, otherwise it is a 1.
Data 150s (OPTIONAL) This is the data for the 150s applet. This entry is present ONLY if the Data Indicator 150 value is 1.

Getting Started

When your program is first invoked, you have to set a bit to tell the Roms that you are ready to handle processing.  To do this, you need to set bit 7 in the WRISTAPP_FLAGS ($96).  At this time, you probably want to set a few of the other requests to indicate how your Wristapp wants to process things.  The bits in this flag byte are interepreted as:
WRISTAPP_FLAGS - $96
7 Wristapp has been loaded SET=LOADED
6 Uses system rules for button beep decisions SET=SYSTEM RULES
5 Play button beep sound on wristapp for mode button SET=ENABLE
4 Play button beep sound on wristapp for any button SET=ENABLE
3 wristapp wants a call once a day when it changes (WRIST_DOTIC) SET=CALL
2 wristapp wants a call once an hour when it changes (WRIST_DOTIC) SET=CALL
1 wristapp wants a call once a minute when it changes (WRIST_DOTIC) SET=CALL
0 wristapp wants a second timer function called at start of interrupt (WRIST_DOTIC) SET=CALL