Lunar Calendar Display Error & OTA Upgrade Guide
—— Happy International Labor Day! —
Dear friends, did you notice that after April 27, the lunar calendar date displayed on your clock was incorrect? This is a software BUG, and it has now been fixed.
Incident Timeline
On April 28, a user reported: “The lunar calendar shows one day ahead.” At first, we doubted if it was really a problem, but after verification, the lunar calculation error was confirmed. The cause was identified and a new version with the fix was released the same day.
Which Devices Are Affected?
All our clocks with lunar calendar features are affected. The issue: the lunar date is one day ahead. For example, April 27 should show “Third month, day 30” but instead shows “Fourth month, day 1”.
How to Fix
- Affected period: 2025-04-27 to 2025-05-26 (after May 26, it will automatically return to normal), so if the impact is small, you can simply wait until May 27.
- Upgrade to version 1.9.x (WHEN clock). If you use lunar calendar, please contact us for upgrade instructions (see later in this article).
A Common Problem Across Devices
This is a widespread bug in various devices, such as perpetual calendars, clocks, attendance machines, etc.
If your device displays lunar dates, please check. A quick search online shows that many smartphones are also affected.
Technical Reason & Lunar Algorithm Background
This section is for those interested in technical details and embedded development.
Phenomenon:
During 2025-04-27 ~ 2025-05-26, the lunar date is +1 day ahead.
Direct Cause:
A single bit error in the classic “3-byte year code” lunar calendar algorithm.
Origin of the 3-byte year code:
Lunar calendar calculation is complex and can’t be simply offset; due to early MCU resource limitations, someone proposed to hard-code the lunar calendar from 1901-2099 into ROM as a table. This “3-byte year code” lookup algorithm avoids complex floating-point calculations and saves memory.
According to various sources:
| Year | Source / Person | Milestone |
|---|---|---|
| 1994 | Computer Programming Skills & Maintenance magazine | Published Turbo C code storing lunar calendar as 4 bytes × 199 years |
| 2002 | 8052.com / Electronic Engineering Forum | User Campo released "3-byte lunar year code + C routine", only 600 bytes |
| 2004-2007 | Various MCU providers | Integrated code into "perpetual calendar" and "clock voice chip" DEMOs, creating many variants |
| 2010+ | Arduino/ESP8266 Chinese Community | Regained popularity; over a dozen forks on GitHub |
Since then, “3 bytes × 199 years” became the industry standard for lunar calculation.
Risks include:
- Manual data entry: any single wrong bit causes a +1/-1 day error cascade for a whole month.
- Delayed exposure: errors often surface 10–20 years later (e.g., 2025, 2033, 2093).
- Hard to trace: many "enthusiastic fixes" in forums led to different tables fixing different years, making it hard to tell right from wrong downstream.
These inherited tables are widely used, but rarely double-checked.
Unfortunately, the table everyone uses does contain errors!
Years and Issues Affected
| Year | Possible Problem |
|---|---|
| 2033 | Leap month marked as 11th leap → "2033 Bug": 8 months offset |
| 2025 | March/April days reversed → March 30 appears as April 1 |
| 2036 | Leap month error → All lunar months off by 1 from June |
| 2091 | Chinese New Year shifted +1 → Shown as Feb 1 instead of Jan 31 |
| 2093 | Leap month error → Whole winter month shifted |
These errors have only started to surface in recent years. Devices that can be OTA-upgraded are fine, but older devices without maintenance or upgrade options can’t be fixed. Fortunately, the error only affects about one month and does not have major consequences.
Why Spend Effort on This "Small Bug"
This year code table was used directly in my project, and now my own product is affected. Without tracing the root cause, there’s no way to fully patch the issue.
It’s a small bug, but it can lurk for decades and persist to this day. If this error isn’t widely known, more devices will keep using the uncorrected code in the future.
This isn’t a unique incident of any one manufacturer, but a reflection of the “copy-paste culture.”
Once again, it proves: “The world is a makeshift troupe.”
For small teams, “borrowing” is understandable. But even big companies with seemingly complete resources, process, and QA, will copy, integrate, and mass-produce old code if it “just works,” often lacking effective validation and testing.
I recall a saying from a previous job: Respect technology, treat product development as walking on thin ice.
How to OTA Upgrade for Our Products?
