rtc_hardware

Support for builtin RealTimeClockCalendar modules of 18FxxJxx.

Author Rob Hamerling, Copyright (c) 2010..2010, 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:
  - rtc_init()                  -- initialize rtc module and library
  - rtc_calibrate()             -- compensate crystal frequency aberration
  - rtc_pin_signal()            -- RTCC output pin signal control
  - rtc_get_hhmm_bcd()          -- obtain hours,minute (bcd format)
  - rtc_get_hhmm_bin()          -- obtain relative minute of day (binary)
  - rtc_get_hhmmss_bcd()        -- obtain hours,minutes,seconds (bcd format)
  - rtc_get_hhmmss_bin()        -- obtain relative second of day (binary)
  - rtc_set_hhmmss_bcd()        -- set new hours,minutes,seconds (bcd format)
  - rtc_get_yymmdd_bcd()        -- get year,month,day (bcd format)
  - rtc_set_yymmdd_bcd()        -- set new year,month,day (bcd format)
  - rtc_get_weekday()           -- get day of week number (binary)
  - rtc_get_alarm_hhmmss_bcd()  -- get alarm time (bcd format)
  - rtc_set_alarm_hhmmss_bcd()  -- set alarm time (bcd format)
  - rtc_set_alarm_period()      -- set alarm period
  - rtc_set_alarm_repeat()      -- set alarm repeat
  - rtc_set_alarm()             -- enable/disable alarm
.
Additional general purpose functions and procedures:
  - bcd2bin()                   -- convert byte from bcd to binary
  - mult60()                    -- hours -> minutes, minutes -> seconds
.
Several procedures and functions use multi-byte variables to pass
arguments in bcd-notation. This is done in high-to-low sequence.
To access the individual bytes of such a 'composite' variable you
could use the data overlay facility of the compiler.
For example for the date in years, months and days you could
declare a variable as:
.
   var  byte*3  yymmdd_bcd                   -- date (bcd)
.
and in addition:
.
   var  byte    yymmdd[3] at  yymmdd_bcd     -- overlay as array
   var  byte    yy        at  yymmdd[0]      -- )
   var  byte    mm        at  yymmdd[1]      -- ) overlay as bytes
   var  byte    dd        at  yymmdd[2]      -- )
.
Now you can access the year-byte of 'yymmdd_bcd' simply with 'yy'
(contents still in bcd notation!), and month and day similarly.
.
PICs use little endian notation (store multi-byte variables with
low order byte first)! So when you want to set the date to 10:07:28
you must specify:
   rtc_set_yymmdd(0x280710)                  -- 'reversed' sequence!
.
Bytes in bcd-notation can easily be displayed with print_byte_hex()
of the Jallib print library.


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_repeat(byte in alarm_repeat)

    Set alarm repetition factor.
    input: alarm_repeat (byte): number of times to repeat alarm signal
    output: none
    returns: nothing
    
    

  • rtc_set_yymmdd_bcd(byte*3 in yymmdd_bcd)

    Set date (yymmdd) in BCD format.
    input:   year,month,day-of-month in bcd format (byte*3)
    output:  none
    returns: nothing
    notes: - Expected range: yy 0..99, mm 1..12, dd 1..31 in bcd notation
           - RTC hardware does not calculate weekday from date, so we have
             to do it here.  We use the algorithm by Tomohiko Sakamoto of Sony,
             slightly squeezed to support 21st century only (2000..2099).
    
    

  • rtc_set_alarm(bit in alarm_state)

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

  • rtc_init()

    Initialize the RTCC module.
    input: none
    output: none
    returns: nothing
    notes:
    
    

  • rtc_set_alarm_hhmmss_bcd(byte*3 in hhmmss_bcd)

    Set alarm time in bcd format.
    input: hour-minute-second in bcd format
    output: none
    returns: nothing
    
    

  • rtc_set_alarm_signal(bit in alarm_signal)

    Set alarm signal.
    input: alarm_signal (bit): true  - alarm signal activated
                               false - alarm signal deactivated
    output: none
    returns: nothing
    
    

  • rtc_set_hhmmss_bcd(byte*3 in hhmmss_bcd)

    Set time of day (hhmmss) in BCD format.
    input: year,month,day-of-month in bcd format (byte*3)
    output: none
    returns: nothing
    
    

  • rtc_set_alarm_period(byte in alarm_period)

    Set alarm period.
    input: alarm_period with a RTC_ALARM_PERIOD_xxxx mask
           (see the defined RTC_ALARM_PERIOD_xxxx masks above)
    output: none
    returns: nothing
    
    

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

Private
  • _rtc_read()

    Read the realtime clock.
    input:  none
    output: none
    returns: nothing
    notes: copy RTC registers to 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 generates the correct sequences with the code below.
    
    

  • _rtc_alrm_read()

    Read the alarm setting.
    input:  none
    output: none
    returns: nothing
    notes: copy RTC alarm registers to local variables
    
    

  • _rtc_write()

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

  • _rtc_alrm_write()

    Write te alarm time of realtime clock.
    input:  none
    output: none
    returns: nothing
    notes: - disable alarm
           - copy RTC alarm registers to 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_hhmmss_bcd() return byte*3

    Get time of day (hhmmss) in BCD format.
    input: none
    output: none
    returns: hhmmss in bcd format (byte*3)
    
    

  • rtc_get_hhmm_bin() return word

    Get relative minute of day in binary format
    input: none
    output: none
    returns: minute of day binary (word)
    
    

  • rtc_get_weekday() return byte

    Get weekday number in binary format.
    input: none
    output: none
    returns: day of week number (0..6)
    
    

  • rtc_get_hhmm_bcd() return word

    Get time of day (hhmm) in BCD format.
    input: none
    output: none
    returns: hhmm in bcd format (word)
    
    

  • rtc_get_hhmmss_bin() return dword

    Get relative second of day in binary format
    input: none
    output: none
    returns: second of day binary (dword)
    
    

  • rtc_get_alarm_hhmmss_bcd() return byte*3

    Get alarm time of day in BCD format.
    input: none
    output: none
    returns: alarm time setting (hhmmss) in bcd format
    
    

  • rtc_get_yymmdd_bcd() return byte*3

    Get date (yymmdd) in BCD format.
    input: none
    output: none
    returns: yymmdd in bcd format
    
    

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


Related samples

Here are the list of samples which use this library:

18f26j1118f26j11_rtc_hardware.jal