rtcc_hw

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

Author Rob Hamerling, Copyright (c) 2010..2011, all rights reserved.
Adapted-by
Compiler 2.4n

Description

RealTimeClock support:
  - routines for control of realtime clock and alarm
.
This library supports:
  - RTCC modules like in 18fxxj11, 18fxxj50 and several other PICs.
.
Available procedures and functions for application programs
(not all of these may be implemented yet!).
.
Time/clock related operations:
  - rtc_set_clock()              -- enable/disable RTCC module
  - rtc_calibrate()              -- compensate crystal frequency aberration
  - rtc_pin_signal()             -- RTCC output pin signal control
  - rtc_get_date()               -- year,month,day (bcd)
  - rtc_set_date()
  - rtc_get_time()               -- hour,minute,second (bcd)
  - rtc_set_time()
  - rtc_get_secondofday()        -- second of day (binary)
  - rtc_get_minuteofday()        -- minute of day (binary)
  - rtc_get_dayofweek()          -- day of week number (binary)
  - rtc_get_dayofmonth()         -- day of month (binary)
  - rtc_get_dayofyear()          -- day of year (binary)
.
Alarm related operations:
  - rtc_set_alarm()              -- enable/disable alarm
  - rtc_get_alarm_date()         -- alarm month,day (bcd), no year!
  - rtc_set_alarm_date()
  - rtc_get_alarm_time()         -- alarm hour,minute,second (bcd)
  - rtc_set_alarm_time()
  - rtc_set_alarm_dayofweek()
  - rtc_set_alarm_interval()     -- alarm interval (binary)
  - rtc_set_alarm_repeat()       -- alarm repeat (binary)
.
General purpose functions and procedures:
  - bcd2bin()                   -- convert byte from bcd to binary
  - mult60()                    -- hours -> minutes; minutes -> seconds
.
The RTCC uses bcd notation for year, month, day, hour, minute and
second (all of these are byte variables).
.
Bytes in bcd-notation can easily be displayed with print_byte_hex()
of the Jallib print library.
.
For the compare of dates and times (for smaller or larger) the
library provides some functions which return binary values for
minute or second of the day, day of the week, day of the month
and day of the year.


Dependencies

No dependency found



Summary

Global variables/contants

Procedures

Private

Functions


API details

Global variables/contants

Procedures

  • 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_set_alarm_interval(byte in interval)

    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
    
    

  • rtc_set_alarm_dayofweek(byte in weekday)

    Set alarm time.
    input: day-of-week of alarm (binary, 0..6)
    output: none
    returns: nothing
    Notes: When setting the alarm date the alarm interval is
           by default set to once a week on the specified day of the week.
           You may want to set the alarm time first, or control the
           alarm interval separately.
    
    

  • 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_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 as 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_pin_signal(bit*2 in pin_signal_selection_mask)

    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.
    
    

  • 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!
    
    

Private
  • _rtc_read()

    Read the realtime clock.
    input:  none
    output: none
    returns: nothing
    notes: read clock/calendar registers into local variables
    
    

  • _rtc_write_control(bit in control)

    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.
            JalV2 2.4n and 2.4o(beta) generate the correct sequences
            with the code below.
    
    

  • _rtc_write()

    Write the realtime clock.
    input:  none
    output: none
    returns: nothing
    notes: - enable writing to RTC registers
           - write clock/calendar registers
           - disable writes
    
    

  • _rtc_alrm_read()

    Read the alarm setting.
    input:  none
    output: none
    returns: nothing
    notes: read alarm registers into local variables
    
    

  • _rtc_alrm_write()

    Write the alarm time of realtime clock.
    input:  none
    output: none
    returns: nothing
    notes: - disable alarm
           - write alarm registers from local variables
           - restore alarm state
    
    


Functions

  • mult60(word in x) return dword

    Multiply a word by 60 (typically for minutes to seconds or hours to minutes)
    input:   byte with binary data
    output:  none
    returns: word with product
    notes: - (x * 60) -> x * (64 - 4) -> (x * 64) - (x * 4)
           - algorithm without multiplication
           - word as input, dword as returnvalue chosen for
             relative second of day (function rtc_hhmmss_bin())
    
    

  • rtc_get_dayofweek() return byte

    Get day of week.
    input: none
    output: none
    returns: day of the week (binary byte 0..6)
    
    

  • rtc_get_dayofyear() return word

    Get day of year.
    input: none
    output: none
    returns: number of days sinece 1st of January (binary word 0..365)
    
    

  • rtc_get_minuteofday() return word

    Get minute of day.
    input: none
    output: none
    returns: number of minutes since midnight (binary word)
    
    

  • bcd2bin(byte in bcd) return byte

    ======================================================================
     General purpose functions / procedures
    ======================================================================
    
    Convert one byte packed bcd to one byte binary.
    input:   byte with bcd data
    output:  none
    returns: byte with binary value of bcd byte
    notes: - A byte in bcd notation contains ((16 * tens) + ones).
             To convert it to a binary value: subtract (6 * tens)
             Algorithm is modeled after an assembler version of
             Scott Dattalo at PicList (but slightly less efficient!).
    
    

  • rtc_get_secondofday() return dword

    Get second of day.
    input: none
    output: none
    returns: number of seconds since midnight (binary dword)
    
    

  • rtc_get_dayofmonth() return byte

    Get day of month.
    input: none
    output: none
    returns: number of days since 1st of the month (binary byte 0..30)
    
    


Related samples

Here are the list of samples which use this library:

18f26j1118f26j11_rtcc_hw_kbd_lcd.jal
18f27j5318f27j53_rtcc_hw_alarm.jal