# rtc_ds1302

communication between rtc DS1302 chip and microcontroller

Author | Richard Zengerink, Copyright © 2008, all rights reserved
Adapted-by | Rob Hamerling (2013, 2015), refactoring.
Compiler | 2.4q3

Description

    Library to handle DS1302 rtc chip

Dependencies

- rtc_common

## Summary

### Global variables/contants

- `var volatile byte rtc_protect_ = 0x00`
- `const byte rtc_reg_year_ = 0x8C`
- `var bit rtc_trickle__rs1 at rtc_trickle_ : 1`
- `const byte rtc_reg_month_ = 0x88`
- `const byte rtc_reg_burst_ram_ = 0xFE`
- `const byte rtc_reg_protect_ = 0x8E`
- `var bit rtc_trickle__ds0 at rtc_trickle_ : 2`
- `const byte rtc_reg_dayofmonth_ = 0x86`
- `var volatile byte rtc_trickle_ = 0b1010_0000`
- `const byte rtc_reg_second_ = 0x80`
- `const byte rtc_reg_dayofweek_ = 0x8A`
- `const byte rtc_reg_burst_clock_ = 0xBE`
- `const byte rtc_reg_hour_ = 0x84`
- `const RTC_HW = 1302`
- `const byte rtc_reg_minute_ = 0x82`
- `var bit rtc_trickle__ds1 at rtc_trickle_ : 3`
- `const byte rtc_reg_ram_ = 0xC0`
- `var bit rtc_trickle__rs0 at rtc_trickle_ : 0`
- `const byte rtc_reg_trickle_ = 0x90`

### Procedures

- `rtc_write_month(byte in month)`
- `rtc_stop()`
- `rtc_write_byte_raw_(byte in data)`
- `rtc_write_reg_(byte in register, byte in data)`
- `rtc_init()`
- `rtc_start()`
- `rtc_clock_pulse_()`
- `rtc_write_dayofmonth(byte in dayofmonth)`
- `rtc_write_hour(byte in hour)`
- `rtc_read_byte_raw_(byte out data)`
- `rtc_write_second(byte in second)`
- `rtc_write_protect(bit in flag)`
- `rtc_read_reg_(byte in register, byte out data)`
- `rtc_write_minute(byte in minute)`
- `rtc_write_year(byte in year)`

### Functions

- `rtc_read_hour() return byte`
- `rtc_read_dayofmonth() return byte`
- `rtc_read_year() return byte`
- `rtc_read_month() return byte`
- `rtc_read_second() return byte`
- `rtc_read_protect() return bit`
- `rtc_read_minute() return byte`

## API details

### Global variables/contants

- `var volatile byte rtc_protect_ = 0x00`

      no write protection

- `const byte rtc_reg_year_ = 0x8C`

  No documentation found

- `var bit rtc_trickle__rs1 at rtc_trickle_ : 1`

  No documentation found

- `const byte rtc_reg_month_ = 0x88`

  No documentation found

- `const byte rtc_reg_burst_ram_ = 0xFE`

  No documentation found

- `const byte rtc_reg_protect_ = 0x8E`

  No documentation found

- `var bit rtc_trickle__ds0 at rtc_trickle_ : 2`

  No documentation found

- `const byte rtc_reg_dayofmonth_ = 0x86`

  No documentation found

- `var volatile byte rtc_trickle_ = 0b1010_0000`

      basic trickle pattern

- `const byte rtc_reg_second_ = 0x80`

  No documentation found

- `const byte rtc_reg_dayofweek_ = 0x8A`

  No documentation found

- `const byte rtc_reg_burst_clock_ = 0xBE`

  No documentation found

- `const byte rtc_reg_hour_ = 0x84`

  No documentation found

- `const RTC_HW = 1302`

       realtime clock hardware identification

- `const byte rtc_reg_minute_ = 0x82`

  No documentation found

- `var bit rtc_trickle__ds1 at rtc_trickle_ : 3`

  No documentation found

- `const byte rtc_reg_ram_ = 0xC0`

      first of 31 bytes

- `var bit rtc_trickle__rs0 at rtc_trickle_ : 0`

      Declare and pre-format the trickle charge mask byte
      according the constants defined in the application program.
      Trickle charging of the backup battery will only be active
      with rtc_diode value 1 or 2, and rtc_resistor value 2, 4 or 8.
      Any other combination will result in no trickle charging, without warning!

- `const byte rtc_reg_trickle_ = 0x90`

  No documentation found

### Procedures

- `rtc_write_month(byte in month)`

      write month value to the rtc

- `rtc_stop()`

- `rtc_write_byte_raw_(byte in data)`

      physical write of a byte to ds1302 (register or data)

- `rtc_write_reg_(byte in register, byte in data)`

      Write specified data to a specified register

- `rtc_init()`

      initialize the rtc

- `rtc_start()`

      start the rtc

- `rtc_clock_pulse_()`

      physical clock pulse  { high - 1us - low - 1us }

- `rtc_write_dayofmonth(byte in dayofmonth)`

      write day of month value to the rtc

- `rtc_write_hour(byte in hour)`

      write hour value to the rtc

- `rtc_read_byte_raw_(byte out data)`

      physical read of byte from ds1302

- `rtc_write_second(byte in second)`

      write second value to the rtc

- `rtc_write_protect(bit in flag)`

      write clock-write-protection state to rtc

- `rtc_read_reg_(byte in register, byte out data)`

      Read specified data from a specified register

- `rtc_write_minute(byte in minute)`

      write minute value to the rtc

- `rtc_write_year(byte in year)`

      write year value to the rtc

### Functions

- `rtc_read_hour() return byte`

      read hour value from rtc

- `rtc_read_dayofmonth() return byte`

      read day of month value from rtc

- `rtc_read_year() return byte`

      read year value from rtc

- `rtc_read_month() return byte`

      read month value from rtc

- `rtc_read_second() return byte`

      read second value from rtc

- `rtc_read_protect() return bit`

      read clock-write-protection state from rtc

- `rtc_read_minute() return byte`

      read minute value from rtc

## Related samples

Here are the list of samples which use this library:

18f2580 | 18f2580_rtc_ds1302_glcd.jal