drivers/max31343: add driver for MAX31343 I2C RTC by Jakob-Mueller-97 · Pull Request #22115 · RIOT-OS/RIOT

Jakob-Mueller-97 · 2026-03-02T20:43:25Z

Contribution description

This PR adds a new device driver for the MAX31343 I2C real-time clock with
integrated MEMS oscillator.

The driver implements the periph_rtc interface, allowing it to serve as a
drop-in external RTC on any board that has an I2C bus. If another (internal) rtc already
provides the feature periph_rtc, the periph_rtc functions are omitted, but the device-specific API
can still be used directly, e.g. "max31343_get_time".

Supported features:

Time get/set via periph_rtc interface (rtc_get_time, rtc_set_time)
Alarm 1: set, get, enable/disable, clear
Oscillator power on/off
Square-wave output (1, 2, 4, 8, 16, 32 Hz)
Temperature sensor readout (centi-°C, i.e. 2350 = 23.50 °C)
Trickle charger configuration
Automatic temperature conversion mode and interval

The Oscillator Stop Flag (OSF) is checked during max31343_init(). If the
oscillator was stopped (e.g. after power loss), -ENODATA is returned to
signal that the stored time is invalid and must be set before use.

Note: interrupt-driven alarm callbacks via rtc_set_alarm() are not
supported. The INT pin must be handled externally via GPIO by the
application. cb and arg are accepted but intentionally ignored.

Datasheet:
MAX31343

Testing procedure

Tested on a nucleo-g070rb with the MAX31343 evaluation shield connected
via I2C.

Run the included driver test application:

make -C tests/driver_max31343 BOARD=nucleo-g070rb flash term

After flashing, run the built-in self-test from the shell:

> test
[test] setting reference time...
[test] reading back time...
[test] time readback OK
[test] waiting for clock to tick...
[test] time progression OK
[test] testing alarm set/get...
[test] alarm set/get OK
[test] testing alarm clear...
[test] alarm clear OK
[test] testing temperature read...
[test] temperature: 23.50°C  OK
[test] all tests PASSED

Issues/PRs references

None.

riot-ci · 2026-03-03T12:51:48Z

Murdock results

✔️ PASSED

b500ea9 makefiles,sys/walltime: add support for MAX31343 RTC

Success	Failures	Total	Runtime
11180	0	11180	12m:06s

Artifacts

Documentation preview

AnnsAnns · 2026-03-04T10:16:45Z

Thank you for your contribution to RIOT, your commit appears to not be connected to your github account, try either adding your git config email into your github emails at https://github.com/settings/emails or changing it to one you have in there 😄

Other than that the PR already looks promising with very detailed comments for the driver. I have a feeling a certain @crasbe looked over this 🤨

AnnsAnns

Just some minor nitpicks, I haven't tried this since I don't have the hardware for this, in general this looks really good already though

AnnsAnns · 2026-03-04T12:42:38Z

Btw, while fine here since you had to to change the email, generally don't force push while your PR is getting reviewed, Githubs review flow starts really panicking sometimes and if somebody is actively reviewing this PR while it happens all review comments will be lost (I also did that once by accident 😔)

AnnsAnns · 2026-03-04T14:49:10Z

Please look at the new static tests output, there are a lot of undefined things that need to have comments (even if I get why you didn't comment them since most of them feel obvious) and a few other formatting issues

Jakob-Mueller-97 · 2026-03-05T03:00:51Z

Thanks for the help. I tried my best to fix all of it.
I am not quite sure on how to fix the issue with the Makefiles. I am open to suggestions and happy to explain my thought process, if there are any questions.

AnnsAnns · 2026-03-09T15:27:49Z

I'd recommend looking at the static test output, I'd argue that most of them are fairly clear, e.g.:

A Makefile.dep is for dependency modelling only. Modify CFLAGS in a Makefile.include, in an app's Makefile, or (if only relevant to a single module/package) in the module's/package's Makefile:
  		drivers/max31343/Makefile.dep:7:      CFLAGS += -DUSE_INTERNAL_RTC

But feel free to explain your specific issue, maybe we can help.

Jakob-Mueller-97 · 2026-03-09T17:01:06Z

I'd recommend looking at the static test output, I'd argue that most of them are fairly clear, e.g.:
A Makefile.dep is for dependency modelling only. Modify CFLAGS in a Makefile.include, in an app's Makefile, or (if only relevant to a single module/package) in the module's/package's Makefile:
  		drivers/max31343/Makefile.dep:7:      CFLAGS += -DUSE_INTERNAL_RTC
But feel free to explain your specific issue, maybe we can help.

Thank you for the hint! I've moved the CFLAGS to Makefile.include and FEATURES_PROVIDED to Makefile.features as suggested by the static test.
However, I'm running into a problem with providing periph_rtc from this driver:
the goal is that applications can use the standard rtc_get_time() / rtc_set_time() API without knowing the underlying hardware. But from what I can tell, driver Makefile.features are not included during feature resolution — only board Makefile.features are. This means FEATURES_REQUIRED += periph_rtc in an app fails even though the driver provides it.

benpicco

I have some comments on the API.

I'm not sure how I feel about implementing the RTC API directly in the driver.
Ideally going forward applications should just use the walltime API instead of accessing the RTC directly. That way we can have time change notifications and easily implement different backends, see e.g. a282d31

Jakob-Mueller-97 · 2026-03-17T22:54:49Z

I have some comments on the API.

I'm not sure how I feel about implementing the RTC API directly in the driver. Ideally going forward applications should just use the walltime API instead of accessing the RTC directly. That way we can have time change notifications and easily implement different backends, see e.g. a282d31

Thank you for your input.
Implementing the RTC API seems like more trouble that it is worth right now. It seems to just cause a bunch of Makefile problems.
I will take a look at the walltime API.

crasbe

Overall I'm very happy with the code, it looks very clean and structured. Below are some minor comments, mostly about styling related aspects.

I'll have to do a second round of review because I'm too tired now 😅

Jakob-Mueller-97 · 2026-03-20T17:02:45Z

That rebase went very wrong.

I am very sorry about that. I made a mistake somewhere and hope it is fixed now.

benpicco · 2026-03-20T18:37:51Z

+ */
+typedef struct {
+    i2c_t i2c;                              /**< I2C bus the device is connected to */
+    max31343_sqw_freq_t sqw_freq;           /**< SQW output frequency */


Why do we need to do this on init?
(and what is SQW?)

SQW is the squarewave output of the RTC, but arguably that can be set with the appropriate setter function.
Also the other parameters don't need to be in the parameters.

Fixed in d899775ac9

benpicco · 2026-03-20T18:39:54Z

+ *
+ * Writes the alarm time to the device. The alarm interrupt (A1IE) is
+ * disabled before writing and must be explicitly re-enabled afterwards
+ * using max31343_alarm_enable(), as required by the datasheet.


Why not enable the alarm when calling max31343_set_alarm() to mirror the RTC API?

I guess that's because of the 1 second delay that's required. Not sure if I want to add ztimer as a dependency to wait for 1s in the setter function?

benpicco · 2026-03-20T18:40:30Z

+ * @retval  0       Success
+ * @retval -EIO     I2C communication error
+ */
+int max31343_clear_alarm(const max31343_t *dev);


What's the difference between this and max31343_alarm_enable(dev, false)?

Seems redundant, I changed the name of max31343_alarm_enable to max31343_set_alarm_int and added the clearing of the Alarm Flag when enable == false.

f0704165d1

benpicco · 2026-03-20T18:41:48Z

+    i2c_t i2c;                              /**< I2C bus the device is connected to */
+    max31343_sqw_freq_t sqw_freq;           /**< SQW output frequency */
+    bool trickle_enable;                    /**< enable trickle charger on init */
+    max31343_trickle_diode_t trickle_diode; /**< trickle charger diode path */


Suggested change

max31343_trickle_diode_t trickle_diode; /**< trickle charger diode path */

bool trickle_diode; /**< trickle charger diode path */

The Schottky diode is always enabled, so this only controls the trickle diode, right?

Fixed in 5d73975b9a

benpicco · 2026-03-20T18:48:56Z

+    return _write_regs(dev, reg, &val, 1);
+}
+
+static int _validate_tm(const struct tm *t)


Why not use rtc_tm_valid()

Fixed in 7ff86c5d98

benpicco · 2026-03-20T18:53:34Z

+{
+    memset(t, 0, sizeof(*t));
+
+    int sec  = bcd_to_byte(raw[0] & 0x7FU);


Does the RTC set those bits outside the value range?

Suggested change

int sec = bcd_to_byte(raw[0] & 0x7FU);

int sec = bcd_to_byte(raw[0]);

It does, but I rather wonder why the _decode_time_regs and _encode_time_regs functions are only used once.

Incorporated in dd25c0cf16

benpicco · 2026-03-20T18:54:18Z

+    if (en) {
+        ie |= MAX31343_INTEN_A1IE;
+    } else {
+        ie &= (uint8_t)~MAX31343_INTEN_A1IE;


Suggested change

ie &= (uint8_t)~MAX31343_INTEN_A1IE;

ie &= ~MAX31343_INTEN_A1IE;

Fixed in 6d1a9bc90d

AnnsAnns · 2026-03-23T10:39:14Z

That rebase went very wrong.

I am very sorry about that. I made a mistake somewhere and hope it is fixed now.

Don't worry too much about it, it happens to everyone at least once 😉

crasbe · 2026-05-28T10:00:20Z

@Jakob-Mueller-97 Can you address the last review comments, so we can get this merged soon?

crasbe · 2026-07-27T16:01:34Z

Since Jakob Müller decided to not continue working on this despite having promised it after we gave him the final grade of his thesis, I'm taking over the PR now.

Disappointing to say the least.

crasbe · 2026-07-27T17:21:22Z

The walltime test fails because the MAX31343 RTC takes one second to update it's registers:

> time_set 2026-01-30T00:03:12
2026-07-27 19:17:12,775 # time_set 2026-01-30T00:03:12
2026-07-27 19:17:12,780 # time set to 2026-01-30T00:03:12
> time_get
2026-07-27 19:17:13,397 # time_get
2026-07-27 19:17:13,401 # current time: 2028-01-03T00:03:23
> time_get
2026-07-27 19:17:15,165 # time_get
2026-07-27 19:17:15,169 # current time: 2026-01-30T00:03:14
>

The self test does work though:

2026-07-27 19:20:56,748 # main(): This is RIOT! (Version: 2026.10-devel-149-g7b941-MAX31343-Driver)
2026-07-27 19:20:56,750 # MAX31343 RTC driver test
2026-07-27 19:20:56,750 #
2026-07-27 19:20:56,752 # MAX31343 initialized OK
> test
2026-07-27 19:20:58,740 # test
2026-07-27 19:20:58,742 # [test] setting reference time...
2026-07-27 19:21:00,746 # [test] reading back time...
2026-07-27 19:21:00,748 # [test] time readback OK
2026-07-27 19:21:00,752 # [test] waiting for clock to tick...
2026-07-27 19:21:02,755 # [test] time progression OK
2026-07-27 19:21:02,757 # [test] testing alarm set/get...
2026-07-27 19:21:02,762 # [test] alarm set/get OK
2026-07-27 19:21:02,765 # [test] testing alarm clear...
2026-07-27 19:21:02,768 # [test] alarm clear OK
2026-07-27 19:21:02,770 # [test] testing temperature read...
2026-07-27 19:21:02,773 # [test] temperature: 26.50°C  OK
2026-07-27 19:21:02,775 # [test] all tests PASSED

Teufelchen1 · 2026-07-29T09:08:28Z

I think you could squash before the next/last review comes in.

Co-authored-by: crasbe <crasbe@gmail.com>

crasbe · 2026-07-29T09:42:13Z

I think you could squash before the next/last review comes in.

Done 👍

Teufelchen1

Soft ack, I read through it but didn't invest toooo much time ;) but given that crasbe cleaned it up and it's new code, the risk is minimal.

Jakob-Mueller-97 requested review from MichelRottleuthner, aabadie and leandrolanzieri as code owners March 2, 2026 20:43

github-actions Bot added Area: tests Area: tests and testing framework Area: build system Area: Build system Area: drivers Area: Device drivers labels Mar 2, 2026

crasbe added Type: new feature The issue requests / The PR implemements a new feature for RIOT CI: ready for build If set, CI server will compile all applications for all available boards for the labeled PR labels Mar 3, 2026

Jakob-Mueller-97 force-pushed the MAX31343-Driver branch from c75042f to 97acc2d Compare March 4, 2026 00:48

AnnsAnns reviewed Mar 4, 2026

View reviewed changes

Jakob-Mueller-97 force-pushed the MAX31343-Driver branch from 97acc2d to 16610a7 Compare March 4, 2026 12:22

Teufelchen1 reviewed Mar 4, 2026

View reviewed changes

Comment thread tests/drivers/max31343/Makefile Outdated

AnnsAnns added the State: waiting for author State: Action by the author of the PR is required label Mar 9, 2026

benpicco reviewed Mar 10, 2026

View reviewed changes

Comment thread drivers/include/max31343.h Outdated

Comment thread drivers/include/max31343.h Outdated

Comment thread drivers/include/max31343.h Outdated

Comment thread drivers/include/max31343.h Outdated

Comment thread drivers/include/max31343.h Outdated

crasbe reviewed Mar 17, 2026

View reviewed changes

crasbe removed the State: waiting for author State: Action by the author of the PR is required label Mar 17, 2026

github-actions Bot added the Area: sys Area: System label Mar 20, 2026

Jakob-Mueller-97 requested review from MrKevinWeiss, bergzand, jia200x, kaspar030 and miri64 as code owners March 20, 2026 14:18

benpicco reviewed Mar 20, 2026

View reviewed changes

crasbe added the State: waiting for author State: Action by the author of the PR is required label May 28, 2026

crasbe self-assigned this May 28, 2026

crasbe added AI: Co-Authored PR/Issue relies on AI. Documentation / Code was partly generated by AI. and removed State: waiting for author State: Action by the author of the PR is required labels Jul 27, 2026

crasbe force-pushed the MAX31343-Driver branch from a2c5556 to 02f28d3 Compare July 27, 2026 16:36

github-actions Bot added the Area: doc Area: Documentation label Jul 27, 2026

crasbe force-pushed the MAX31343-Driver branch 3 times, most recently from 4c46439 to 7a4ac9a Compare July 29, 2026 09:38

Jakob-Mueller-97 and others added 3 commits July 29, 2026 11:40

drivers/max31343: add driver for MAX31343 RTC

25f89b9

Co-authored-by: crasbe <crasbe@gmail.com>

tests/drivers: add test for MAX31343 driver

e705208

Co-authored-by: crasbe <crasbe@gmail.com>

makefiles,sys/walltime: add support for MAX31343 RTC

b500ea9

Co-authored-by: crasbe <crasbe@gmail.com>

crasbe force-pushed the MAX31343-Driver branch from 7a4ac9a to b500ea9 Compare July 29, 2026 09:41

Teufelchen1 approved these changes Jul 29, 2026

View reviewed changes

crasbe added this pull request to the merge queue Jul 29, 2026

	max31343_trickle_diode_t trickle_diode; /*< trickle charger diode path /
	bool trickle_diode; /*< trickle charger diode path /

	int sec = bcd_to_byte(raw[0] & 0x7FU);
	int sec = bcd_to_byte(raw[0]);

	ie &= (uint8_t)~MAX31343_INTEN_A1IE;
	ie &= ~MAX31343_INTEN_A1IE;

Uh oh!

Conversation

Jakob-Mueller-97 commented Mar 2, 2026

Contribution description

Testing procedure

Issues/PRs references

Uh oh!

riot-ci commented Mar 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Murdock results

Artifacts

Uh oh!

AnnsAnns commented Mar 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

AnnsAnns left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

AnnsAnns commented Mar 4, 2026

Uh oh!

Uh oh!

AnnsAnns commented Mar 4, 2026

Uh oh!

Jakob-Mueller-97 commented Mar 5, 2026

Uh oh!

AnnsAnns commented Mar 9, 2026

Uh oh!

Jakob-Mueller-97 commented Mar 9, 2026

Uh oh!

benpicco left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Jakob-Mueller-97 commented Mar 17, 2026

Uh oh!

crasbe left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Jakob-Mueller-97 commented Mar 20, 2026

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

riot-ci commented Mar 3, 2026 •

edited

Loading

AnnsAnns commented Mar 4, 2026 •

edited

Loading