{"id":27117024,"url":"https://github.com/pkarsy/toit-ds3231","last_synced_at":"2026-01-19T09:01:32.370Z","repository":{"id":285083938,"uuid":"949648511","full_name":"pkarsy/toit-ds3231","owner":"pkarsy","description":"toit driver for the DS3231 real time clock","archived":false,"fork":false,"pushed_at":"2025-04-01T14:48:03.000Z","size":38,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-07T05:53:33.819Z","etag":null,"topics":["ds3231","rtc","rtc-ds3231","rtc-module","toit","toit-lang","toit-language"],"latest_commit_sha":null,"homepage":"","language":"Toit","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pkarsy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-03-16T22:43:00.000Z","updated_at":"2025-04-01T14:48:06.000Z","dependencies_parsed_at":"2025-03-29T12:32:37.199Z","dependency_job_id":null,"html_url":"https://github.com/pkarsy/toit-ds3231","commit_stats":null,"previous_names":["pkarsy/ds3231-toit","pkarsy/toit-ds3231"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/pkarsy/toit-ds3231","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pkarsy%2Ftoit-ds3231","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pkarsy%2Ftoit-ds3231/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pkarsy%2Ftoit-ds3231/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pkarsy%2Ftoit-ds3231/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pkarsy","download_url":"https://codeload.github.com/pkarsy/toit-ds3231/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pkarsy%2Ftoit-ds3231/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28565001,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-19T08:53:44.001Z","status":"ssl_error","status_checked_at":"2026-01-19T08:52:40.245Z","response_time":67,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ds3231","rtc","rtc-ds3231","rtc-module","toit","toit-lang","toit-language"],"created_at":"2025-04-07T05:53:41.997Z","updated_at":"2026-01-19T09:01:32.364Z","avatar_url":"https://github.com/pkarsy.png","language":"Toit","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Ds3231\n[Toit](https://toitlang.org/) driver for the DS3231 real time clock.\n\n## Warning\nWorking with time, especially if there are constraints on the accuracy, is a\nhard job. At the moment the library has limited testing and bugs are expected.\nAny help on inmpoving the driver is welcome.\n\n## Installing + documentation\nSee [ds3231 at Toid package registry](https://pkg.toit.io/search?query=ds3231)\n\n## Connection\nYou need 4 pins:\n\n\u003e SCL SDA VCC GND\n\nThe popular blue DS3231 boards (check the documentation for your board) do not\nhave level conversion circuitry. So the VCC pin should be connected to 3.3V.\nThe breakout consumes minimal current, and you can use GPIO pins for the VCC and\nGND. See the examples.\n\n## RTC Coin Cell\nNote: This section applies to the popular blue DS3231 breakout board, with the\nprimitive diode charging circuit.\n\nUse a good CR2032 coin cell. Some internet sources mention LIR2032 (rechargable)\nbut with 3.3V (see the above paragraph) the rechargable cell cannot be charged\nat all, making the module unusable. The CR2032 is safe with 3.3V for the same\nreason the LIR2032 canot be charged (No reverse current, as the diode has a voltage\n drop ~0.7 Volt). You can remove the diode as many sources mention, but it is\n not necessary if you power the module with 3.3V only.\n\n## Accuracy\nYou can expect to get and set the time with a less than 1-2ms error.\nHowever, the DS3231 RTC clock can have up to 2ppm drift (0 - 40C).\n\n```\n1 day : 0.17 sec\n1 week : 1.2 sec\n1 month : 5 sec\n1 year : 1 min\n```\n\nThe above values are more or less the worst cases, unless you expose the module\nto extreme temperatures. (See the Aging Correction below)\n\nIf the project can have internet access (even occasionally, for example a mobile\nphone as access point) the time could be fixed using NTP. See the\n\"ntp-plus-rtc.toit\" example.\n\nThe crystal of the ESP32 board inevitably has much worse performance than\nthe TCXO crystal of the Ds3231, and it makes sense (when not using NTP) to\nupdate the system (ESP32) time every hour using the DS3231 time. See\nthe example \"nowifi.toit\" for this.\n\nAll the above are only useful, if you know the wanted accuracy. Some hints:\n\n- For a project having NTP(internet) time, but need the RTC as a backup,\n  the DS3231 is already extremely accurate.\n\n- For projects expecting to be mostly without wifi, the aging correction can be\n  useful, but a 1 minute error per year can still be insignificant \n  (irrigation timer comes to mind). See below on how to calculate the aging offset\n  \n- For projects really isolated (from the internet) and still requiring high time\n  precision, a GNSS module can be a solution (you have to solve other problems of\n  course). For Toit there are GNSS drivers, but I have not tested them.\n  I have created such a\n  [GNSS time driver for tasmota](https://github.com/pkarsy/TasmotaBerryTime/tree/main/ds3231)\n  if you are interested.\n\n## Developer Hints\n- library documentation at [ds3231 @ toit package registry](https://pkg.toit.io/search?query=ds3231)\n- Inspect the examples to see how they work in practice.\n- Almost all library calls can raise exceptions, for example when the cabling is bad.\n\n## Constructor\nYou can create the driver instance in 2 ways.\n- Create the i2c bus object first, and then pass it to the constructor.\n- If the DS3231 is the only i2c device in the bus (most common case) you\n  can simply pass the pin numbers to the constructor.\n\n## Setting and getting the time\nThis library, just like the ntp library, uses time-adjustment instead of absolute\ntime. This is a clever way to set the time correctly, even if there is a time gap\nbetween time-get (for instance from NTP) and time-set (to the DS3231)\n\n## SQW pin\nThe library does not use/need this pin by itself, but you may find it usefull\nfor other purposes, as interrupt source etc. The following functions can\ncontrol the SQW output.\n\n```\nenable-sqw-output\ndisable-sqw\nenable-battery-backed-sqw\ndisable-battery-backed-sqw\n```\n\nDS3232 will retain the register settings as long as the module is active or\nis battery backed.\n\n## Temperature\n\u003e get-temperature\n\nreturns the temperature in °C as a float. Internally is updated every about 1 min (SN model). However you can force a temperature conversion with\n\u003e force-temp-conversion\n\n## Clock drift\n\u003e expected-drift\n\nshows the expected time drift (assuming 2ppm error) since the given time. The real drift is usually smaller. You can set the ppm error.\n\n## ALARM 1/2\nNot implemented at the moment.\n\n## Aging correction\n\n\u003e set-aging-offset\n\nCan get a value from -128 up to 127 to make the clock more accurate (significantly less than 2ppm).\n- inside tools there is the **offset-calculator.toit** program. The hardware setup is minimal a\n  ESP32x and a Ds3231 module. It is very slow, but you can use\n  multiple modules in parallel.\n- [this project](https://github.com/gbhug5a/DS3231-Aging-GPS), is much faster but also\n  needs more work (and hardware) to implement.\n\n## VCC GND and battey powered projects\nOn battery, the 4mA the DS3231 is using, is a huge consumption. For this\npurpose the VCC and GND can be GPIO pins, and the DS3231 module is powered OFF when\nin deep-sleep. Assuming a good CR2032 coin cell, the time keeping function will\nstill work (for 10 years !) and the registers will retain their values.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpkarsy%2Ftoit-ds3231","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpkarsy%2Ftoit-ds3231","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpkarsy%2Ftoit-ds3231/lists"}