Peripherals: Real Time Clocks
BASIC has built-in time algorithms. The way to access the clock are a special array @T() and a string @T$. The array can be used to access elements of the time individually.
- @T(0): seconds (0-59)
- @T(1): minutes (0-59)
- @T(2): hours (0-23) (24 hour clock mode only is supported)
- @T(3): day of week with range 0-6
- @T(4): date - day (1-31)
- @T(5): date - month (1-12)
- @T(6): date - year (0-99)
The special string @T$ contains the time in the format hour:minute:second-day/month/year.
Values of @T() with indices greater than zero are hardware specific. See below for more information.
There are three hardware mechanisms providing the data for the time array and the time string.
- Built-in hardware clocks on STM32, Arduino MKR, and ESP32
- RTC emulation
- I2C clocks
For ESP32, STM32 and Arduino MKR the built-in hardware clocks are activated by default. No settings need to be changes in hardware-arduino.h. For Arduino MKR and STM32 the respective libraries need to be installed to compile BASIC. Both clocks keep running as long as the board has power including in low power sleep modes. Some STM32 boards have battery buffered clocks. These boards continue to run even if the board is switched off as long as there is a battery.
For all other boards, a RTC emulation can be switched on in hardware-arduino.h. This code needs approximately 1.7kB of flash on an Arduino UNO and is switched off by default. It uses the data in millis() to create a UNIX style real time clock. The clock is reset after each board restart.
The third option is an I2C real time clock. This clock is also activated in hardware-arduino.h. If an I2C clock is integrated, all other clock mechanisms are disabled. It overrides the other clocks in BASIC.
The most common real time clock modules in the Arduino world are the DS1307, DS3231, and DS3232 modules. Countless libraries have been written for them. BASIC has a built-in support for the clock chips without using any of these libraries. Much of the functions the libraries offer are already included in BASIC. Therefore the libraries make little sense.
All three DS clock chips are I2C components. The default I2C address is 0x69. It can be configured sometimes to another value, typically 0x69. The modules have a battery. This battery keeps the clock running and also preserves the state of the NVRAM that some of the chips have.
The first 7 bytes of the clocks internal memory from address 0-6 are the same for all three chips. They contain the seconds, minutes, hours, the day of month, and the date in the order day, month, year in BCD encoded form. The following registers are different for the various clocks.
Almost all registers are read/write. They can simply be set and read from a single I2C command.
DS1307 clocks have 56 bytes of NVRAM that can be accessed as a register. DS3231 has no RAM. DS3232 has 236 bytes of RAM. The registers from 0x07 onwards are control registers with different function. They can all be accessed directly from BASIC.
@T(7) is the clock status register. It controls square wave output of the chip.
@T(8)-@T(63) are the NVRAM bytes.
@T(7)-T(13) are alarm settings. They are currently not supported by BASIC but can be programmed through the registers.
@T(14)-T(16) are the clock status registers.
@T(17) is the most significant byte of the temperature in degrees, @T(18) is the least significant byte. Only the top most bits are set as the clocks temperature sensor only has an accuracy of 0.25 degrees.
There is no NVRAM available on this clock.
This clock is like the DS3231 but registers @T(19)-@T(255) are NVRAM bytes just like on the DS1307.
Many clock modules have on board I2C EEPROMS. Many have them a 0x50, some on 0x57. Typical sizes are 4k. They are very useful as BASIC program storage. This is explained in the following chapter of this Wiki.