Documentation request : specify alarm AxM bits position

[JLC333-Github]

Hi,

would it be possible to add an information about the positions of the alarm bits used in functions setA1Time and setA2Time please (I don't know how to do it by my self, sorry).

Having a look inside the setA1Time and setA2Time code and the DS3231.pdf, the use of AlarmBits parameter is not obvious.

Could you specify something like this, whatever the function setA1Time or setA2Time used, the AlarmBits parameter bits are placed this way (b7 to b0) : x A2M4 A2M3 A2M2 A1M4 A1M3 A1M2 A1M1

Those bits correspond to page12/20 of DS3231.pdf from www.maximintegrated.com file.

Thanks.

[IowaDave]

Hi, your question is an interesting one. Those alarm bits certainly do get stored somewhere, but where do they go?

I think I found the information you are requesting. I will focus on the bits for Alarm 1. The locations described below may help you to identify the same information for Alarm 2.

• The bits A1M4, A1M3, A1M2 and A1M1 are stored individually, one bit at a time, in four, different registers inside the DS3231 chip. You can see this by looking on page 11 of the datasheet available at the following URL: https://datasheets.maximintegrated.com/en/ds/DS3231.pdf. Do you see the table there? The bits are stored as BIT7 for the addresses 07h through 0Ah.
• The bits are stored on the DS3231 by the setA1Time() function. At the time I wrote this response, the relevant code lines in the DS3231.cpp file were:
  • A1M1: line 524
  • A1M2: line 526
  • A1M3: line 549 (not clearly labeled as such; try to study it until you can see the pattern)
  • A1M4: line 552

The code uses several of the bitwise operators in C/C++. I am going to respect you by assuming that you already understand the bitwise operators. The web offers many references and tutorials about writing code in C/C++. It always helps me to go back and review coding topics such as these.

Stay confident! It took me a while to settle this information comfortably in my head. The study was worth the effort! Now I am more familiar with the DS3231 datasheet and with the code in this library. I can more easily find answers to other questions in the same places. I hope sincerely that you may enjoy the same result.

[jnuernberg]

Hi @JLC333-Github,

My post on issue #42 may help: https://github.com/NorthernWidget/DS3231/issues/42#issuecomment-1190372074

Best regards,

Jacob

[IowaDave]

I understand this question better now. @JLC333-Github addresses the location of the different bits in the AlarmBits parameter of the set/getAxtime() functions. The locations are described accurately in the original post.

I am working on documentation for the alarm functions and will be sure to make this information very clear.

[IowaDave]

Hi @JLC333-Github , @jnuernberg I've opened PR #70 providing extensive documentation for the Alarm Bits and the alarm functions in detail. A couple of example programs are included to demonstrate using the AlarmBits parameter. Hope to merge this content into the master branch soon.

[IowaDave]

Closing this issue on 18Sep2022 because extensive documentation of the Alarm Bits has been provided in a recently added file. See Alarms Documentation.