# rtcc_hw

Support for builtin RealTimeClockCalendar (RTCC) module of 18FxxJxx.

Author | Rob Hamerling, Copyright © 2010..2015, all rights reserved.
Adapted-by |
Compiler | 2.4q3

Description

    RealTimeClock support:
      - Routines for control of the buitin Realtime Clock Calendar module of
        18fxxj11, 18fxxj50 and other smilar PICs.
    .
    his library provides the device specific interface for the services
    defined in the rtc_common library, ic functions and procedures for
    the realtime clock time and date services.
    in addition it contains procedures and functions for the alarm and
    some other facilities of the RTCC module, like:
    .
      - rtc_set_alarm()              -- enable/disable alarm
      - rtc_get_alarm_date_bcd()     -- alarm month,day (bcd), no year!
      - rtc_set_alarm_date_bcd()
      - rtc_get_alarm_time_bcd()     -- alarm hour,minute,second (bcd)
      - rtc_set_alarm_time_bcd()
      - rtc_set_alarm_interval()     -- alarm interval (binary)
      - rtc_set_alarm_repeat()       -- alarm repeat (binary)
      - rtc_set_clock()              -- enable/disable RTCC module
      - rtc_calibrate()              -- compensate crystal frequency aberration
      - rtc_pin_signal()             -- RTCC output pin signal control
    .

Dependencies

- rtc_common

## Summary

### Global variables/contants

- `const byte RTC_ALARM_INTERVAL_DAY = 0b0110`
- `const RTC_HW = 0`
- `const byte RTC_ALARM_INTERVAL_TENMINUTES = 0b0100`
- `const byte RTC_ALARM_INTERVAL_YEAR = 0b1001`
- `const bit*2 RTC_PIN_SOURCE_CLOCK = 0b10`
- `const bit*2 RTC_PIN_NONE = 0b11`
- `const bit*2 RTC_PIN_SECONDS = 0b01`
- `const byte RTC_ALARM_INTERVAL_MINUTE = 0b0011`
- `const byte RTC_ALARM_INTERVAL_HALFSECOND = 0b0000`
- `const byte RTC_ALARM_INTERVAL_MONTH = 0b1000`
- `const byte RTC_ALARM_INTERVAL_SECOND = 0b0001`
- `const byte RTC_ALARM_INTERVAL_HOUR = 0b0101`
- `const byte RTC_ALARM_INTERVAL_WEEK = 0b0111`
- `const bit*2 RTC_PIN_ALARM = 0b00`
- `const byte RTC_ALARM_INTERVAL_TENSECONDS = 0b0010`

### Procedures

- `rtc_set_alarm_time_bcd(byte in hh, byte in mm, byte in ss)`
- `rtc_write_sync_(bit*2 in mask, bit in hl, byte in value)`
- `rtc_write_month(byte in month)`
- `rtc_calibrate(sbyte in calibration)`
- `rtc_write_control_(bit in control)`
- `rtc_set_alarm_interval(byte in interval)`
- `rtc_read_sync_()`
- `rtc_write_minute(byte in minute)`
- `rtc_set_alarm_date_bcd(byte in mm, byte in dom, byte in dow)`
- `rtc_set_alarm_repeat(byte in repeats)`
- `rtc_write_hour(byte in hour)`
- `rtc_write_second(byte in second)`
- `rtc_pin_signal(bit*2 in pin_signal_selection_mask)`
- `rtc_write_dayofmonth(byte in dayofmonth)`
- `rtc_get_alarm_time_bcd(byte out hh, byte out mm, byte out ss)`
- `rtc_set_alarm(bit in state)`
- `rtc_write_year(byte in year)`
- `rtc_get_alarm_date_bcd(byte out mm, byte out dom, byte out dow)`
- `rtc_set_clock(bit in state)`

### 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_minute() return byte`

## API details

### Global variables/contants

- `const byte RTC_ALARM_INTERVAL_DAY = 0b0110`

  No documentation found

- `const RTC_HW = 0`

      identification: RTCC module of PIC

- `const byte RTC_ALARM_INTERVAL_TENMINUTES = 0b0100`

  No documentation found

- `const byte RTC_ALARM_INTERVAL_YEAR = 0b1001`

  No documentation found

- `const bit*2 RTC_PIN_SOURCE_CLOCK = 0b10`

  No documentation found

- `const bit*2 RTC_PIN_NONE = 0b11`

      (disable RTCC pin)

- `const bit*2 RTC_PIN_SECONDS = 0b01`

  No documentation found

- `const byte RTC_ALARM_INTERVAL_MINUTE = 0b0011`

  No documentation found

- `const byte RTC_ALARM_INTERVAL_HALFSECOND = 0b0000`

      Set alarm interval.
      input:   alarm_interval with a RTC_ALARM_INTERVAL_xxxx mask
      (see the defined RTC_ALARM_INTERVAL_xxxx masks above)
      output:  none
      returns: (nothing)

      RTCC alarm repetition interval masks

- `const byte RTC_ALARM_INTERVAL_MONTH = 0b1000`

  No documentation found

- `const byte RTC_ALARM_INTERVAL_SECOND = 0b0001`

  No documentation found

- `const byte RTC_ALARM_INTERVAL_HOUR = 0b0101`

  No documentation found

- `const byte RTC_ALARM_INTERVAL_WEEK = 0b0111`

  No documentation found

- `const bit*2 RTC_PIN_ALARM = 0b00`

      Select the RTCC output pin signal functionality.
      input: 2-bits mask: one of the RTC_PIN_xxxx constants (see above)
      output: none
      returns: nothing
      notes: - With 'NONE' pin_RTCC is released and available for I/O
       See the datasheet for the meaning of the different masks.

      RTCC pin function masks

- `const byte RTC_ALARM_INTERVAL_TENSECONDS = 0b0010`

  No documentation found

### Procedures

- `rtc_set_alarm_time_bcd(byte in hh, byte in mm, byte in ss)`

      Write alarm time
      input:   alarm hour, minute, second (bcd format)
      output:  none
      returns: (nothing)
      notes:   - disable alarm, modify alarm registers, restore alarm

- `rtc_write_sync_(bit*2 in mask, bit in hl, byte in value)`

      Title: Write a byte to the RTCC module.
      input: - bit*2 mask determining the entity
       bit determining high or low byte of RTCVAL (LOW = 0, HIGH = 1)
       byte with vale to be written (bcd notation)
      Notes: - Writes are nrmally disabled, but here enabled when needed
      and disabled again before returning to caller.

- `rtc_write_month(byte in month)`

      Write month

- `rtc_calibrate(sbyte in calibration)`

      Calibrate the RTCC module.
      input: calibration value
      output: none
      returns: nothing
      note: Calibration value is a signed byte  (-128..+127).
      A negative value must be specified when the crystal is too fast.
      See datasheet for the calculation of the amount.

- `rtc_write_control_(bit in control)`

      ======================================================================
      RTCC library internal functions and procedures (not for user programs)
      ======================================================================

      Enable or disable RTCC register writes.
      input: bit (enable / disable)
      output: none
      returns: nothing
      notes:  (Re)setting the RTCWREN bit in RTCCFG requires a strict
      sequence, see datasheets for details.

- `rtc_set_alarm_interval(byte in interval)`

  No documentation found

- `rtc_read_sync_()`

      Wait for the proper moment to read the clock

- `rtc_write_minute(byte in minute)`

      Write minute

- `rtc_set_alarm_date_bcd(byte in mm, byte in dom, byte in dow)`

      Write alarm date
      input:   alarm month, dayofmonth, dayofweek
      output:  none
      returns: (nothing)
      notes:   - disable alarm, write alarm registers,  restore alarm state

- `rtc_set_alarm_repeat(byte in repeats)`

      Set alarm repetition.
      input:   repeats: number of times to repeat alarm signal (binary)
      output:  none
      returns: (nothing)
      notes:   The following will happen after an alarm condition:
       with repeat value 0 there will be 1 alarm event
       with repeat values 1..254 there will be as many more alarm
      events as specified with
      (at intervals specified with rtc_set_alarm_interval() )
       with repeat value 255 there will be indefinite alarm events
      The ALRMCFG_ALRMEN bit will be cleared after the last alarm event
      (thus never with repeat value 255).

- `rtc_write_hour(byte in hour)`

      Write hour

- `rtc_write_second(byte in second)`

      Write second

- `rtc_pin_signal(bit*2 in pin_signal_selection_mask)`

  No documentation found

- `rtc_write_dayofmonth(byte in dayofmonth)`

      Write dayofmonth

- `rtc_get_alarm_time_bcd(byte out hh, byte out mm, byte out ss)`

      Read alarm time
      input:   none
      output:  alarm hour, minute, second (bcd format)
      returns: (nothing)
      notes:   read alarm registers into user variables

- `rtc_set_alarm(bit in state)`

      Enable or disable alarm
      input:   alarm_state (bit): true  - enable alarm
      false - disable alarm
      output:  none
      returns: (nothing)

- `rtc_write_year(byte in year)`

      Write year

- `rtc_get_alarm_date_bcd(byte out mm, byte out dom, byte out dow)`

      Read alarm date
      input:   none
      output:  alarm month, dayofmonth, dayofweek (bcd format)
      returns: (nothing)
      notes: read alarm registers into local variables

- `rtc_set_clock(bit in state)`

      Enable or disable the RTCC module.
      input: none
      output: none
      returns: nothing
      notes: The T1 oscillator is enable/disabled too!

### Functions

- `rtc_read_hour() return byte`

      Read hour

- `rtc_read_dayofmonth() return byte`

      Read day of month

- `rtc_read_year() return byte`

      Read year

- `rtc_read_month() return byte`

      Read month

- `rtc_read_second() return byte`

      ======================================================================
      Services for the rtc_common library
      ======================================================================

      Read second

- `rtc_read_minute() return byte`

      Read minute

## Related samples

Here are the list of samples which use this library:

18f26j11 | 18f26j11_rtcc_hw_kbd_lcd.jal
18f27j53 | 18f27j53_rtcc_hw_alarm.jal