Logbuch QlockWiFive

Alle Änderungen gegenüber Manuel Brachers QlockWiFive Firmware für Wort-Uhren:

/**************** **************** **************** **************** ****************

 ATTENTION! v
  ------------------ ------------------ ------------------ ------------------ ------------------ ------------------ |
 The following components MUST NOT be newer than:                 |
|                              |
| Libraries:         Version:               |
| FastLED          V3.7.0                |
|                              |
| Boards:          Version:               |
| Arduino core for ESP8266 WiFi chip   V2.7.4  ( 0 errors, 20 warnings)        |
| Arduino core for ESP8266 WiFi chip   V3.0.2  (29 errors,  7 warnings - still compiles and installs) |
|                              |
| Hint: Use Arduino IDE V2.x to change libs and boards easily              |
| Additional Hints:                                                                                                   |
| In VS 2019 enable "Deep Search for Libraries" to get code compiled (using VisualMicro extension)                  |
| Changing board type from "Wemos D1 R2" to "Generic ESP8266" and vice versa sometimes scrambles settings in EEPROM |
  ------------------ ------------------ ------------------ ------------------ ------------------ ------------------
 ATTENTION! ^

Installing QlockWiFiveA firmware on a new ESP8266 - HowTo:
 Flash firmware via Arduino IDE
 After boot use smartphone/tablet, search for ESP access point - connect to this AP
 Start browser, open IP 192.168.4.1
 Configure WLAN access with correct credentials - they will be saved in EEPROM
 Reset/repower ESP
 Start browser, enter GUI of QlockWiFiveA
 Enter CorrectIPofQlockWiFiveA and add "192.168.xxx.yyy/reset" -> this initializes EEPROM with SETTINGS_MAGIC_NUMBER
 Done

QLOCKWORK
An advanced firmware for a DIY "word-clock"  by bracci

@mc      ESP8266
@created 01.02.2017

Changes to original firmware of bracci by deHarry:
- 19.01.2019
Added support for BH1750 LightSensor (as replacement for LDR)
  The brightness adaption is managed by an BH1750 ambient light sensor which is conected via I2C bus.
  To enable the BH1750 uncomment define USE_BH1750 in Configuration.h.
  To make the BH1750 working you have to include the new class "BH1750_LightSensor" (.cpp, .h files) into the project.
  Be sure to have PullUps at I2C signals SDA and SCL, respectively - the BH1750 has no PullUps on board.

- 02.12.2019 - FW 20191202
Added support for entering NTP timeserver via WEB interface
  I had sporadic problems with the default ntp server and wanted to change it to another address easily and without recompiling.

- 05.01.2020
Reworked the time code to make the clock able to run without _permanent_ network connection and _without RTC-Chip_.
Problem: Some users want to have a wordclock based on the code from bracci (QlockWiFive), with all its stunning features, but
  don't want to have their WLAN running all the time. With the original firmware, QlockWiFive, the clock reverts to 12 o'clock
  when there is no NTP server available (provided, that no RTC chip is implemented).
  Therefore I added a software clock which is set once in 24 hours from WLAN (if connected) and which is driven from the
  secondly heartbeat signal of the DS3231RTC. This allows an accurate clock without having to read the time every minute
  from the RTC (which demonstrably slows down the internal counter of the RTC, at least on my cheap RTC modules - have a look at
  http://www.harald-sattler.de/html/ds3231_-_ungenau-.htm, in german -> use "google translate" at the bottom of the page)
  and preventing the clock from reverting to 12 o'clock midnight on 01.01.1970 after not reaching a time server on the internet.
  The solution is somewhat weird, since the clock has to have a RTC, but the time information of the RTC is not used.
  Instead the SQW output of the RTC chip is utilized to clock a software clock.
  To switch on the SQW signal, which is defaulted to OFF, the RTC has to be connected via I2C.
  Enabling the define USE_RTC_SQW also enables RTC_BACKUP to make use of the existing routines for initialization and reading.
  Only the register accesses to the RTC have to be suppressed to prevent the slowing down of the clock.
  To enable this SQW feature uncomment define USE_RTC_SQW in Configuration.h.
  --> not finished yet! <--

- 12.01.2020 - FW 20200112
Changed support for outdoor weather information to OpenWeatherMap service (OWM) https://openweathermap.org/ (by copying/merging
  the implementation of Th0rsten from his QlockWork into Braccis QlockWiFi. Thank you Th0rsten!) - see #define APIKEY 
  The API for current weather is described at OWM https://openweathermap.org/current.
  You have to get your own API-Key from OWM (you have to register with a valid email address) to get it working.
Added WEB interface option to enter the OWM API-Key
  nota bene: You can enter the ZIP code and country as well (e.g. "76131, DE"), the resulting weather data and lon/lat values are
  identical. But they translate the ZIP code into false city names (at least for my home city). This can be seen in the OWM response (debug).

- 21.01.2020 - FW 20200121
Added visualization of weather icon from OWM in WEB interface

- 24.01.2020 - FW 20200124
Get rid of Fahrenheit and other notations when location is in Germany ("xxx, DE" or "xxx, de")
Description of weather conditions in german when location is in Germany (clear sky -> Klarer Himmel)
Added pressure reading to list of weather conditions in WEB interface

- 25.01.2020 - FW 20200125
Finished SQW workaround for running without WLAN.
  When WLAN connection is lost during operation the A in the center of the display is lit (for a short time on minute update. Seen
  best with transition "fade". To be honest, it can be seen _only_ with fade transition, all other transitions are too fast).
  To set the time, WLAN connection has to be established at least once (no manual setting implemented, yet)
  -> Have to check whether reading temperature from RTC also slows down the RTC internal clock... -> look for 2x "!defined(USE_RTC_SQW)"

- 26.01.2020 - FW 20200127
Get completely rid of RTC readings when using SQW (RTC time was slow by 3 minutes in 10 hours) -> no temperature readout in WEB interface.
  The deviations seem to result from a too slow RTC-Module clock.
Implemented time correction "countCorrSecs".
  Measurements revealed a loss of one second every 345 seconds when SoftClock is triggered by SQW :(
  (It's ~2.898 ms per second)
  So I add one second every 345 seconds to compensate for that. Runs smoothly with DS3231 and SQW controlling the clock.

- 29.01.2020 - FW 20200129
Rearranged the checks and conditions for NTP updates after missing WLAN. There where issues when WLAN was accessible but NTP server was not.
  Now the automatic restarting of Station Mode works under all conditions of missing ressources.

- 02.02.2020 - FW 20200202
Idea: Implement a means of catching the time deviation of the free running clock when there is no WLAN/no NTP server. A calibration value
  is derived from the measurement and can be entered in the GUI to adjust the clock speed.
  To calibrate the clock, call "xxx/calibrate" from your WEB browser where xxx is the IP address of the clock.
  In turn, the time is captured and the check run is started. The passed time since start of the calibration run is displayed like normal (in words).
  Seconds display is switched on for the last 10 seconds of every minute, so one can compare the passed time against a stop watch.
  At least three hours should be measured to get a decent result (see HOURS2CHECK).

- 06.02.2020 - FW 20200206
Show only the last octet of the IP address at power on. If this octet has 3 digits srcoll it, 2 digits are shown statically for one second.
Calibration code implemented. Search for define ENABLE_CALIBRATION.
  The calibration is issued automatically. After 3 hours (see HOURS2CHECK) the calibration run is stopped and the calibration value is
  derived from the deviation between ESP clock and NTP clock. No need to put the clock into normal mode manually. During the test run
  the clock shows the normal time (without deviation, derived from NTP server).
  The GUI shows whether a RTC is installed, whether a calibration is running, the current calibration value and the remaining time for the test.
  The calibration value is stored via settings to EEPROM automatically and is applied from then on with every start.
  The calibration is only issued if the NTP server is local (i.e. the own router. Explanation see text at bottom of this file).
Changed recognition of "internal" NTP server to only check the first two octets of the IP to be "192.168.".

- 07.02.2020 - FW 20200207
Added possibility to make a calibration run even if no RTC module is present.
Added time display to the GUI.
Added some info about calibration and RTC present/not present to the GUI.

- 08.02.2020 - FW20200208
Check for RTC module only once in setup()

- 14.02.2020 - FW20200214
Added layout for 144 LED/m strips with only every second LED in use (preparations for 190er WordClock with ESP-01)
Added GUI for viewing debug values (call "IP-address/getDebugVals" in browser). The presentation of values has to be hardcoded - see end of file.

- 17.02.2020 - FW20200217
ESP time is only set once every random minute (to relieve NTP server). When NTP server is local (e.g. the own Router),
  the time is set every minute (look for 2020-02-17)

- 23.02.2020 - FW20200223
New matrix for 144 LEDs/m implemented, runs with ESP-01 and BH1750

- 02.03.2020 - FW20200302
New matrices for 2 CJMCU LED modules implemented, runs with Wemos D1 mini, compiled as Generic ESP8266 Module

- 12.05.2020 - FW20200512
Update of DS3232RTC lib crashed firmware since I modified this lib -> Moved modification into code
Changed define HW_QLOCKWIFIVE_12 to HW_QLOCKWIFIVE_11 for 11x11 cm "Testboard" to better distiguish from "Holz-Wecker" (which is 12x12 cm)
Changed Button.cpp to not reference D0 as check for used button IO, replaced "D0" by literal "16" -> no need to define D0 for Wemos D1 mini/Pro

- 15.05.2020
Display last octet of IP address with "lettersBig" if it has only two digits

- 02.06.2020 - FW20200602
Added layout for "Mini-Wecker", runs with Wemos D1 mini or Wemos D1 mini Pro

- 09.06.2020 - FW20200609
If layout is changed via GUI restart ESP automatically

- 11.08.2020
Added a call to yield() in "pressed minus- and plus- button simultanously" since this resulted in a watchdog timeout with reboot

- 17.08.2020
Added an option to enter the time correction factor manually for cancelling time deviation when no NTP server is availabe

- 04.09.2020
If OWM API Key is not set or wrong, perform no call for weather info, the call will time out and stop the clock for this amount of time (no update of the display).
If so (no key), don't display weather info in the GUI (root screen).
Update APIKEYpresent after leaving settings page.

- 05.09.2020
Changed fetching OWM weather info to only occur in the main loop (removed in setup -> faster start).
Added check for location to decide, whether to fetch weather info or not.

- 18.11.2020 - FW20201118
Error: If WLAN is not connected, the ESP8266 internal clock is overridden by the SoftClock. The SoftClock, controlled by the SQW signal of the RTC module, seems to imply significant deviations as long as no RTC module is part of the WordClocks hardware (ok, I should have expected that, honestly :)
 Solution: Undefined USE_RTC_SQW but enabled ENABLE_CALIBRATION, fixed.

- FW20201118.2
Add correction second to ESP clock to correct deviation. (SoftClock doesn't run anymore)
Setting the internal ESP time via NTP server missed 1 hour in STD time (no DST, daylight saving time), fixed.

- 19.11.2020 - FW20201119
Changes to the correction factor via GUI are applied immediately, formerly applied only after a reset, fixed.
Disable RTC explicitly when not installed (I missed that fact).
Disable OWM during calibration run to prevent (false) time deviation from OWM timeout.

- FW20201119.2
If correction value is 0 (zero) prevent division /0 and don't add correction seconds at all.

- 02.12.2020 - FW20201202
Enable negative correction factors (manually in the GUI), leads to slower clock (recently the clocks are too fast!?)

- 04.12.2020 - FW20201204
Seconds correction is not issued when negative values are set. Fixed.

- 07.12.2020 - FW20201207
Remove all code for RTC_SQW (doesn't work as expected, no RTC modules in my watches) and clean up the rest.

- 10.12.2020 - FW20201210
Cleanup finished.
A missing WLAN after successful connection now doesn't disturb the clock. After finding the WLAN again, it connects and gets the time from NTP.

- 11.12.2020 - FW20201210.11
Cancelled setSyncProvider(), no setSyncInterval(). Initial time is set in setup() by explicit calling setTime(getNtpTime()).
No WiFi.reconnect() in loop.

-      FW20201210.12
WiFi.reconnect() in loop reactivated for test purposes. WiFi.reconnect() doesn't hurt, so leave it in.

-      FW20201211
Reestablished setSyncProvider() and setSyncInterval() in setup() for test purposes. Result: With setSyncProvider there are exceptions after exactly 1 hour -> So leave those two calls disabled.

- 04.01.2021 - FW20210104
Changed correction value from integer to long for very cool running clocks (low deviation leads to very seldom corrections)

- 08.01.2021 - FW20210108
Fixed some leftouts for clocks with RTC chip (thanks go to Tom ;)

- 21.06.2021 - FW20210621
Fixed compiler error when calibration is not enabled

- 11.12.2022 - FW20221211
Clicking "bracci" or "deHarry" in the GUI, the links are opened in new window/tab.
Since asking OWM for weather data lasts for about 8 to 9 seconds before the answer arrives, the clock firmware is blocked for
 this duration. This results in 8..9 s  delay in updating the clock display when interrogating OWM is enabled.
 Therefore the OWM call is moved to the middle between minutes updates. The only action within the clocks firmware which
 is blocked then, is mood color change, when set to "fast". This seems acceptable to me :)

- 12.12.2022
To get the code compiled with the current version of ESP8266 framework 3.0.2, some variables of OWM have to be casted as (const char*)
-->> Beware!! Don't use ESP8266 V3.x, stay to V2.7.4 for the WordClock <<--

- 13.12.2022 - FW20221213
The return value of function "OpenWeather::getOutdoorConditions()" has to be defined for all circumstances.

- 14.12.2022 - FW20221214
Made GUI text for RTC (present or not) independent from calibration activation define.

- 29.04.2024 - FW2024429
Switch GUI temperatures to Fahrenheit when not in Germany (location is NOT xxx.DE).
Fixed error in code for displaying GUI temperatures (german and international)

- 04.05.2024 - FW20240504
Display Fahrenheit temperatures beyond 100 degree as scrolling numbers (on the clock display)

- 06.05.2024 - FW20240506
Display temperatures in Fahrenheit reworked. Fahrenheit is used in 11 (19) countries only, rest of the world uses metric units.
 See function useCelsius() at the bottom of this file for reference.
When using OWM weather info, display "XX" as long as no data is available.
Comments on calibration are displayed in German for Germany, Autriche, Belgium, Swizzerland and Liechtenstein.
Corrected attribution of citation "The only reason for time..." to Ray Cummings.

- 07.05.2024 - FW20240507
Fixed C&P error in commented part of code.

- 08.05.2024 - FW20240508
Moved OWM interrogation from "every random minute" to "every minute".
Added "private IP address space" 10.0.0.x to allowed NTP servers per IP address.

- 09.05.2024 - FW20240509
Fixed mathematics around roomtemperature for GUI and display when DHT22 or RTC is present.

- 11.05.2024 - FW20240511
Fixed problem with changing time display every 5 minutes with Matrix or Fade effect when auto mode change is enabled.
 In this situations temperature reading and change time effect are overimposed resulting in flickering display.
 Still seldomly happening, depends from when in the minute the firmware is startet. Fix see below, 13.05.2024

- 13.05.2024 - FW20240513
If no RTC and no DHT22 are present, then don't display the "XX" as info for "there is no weather data available",
 whether auto mode change is set or not.
Display outdoor temperature (if enabled) @18 seconds to prevent flickering display when using Matrix or Fade transitions.
 @18 s to prevent interferences with getOutdoorConditions() starting @30 s.

- 15.05.2024 - FW20240515
Added "deutsche Umlaute" (äöüßÄÖÜ) support for events.
Coded GUI heart into red.
Changed formatting of dedication.

- 15.09.2024, 16.09.2024 - FW20240916
Corrected API call for OWM, apikey has to be the last parameter in the call. - No, has not to be the last parameter. Leave it or change it.
Added longitude/latitude values for alternative OWM API (the values can be entered and are stored in settings).
 To get correct language information on weather data, city and country code have to be set too, additionally to Lon/Lat values.
 Lon/Lat values can be derived from CITY/COUNTRYCODE via call to OWM, but you have to have your private APIKEY (31 chars) on hands.
 https://api.openweathermap.org/geo/1.0/direct?q=CITY,COUNTRYCODE&limit=5&appid=APIKEY
 Lon/Lat feature is disabled by //#define LONLAT
Added alternative "private IP address space" 10.0.0.x to calibrating functionality logic.
Added means for discarding spaces in the location string to be compatible with recently changed(?)/actual OWM weather API.

- 07.11.2024 - FW20241107
Added description for first start of firmware on a new ESP8266.
Added hints for needed libraries and boards definition files (see top of this file).
Added favicon (Q with embedded 5, for _Q_lockWi_Five_).

- 31.05.2025 - FW20250531 - 2025-05-31
Cities with spaces (e.g. San Franzisco, New York, Las Vegas, ...) get no weather info from OWM. The space is removed falsely. Fixed.
 (Thanks go to Tom Reiter, he found the solution).

- 31.05.2025 - FW20250531.01 - 2025-05-31
Added layout for 16 x 16 pixel flexible RGB LED matrix display (https://de.aliexpress.com/item/1005003901833984.html)
 (changes in Layouts.h and Configuration.h).
Fixed D0 chaos from Arduino V1.x - Arduino V2.x has D0 defined for Wemos D1, but not for Generic ESP8266.
Firmware version may have decimals (e.g. 20250531.01).

- 13.06.2025 - FW20250513 - 2025-06-13
Added support for SK6812RGBW LEDs with the FastLED library.
 Implemented a hack published by several providers, all based an the initial work of Jim Bumgardner.
 Hints are found here:
  https://www.partsnotincluded.com/fastled-rgbw-neopixels-sk6812/
  https://gist.github.com/ChristofKaufmann/71a6259a1483df180cde76cb032debe8
  https://www.dmurph.com/posts/2021/1/cabinet-light-3.html
 The hack adds a fourth byte for every LED in the screenbuffer and fills in the information for WHITE into the bitstream to the LED array.
 In addition to that, the parts of R, G and B, respectively, forming a white basement, are subtracted from the RGB channels and are substituted
 by the white LED. The white LED is of course only involved when all three colors are "on", even partly, at least.

**************** **************** **************** **************** ****************/


#define FIRMWARE_VERSION 20250613.00