Overview
The rtc_ds3231 node interfaces with the DS3231 precision real-time clock module
over I2C. The DS3231 features a temperature-compensated crystal oscillator (TCXO) that maintains accuracy of
approximately 2 ppm across -40 to +85 degrees Celsius, making it one of the most accurate RTC modules available for
embedded applications.
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, 1.024kHz, 4.096kHz, 8.192kHz | Square wave output frequency on SQW pin |
Output Format
{
"year": 2026,
"month": 2,
"day": 12,
"hour": 14,
"minute": 30,
"second": 45,
"dayOfWeek": 4,
"temperature": 23.25,
"alarm1": false,
"alarm2": false,
"timestamp": 1771080645
}Note: The DS3231 includes an on-chip temperature sensor with 0.25 degree Celsius resolution, used internally for TCXO compensation. This value is also available in the output.
Wiring / Connection Diagram
Raspberry Pi DS3231 Module
+-----------+ +-------------+
| | | |
| 3.3V (1) +------------+ VCC |
| | | |
| SDA (3) +------------+ SDA |
| | | |
| SCL (5) +------------+ SCL |
| | | |
| GND (6) +------------+ GND |
| | | |
| GPIO (7) +----opt-----+ SQW/INT |
| | | |
+-----------+ +-------------+
| CR2032 |
| (backup) |
+----------+
Note: SQW/INT pin is optional - used for
alarms and square wave output.
Example Use Cases
Scheduled Data Logger
Read the RTC and timestamp sensor data for logging to a file.
// Function node: format timestamp for CSV logging
var rtc = msg.payload;
var timestamp = rtc.year + "-"
+ String(rtc.month).padStart(2, "0") + "-"
+ String(rtc.day).padStart(2, "0") + " "
+ String(rtc.hour).padStart(2, "0") + ":"
+ String(rtc.minute).padStart(2, "0") + ":"
+ String(rtc.second).padStart(2, "0");
msg.payload = timestamp + "," + rtc.temperature + "\n";
return msg;Alarm-Based Wake Trigger
Use DS3231 alarm flags to trigger actions at specific times.
[
{
"id": "rtc-read",
"type": "rtc_ds3231",
"i2cBus": "/dev/i2c-1",
"address": "0x68",
"use24Hour": true
},
{
"id": "alarm-check",
"type": "function",
"func": "if (msg.payload.alarm1) {\n msg.payload = { alert: 'Alarm 1 triggered', time: msg.payload.timestamp };\n return msg;\n}\nreturn null;"
},
{
"id": "notify",
"type": "debug",
"name": "Alarm Alert"
}
]On-Chip Temperature Monitor
Use the built-in temperature sensor to monitor ambient conditions near the RTC.
// Function node: extract temperature and check threshold
var temp = msg.payload.temperature;
msg.payload = {
temperature: temp,
unit: "C",
overheating: temp > 50
};
return msg;Common Use Cases
Data Logging
Accurate timestamps for sensor data without network dependency
Scheduled Automation
Trigger events at precise times using hardware alarms
Wake-on-Alarm
Use SQW/INT pin to wake a sleeping microcontroller
NTP Fallback
Maintain accurate time when network connectivity is unavailable