API Reference

ds1302

CircuitPython driver for the Maxim Integrated / Analog Devices DS1302 Real Time Clock.

  • Author(s): Avery Ramsey

Implementation Notes

Hardware:

  • Maxim Integrated / Analog Devices DS1302 Real Time Clock

Software and Dependencies:

class ds1302.DS1302(ce_pin: microcontroller.Pin, io_pin: microcontroller.Pin, ck_pin: microcontroller.Pin)

Interfaces with the DS1302 real-time clock

Create a DS1302 RTC.

Parameters:

Quickstart: Importing and using the device

Here is an example of using the DS1302 class.

First, import the required libraries:

import time
import board
import ds1302

Next, define your Chip Enable, I/O, and Clock pins:

ce_pin = board.GP13
io_pin = board.GP14
ck_pin = board.GP15

Instantiate the RTC:

rtc = ds1302.DS1302(ce_pin, io_pin, ck_pin)

Set the current date and time:

t = time.struct_time((2026, 7, 16, 12, 38, 0, 3, -1, -1))
rtc.datetime = t

Read the current date and time from the datetime property:

current_time = rtc.datetime
static bcdtodec(num: int) → int

Convert a Binary-Coded Decimal (BCD) value to decimal.

Parameters:

num (int) – A number encoded in Binary-Coded Decimal (BCD).

Returns:

The decimal representation of num.

Return type:

int

static clamp(num: int | float, a: int | float, b: int | float) → int | float

Clamp num between a and b.

Parameters:

  • num (int or float) – The number to clamp.

  • a (int or float) – One bound of the valid range.

  • b (int or float) – The other bound of the valid range.

Returns:

num constrained to the range defined by a and b.

Return type:

int or float

a and b may be provided in either order.

clear_ram() → None

Clear all user-accessible RAM by writing zeros to each byte.

property clock_enable: bool

Get or set whether the RTC clock is enabled as a bool.

When disabled, the oscillator is stopped and the DS1302 enters a low-power standby mode with a current draw of less than 100nA.

property datetime: struct_time

Get or set the current date and time as a time.struct_time.

Reading this property returns the current date and time.

The tm_yday field of an assigned time.struct_time is ignored. When reading datetime, tm_yday is calculated from the stored date.

Assign a time.struct_time to update the RTC date and time.

Raises:

TypeError – If the assigned value is not a time.struct_time.

static dectobcd(num: int) → int

Convert a decimal value to Binary-Coded Decimal (BCD).

Parameters:

num (int) – A decimal number.

Returns:

The Binary-Coded Decimal (BCD) representation of num.

Return type:

int

property is_12_hour: bool

Whether the RTC uses 12-hour or 24-hour mode internally as a bool.

This does not affect datetime, which always uses 24-hour time.

read_ram(offset: int, length: int = 1) → bytearray

Read a block of user-accessible RAM.

Parameters:

  • offset (int) – The starting RAM address (0-30) to read.

  • length (int) – The number of bytes to read (1-31).

Returns:

The data read from RAM.

Return type:

bytearray

Raises:

  • ValueError – If offset or length is out of range.

  • IndexError – If the read would extend beyond the end of RAM.

read_ram_single(offset: int) → int

Read a single byte of user-accessible RAM.

Parameters:

offset (int) – The RAM address (0-30) to read.

Returns:

The value stored at offset.

Return type:

int

Raises:

ValueError – If offset is out of range.

property trickle_diode: int

Get or set the trickle charger diode configuration.

Valid values are:

property trickle_enable: bool

Get or set whether the trickle charger is enabled as a bool.

The trickle charger is only active when both trickle_diode and trickle_resistor are configured.

property trickle_resistor: int

Get or set the trickle charger resistor configuration.

Valid values are:

write_ram(offset: int, data: ReadableBuffer) → None

Write a block of user-accessible RAM.

Parameters:

  • offset (int) – The starting RAM address (0-30) to write to.

  • data (ReadableBuffer) – The byte data to write to RAM.

Raises:

  • ValueError – If offset is out of range or any value in data is not between 0 and 255.

  • IndexError – If the write would extend beyond the end of RAM.

write_ram_single(offset: int, data: int) → None

Write a single byte of user-accessible RAM.

Parameters:

  • offset (int) – The RAM address (0-30) to write to.

  • data (int) – The byte value (0-255) to write to RAM.

Raises:

ValueError – If offset is out of range or data is not between 0 and 255.

ds1302.TRICKLE_DIODE_1 = 4

One diode drop in the trickle charger path.

ds1302.TRICKLE_DIODE_2 = 8

Two diode drops in the trickle charger path.

ds1302.TRICKLE_RESISTOR_2 = 1

2kΩ trickle charger resistor.

ds1302.TRICKLE_RESISTOR_4 = 2

4kΩ trickle charger resistor.

ds1302.TRICKLE_RESISTOR_8 = 3

8kΩ trickle charger resistor.