HOW TO USE DATE & TIME
There are two timekeeping mechanisms on TDS2020F:
In an application needing non-volatile date and time use the words NOW and HRS to set the current date and time in the board clock, then use W! to transfer a copy to the chip clock. For example at 9pm on Christmas Day evening:
25.12.01 NOW 21.00.00 HRS W!
If you now switch off, the board clock will be lost but a battery connected to pin VBATT (z3) will maintain the chip clock. When you power up again the board clock will have the default date and time of 1.01.84 and 00.00.00. Use W@ to set the board clock from the chip clock. The board clock can be seen most easily with .DATE and .TIME which display via the serial port to your terminal (unless EMIT is redirected).
The reason for this scheme is to avoid delay in obtaining time. Using the board clock an application can tell the current moment to the nearest microsecond.
To keep the clocks in synchronism we suggest that an application uses W@ at regular intervals (say once per hour or day) at a moment its execution time of about 4.2ms will not be important (7.4ms when using the TDS2020DV development board).
Execute USA before any use of dates to change the format manipulated by DMY NOW (DATE) and .DATE . The above example becomes:
12.25.01 NOW 21.00.00 HRS W!
and when the date is retrieved with .DATE the response is 12.25.01.
NON-VOLATILE CLOCK & RAM
The PCF8583 clock chip has 8 clock bytes, 8 alarm bytes and 240 bytes of RAM. Connection of the TDS2020BYN, TDS2020BYD or other battery will make it non-volatile (consumption typically 3.5�A including a 128k bytes RAM). The TDS2020F contains circuitry to avoid corruption while the power is going up or down. The system does not make any use of the PCF8583 internal addresses $11 to $FF inclusive, these 239 bytes are available to you as non-volatile RAM. For more accurate timekeeping trim the adjacent capacitor (it is not adjusted before despatch). Set the 1Hz clock output on the NMI pin (a26) to be as accurate as possible using a precision period meter as a reference.
W! and W@ provide the only access you are ever likely to need to the clock registers and STANDBY SUSPEND ADJOURN allow use of the alarm bytes (see LOW POWER OPERATION, page 89).
The raw data which the Forth words use are in the 3 variables TICKS MINS DAYS . These can be accessed directly to give special functions.
The clock works using the Timer 3 Overflow Interrupt. Every 53.333ms this interrupt increments the ticks register, and each minute resets it and increments the minutes register. Once per day the minutes register is reset and the day register is incremented. Most time and date words work with these three variables. The interrupt is written in machine code and takes less than 0.1% of the processor time. Although timer 3 is used for this purpose it is also essentially free for most other purposes concurrently, for example both output captures and the input capture are unused by the timekeeping function.
Some applications need exact one second (or multiple) timing. If bit 1 of address hex FD05 is set and Timer 3 Overflow Interrupt is disabled by -TIMER the system keeps the board clock using the Non Masked Interrupt of the chip clock. The variable TICKS now contains seconds instead of 53.333ms increments. E.g.
-TIMER $FD05 1 ONE
Real time down to the nearest microsecond is available from the board clock. Provided it is not in the seconds mode as described above, read 16 bits from address FFB2 (the free running timer 3) to get fractions of one 'tick'. Every count represents 813.8ns. For example the following gets a 32-bit double number to the stack-it repeats only every minute:
-TIMER $FFB2 @ TICKS @ +TIMER
The word REAL in file #TIMING.TDS uses this principle to give a 48-bit real time, with a resolution of 813.8ns. It repeats only every 7 years.
Note how timer interrupts should be turned off while reading the registers to avoid spurious results, but no time will be lost provided they are re-enabled within 53.3ms.
At the top of this section there are many words to give delays in programs. Some come from the file #TIMING.TDS. Those marked 'real time' use the timers, use these alternatives where accurate timing is needed.
The words REST WAIT and the default version of MS are based on software loops. Those times shown refer to use with the Forth in the microprocessor. They are longer when the TDS2020DV board is present. When interrupts or multitasking have been added they may be slower and indeterminate in duration.
You can also use the Chip Clock to create delays, see LOW POWER OPERATION, page 89 to see how to create an NMI after a time up to a year.
Library routine #TONES.TDS gives three independent tones generated under interrupt. The program can change the three pitches while it is running. Use it to give user-feedback as jingles, chords, music or sound effects.