Initial Setup, Settings and Options - Resinchem/LED-Matrix-Clock_WS2812b GitHub Wiki
Initial Setup
The first time you boot your new clock (or if you have powered down, removed or replaced the board, etc). There are some initial steps you should take. This primarily includes setting the proper time. There are numerous other options and settings you can define for boot defaults and these are covered below.
The Boot Process
When the clock is powered up, a boot process will begin. First, the clock will attempt to connect to your wifi. Pixels will light in green, starting with pixel 1, then pixel 2, etc. while the boot process and wifi connection occurs:
This process normally only takes a few seconds and should complete well before the first row is fully lit. If wifi connection takes more than 1 minute, the wifi connection will be aborted and the clock will not be accessible via wifi. Check your wifi settings in the Credentials.h file (see below).
Once wifi is successfully connected, the clock will attempt to connect to your MQTT broker if MQTT is enabled. This is indicated by blue lights, again starting with pixel 1, then pixel 2, etc. Note that often the connection to the MQTT broker is so fast, you may not see any blue lights at all.
Finally, the over-the-air (OTA) updating will be enabled. This is indicated by about a 2 second display of "UPLOAD" in red on the clock display:
This does not mean that any upload is occurring, nor that you can upload a new file at this point. It is simply indicating that the OTA module is starting and that the mDNS port is broadcasting. For more information on enabling OTA mode to load a new sketch, see OTA Updates. Once the boot and startup processes have completed, the clock will show the time (or other default mode if you changed this in the Settings.h file - see below).
Setting the Clock
The very first time you boot the clock, or if the RTC module has a dead or missing battery, the time will show the time of the last compile of the matrix_clock.ino file. To update the time, launch the web browser (enter IP address of the board into a browser on the same network as the clock) and utilize the 'Set Date/Time' feature to update the clock to the current time. If you have enabled MQTT, you may also update the time via MQTT commands. See MQTT / Home Assistant Integration for more details on using MQTT.
Once the time is set and if you have a non-dead CR2032 battery installed in the real-time clock module, the time should be retained upon future restarts or brief power outages.
Note on CR2032 Battery Life: If you disconnect the clock from the main power supply often, for any significant length of time, it is recommended that you either remove the battery from the RTC module or disconnect the 5V connection to the RTC. This is because the 5V connection will attempt to power the rest of the clock using the 3V CR2032 battery. Since 3V is not enough to power up the other components when main power is removed, the clock will not function, but it will drain the CR2032 battery over time. Short power outages are OK (but the more often power is removed, the more quickly the battery will die). If you are going to be disconnecting the clock for any extended period, it is advisable to remove the battery or disconnect the 5V line to the RTC to conserve the battery.
Credential.h
The Credentails.h file contains information regarding the wifi SSID, wifi password and MQTT user ID and password settings. These should have been set when you were initially installing the code to the board. Normally, you will not need to edit this file unless your wifi or MQTT broker changes. If that occurs, edit and save this file and upload the clock_main.ino file again. If not connected via wifi, you will need to remove the board from the clock assembly and upload via USB. See Installation for more details on uploading via USB.
Setttings.h
The top section of the Settings file contains settings that are normally set during the initial installation process. This includes items such as the milliamps of your power supply, wifi and MQTT settings, etc. and do not need to be changed unless something in your environment (like MQTT broker) changes.
WiFi Modes
In addition to joining your local wifi, the clock can broadcast a local 'hot spot' for connecting to the web app in situations where the normal wifi is not available. This might be useful if using the clock in the backyard for timer or scoreboard functions, or at a friend's house for game night (or if you simply do not want the clock on your wifi network). When local AP mode is enabled, you can connect to the broadcast hotspot via phone, table or laptop and connect to the web server for controlling most functions of the clock. WiFi modes are set in the Settings.h file as follows:
- 0: Only broadcast a local hot spot (soft access point) and do not attempt to connect to normal wifi
- 1: Only connect to normal wifi and do not broadcast a hot-spot
- 2: Both
If using the local hot spot, you will need to connect your device to the broadcasting 'MATRIX-CLOCK-AP' access point with a default password of '1234567890'. You can change both the access point name and password if desired by editing the value for APssid and APpassword in the clock_main.ino file.
When connected to the hot-spot, the web interface can be reached via browser at IP address: 192.168.4.1.
Additional Notes:
- If the clock is normally connected to your wifi and you do not envision needing the hot-spot, it is recommended for security reasons to set WIFIMODE to 1.
- MQTT is only available when the clock is connected to normal wifi and the MQTT broker is visible on the same network as the clock.
Other Options
The more interesting part of this file are listed under the "Options" portion. This allows you to change or update a number of default boot options, such as 12/24 hour display for the clock, Fahrenheit or Celsius for temperature, default colors for the various modes, etc. Note that these are just the 'boot' defaults. Any of these values can be changed via the web app or MQTT after boot up completes. Open the Settings.h file in the Arduino IDE or other text editor to review and change. Each of the options are documented within the Settings.h file itself with the valid values or ranges, but are summarized here:
| Option Setting | Description |
|---|---|
| clockMode | Set the default display mode after boot (Clock, Countdown, Scoreboard, Text Display) |
| brightness | Set the default display brightness |
| numFont | Set the default large number font (7-segment, Modern, Hybrid) |
| temperatureSymbol | Display temperature in Fahrenheit or Celsius |
| temperatureSource | Display interior or exterior temperature |
| temperatureCorrection | Interior temperature is reported from the RTC module and generally runs a bit high due to heat generation |
| temperatureUpdatePeriod | How often to update external temperature via MQTT |
| hourFormat | Display time in 12 or 24 hour format |
| scoreboardLeft | Initial starting score for the left (visitor) score on the scoreboard |
| scoreboardRight | Initial starting score for the right (home) score on the scoreboard |
| scoreboardTeamLeft | Default team name for left score on the scoreboard |
| scoreboardTeamRight | Default team name for right score on the scoreboard |
| textEffect | Default text effect to use for text display |
| textEffectSpeed | Default speed applied to the text effect |
Default colors at boot (can be RGB values or named colors):
| Option Setting | Description |
|---|---|
| clockColor | The color of the time display |
| countdownColor | The color for the clock/time display |
| countdownColorPaused | The color of the countdown timer when paused/stopped (to disable, set to the same as running color) |
| countdownColorFinalMin | The color of the countdown clock in the final minute (to disable, set to the same as running color) |
| temperatureColor | The color for the temperature display |
| scoreboardColorLeft | The color for the left (visitor) score display |
| scoreboardColorRight | The color of the right (home) score display |
| textColorTop | Default color for top row of text for Text Display mode |
| textColorBottom | Default color for the bottom row of text for Text Display mode |
| alternateColor | The color used for 'unlit' pixels. Highly recommended to leave this set to the named color "Black" |
Additional details and valid values can be found in the comments within the Settings.h file. If you make any changes to this file, you will need to save these changes and upload the matrix_clock_main.ino to your board again via USB or the OTA Update process.