experimental.clocks.ds3231

Interface class for the DS3231 Realtime Clock

This class is designed to work with a DS3231 chip mounted on an I2C carrier board that can be connected to EuroPi’s external I2C interface. The user is required to 1) provide their own RTC module 2) create/source an appropriate adapter to connect the GND, VCC, SDA, and SCL pins on EuroPi to the RTC module 3) Mount the RTC module securely in such a way that it won’t come loose nor accidentally short out any other components.

Compatible RTC modules can be purchased relatively cheaply online. e.g.: - https://www.amazon.ca/DS3231-Precision-AT24C32-Arduino-Raspberry/dp/B07V68443F (not an afficliate link)

Based on code by Willem Peterse released under the MIT license (c) 2020: https://github.com/pangopi/micropython-DS3231-AT24C32/blob/main/ds3231.py

in-turn based on work by Mike Causer for the DS1307: https://github.com/mcauser/micropython-tinyrtc-i2c/blob/master/ds1307.py

If you have a brand-new DS3231, or have recently replaced your module’s battery, you may need to manually update the clock. To do so:

  1. Connect the clock module to your EuroPi

  2. Connect your EuroPi to a computer via the USB port

  3. Open Thonny and make sure experimental_config is configured to use the DS3231. If you make any changes to experimental_config, restart the Raspberry Pi Pico before proceeding.

  4. In Thonny’s Python terminal, run the following code:

>>> from experimental.rtc import clock
>>> clock.source.set_datetime((2025, 6, 14, 22, 59, 0, 6, 0))

This will set the clock to 14 June 2025, 22:59:00, and set the weekday to Saturday (6). The tuple is of the form (Year, Month, Day, Hour, Minute, Second, Weekday, Yearday). It is recommended to set the seconds & weekday, but it is optional.

Note that the clock _should_ be set to UTC, not local time. If you choose to use local time instead some scripts that assume the clock is set to UTC may behave incorrectly.

class experimental.clocks.ds3231.DS3231(i2c, addr=104)

DS3231 RTC driver.

Hard coded to work with year 2000-2099.

OSF()

Returns the oscillator stop flag (OSF).

1 indicates that the oscillator is stopped or was stopped for some period in the past and may be used to judge the validity of the time data. returns : bool

alarm1(time=None, match=0, int_en=True, weekday=False)

Set alarm1, can match mday, wday, hour, minute, second

Parameters

  • time – tuple, (second,[ minute[, hour[, day]]])

  • weekday – bool, select mday (False) or wday (True)

  • match – int, match const

  • int_en – bool, enable interrupt on alarm match on SQW/INT pin (disables SQW output)

alarm2(time=None, match=0, int_en=True, weekday=False)

Get/set alarm 2 (can match minute, hour, day)

Parameters

  • time – tuple, (minute[, hour[, day]])

  • weekday – bool, select mday (False) or wday (True)

  • match – int, match const

  • int_en – bool, enable interrupt on alarm match on SQW/INT pin (disables SQW output)

Returns

bytearray(3), the alarm settings register

alarm_int(enable=True, alarm=0)

Enable/disable interrupt for alarm1, alarm2 or both.

Enabling the interrupts disables the SQW output

Parameters

  • enable – bool, enable/disable interrupts

  • alarm – int, alarm nr (0 to set both interrupts)

Returns

the control register

check_alarm(alarm)

Check if the alarm flag is set and clear the alarm flag

check_valid_datetime(datetime)

Check if a datetime contains valid values.

Raises

ValueError – if any field is out of range

Parameters

datetime – The datetime tuple to validate

datetime()

Get the current time.

Returns in 24h format, converts to 24h if clock is set to 12h format

Returns

a tuple of the form (0-year, 1-month, 2-day, 3-hour, 4-minutes, 5-seconds, 6-weekday, 7-yearday)

is_leap_year(datetime)

Determine if the datetime’s year is a leap year or not.

Returns

True if the datetime is a leap year, otherwise False

month_length(datetime)

Get the numer of days in the month.

This takes leap-years into consideration

Returns

The number of days in the datetime’s month

output_32kHz(enable=True)

Enable or disable the 32.768 kHz square wave output

set_datetime(datetime)

Set the current time.

Parameters

datetime – tuple of the form (0-year, 1-month, 2-day, 3-hour, 4-minutes, 5-seconds, 6-weekday, 7-yearday)

square_wave(freq=None)

Outputs Square Wave Signal

The alarm interrupts are disabled when enabling a square wave output. Disabling SWQ out does not enable the alarm interrupts. Set them manually with the alarm_int() method.

Parameters

freq – specify the frequency: * None: returns current setting * False = disable SQW output, * 1 = 1 Hz, * 2 = 1.024 kHz, * 3 = 4.096 kHz, * 4 = 8.192 kHz

year_length(datetime)

Determine the number of days in the datetime’s year.

Returns

The number of days in the year, taking leap years into account

experimental.clocks.ds3231.bcdtodec(bcd)

Convert binary coded decimal to decimal

experimental.clocks.ds3231.dectobcd(decimal)

Convert decimal to binary coded decimal (BCD) format