Is there a package or library for controlling the DS3231 on the Raspberry Pi

Ask QuestionAsked 17 days agoActive 5 days agoViewed 89 times21

I’ve just obtained a DS3231 real time clock (RTC), and added it to my RPi 3b. It seems to work as far as keeping time, but I wanted more.

I’d like to be able to set alarms to trigger the INT/SQW pin on the chip (while retaining the basic timekeeping function I currently have), but I’ve been unable to find any way to do that with the toolset in RPi. I’ve installed python-smbus and i2c-tools as part of the RTC configuration. Have I overlooked something? – how should I go about reading & writing the DS3231’s internal registers to set up the alarm function on my RPi 3b?packagesrtctimekeepingshared-librariesds3231ShareEditFollowCloseFlagedited Apr 8 at 8:07asked Apr 6 at 21:41anon

• I played with DS3231 some three years ago. I found the drivers around then had too limited, (and only minimal functions like many other drivers). So I DIYed my own python library. Fast forward 3 years, now I am playing with Pico and plan to port my old package such as MCP23017, ADS1115 etc to Pico. In case you and other newbie readers are interested to know me the hobbyist developer learned how to do the job, I am writing an answer below. Comments and counter suggestions welcome. Cheers. – tlfong01 Apr 7 at 1:43   
• I remember 3 years ago the DT3231 libraries then were written in C/C++, me python guy found it hard to append more functions. But if you can now find any python package and wish to add more functions, my little DIY functions and design notes might help you modify any existing python or C/C++ packages. – tlfong01 Apr 7 at 1:58   
• 2@tlfong01: I appreciate the effort you put into your answer, but it doesn’t actually address my question… with no offense intended, it strikes me as a stream of consciousness rather than an answer. My research suggests all of the code written to configure the ds3231 is written for the Arduino – which is baffling to me. However, I’ve found one resource that seems useful, and may help you in formulating a useful answer. – anon Apr 8 at 5:35 
• 1After reading through the resource I mentioned above, I think I understand more clearly what needs to be done in terms of setting the registers in the ds3231, but I remain at a loss in terms of how to do this from the RPi. – anon Apr 8 at 5:40
• Ha, I like your “literary criticism” on my “answer” which I always think is of a style of “stream of consciousness” or “interior monologue”. I must first point out the misunderstanding that my answer in its current form of not an answer at all. I think it is about one tenth of my final answer which I hope to include a complete “instructable” with Pico python program in Stack Overflow’s recommended style of MCVE (Minimal, Comprehensive, Verifiable, Example). / to continue, … – tlfong01 Apr 8 at 7:09   
• 1OK, so a work in progress – I’ll leave you to it. However, I’m trying to move forward on this myself. I don’t think now that I need an extraordinarily lengthy answer. It could be as simple as install pkg-X, write code in Python. import smbus, read register, write register, etc. Nothing I’ve tried so far is working. – anon Apr 8 at 7:18
• So I think you can for now, just sit back, and watch my “technical presentation” of a smart home project using a (1) MCU (Rpi Pico) with microPython, (2) Real time clock (DS3231) and (3) 8 bit/pin GPIO expanders (PCF8574). Internal monologue: My educational object is to introduce the newbies the idea of (a) System integration, (b) Thonny microPython functional programming style for developing scalable, complex systems, using ideas from software engineering languages such as LUA and Scala. / to continue, … – tlfong01 Apr 8 at 7:18   
• I’m not familiar with ‘micro Python’. I know it’s used on the Pico… BUT this is not for a Pico – it’s for a Raspberry Pi. – anon Apr 8 at 7:25
• Ha, your suggestion is good: You move forward for a quick solution, me a TL:DR answer. Actually my 50+ old posts in rpi.org.forum include the following fully debugged demo programs on (1) How to setup i2cdetect/ping the DS3231, (2) How to read and write DS3231 registers, (3) How to read DS3231 temperature, (4) How to program alarm with interrupts. I am not surprised to hear you saying that “nothing tried so far is working”. One reason is that you might have not understood or have a solid knowledge and troubleshooting skills in basic I2C hardware/software development. / to continue, … – tlfong01 Apr 8 at 7:29   
• Let us continue this discussion in chat. – tlfong01 Apr 8 at 7:30   
• The chat room seems not working, so I continued here. This is the very old DS3231 program for your reference. (1) DS3231 2017 not fully debugged program public link: penzu.com/p/f9c316cf. Happy programming!. Cheers. – tlfong01 Apr 19 at 4:26   

Add a commentStart a bounty

1 Answer

ActiveOldestVotes1This post is hidden. It was deleted 1 min ago by goldilocks♦.

Question

How to write a Rpi4B/Pico Thonny Python program to talk to the DS3231 RTC (Real Time Clock) to do things such as the following:

1. Detect interrupts,
2. Trigger on chip square wave signals.

Short Answer

1. I have searched my 3 year old posts (over 50) in rpi.org.forum to refresh my memory on how I messed around with DS3231, listening to its interrupts, and program/trigger the on chip 32kHz square signals etc.
2. My old posts are messily scattered in a couple of forums and intermingled with other I2C devices such as MCP23017 IOX and ADS1115 ADC. Porting to Pico is a good opportunity for me to tidy them up.
3. The OP would like to be able to set alarms to trigger the INT/SQW pin, so I am jumping start to this part. I would first paste the design parameters in Appendix A below, then show a python function on how to program this pin. This double function pin is a bit tricky to handle, you might need to choose SQW mode, program the square wave frequencies, then go back to enable INT, and when INT comes, you need to switch to SQW mode to trigger it. In short, it is a bit tedious and easy to go wrong, so I gave up and tried other workarounds, … 🙂
4. DS3231 has two alarms, Alarm 1 and Alarm 2, as summarized in Appendix B. I am going to show how to set Alarm 1 for day, hour, min, sec.
5. There are a couple of DS3231N moudles around in the market. For prototyping and evaluation, I would recommend to buy the most expensive, deluxe version, with a lot of pins to play with, address pins for multiple RTCs, and daisy chain I2C pins for easy extending signals. See Appendix C for more details

6. Now I have written a little python program to detect the addresses of the devices on the two I2C buses of Rpi Pico. DS3231 and 24C32 EEPROM occupy addresses 0x68 and 0x57.

/ to continue, …

Long Answer (TL;DR)

/ to continue, …

References

(1) Search query: DS3231 tlfong01 Record – found 54 matches

(2) Python Program to Ping DS3231 and MCP23017

(3) DS3231 Python Programming Code

(4) DS3231 python Write Register Example

(5) DS3231 Old Posts Reference Links

(6) DS3231 i2cdetect record

(7) DS3231 driver vs dit programming

(8) DS3231 read register functions

(9) DS3231 Set alarm etc

(10) DS3231 python programming design notes

(11) DS3231 python programming design notes

(12) DS3231 python programming design notes

(13) DS3232 Square Wave Setup

(14) DS3231SN Realtime Clock with AT24C32 EEPROM Module – AliExpress US$1.28

(15) Using a $1 DS3231 Real-time Clock Module with Arduino (and which components to remove) – Underwater Arduino Data Loggers

(16) MicroPython class I2C

(17) MicroPython Class RTC

(18) Build Programmable Time-based Switches Using a Real Time Clock (Arduino) – Raymond Genovese, All About Circuits, 2016apr07

/ to continue, …

Appendices

Appendix A – DS3231 INT/SQ pin programming design notes

Appendix B – DS3231 Alarm programming design notes

Appendix C – Real Time Clock Module

(14) DS3231SN Realtime Clock with AT24C32 EEPROM Module – AliExpress US$1.28

Appendix D – Schematic and Pullups to remove to reduce capacitance to < 400pF

Notes

1. I2C bus uasually has a capacitance limit of 400pF, exceeding which might cause I/O transmission errors.
2. R4B I2C pins already have strong pullups of 1k8, so it is a good idea to remove the DS3231 and other devices’ on board pullups of usually 4k7, sometimes 10k
3. It is also a good idea of keeping the I2C wiring short, less than 30cm if possible.
4. It is also a good idea, especially during prototyping or troubleshooting, to use low frequencies for I2C, say 100kHz or even down to 50kHz, so that resulting impedance is less than 400pF.

Appendix E – Summary of MicroPython I2C I2C and RTC class and methods used to control DS3231

MicroPython class I2C

1. Example usage:

from machine import I2C i2c = I2C(freq=400000)
i2c.scan()
i2c.writeto(42, b’123′) i2c.readfrom(42, 4)

2. Constructors

class machine.I2C(id, *, scl, sda, freq=400000)

3. General Methods

I2C.init(scl, sda, *, freq=400000) I2C.scan()

4. Standard bus operations

I2C.readfrom(addr, nbytes, stop=True, /) Read nbytes from the slave specified by addr. If stop is true then a STOP condition is generated at the end of the transfer. Returns a bytes object with the data read.

I2C.readfrom_into(addr, buf, stop=True, /) Read into buf from the slave specified by addr. The number of bytes read will be the length of buf. If stop is true then a STOP condition is generated at the end of the transfer. The method returns None.

I2C.writeto(addr, buf, stop=True, /) Write the bytes from buf to the slave specified by addr. If a NACK is received following the write of a byte from buf then the remaining bytes are not sent.

I2C.writevto(addr, vector, stop=True, /) Write the bytes contained in vector to the slave specified by addr. vector should be a tuple or list of objects with the buffer protocol. The addr is sent once and then the bytes from each object in vector are written out sequentially. The objects in vector may be zero bytes in length in which case they don’t contribute to the output.

MicroPython Class RTC

class machine.RTC(id=0, …) Create an RTC object. See init for parameters of initialization

RTC.init(datetime) Initialise the RTC. Datetime is a tuple of the form: (year, month, day[, hour[, minute[, second[, microsecond[, tzinfo]]]]])

RTC.now() Get get the current datetime tuple.

Appendix F – Old Rpi python program for DS3231

Update 2021apr19hkt1229

The program list uploaded here yesterday is too long and hit the SE’s 30k words limit. The listing was ported from Chinese Windows 10 and edited to fit RpiSE format but stil has wrong formatting, funny charaters here is there. So I put the completed lising as a PenZu lab log, with this link:

DS3231 Old 2012 Penziu Listing

Notes:

1. The program was written in pure functional programming style, with no global variables and no side effect. So it is easy to copy any DS3231 functions with their independent higher level variables, and paste as a module/package. In other words, never mind the pretty print, user menu, mux functions.

/ to continue, …

ShareEditUndeleteFlagedited Apr 19 at 4:37answered Apr 7 at 1:53tlfong013,68633 gold badges88 silver badges2222 bronze badges

• 1FWIW, this is the module I need to program. – anon Apr 8 at 7:21
• Ah, your DS3231 RTC module is a “mini” version. It is small and therefore good if you want to save space. For prototyping, my module is better for the following reasons: (1) with address jumpers A0, A1, A2 to set 8 device address, so to use more than a DS3231 on the same bus. (2) With an EEPROM to store data. (3) Generously spaced components to easily modify circuits. eg. remove pullup resistors, modify battery charging options. See Ref 15 for more details. – tlfong01 Apr 8 at 14:47   
• You recommended tutorial by All About Circuits is as good as mine. So I have included in to my reference list (Ref #18). Cheers. – tlfong01 Apr 9 at 13:44   
• 1You still have / to continue, ... remarks in several places, but since it’s been over a week since your last edit, I assume you’re finished. I don’t understand how you mis-interpreted my question. It’s not a long, detailed question – but you even summarized it incorrectly. With no disrespect intended, this answer is not helpful. I’d like to delete my question. I don’t want to impact your efforts, so perhaps you could post your own question, and then copy & paste your answer there? – anon Apr 17 at 19:50
• Ah I did hesitate to update with this info. seeedstudio.com/…. I now have 6 or more Pico in hand, and 10 more are on their way from RS. I also have perhaps 10 Pico breakout boards in hand, mostly by perorder,. as soon as the morning I read the Google alert. I do have 3 Pico and 6 breadout boards from Seeed. RTS is not urgent for me, so I might just order them after I see the reviews. I also have more than 10 breakout boards from Piromori. Perhaps they have already been making RTC boards for Pico. – tlfong01 Apr 18 at 1:23   
• There might be some misunderstand. I told you that your RTC breakout is a minimal version without terminals so not easy to extract the squarewave and 32k signal. So I thouht you either (1) gave up, because it was just a weekend fun project, (2) you have ordered the full version from Ebay, AliExpress, which I know might take 2 to 5 weeks to deliver. Recently I ordered MCP23S17 and the 4g LET box from AliExpress and it indeed take three weeks. / tonctinue, – tlfong01 Apr 18 at 1:30   
• I usually order from TaoBao, and direct from Factory Flagship shop, and because I have a VIP account in most of the shops I regularly shop, and they can see my old orders are usually 10 times than the average clients, and almost pay my bill within 4 hours, so they usually give me special treatment and ship my goods within average 24 hours. – tlfong01 Apr 18 at 1:31   
• I vaguely remember that I gave you a list of my old blog posts which include python programs on how to read DS3231 temperatue, ping a register, and include a program showing the dictionry struacure of the DS3231 registers (yes, borrowed from Arduino). I forgot if I told you that once you know how to read/write a DS3231 register, then the rest is easy. I know my python program in my blog is mingled with MCP23017 and mux with 8 DS3231 on the same I2C bus, so I thought you were able to handle it. Perhaps you are not experience in python.so if my program was in C, you could rewrte it in 1 hour. – tlfong01 Apr 18 at 1:37   
• Anyway, perhaps I would try to search my old file directories and see if I can find a 3 year fold newbie friendly demo program for your reference. I will let you know perhaps in a couple of days. – tlfong01 Apr 18 at 1:39   
• I am back. I have luck and quickly found from my messy old file box a year 2017 DS3231 program with the basic functions on read temperature, read DS3231 register, ping, set date, set alarms etc. They are all in functional programming style, ie no side effects, no global variable. So you can almost just copy an paste functions and their dependent functions upwards. PS – my old program is in last appendix. I did not upload the complete program listing, because I already hit the SE’s 30k word limit. – tlfong01 Apr 18 at 1:56    
• So I actually cut the EEPROM part of the program. The original file in in Chinese Window file format. If you have problems or reading funncy charaters, I can try to compile a PenZu lab log for you. – tlfong01 Apr 18 at 1:59   
• And because my program is actually a “package”, so I can import it to other programs. You see many of the mid level functions have parameters such as “demux number” and “device num”, because most of the low level stuff like device address, reg addr etc are also abstracted to numbers which can freely transfer among different levels of functions (but not “objects” which cannot flow up/down levels. If you have been doing functional programming in LISP, Scheme, ML, Haskell, LUA, Scala, Python, … you might find my programs very “expressive” and “self documenting”, with little/no comments. 🙂 – tlfong01 Apr 18 at 2:19   
• This is not an answer to the question. – goldilocks♦ 1 min ago

Comments disabled on deleted / locked posts / reviews