Overview
The rtc_ds1307 node interfaces with the DS1307 real-time clock module over I2C.
The DS1307 is a widely used, low-cost RTC with battery backup that maintains time and date even when the main
system power is off. It includes 56 bytes of battery-backed SRAM for general-purpose storage and a programmable
square wave output.
Properties
| Property | Type | Default | Options | Description |
|---|---|---|---|---|
| i2cBus | select | "/dev/i2c-1" | /dev/i2c-0, /dev/i2c-1 | I2C bus device path |
| address | string | "0x68" | - | I2C device address |
| use24Hour | boolean | true | - | Use 24-hour time format instead of 12-hour |
| squareWaveFreq | select | "off" | off, 1Hz, 4.096kHz, 8.192kHz, 32.768kHz | Square wave output frequency on SQW pin |
Output Format
{
"year": 2026,
"month": 2,
"day": 12,
"hour": 14,
"minute": 30,
"second": 45,
"dayOfWeek": 4,
"running": true,
"timestamp": 1771080645
} Note: The running field indicates whether
the DS1307 oscillator is active. If false, the clock has
stopped and needs to be re-initialized (typically after a battery change).
Wiring / Connection Diagram
Raspberry Pi DS1307 Module
+-----------+ +-------------+
| | | |
| 5V (2) +------------+ VCC |
| | | |
| SDA (3) +------------+ SDA |
| | | |
| SCL (5) +------------+ SCL |
| | | |
| GND (6) +------------+ GND |
| | | |
| GPIO (7) +----opt-----+ SQW |
| | | |
+-----------+ +-------------+
| CR1220 |
| (backup) |
+----------+
IMPORTANT: DS1307 operates at 5V logic.
Use a level shifter if connecting to a
3.3V I2C bus on newer Raspberry Pi models.
Warning: The DS1307 requires 5V power. While many breakout boards include voltage regulation and level shifting, verify your module supports 3.3V I2C logic before direct connection.
Example Use Cases
Basic Time Display
Read current time from the DS1307 and format for display on a dashboard.
// Function node: format time as HH:MM:SS
var rtc = msg.payload;
var hours = String(rtc.hour).padStart(2, "0");
var mins = String(rtc.minute).padStart(2, "0");
var secs = String(rtc.second).padStart(2, "0");
msg.payload = hours + ":" + mins + ":" + secs;
return msg;Oscillator Health Check
Monitor the DS1307 running status and alert if the oscillator has stopped.
[
{
"id": "rtc-poll",
"type": "rtc_ds1307",
"i2cBus": "/dev/i2c-1",
"address": "0x68",
"use24Hour": true
},
{
"id": "running-check",
"type": "function",
"func": "if (!msg.payload.running) {\n msg.payload = 'DS1307 oscillator stopped - check battery';\n return msg;\n}\nreturn null;"
},
{
"id": "email-alert",
"type": "email",
"subject": "RTC Battery Warning"
}
]NTP Time Synchronization
Sync the DS1307 time with NTP server when network becomes available.
// Function node: prepare time set command from NTP
var now = new Date();
msg.payload = {
command: "set",
year: now.getFullYear(),
month: now.getMonth() + 1,
day: now.getDate(),
hour: now.getHours(),
minute: now.getMinutes(),
second: now.getSeconds(),
dayOfWeek: now.getDay()
};
return msg;Common Use Cases
Offline Timekeeping
Maintain wall-clock time without network or NTP access
Event Scheduling
Schedule irrigation, lighting, or feeding cycles by time of day
Square Wave Generator
Use SQW pin to generate reference clocks up to 32.768kHz
Timestamped Logging
Add real-time timestamps to sensor readings and event logs