# rtc_ds3231

Library for the DS3231 Real Time Clock IC.

Author | Rob Jansen, Copyright © 2021..2023, all rights reserved.
Adapted-by |
Compiler | 2.5r8

Description

    Library for controlling the SD3231 Real Time Clock IC.
                 The chip uses an IIC interface. The library provides all
                 functions and procedures to support the rtc_common.jal library and
                 includes extra functions and procedures specific for the DS3231.
                 For all common rtc procedures and functions see rtc_common.jal.

Sources

    Maxim datasheet rtc. 19-5170; Rev 10; 3/15

Dependencies

- rtc_common

## Summary

### Global variables/contants

- `const byte RTC_SQUARE_WAVE_8_KHZ = 0b0001_1000`
- `const byte RTC_ALARM_1_SECONDS_ADDRESS = 0x07`
- `const byte RTC_ALARM_2_DAY_DATE_ADDRESS = 0x0D`
- `const RTC_HW = 3231`
- `const byte RTC_STATUS_ADDRESS = 0x0F`
- `const byte RTC_TIME_SECONDS_ADDRESS = 0x00`
- `const byte RTC_SQUARE_WAVE_1_HZ = 0b0000_0000`
- `const byte RTC_IIC_WR_ADDRESS = 0b1101_0000`
- `const byte RTC_TIME_YEAR_ADDRESS = 0x06`
- `const byte RTC_IIC_RD_ADDRESS = 0b1101_0001`
- `const byte RTC_ALARM_1_DATE_HOUR_MIN_SEC_MATCH = 4`
- `const byte RTC_ALARM_2_ONCE_PER_MIN = 0`
- `const byte RTC_SQUARE_WAVE_1_KHZ = 0b0000_1000`
- `const byte RTC_SQUARE_WAVE_4_KHZ = 0b0001_0000`
- `const byte RTC_ALARM_1_DAY_DATE_ADDRESS = 0x0A`
- `const byte RTC_TIME_HOUR_ADDRESS = 0x02`
- `const byte RTC_ALARM_1_MINUTES_ADDRESS = 0x08`
- `const byte RTC_ALARM_1_SEC_MATCH = 1`
- `const byte RTC_AGING_ADDRESS = 0x10`
- `const byte RTC_TIME_DATE_ADDRESS = 0x04`
- `const byte RTC_ALARM_1_ONCE_PER_SEC = 0`
- `const byte RTC_ALARM_1_HOUR_MIN_SEC_MATCH = 3`
- `const byte RTC_ALARM_1_HOUR_ADDRESS = 0x09`
- `const byte RTC_ALARM_2_MIN_MATCH = 1`
- `const byte RTC_TIME_MINUTES_ADDRESS = 0x01`
- `const byte RTC_CONTROL_ADDRESS = 0x0E`
- `const byte RTC_TIME_DAY_ADDRESS = 0x03`
- `const byte RTC_ALARM_1_MIN_SEC_MATCH = 2`
- `const byte RTC_ALARM_2_HOUR_MIN_MATCH = 2`
- `const byte RTC_ALARM_2_HOUR_ADDRESS = 0x0C`
- `const byte RTC_ALARM_1_DAY_HOUR_MIN_SEC_MATCH = 5`
- `const byte RTC_TEMP_MSB_ADDRESS = 0x11`
- `const byte RTC_ALARM_2_MINUTES_ADDRESS = 0x0B`
- `const byte RTC_ALARM_2_DATE_HOUR_MIN_MATCH = 3`
- `const byte RTC_TEMP_LSB_ADDRESS = 0x12`
- `const byte RTC_TIME_MONTH_ADDRESS = 0x05`
- `const byte RTC_ALARM_2_DAY_HOUR_MIN_MATCH = 4`

### Procedures

- `rtc_get_alarm_2_time_bin(byte out hour, byte out minutes)`
- `rtc_write_month(byte in month)`
- `rtc_write_full_year(word in year)`
- `rtc_set_square_wave(byte in frequency)`
- `rtc_set_alarm_1_day(byte in day)`
- `rtc_init()`
- `rtc_write_register(byte in register, byte in data)`
- `rtc_write_hour(byte in hour)`
- `rtc_start()`
- `rtc_get_alarm_1_time_bin(byte out hour, byte out minutes, byte out seconds)`
- `clear_rtc_alarm_1_flag()`
- `rtc_write_minute(byte in minute)`
- `rtc_disable_alarm_2_interrupt()`
- `rtc_set_alarm_1_time_bcd(byte in hour, byte in minutes, byte in seconds)`
- `rtc_disable_32_khz()`
- `rtc_set_alarm_2_time_bin(byte in hour, byte in minutes)`
- `rtc_write_year(byte in year)`
- `rtc_set_alarm_1_time_bin(byte in hour, byte in minutes, byte in seconds)`
- `rtc_set_alarm_1_date(byte in date)`
- `rtc_enable_32_khz()`
- `rtc_get_alarm_1_time_bcd(byte out hour, byte out minutes, byte out seconds)`
- `rtc_disable_alarm_1_interrupt()`
- `rtc_read_register(byte in register, byte out data)`
- `rtc_set_alarm_1_rate(byte in rate)`
- `rtc_enable_alarm_2_interrupt()`
- `rtc_enable_alarm_1_interrupt()`
- `rtc_write_dayofweek(byte in dayofweek)`
- `rtc_set_alarm_2_rate(byte in rate)`
- `rtc_stop()`
- `rtc_get_alarm_2_time_bcd(byte out hour, byte out minutes)`
- `clear_rtc_alarm_2_flag()`
- `rtc_write_second(byte in second)`
- `rtc_write_dayofmonth(byte in dayofmonth)`
- `rtc_set_alarm_2_time_bcd(byte in hour, byte in minutes)`

### Functions

- `rtc_alarm_1_flag() return bit`
- `rtc_read_hour() return byte`
- `rtc_read_dayofmonth() return byte`
- `rtc_read_dayofweek() return byte`
- `rtc_alarm_2_flag() return bit`
- `rtc_read_month() return byte`
- `rtc_read_second() return byte`
- `ds3231_get_temperature() return sword`
- `rtc_read_minute() return byte`
- `rtc_read_year() return byte`
- `rtc_read_full_year() return word`

## API details

### Global variables/contants

- `const byte RTC_SQUARE_WAVE_8_KHZ = 0b0001_1000`

  No documentation found

- `const byte RTC_ALARM_1_SECONDS_ADDRESS = 0x07`

  No documentation found

- `const byte RTC_ALARM_2_DAY_DATE_ADDRESS = 0x0D`

  No documentation found

- `const RTC_HW = 3231`

      Realtime clock hardware identification needed for the rtc_common.jal library,

- `const byte RTC_STATUS_ADDRESS = 0x0F`

  No documentation found

- `const byte RTC_TIME_SECONDS_ADDRESS = 0x00`

      Address constants of the RTC rtc chip. Shown here in case the user wants to
      write the register using the advanced procedures to control the registers.

- `const byte RTC_SQUARE_WAVE_1_HZ = 0b0000_0000`

      Sqare wave frequency definitions.

- `const byte RTC_IIC_WR_ADDRESS = 0b1101_0000`

      IIC address, read and write

- `const byte RTC_TIME_YEAR_ADDRESS = 0x06`

  No documentation found

- `const byte RTC_IIC_RD_ADDRESS = 0b1101_0001`

  No documentation found

- `const byte RTC_ALARM_1_DATE_HOUR_MIN_SEC_MATCH = 4`

  No documentation found

- `const byte RTC_ALARM_2_ONCE_PER_MIN = 0`

      Alarm rates of alarm 2.

- `const byte RTC_SQUARE_WAVE_1_KHZ = 0b0000_1000`

  No documentation found

- `const byte RTC_SQUARE_WAVE_4_KHZ = 0b0001_0000`

  No documentation found

- `const byte RTC_ALARM_1_DAY_DATE_ADDRESS = 0x0A`

  No documentation found

- `const byte RTC_TIME_HOUR_ADDRESS = 0x02`

  No documentation found

- `const byte RTC_ALARM_1_MINUTES_ADDRESS = 0x08`

  No documentation found

- `const byte RTC_ALARM_1_SEC_MATCH = 1`

  No documentation found

- `const byte RTC_AGING_ADDRESS = 0x10`

  No documentation found

- `const byte RTC_TIME_DATE_ADDRESS = 0x04`

  No documentation found

- `const byte RTC_ALARM_1_ONCE_PER_SEC = 0`

      Alarm rates of alarm 1.

- `const byte RTC_ALARM_1_HOUR_MIN_SEC_MATCH = 3`

  No documentation found

- `const byte RTC_ALARM_1_HOUR_ADDRESS = 0x09`

  No documentation found

- `const byte RTC_ALARM_2_MIN_MATCH = 1`

  No documentation found

- `const byte RTC_TIME_MINUTES_ADDRESS = 0x01`

  No documentation found

- `const byte RTC_CONTROL_ADDRESS = 0x0E`

  No documentation found

- `const byte RTC_TIME_DAY_ADDRESS = 0x03`

  No documentation found

- `const byte RTC_ALARM_1_MIN_SEC_MATCH = 2`

  No documentation found

- `const byte RTC_ALARM_2_HOUR_MIN_MATCH = 2`

  No documentation found

- `const byte RTC_ALARM_2_HOUR_ADDRESS = 0x0C`

  No documentation found

- `const byte RTC_ALARM_1_DAY_HOUR_MIN_SEC_MATCH = 5`

  No documentation found

- `const byte RTC_TEMP_MSB_ADDRESS = 0x11`

  No documentation found

- `const byte RTC_ALARM_2_MINUTES_ADDRESS = 0x0B`

  No documentation found

- `const byte RTC_ALARM_2_DATE_HOUR_MIN_MATCH = 3`

  No documentation found

- `const byte RTC_TEMP_LSB_ADDRESS = 0x12`

  No documentation found

- `const byte RTC_TIME_MONTH_ADDRESS = 0x05`

  No documentation found

- `const byte RTC_ALARM_2_DAY_HOUR_MIN_MATCH = 4`

  No documentation found

### Procedures

- `rtc_get_alarm_2_time_bin(byte out hour, byte out minutes)`

      Get alarm 2 time in hours and minutes in binary notation.
      Hours must be in 24-hours format.

- `rtc_write_month(byte in month)`

      Write month value in bcd notation to the rtc.

- `rtc_write_full_year(word in year)`

      Write year full value in bcd notation to the rtc. The high byte of the
      parameter contains the year hunderds in bcd, the low byte the tens years
      in bcd.

- `rtc_set_square_wave(byte in frequency)`

      Set the square wave frequency and output.
      Note: This will disable the interrupt functionality on the INT/SQW pin.
      The M version of the DS3231 can only generate the 1 Hz signal.

- `rtc_set_alarm_1_day(byte in day)`

      Set alarm 1 day (day of the week) in bcd notation.

- `rtc_init()`

      Intialize the rtc by initializing the IIC interface and setting the
      clock to 24-hour mode and setting the year above the year 2000.
      All the device interrupts will be disabled.

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

      Write a byte to the given register of the DS3231.

- `rtc_write_hour(byte in hour)`

      Write 24-hour value in bcd notation to the rtc.

- `rtc_start()`

      Start the rtc.

- `rtc_get_alarm_1_time_bin(byte out hour, byte out minutes, byte out seconds)`

      Get alarm 1 time in hours, minutes and seconds in binary notation.
      Hours must be in 24-hours format.

- `clear_rtc_alarm_1_flag()`

      Clears alarm flag 1.

- `rtc_write_minute(byte in minute)`

      Write minute value in bcd notation to the rtc.

- `rtc_disable_alarm_2_interrupt()`

      Disable alarm 2 interrupt.
      Note: This will also disable the square wave output on the INT/SQW pin.

- `rtc_set_alarm_1_time_bcd(byte in hour, byte in minutes, byte in seconds)`

      Set alarm 1 time in hours, minutes and seconds in bcd notation.
      Hours must be in 24-hours format.
      When the alarm time matches then rtc_alarm_1_flag will be set and must be
      cleared by the user.

- `rtc_disable_32_khz()`

      Disable the 32 kHz output pin.

- `rtc_set_alarm_2_time_bin(byte in hour, byte in minutes)`

      Set alarm 2 time in hours and minutes in binary notation.
      Hours must be in 24-hours format.
      When the alarm time matches then rtc_alarm_2_flag will be set and must be
      cleared by the user.

- `rtc_write_year(byte in year)`

      Write year value in bcd notation to the rtc.

- `rtc_set_alarm_1_time_bin(byte in hour, byte in minutes, byte in seconds)`

      Set alarm 1 time in hours, minutes and seconds in binary notation.
      Hours must be in 24-hours format.
      When the alarm time matches then rtc_alarm_1_flag will be set and must be
      cleared by the user.

- `rtc_set_alarm_1_date(byte in date)`

      Set alarm 1 date (day of the month) in bcd notation.

- `rtc_enable_32_khz()`

      Enable the 32 kHz output pin.

- `rtc_get_alarm_1_time_bcd(byte out hour, byte out minutes, byte out seconds)`

      Get alarm 1 time in hours, minutes and seconds in bcd notation.
      Hours must be in 24-hours format.

- `rtc_disable_alarm_1_interrupt()`

      Disable alarm 1 interrupt.
      Note: This will also disable the square wave output on the INT/SQW pin.

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

      Read a byte from the given register of the DS3231.

- `rtc_set_alarm_1_rate(byte in rate)`

      Set alarm 1 rate according to the given parameter.
      Note: When using RTC_ALARM_1_DATE_HOUR_MIN_SEC_MATCH or
      RTC_ALARM_1_DAY_HOUR_MIN_SEC_MATCH make sure to have set the
      alarm date or alarm day accordingly.

- `rtc_enable_alarm_2_interrupt()`

      Enable alarm 2 interrupt.
      Note: This will disable the square wave output on the INT/SQW pin.

- `rtc_enable_alarm_1_interrupt()`

      Enable alarm 1 interrupt.
      Note: This will disable the square wave output on the INT/SQW pin.

- `rtc_write_dayofweek(byte in dayofweek)`

      Write day of week value to the rtc.

- `rtc_set_alarm_2_rate(byte in rate)`

      Set alarm 2 rate according to the given parameter.
      Note: When using RTC_ALARM_2_DATE_HOUR_MIN_MATCH or
      RTC_ALARM_2_DAY_HOUR_MIN_MATCH make sure to have set the
      alarm date or alarm day accordingly.

- `rtc_stop()`

      Stop the rtc.

- `rtc_get_alarm_2_time_bcd(byte out hour, byte out minutes)`

      Get alarm 2 time in hours and minutes in bcd notation.
      Hours must be in 24-hours format.

- `clear_rtc_alarm_2_flag()`

      Clears alarm flag 2.

- `rtc_write_second(byte in second)`

      Write second value in bcd notation to the rtc.

- `rtc_write_dayofmonth(byte in dayofmonth)`

      Write day of month value in bcd notation to the rtc.

- `rtc_set_alarm_2_time_bcd(byte in hour, byte in minutes)`

      Set alarm 2 time in hours and minutes in bcd notation.
      Hours must be in 24-hours format.
      When the alarm time matches then rtc_alarm_2_flag will be set and must be
      cleared by the user.

### Functions

- `rtc_alarm_1_flag() return bit`

      Returns TRUE when the set alarm 1 time matches the current RTC time.

- `rtc_read_hour() return byte`

      Read hour value from rtc in 24-hour bcd notation.

- `rtc_read_dayofmonth() return byte`

      Read day of month value from rtc in bcd notation.

- `rtc_read_dayofweek() return byte`

      Read day of week value from rtc.
      Note: In rct_common.jal this is calculated using rtc_calc_dayofweek()

- `rtc_alarm_2_flag() return bit`

      Returns TRUE when the set alarm 2 time matches the current RTC time.

- `rtc_read_month() return byte`

      Read month value from rtc in bcd notation.

- `rtc_read_second() return byte`

      Read second value from rtc in bcd notation.

- `ds3231_get_temperature() return sword`

      Read the temperature of the DS3231 and return the value. The value is given
      in Celsius with a 0.25 resolution. A value of 23.25 degrees is returned
      as 2325.
      Note: This is a specific DS3231 feature, not an rtc feature.

- `rtc_read_minute() return byte`

      Read minute value from rtc in bcd notation.

- `rtc_read_year() return byte`

      Read year value from rtc in bcd notation.

- `rtc_read_full_year() return word`

      Read the full year value from rtc in bcd notation. The high byte of the
      return value contains the year hunderds in bcd, the low byte the tens years
      in bcd.

## Related samples

Here are the list of samples which use this library:

16f1825 | 16f1825_rtc_ds3231.jal