FAQ
TL;DR: OpenBK7231 sunrise/sunset NTP events are now fully functional, add about 1 minute of typical timing error, and were described as "fully acceptable" in self-tests. This FAQ helps BK7231N/BK7231T users automate relays at dawn and dusk, avoid autoexec timing mistakes, and document or submit the feature correctly. [#20869623]
Why it matters: Sunrise/sunset scheduling solves a real automation problem: lights and relays follow local daylight instead of fixed clock times, with workable accuracy and known startup limits.
| Approach |
Best use |
Main requirement |
Known limitation |
addClockEvent sunrise/sunset |
Daily daylight-based switching |
Valid timezone, latitude/longitude, NTP sync |
First-day edge cases can occur after initial setup |
Fixed-time addClockEvent HH:MM |
Stable manual schedules |
Only local clock time |
Does not track seasonal daylight changes |
addRepeatingEvent after sunset |
Simple delay like +30 minutes |
Sunset event must run first |
Reboot during delay loses the pending action |
Key insight: Put timezone and location in autoexec.bat, then wait for NTP before creating sunrise or sunset events. That ordering prevents wrong-time calculations and makes the feature reliable after daily rescheduling. [#20823027]
Quick Facts
- The sunrise/sunset code was first estimated at <900 bytes, but later measured at roughly 11 kB, likely due to trig functions such as
atanf and sinf. [#20828276]
- Test results across cities such as Tokyo, Hawaii, São Paulo, New York, Cairo, Moscow, and Sydney showed about ±2 minutes error in manual checks. [#20870355]
- Built-in self-tests later reported sunrise/sunset timestamp discrepancy of about 1 minute versus official websites, which was accepted for automation use. [#20869623]
- A failed NTP receive can appear in bursts of 10 messages because UDP is not reliable and
recv may fail without indicating a firmware fault. [#20824897]
- OpenBK7231 documentation examples are generated from JSON sources, including
autoexecExamples.json, not by editing Markdown directly. [#20854291]
How do I set up sunrise and sunset NTP events in OpenBK7231T_App using autoexec.bat?
Use
autoexec.bat to start NTP, set timezone and coordinates, wait for sync, then add the events. 1.
startDriver ntp and
ntp_timeZoneOfs .... 2. Set
ntp_setLatlong <lat> <long> and run
waitFor NTPState 1. 3. Add
addClockEvent sunrise ... and
addClockEvent sunset ..., for example event IDs
12 and
13. A working sample turns
POWER OFF at sunrise and
POWER ON at sunset after the wait step.
[#20828244]
Why does addClockEvent sunrise or sunset fail if I set ntp_timeZoneOfs in autoexec.bat before NTP has fully synced?
It fails because the new timezone offset is not applied immediately to the current NTP time. The firmware explicitly reports,
NTP offset set, wait for next ntp packet to apply changes, so a sunrise or sunset event created right away can use the wrong timezone. That produces the wrong local event time until the next NTP packet arrives.
[#20823018]
What is waitFor NTPState 1 in OpenBK7231T_App, and when should I use it in an autoexec script?
waitFor NTPState 1 is a script gate that pauses execution until NTP is live. Use it before any command that depends on correct local time, especially
addClockEvent sunrise and
addClockEvent sunset. In this thread, it was recommended specifically to fix startup ordering in
autoexec.bat.
[#20823027]
What is SafeMode in OpenBK7231T_App, and how do I enter it without adding an OnHold event handler?
SafeMode is a recovery mode that lets you regain control after a bad script or configuration. You do not need an
OnHold event for it. Enter it by doing
5 quick power off/on cycles, which makes the extra
addEventHandler OnHold 8 SafeMode line unnecessary for normal sunrise/sunset automation.
[#20950287]
Why does OpenBK7231T_App show "Info:NTP:NTP_CheckForReceive: Error while receiving server's msg" in groups, and is that normal for UDP NTP polling?
Yes, that can be normal because NTP here uses UDP, and UDP does not guarantee delivery. The maintainer checked the code and said the message appears when
recv fails. One user noticed the messages arriving in groups of
10, but that alone did not indicate a firmware bug.
[#20824897]
How accurate are the OpenBK7231 sunrise and sunset calculations compared with official sunrise/sunset times?
They are accurate enough for home automation, usually around
1 minute in self-tests and up to about
±2 minutes in broader city checks. One maintainer wrote that a
1 minute discrepancy versus official websites was "fully acceptable." That makes the feature suitable for lights, relays, and similar daily triggers.
[#20869623]
What's the best way to turn a relay on at sunset and off at sunrise on a BK7231N or BK7231T device?
Use two sunrise/sunset clock events after NTP sync, because that tracks seasonal daylight automatically. For relay 2, a tested pattern is
addClockEvent sunrise 0x7f 12 POWER2 OFF and
addClockEvent sunset 0x7f 13 POWER2 ON, preceded by timezone, coordinates, and
waitFor NTPState 1. That is better than hard-coded times when daylight changes through the year.
[#20950188]
How can I make a device restore the correct day or night state after a reboot or power outage if it missed the sunrise or sunset transition?
Use time constants after NTP sync to set the initial state at boot, then let sunrise/sunset events handle later transitions. A posted script compared
$hour and
$minute with
$sunset_hour and
$sunset_minute to choose the correct startup mode.
"Time constants" are runtime variables that expose computed clock values, including next solar event times, so scripts can restore state after reboot instead of waiting for the next transition. [#20878116]
What is the proper way to add sunrise/sunset documentation and example autoexec files to the OpenBK7231T_App docs system on GitHub?
Update the JSON doc sources, not the generated Markdown file. Put the example script in
docs/autoexecs, add its metadata to
docs/json/autoexecExamples.json, and then run the docs generation step. The maintainer said
commands.md is autogenerated from JSON comments, so direct Markdown edits are not the preferred path.
[#20854291]
How do I create a GitHub pull request for OpenBK7231T_App from my own fork if pushing to the main repository gives a 403 permission error?
Push your branch to your own fork first, then open a pull request from that fork to the parent repository. The
403 happened because direct push access to
openshwprojects/OpenBK7231T_App.git was denied. After pushing to the personal fork, the contributor successfully created PR
#1001 from branch
sunrise_sunset_NTP.
[#20865847]
Why should sunrise/sunset latitude and longitude settings use globals or autoexec.bat instead of adding fields to the OpenBK7231 config structure?
Use globals or
autoexec.bat to avoid changing the persistent config structure size across firmware versions. The maintainer warned that if config size changes, downgrade compatibility breaks. He recommended globals or statics and simply setting latitude and longitude on every startup through
autoexec.bat.
[#20843876]
OpenBK7231 sunrise/sunset vs Tasmota timers: which approach is better for offset events like civil sunset or delayed light switching?
Use native OpenBK7231 sunrise/sunset events for exact dawn and dusk switching, but Tasmota-style offset behavior is more convenient for civil sunset. In this thread, offset support was not implemented directly. The suggested OpenBK7231 workaround was to trigger a delayed action from the sunset event, which works but is less robust than a built-in offset model.
[#20879370]
How can I delay a sunset-triggered action by 30 minutes in OpenBK7231T_App, and what happens if the device reboots during that delay?
Trigger a one-shot repeating event from the sunset event with a
30 minute delay, or
30×60 seconds. That is the simplest workaround for civil-sunset-like behavior. The downside is clear: if the device reboots during that delay window, the pending delayed action is lost because the temporary timer is not preserved across reboot.
[#20879370]
Where can I find a real BK7231N datasheet, and what official hardware information is actually available?
You likely cannot get a full public BK7231N datasheet from this project, because the maintainer said the forum information is all they know. In other words, the practical hardware reference here is the project’s forum and command documentation, not an official vendor datasheet package. That was the direct answer given in the thread.
[#20843876]
Why is BL602 apparently ignored by the sunrise/sunset implementation in OpenBK7231T_App, and what needs to change to make sunset calculation work there?
The thread raises the BL602 issue but does not answer it, so the exact reason is unresolved here. The only concrete clue is a
2025-01-12 report pointing to a commit in PR
#1030 and asking why BL602 was excluded from sunset calculation. From this thread alone, the next step is to inspect that commit and add the missing BL602-specific path or guard changes there.
[#21389444]
Generated by the language model.
