______________________________________________________________________
>                                                                      <
>                    DS1337 (external RTC) driver                      <
>                                 for                                  <
>                         PICos18 release 2.03                         <
>                                                                      <
>             PICos18 - Real-time kernel for PIC18 family              <
>                                                                      <
>                                                                      <
> www.picos18.com                                    www.pragmatec.net <
>______________________________________________________________________<


This file contains all necessary informations to use properly the 
external RTC DS1337 driver for PICos18 v2.xx. This driver lets you 
design a multi-task application using the MAXIM DS1337 that can manage 
date and time. The device has to be access through the I2C interface 
and this driver lets you have a safe access to the chip without woring
about multiple I2C bus access.


 ______________________________________________________________________
>                                                                      <
>                         I - Zip file content                         <
>______________________________________________________________________<

The drv_DS1337 zip file contains :
- drv_DS1337.c
- drv_DS1337.h   : header file
- drv_DS1337.txt : this file

To use the external RTC driver, first unzip the file.
Place the C and H files in your project directory.

This driver is supposed to be use with PICos18 and has been tested with 
MPLAB 7.10 and C18 v2.42. This driver is suitable for PIC18 with MAXIM/
DALLAS DS1337 device.

 ______________________________________________________________________
>                                                                      <
>                        II - Hardware settings                        <
>______________________________________________________________________<

Have a look at the DS1337 datasheet to connect your device properly to 
the I2C bus.
If you already have a I2C install you don't have to plug additionnal
pullup resistors. 

A basic intallation consists to connect the chip to the power lines
(VDD and VSS) and to add an external crystal with the dedicated
capacitors (cf datasheet), then to connect the SDA and SCL lines to the
PIC18 (with pullup resistors if needed).

The DS1337 manages a special interrupt line and programmable alarms.
The actual version of the driver does not manage such features.


 ______________________________________________________________________
>                                                                      <
>                       III - TASCDESC settings                        <
>______________________________________________________________________<

The DS1337 driver needs the I2C driver to be install at first.
Have a llok at the drv_I2C.txt file to learn more on how to install such
a driver.

The DS1337 driver is not excatly a driver but much more a library (a set
of funtions) that let you interface the DS1337 without wasting time to
validate your own code during many hours.

Then once you have propermy install the I2C driver you don't need to 
specify anything else in the tascdesc.c file.


 ______________________________________________________________________
>                                                                      <
>                        IV - DS1337 usage                             <
>______________________________________________________________________<

First of all you need to declare a I2C_message structure in your task.
It's mandatory for all the task that needs to use the I2C driver :

I2C_message_t I2Cmsg;


In the TASK0 task of the MyApp directory, include the driver header:

#include "drv_DS1337.h"

And declare a DS1337 structure to manage date and time:
DS1337_t I2Ctime;

See hereafter a basic example to have a correct access to the DS1337:
(the task access the DS1337 every minute to know the correct date)


#include "define.h"
#include "drv_DS1337.h"


I2C_message_t I2Cmsg;
DS1337_t I2Ctime;

/**********************************************************************
 * ----------------------------- TASK0 --------------------------------
 *
 * First task of the tutorial. 
 *
 **********************************************************************/
TASK(TASK0)
{
typedef struct DS1337
{
  I2Ctime.year    = 05; // 2005
  I2Ctime.month   = 8;  // August
  I2Ctime.date    = 5;  // Friday
  I2Ctime.day     = 12;
  I2Ctime.hour    = 16;
  I2Ctime.minutes = 44;
  I2Ctimeseconds  = 25;
  DS1337_Write(&I2Cmsg, &I2Ctime);

  /* Do not forget to declare an alarm in tascdesc.c file (index 0) */
  SetRelAlarm(0, 60000, 60000);  /* every minute */
 
  while (1)
  {
    WaitEvent(ALARM_EVENT);
    ClearEvent(ALARM_EVENT);

    DS1337_Read(&I2Cmsg, &I2Ctime);
  }
}

 ______________________________________________________________________
>                                                                      <
>                         V - Conclusion                               <
>______________________________________________________________________<

The DS1337 driver offers 2 basic functions to have an easy access to the
external RTC from MAXIM. 

You can use the device to be waked up on an alarm event (the DS1337 can
manage upto 2 alarms). To do so connect the DS1337 INT pin to the PIC18
and add a new entry to the InterruptVectorL to treat the interrupt.

Of course you can create such an alarm easily with PICos18. In the TASK0
example the code can compare the Time structure read from the DS1337 to 
a list of alarm. It is a software alarm management but it is easy to 
write and to debug... and there is no alarm limitation !


/* End of File : drv_DS1337.txt */