ricohRTC - get/set time maintained by the Ricoh RTC; or interactively set its registers

ricohRTC [-i] [-s] [-t] [-a <oscadj>] [-k <0|1>] [-m <12|24>] [-h]

ricohRTC is a utility to manipulate the Ricoh RTC clock on Sidearm version 4 (and later).  Note that the Ricoh RTC is separate and distinct from the RTC built into the SA-1100 StrongArm processor (dubbed the SA1100 RTC).  The Ricoh RTC was added to the hardware to maintain time across power outages -- the SA1100 RTC doesn't do this.  The Ricoh has its own backup battery.

Clearly, for the Ricoh to become a useful resource, the chip must first be properly set up, including having the proper date & time set.  This utility allows that maintenance to take place; and is also the utility used by various system shell scripts that manage the system time.

To be clear, with the addition of the Ricoh RTC hardware, the system has 3 concepts of time:

• The system time - this is the time maintained in the Linux software, driven by a periodic interrupt.  It's volatile; it goes away when the system boots.  The resolution is dependent on the frequency of the clock interrupt, but typically it's on the order of 10 ms.
• The SA1100 RTC - the RTC built into the StrongArm processor chip.  It persists through reboot cycles, but will be cleared if the system is powered down.  It has a resolution of 1 second.
• The Ricoh RTC, which this utility manages.  It persists forever, as long as its battery is alive.  It has a resolution of 1 second.


This utility manipulates the Ricoh RTC time, and optionally the system time.  It has no effect on SA1100 RTC time.

With no options specified (i.e. running "ricohRTC", this utility simply displays the time & date maintained by the Ricoh RTC.  The options are:

• -i - This runs the utility in interactive mode.  It displays an ASCII menu which allows the user to perform various high- and low-level functions on the chips registers.  These range from getting & setting time (Ricoh RTC time or system time) to setting individual registers on the chip.  Before manipulating the individual on-chip registers, it's recommended that you read the Rx5C348 data sheet.
• -s - Set the system (Linux) time from the Ricoh RTC time.  The user must have root privileges.
• -t - Set tje RicohRTC time from the system (Linux) time.
• -a <oscadj> - Set the Ricoh's oscillator adjustment register, based on <oscadj>, expressed in parts per million.  See "Oscillator Adjustment" below.
• -k <0|1> - Disable (0) or enable (1) the 32 kHz output from the Ricoh RTC chip.
• -m <12|24> - Set 12 hour (AM/PM) mode or 24 hour of operation.  24 hour mode is recommended, as it is most compatible with how Linux keeps its time.
• -h - Print a help (usage) message and exit.

The Ricoh RTC chip has an oscillator adjustment register, which allows the user to trim out errors in crystal frequency up to an error of approximately +/- 192 ppm (parts per million), in steps of 3.05 ppm.  It is recommended that you perform the following calibration/adjustment steps on each Sidearm CPU.  However, please take into account that the frequency deviation is dependent on many environmental conditions, including:

• temperature
• operating voltage
• CPU operating mode (sleep vs. awake)

It seems particularly sensitive to the last (sleep vs awake), which makes it difficult to properly calibrate the oscillator.  It's best to calibrate when running the CPU in a manner as close as possible to its final deployment (e.g., SIAM app, number of instruments, sampling schedules, etc).  This is to run it as closely as possible to the intended duty cycle of sleep vs awake.

To adjust the oscillator, do the following:

• Set the Ricoh clock as accurately as possible.  A good way to do this is to set the system clock from NTP using 'ntpdate -b <NTP server>'; and then run 'ricohRTC -t'.
• Set the oscillator adjustment to 0 adjustment by running 'ricohRTC -a 0'.
• Run the system in its deployed mode for as long as possible - 24 hours at a minimum, but 3 to 7 days will give greater accuracy.  Make sure to disable any scripts that manipulate the Ricoh RTC.
• Find the error in the Ricoh time.  A good way to do this is to run:
• 'ricohRTC -s' to set the system time/date from the Ricoh RTC, and then run
• 'ntpdate -b <NTP server>'.  This sets the system time/date accurately, and prints out the offset of the the previous time from accurate time.  Make a note of this offset, but change the sign (NTP needs to step the time in the opposite direction from the time drift; e.g. if the clock was fast, it needs to step it in the negative direction).
• Divide the time error (with sign, positive if the clock is fast, negative if the clock is slow) by the total elapsed time (in seconds) over which you ran the test.  Multiply by 1000000 to get ppm.
• Use the calculated offset in ppm as a parameter to 'ricohRTC -a <offset>'

BUGS

The options to set the RTC time (-a, and menu options 4 & 5 of interactive mode) should really also set the clock to 24 hour mode.  Right now, you must manually set either 24 hour mode or AM/PM mode, and the time set functions do the right things based on that.

ENVIRONMENT

This utiltity does not depend on any environment variables.

In order to set the system time using this utility, the user must have root privileges.

SEE ALSO

The Ricoh Rx5C348 data sheet

Log onto any Linux workstation and do a "man hwclock" to see how to manipulate the SA1100 RTC.