Interfacing the BASIC Stamp 2 with a DS1302 Real Time Clock

copyright, LaVerne Ervin and Peter H. Anderson, Baltimore, MD, Apr, '99

Introduction

This discussion focuses on the Dallas DS1302 Timekeeping Chip. A data sheet is
available at http://www.dalsemi.com. We have the DS1302 in an 8-pin DIP for $3.00 and
the 32.768 kHz crystal for $0.50.

This effort was initiated by undergraduate student LaVerne Ervin as her capstone design
project (2 credits). Her work was very well done and enabled me to quickly make minor
revisions and build on her work.

The DS1302 performs two functions; a 31 byte RAM and a real time clock. Clearly, most
people probably use the real time clock feature, but the RAM might also be of value. For
example; the Parallax BASIC Stamp 2 provides 26 RAM locations. The DS1302 might
be used to add another 31 much like the BS2SX adds 63 RAM bytes

This discussion attempts to discuss all of the features of the DS1302 in the context of
interfacing with the Parallax BASIC Stamp 2. However, BASIC is pretty "basic" and
hopefully this discussion proves of value to people using other target processors.

This was written over the Christmas, '98 break. All of the routines except the last routines
related to computing the Julian date and the number of seconds since the beginning of the
year were tested on a BASIC Stamp 2. The last material relating to Julian date was not
tested.

Overview of the Operation.

The interface consists of three wires; /RST, SCLK and I/O. /RST and SCLK are inputs to
the DS1302 (outputs as viewed by the controlling processor) and I/O is bi-directional.

Normally, /RST is low. All communication sequences are intitiated by driving /RST high.
A communications sequence is terminated by bringing /RST low. SCLK must be low
when /RST is brought to a logic one to initiate a sequence.

Data, including commands is sent to the DS1302 by first bringing I/O to the appropriate
state while SCLK is low. The data bit is then clocked into the DS1302 on the rising edge
of the SCLK. All data, including commands is sent as a byte, least significant bit first.

Data is read from the DS1302 on lead I/O. Each bit is read on the falling edge of SCLK.
Here again, data is read beginning with the least significant bit.

Note that /RST is high throughout the entire interchange.

As with all intelligent serial devices, a data interchange begins with a command byte of
the form;

7 6 5 4 3 2 1 0

1 RAM/CLK A4 A3 A2 A1 A0 RD/WR
Note that RAM is selected by making bit 6 a 1. A read or write operation is indicated by
bit 0 being either a logic 0 or logic 1, respectively.

Thus if one desires to write to RAM location %0 1100, the command byte is;

7 6 5 4 3 2 1 0

1 RAM/CLK A4 A3 A2 A1 A0 RD/WR

1 1 0 1 1 0 0 0
Note that a general expression for writing to RAM memory is;
%1100 0000 | (ADR << 1)

or $C0 | (ADR << 1)

Similarly, a general expression for reading from RAM memory is;
%1100 0001 | (ADR << 1)

or $C1 | (ADR << 1)

Writing and reading from the CLK is similar, except that bit 6 is a logic zero.

Thus, writing to CLK address %0 0011, which is the date within a month, the command
byte is;

7 6 5 4 3 2 1 0

1 RAM/CLK A4 A3 A2 A1 A0 RD/WR

1 0 0 0 0 1 1 0
Thus, general expressions for writing and reading to the clock;
$80 | (ADR << 1) ' write to clock
$81 | (ADR << 1) ' read from clock
Before, we get anymore confused, lets take a look at a simple routine to write to and read
from RAM memory.

Circuit Connection.

In all of the following discussions, connections between the BS2 and the DS1302 are;

BS2 DS1302

P2 (term 7) <-----------10K R---------------> I/O (term 6)

P1 (term 6) --------------------------------> SCLK (term 7)

 P0 (term 5) --------------------------------> /RST (term 5)

Writing to and Reading from RAM.

In program PUT_GET, two subroutines; _PUT and _GET are presented. These are quite
like the PUT and GET commands associated with the BS2SX.

' Program PUT_GET.BS2

'
' Illustrates how to write to and read from the DS1302 RAM.
'
' copyright, LaVerne Ervin, Baltimore, MD, Dec, '98

VAL VAR BYTE

ADDR VAR BYTE

O_BYTE VAR BYTE

N VAR BYTE

MAIN:
DIRS = $0007 ' /RST, SCLK and I/O are outputs

ADR=3
VAL=125
GOSUB _PUT ' write 125 to RAM address 3

ADR=3 ' read from address 3 and display

GOSUB _GET
DEBUG ? VAL

DONE:
GOTO DONE

_PUT: ' writes VAL to ADR. Uses bytes O_BYTE and N

DIR2=1 ' be sure I/O is an output
OUT0=0
OUT1=0
OUT0=1 ' bring /RST high while SCLK is low

O_BYTE=$C0|(ADR<<1) ; write RAM command

GOSUB OUT_BYTE
O_BYTE = VAL
GOSUB OUT_BYTE
OUT0=0 ' /RST brought low to terminate the sequence
RETURN

_GET: ' reads from ADR into VAL. Uses bytes O_BYTE and N
DIR2=1
OUT0=0
OUT1=0
OUT0=1 ' bring /RST high while SCLK is low
O_BYTE=$C1|(ADR<<1) ' read RAM command
GOSUB OUT_BYTE
 DIR2=0
GOSUB IN_VAL
OUT0=0 ' /RST low to terminate the sequence
RETURN

OUT_BYTE: ' shift out O_BYTE on I/O, least sig bit first
FOR N=0 TO 7
OUT2= O_BYTE.BIT0
GOSUB CLK_PULSE
O_BYTE = O_BYTE >>1
NEXT
RETURN

IN_VAL: ' shift in on I/O, least sig bit first

FOR N=0 TO 7
GOSUB CLK_PULSE
VAL = VAL >>1
VAL.BIT7 =IN2
NEXT
RETURN

CLK_PULSE:
OUT1=1
OUT1=0

Discussion.

In subroutine OUT_BYTE, variable O_BYTE is shifted out to the DS1302, beginning

with the least significant bit. Note that OUT2 (I/O) is set to the value of .BIT0 followed
by a clock pulse. O_BYTE is then shifted to the right such that the next bit is now in the
least significant bit position.

In subroutine IN_VAL, a clock pulse occurs. VAL is shifted to the right and the data bit
which is read is placed in the most significant bit position.

These routines might also be implemented using the SHIFTOUT and SHIFTIN
commands. I am not a big fan of these commands during the intitial development as I
tend to lose sight of exactly what I am doing.

However, I have to admit that once you are beyond the initial development, the
SHIFTOUT and SHIFTIN are a whole lot more efficient

OUT_BYTE:
SHIFTOUT 2, 1, LSBFIRST, [O_BYTE\8]
RETURN

IN_VAL:
SHIFTIN 2, 1, LSBPOST, [IN_VAL\8]
RETURN
These later implementations will be used in all subsequent discussions.
In higher level routine, _PUT, the /RST terminal is brought high, the command byte is
sent followed by the data byte and /RST is then brought low.

In _GET, the /RST terminal is brought high, the command byte to read is sent, the data is
read and the sequence is terminated by bringing /RST low.

Arrays.

' ARRAY0.BS2
'
' Illustrates how to use DS1302 memory to implement an array.
' Array is dummied up. Average, MAX and MIN are calculated and
' displayed.
'
' LaVerne Ervin, Baltimore, MD, Dec, '98

SUM VAR WORD

AVG_10 VAR WORD ' ten times the average
_MAX VAR BYTE
_MIN VAR BYTE

VAL VAR BYTE

ADDR VAR BYTE

O_BYTE VAR BYTE

FOR ADR=0 TO 29
VAL = ADR//3
GOSUB _PUT ' put some numbers into the DS1302
NEXT

' Compute the average

SUM = 0
FOR ADR=0 TO 29
GOSUB _GET
SUM = SUM + VAL
NEXT

AVG_10 = SUM * 10 / 50
DEBUG "AVG = ", DEC AVG_10/10, ".", DEC AVG_10//10, CR

' Now for the MIN

_MIN = 255

FOR ADR=0 TO 29
GOSUB _GET
IF (VAL>=_MIN) THEN SKIP_1
_MIN = VAL ' VAL is less than _MIN
SKIP_1:
NEXT
DEBUG "MIN = ", DEC _MIN, CR
' Now for the MAX

_MAX = 0

FOR ADR=0 TO 29
GOSUB _GET
IF (VAL<=_MAX) THEN SKIP_2
_MAX = VAL ' VAL is greater than MAX
SKIP_2:
NEXT
DEBUG "MAX = ", DEC _MAX, CR

DONE:
GOTO DONE

'''''''''

_PUT: ' writes VAL to ADR. Uses byte O_BYTE

DIR2=1 ' be sure I/O is an output
OUT0=0
OUT1=0
OUT0=1 ' bring /RST high while SCLK is low

O_BYTE=$C0|(ADR<<1) ; write RAM command

GOSUB OUT_BYTE
O_BYTE = VAL
GOSUB OUT_BYTE
OUT0=0 ' /RST brought low to terminate the sequence
RETURN

_GET: ' reads from ADR into VAL. Uses bytes O_BYTE and N
DIR2=1
OUT0=0
OUT1=0
OUT0=1 ' bring /RST high while SCLK is low
O_BYTE=$C1|(ADR<<1) ' read RAM command
GOSUB OUT_BYTE

DIR2=0
GOSUB IN_VAL
OUT0=0 ' /RST low to terminate the sequence
RETURN

OUT_BYTE:
SHIFTOUT 2, 1, LSBFIRST, [O_BYTE\8]
RETURN

IN_VAL:
SHIFTIN 2, 1, LSBPOST, [VAL\8]
RETURN
RAM Burst Mode.

Note that only RAM locations 0-30 (31 bytes) are available for general purpose RAM.
RAM location 31 is reserved for placing the DS1302 in a burst mode where multiple
values are written to or read from the DS1302 in a single data exchange. Thus, $C0 | ($1F
<< 1) or $FE places the DS1302 in a RAM burst write mode and $C1 | ($1F << 1) or $FF
places it in the RAM burst read mode.

' ARRAY1.BS2
'
' Illustrates how to use DS1302 memory to implement an array.
' Array is dummied up. The average is calculated and displayed.
'
' Illustrates the use of RAM burst write and RAM burst read modes.
'
' copyright, LaVerne Ervin, Baltimore, MD, Dec, '98

SUM VAR WORD

AVG_10 VAR WORD ' ten times the average

VAL VAR BYTE

N VAR BYTE

DIRS=$0007

' write 30 values to RAM in burst mode

DIR2=1 ' be sure I/O is an output

OUT0=0
OUT1=0
OUT0=1 ' bring /RST high while SCLK is low
SHIFTOUT 2, 1, LSBFIRST, [$FE\8]
' RAM burst write command byte

FOR N=0 TO 29
VAL = N//3
SHIFTOUT 2, 1, LSBFIRST, [VAL\8] ' send 30 bytes
NEXT
OUT0=0 ' terminate the data sequence

' Compute the average

SUM = 0

DIR2=1 ' be sure I/O is an output

OUT0=0
OUT1=0
OUT0=1 ' bring /RST high while SCLK is low
SHIFTOUT 2, 1, LSBFIRST, [$FE\8] ' RAM burst read

DIR2=0 ' be sure I/O is an input

FOR N=0 TO 29
SHIFTIN 2, 1, LSBPOST, [VAL\8] ' fetch each byte
SUM = SUM + VAL ' and add to the sum
NEXT
OUT0=0 ' terminate the data sequence
 AVG_10 = SUM * 10 / 30
DEBUG "AVG = ", DEC AVG_10/10, ".", DEC AVG_10//10, CR

DONE:
GOTO DONE
Intermediate Summary.

Thus far, I have focused on the RAM portion of the DS1302.

Note that very little code is required; bring /RST high, send the command byte, either
$C0 | (ADR << 1) for reading or $C1 | (ADR << 1) followed by either writing or reading
a byte and then bring /RST low. The burst mode is simply a matter of sending $FE and
then sequentially writing byte by byte or, when reading, sending command byte $FF and
then sequentially reading byte by byte.

The BS2SX adds 63 bytes of scratchpad RAM which are fetched and stored using the
new commands GET and PUT. The DS1302 may be a somewhat less expensive
alternative, particularly if you need the real time clock capability.

Real Time Clock.

Operation is similar to that discussed above except that the command byte addresses the
clock portion of the DS1302.

7 6 5 4 3 2 1 0

1 RAM/CLK A4 A3 A2 A1 A0 RD/WR
Note that bit 6 is set to a zero to address the clock. Thus, the general forms of the
command byte are;
$80 | (ADR <<1) ' write to CLK ADR
$81 | (ADR <<1) ' read from CLK ADR
Each address corresponds to an element of the date and time or control as summarized in
the following constant table;
SEC CON 0
MIN CON 1
HR CON 2
DATE CON 3
MONTH CON 4
DAY CON 5
YEAR CON 6
CONTROL CON 7
TRICKLE CON 8
BURST CON 9
Note that addresses 10-31 are not used.

Thus, to write the "seconds" which might be in Stamp variable VAL

' bring /RST high

ADR = SECS
 O_BYTE = $81 | (ADR << 1)
GOSUB OUT_BYTE
O_BYTE = VAL
GOSUB OUT_BYTE
' bring /RST low
Prior to forging into a simple routine that illustrates how to write the time and then
periodically read the time, the are a few bookkeeping matters.

The control byte consists of a single bit, bit 7, which is Write Protect. On powerup, the
state of this bit is not defined. Thus, prior to writing a date and time to the DS1302, the
normal procedure would be to write a zero to bit 7 of address CONTROL, write to the
time and date addresses and then write a logic 1 to the write protect bit.

' CLK_1.BS2
'
' Initializes DS1302 40th sec, 59th min, 11th hour PM, 31st day,
' 12th month, day 5 (Friday), 99th year. (20 secs short of the
' millenium)
'
' Continually reads clock and displays using the debug command.
'
' copyright, LaVerne Ervin, Baltimore, MD, Dec, '98

C_SEC CON 0
C_MINUTE CON 1
C_HOUR CON 2
C_DATE CON 3
C_MONTH CON 4
C_DAY CON 5
C_YEAR CON 6
CONTROL CON 7
TRICKLE CON 8
BURST CON 31

DATE_TIME DATA $40, $59, $23, $31, $12, $5, $00

' secs
DIRS=$0007

ADR VAR BYTE

VAL VAR BYTE

DIRS=$0007
' clear the write protect bit

DIR2=1 ' be sure I/O is an output

OUT0=0
OUT1=0
OUT0=1 ' bring /RST high while SCLK is low

SHIFTOUT 2, 1, LSBFIRST, [$80 | (CONTROL<<1) \8]

SHIFTOUT 2, 1, LSBFIRST, [$00\8]

OUT0=1 ' bring /RST low to terminate

' Now write the date and time, one byte at a time.
 FOR ADR=0 TO 6
READ DATE_TIME+ADR, VAL ' fetch value from EEPROM
GOSUB _PUT_TIME ' and write it to the clock
NEXT

' set the write protect bit

DIR2=1 ' be sure I/O is an output

OUT0=0
OUT1=0
OUT0=1 ' bring /RST high while SCLK is low

SHIFTOUT 2, 1, LSBFIRST, [$80 | (CONTROL<<1) \8]

SHIFTOUT 2, 1, LSBFIRST, [$80\8] ' 1 in most sign bit

OUT0=1 ' bring /RST low to terminate

' Now, display the date and time in YY/MM/DD HH:MM:SS format
DISPLAY_DATE_TIME:

ADR = C_YEAR
GOSUB _GET_TIME
DEBUG HEX2 VAL, "/"

ADR = C_MONTH
GOSUB _GET_TIME
DEBUG HEX2 VAL, "/"

ADR = C_DATE
GOSUB _GET_TIME
DEBUG HEX2 VAL, " "

ADR = C_HOUR
GOSUB _GET_TIME
DEBUG HEX2 VAL, ":"

ADR = C_MINUTE
GOSUB _GET_TIME
DEBUG HEX2 VAL, ":"

ADR = C_SEC
GOSUB _GET_TIME
DEBUG HEX2 VAL, CR

PAUSE 1000 ' wait for a second

GOTO DISPLAY_DATE_TIME

'''''
_PUT_TIME:
DIR2=1 ' be sure I/O is an output
OUT0=0
OUT1=0
OUT0=1 ' bring /RST high while SCLK is low

SHIFTOUT 2, 1, LSBFIRST, [$80 | (ADR<<1)\8] ' command byte

 SHIFTOUT 2, 1, LSBFIRST, [VAL\8]
OUT0=0 ' terminate the sequence

RETURN

_GET_TIME:
DIR2=1 ' be sure I/O is an output
OUT0=0
OUT1=0
OUT0=1 ' bring /RST high while SCLK is low
SHIFTOUT 2, 1, LSBFIRST, [$81 | (ADR<<1)\8] ' command byte
DIR2=0
SHIFTIN 2, 1, LSBPRE, [VAL\8]
OUT0=0

RETURN

Discussion.

In the above, the write protect bit is set to zero. The time and date info is sequentially
read from the Stamp's EEPROM and written to the DS1302. The write protect bit is then
set to a logic one to protect against accidental writes. The date and time are then read
every second and displayed using the DEBUG command.

I happened to use a time which is 20 seconds short of the millenium and indeed, it did
roll over to the new century. However, there is another distinction between the year 2000
and 1900 in that the year 2000 is a leap year, 1900 wasn't. (A leap year occurs every four
years, except at the turn of the century. However, every 400 years, the turn of the century
is a leap year. Thus, the Y2K problem is a bit more complex than at first glance.) I tried
Feb 28, 00 at 23:59:40 and indeed it rolled over to Feb 29.

Note that the date and time quantities are in binary coded decimal (BCD). That is, 32
seconds is saved in the DS1302 as %0011 0010, not as %0010 0000. Thus, note that the
values in EEPROM are saved in hexadecimal format and the results are displayed using
the HEX2 modifier.

However, if you plan to be doing calculations, the quantities must be converted from
BCD to natural binary. For example, assume the quantities are in variables SECS, MINS,
DATE, MONTHS and YEARS. Note that HOURS is discussed later.

SECS = SECS & $7F ' take only the lower 7 bits
SECS = SECS.NIB1 * 10 + SECS.NIB0

MINS = MINS & $7F

MINS = MINS.NIB1 * 10 + MINS.NIB0

HOURS = HOURS & $3F

HOURS = HOURS.NIB1 * 10 + HOURS.NIB0

DATE = DATE & $3F ' take only the lower 6 bits
DATE = DATE.NIB1 * 10 + DATE.NIB0
 MONTHS = MONTHS & $1F
MONTHS = MONTHS.NIB1 * 10 + MONTHS.NIB0

YEARS = YEARS.NIB1 * 10 + YEARS.NIB0

The hours is a bit more complex.

When writing to C_HRS, bit 7 indicates whether the DS1302 is to operated in 12-hour
(logic 1) or 24 hour (logic zero) mode. In the above program, the number of hours was
programmed as $23. Note that bit 7 is a zero, and thus the clock was in a 24 hour mode.
Thus, in this case, the number of hours as shown above.

Note that the DS1302 may be placed in a 12-hour mode by setting bit 7 to a 1 and using
bit 5 to indicate either AM (logic 1) or PM (logic 0). This discussion does not include any
examples of the 12 hour mode.

Program CLK_2.BS2 performs a similar function as CLK_1, except the burst mode is
used to write the data and the date and time are read into variables. This enables you to
use the DS1302 to time between events or to take an action at a particular time. In
addition, the program illustrates how the date may be expressed in the form;

Friday
Dec 31, '99, 23:59:40
' CLK_2.BS2
'
' Initializes DS1302 40th sec, 59th min, 11th hour PM, 31st day,
' 12th month, day 5 (Friday), 99th year. (20 secs short of the
' millenium) using the burst mode.
'
' Continually reads clock and displays using the debug command.
'
' Illustrates how to display strings.
'
' Note that date and time is saved in variables.
'
' copyright, Peter H. Anderson, Baltimore, MD, Dec, '98

C_SEC CON 0
C_MINUTE CON 1
C_HOUR CON 2
C_DATE CON 3
C_MONTH CON 4
C_DAY CON 5
C_YEAR CON 6
CONTROL CON 7
TRICKLE CON 8
BURST CON 31

DATE_TIME DATA $40, $59, $23, $31, $12, $5, $00

JAN DATA "Jan", 0

FEB DATA "Feb", 0
MAR DATA "Mar", 0
APR DATA "Apr", 0
 MAY DATA "May", 0
JUN DATA "Jun", 0

JUL DATA "Jul", 0

AUG DATA "Aug", 0
SEP DATA "Sep", 0
OCT DATA "Oct", 0
NOV DATA "Nov", 0
DEC DATA "Dec", 0

SUN DATA "Sunday", 0

MON DATA "Monday", 0
TUE DATA "Tuesday", 0
WED DATA "Wednesday", 0
THU DATA "Thursday", 0
FRI DATA "Friday", 0
SAT DATA "Saturday", 0

' the following is a table of the days of the week

WEEK_DAYS DATA WORD SUN, WORD MON, WORD TUE, WORD WED
DATA WORD THU, WORD FRI, WORD SAT

DIRS=$0007

ADR VAR BYTE

VAL VAR BYTE

YEARS VAR BYTE

MONTHS VAR BYTE
MO_DAYS VAR BYTE

HOURS VAR BYTE

MINS VAR BYTE
SECS VAR BYTE

WK_DAY VAR BYTE

PTR VAR WORD

DIRS=$0007
' clear the write protect bit

DIR2=1 ' be sure I/O is an output

OUT0=0
OUT1=0
OUT0=1 ' bring /RST high while SCLK is low

SHIFTOUT 2, 1, LSBFIRST, [$80 | (CONTROL<<1) \8]

SHIFTOUT 2, 1, LSBFIRST, [$00\8]

OUT0=1 ' bring /RST low to terminate

' Now write the date and time, in the burst mode.
' Note that eight bytes are written

DIR2=1 ' be sure I/O is an output

OUT0=0
OUT1=0
 OUT0=1 ' bring /RST high while SCLK is low

SHIFTOUT 2, 1, LSBFIRST, [$80 | (BURST<<1) \8]

FOR ADR=0 TO 6
READ DATE_TIME+ADR, VAL ' fetch value from EEPROM
SHIFTOUT 2, 1, LSBFIRST, [VAL\0] ' and write it to the
clock
NEXT

' set the write protect bit

SHIFTOUT 2, 1, LSBFIRST, [$80\8] ' 1 in most sign bit

OUT0=1 ' bring /RST low to terminate

' Now, fetch the date and time

GET_DATE_TIME:

ADR = C_YEAR
GOSUB _GET_TIME
YEARS = VAL.NIB1*10 + VAL.NIB0 ' convert BCD to natural binary

ADR = C_MONTH
GOSUB _GET_TIME
VAL = VAL & $1F
MONTHS = VAL.NIB1*10 + VAL.NIB0

ADR = C_DATE
GOSUB _GET_TIME
VAL = VAL & $3F
MO_DAYS = VAL.NIB1*10 + VAL.NIB0

ADR = C_HOUR
GOSUB _GET_TIME
VAL = VAL & 3F
HOURS = VAL.NIB1*10 + VAL.NIB0

ADR = C_MINUTE
GOSUB _GET_TIME
VAL = VAL & $7F
MINS = VAL.NIB1*10 + VAL.NIB0

ADR = C_SEC
GOSUB _GET_TIME
VAL = VAL & $7F
SECS = VAL.NIB1*10 + VAL.NIB0

ADR = C_DAY ' day of the week

GOSUB _GET_TIME
WK_DAY = VAL & $07

DISPLAY:
' Now display the day of the week
' map the week day into a pointer that points to beginning of desired
' string

READ WEEK_DAYS + (2*WK_DAY), PTR.BYTE0

READ WEEK_DAYS + (2*WK_DAY)+1, PTR.BYTE1
GOSUB DISPLAY_STR

DEBUG CR

' Now, the month

PTR = JAN + 4*(MONTHS-1)

GOSUB DISPLAY_STR

' Now the date and time

DEBUG " ", DEC MO_DAYS, ", '", DEC2 YEARS, " "
DEBUG DEC2 HOURS, ":", DEC2 MINS, ":", DEC2 SECS, CR

PAUSE 1000
GOTO GET_DATE_TIME ' continual loop

DISPLAY_STR:
READ PTR, X
IF X=0 THEN STR_OUT_DONE
DEBUG X
P=PTR+1
GOTO DISPLAY_STR
RETURN

_GET_TIME:
DIR2=1 ' be sure I/O is an output
OUT0=0
OUT1=0
OUT0=1 ' bring /RST high while SCLK is low
SHIFTOUT 2, 1, LSBFIRST, [$81 | (ADR<<1)\8] ' command byte
DIR2=0
SHIFTIN 2, 1, LSBPRE, [VAL\8]
OUT0=0

RETURN
Discussion.

In CLK2.BS2, the "write protect" bit on the Control Address is first set to zero.

The "burst" mode is then used to transmit all eight bytes of data are transmitted in a
single data exchange. Note that the the command byte, $80 | ($1F) is followed by eight
bytes for locations 0 through 7. Addresses 0 through 6 correspond to the time and date
and finally $80 is written to the Control register (address 7) to again place the clock in the
write protect mode.

Note that with the RAM burst, the sending of consecutive bytes may be interrupted at any
time. That is, not all 31 bytes need be transferred.
However, with the CLK burst, all eight bytes (0 - 7) must be transmitted. Note that this
includes the Control register.

In CLK2.BS2, the time and date are periodically read and displayed.

The day of the week is first read. This is then mapped into an PTR address of the
beginning of the associated string as follows;

READ WEEK_DAYS + (2*(WK_DAY-1)), PTR.BYTE0

READ WEEK_DAYS + (2*(WK_DAY-1)+1, PTR.BYTE1
For example, if the week day is Sunday, WK_DAY is 1. Thus, the pointer PTR is read
from WEEK_DAYS + 0 (low byte) and WEEK_DAYS + 1 (high byte).

Computing the Julian Date.

Note that the following material was developed some time ago and unfortunately I put it
away in favor of something more interesting. Thus, this has not been tested nor is it
complete. I hesitate to simply delete it as it may be of use to someone.

The Julian Date is simply the day of the year. Thus, Jan 31 is day 31. Feb 28 is day 59. If
the year is not a leap year, Dec 31 is day 365.

The importance of the Julian date is that it enables one to calculate the number of seconds
between two times. For example, it is mighty hard to calculate the number of days
between Mar 1 and Nov 25, but mighty simple to calculate the number of days between
Julian day 61 and 325. (Note that I don't really know if Mar 1 and Nov 25 days 61 and
325.)

In the following code fragment, an array of the days in each month is implemented in
EEPROM. Note that there are 13 entries, with element 0 being any value. That is, it really
isn't used. Thus, the number of days in month N month may be read into TMP;

READ DAYS_IN_MONTH+N, TMP

Lets avoid the leap year problem for the moment. Assume the date is Jan 7 (MONTH=1,
DAY=7). You really don't care how many days there are in January. The Julian date is
simply the DAY. However, if the day is March 7, the Julian date is the number of days in
Jan (310) plus the number of days in Feb (28), plus DAY.

Thus, in the following, the Julian date is initialized to DAY. If, the MONTH is 1 (Jan), we
are done. Otherwise, we must also add the number of days in each month up through
MONTHS-1. That is, in the case of March 7, we have 7 + 31 + 28.

DAYS_IN_MONTH DATA 00, 31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31
' 1 2 3 4 5 6 7 8 9 10 11 12

JULIAN_DATE = DAY
IF MONTH=1 THEN JULIAN_DONE
 FOR N=1 TO MONTH-1
READ DAYS_IN_MONTH+N, TMP
JULIAN_DATE = JULIAN_DATE + TMP
NEXT
But, we do have the added confusion of the leap year and it is a bit more complex than
many people realize. A leap year occurs every four years, but there is no leap year at the
turn of the century, but every 400 years, there is. Thus, the year 2000 is a leap year and a
leap year occurs every four years thereafter. The year 2100 will not be a leap year, but I
doubt any reader will have to reckon with this. Thus, for now until 2099, a leap year
occurs every four years.

Clearly, if the MONTH is less than 3 (March), we need not be concerned with whether it
is a leap year or not and we are done. Otherwise, if the year is not equally divisible by 4,
we are done. But if MONTH >= 3 and it is a leap year, we add 1 to calculate the Julian
date.

IF (MONTH < 3) THEN JULIAN_DONE

IF (YEAR//4 !=0) THEN JULIAN_DONE ' not a leap year
JULIAN = JULIAN+1

JULIAN_DONE:
By knowing the Julian date, we can calculate the number of seconds that have elapsed
since the beginning of the year. Note that the following statements involve 32 bit
arithmetic and will not work on a BS2 as they are written.
ELAPSED_SECS = JULIAN_DATE * (24 * 3600)
+ (HOURS * 3600) + (MINS * 60) + SECS

There is one problem here in that 24 * 3600 = 86,400 which is too large to be
accommodated in a word. However, we can multiply the Julian date by 2;
ELAPSED_SECS = (JULIAN_DATE * 2) * (12 * 3600)
+ (HOURS * 3600) + (MINS * 60) + SECS
Note that ELAPSED_SECS is a 32-bit quantity which cannot be directly handled as it is
written above. Rather, we must define two 16-bit words.
ES1_H = ((JULIAN_DATE * 2) ** (12*3600))
+ (HOURS ** 3600) ' calculate the high word
Note that the operator ** returns the high 16 bits of the operation.

Now, for the lower 16 bits;

ES1_L = (MINS * 60) + SECS

TMP = ES1_L + (HOURS * 3600)
IF (ES1_L >= TMP) THEN EL_TIME_1 ' no carry occurred
ES1_H = ES1_H + 1
EL_TIME_1:
ES1_L = TMP

TMP = ES1_L + (JULIAN_DATE * 2) * (12*3600)

IF (ES1_L >= TMP) THEN EL_TIME_2 ' no carry occurred
ES1_H = ES1_H + 1
EL_TIME_2:
ES1_L = TMP
Note that in calculating the lower 16 bits, a summing of four terms is required. Clearly,
(MINS * 60) + SECS will not cause an overflow. However, in summing the other two
terms, a check is required to ascertain if an overflow occurred and if so, ES1_H is
incremented.

Note that in the above, ES1_H and ES1_L uniquely identify what might be termed the
current "Julian second". That is, the number of seconds since the beginning of the year.
This might be useful in causing a periodic event to happen or in efficiently logging time
data to EEPROM. That is, log the elapsed time since the beginning of the year and then
after dumping the data to a PC convert this back to a date and time.