v0.98

- Add new Game Manager includes "Slot Machine" and "AWTRIX Says" games. These games can be controlled through the AWTRIX 3 App.
- Adds new timemodes. ( TMODE = 5 shows a clock in big digits where you can customize the backgroundmask with your own GIF. TMODE = 6 shows a  Binary Clock) special thx to Xandr and Justin
- Add MQTT Last Will and Testament feature to /stats/device to indicate online/offline status.
- Add configuration_url to HomeAssistant discovery.
- New documatation entry for each native App.
- fixes a bug where bargraph is showing with zero values.
- fixes an error where the SOUND setting was not saved.

AWL_Backup/build/legal/java.desktop/libpng.md

@@ -20,7 +20,7 @@ derived from libpng-1.0.6, and are distributed according to the same
 disclaimer and license as libpng-1.0.6 with the following individuals
 added to the list of Contributing Authors:
 
-   Simon-Pierre Cadieux
+   AWTRIX-Pierre Cadieux
    Eric S. Raymond
    Mans Rullgard
    Cosmin Truta

docs/_sidebar.md

@@ -14,12 +14,23 @@
 
 - Features
   - [Apps](apps.md)
+     - [Native Apps](apps.md#native-apps)
+     - [Custom Apps](apps.md#custom-apps)
   - [Effects](effects.md)
   - [Icons](icons.md)
   - [Sounds](sounds.md)
   - [Hidden features](dev.md)
 
 - API
   - [MQTT/HTTP](api.md)
-
-
+     - [Status](api.md#status-retrieval)
+     - [Liveview](api.md#liveview)
+     - [Power](api.md#power-control)     -
+     - [Sound](api.md#sound-playback)
+     - [Moodlight](api.md#mood-lighting)
+     - [Indicators](api.md#colored-indicators)
+     - [Customapps & Notification](api.md#custom-apps-and-notifications)   
+     - [Drawing](api.md#drawing-instructions)
+     - [Colored textfragmentss](api.md#display-text-in-colored-fragments)
+     - [App switching](api.md#switch-to-specific-app)
+     - [Settings](api.md#change-settings)

docs/api.md

@@ -374,7 +374,7 @@ You can adjust each property in the JSON object according to your preferences. I
 | `TEFF`        | number                    | Choose between app transition effects.                                                              | 0-10                                               | 1       |
 | `TSPEED`      | number                    | Time taken for the transition to the next app in milliseconds.                                      | Positive integer                                   | 500     |
 | `TCOL`        | string/array of ints      | Global text color.                                                                                  | RGB array or hex color                             | N/A     |
-| `TMODE`       | integer                   | Changes the time app style.                                                                         | 0-4                                                | 1       |
+| `TMODE`       | integer                   | Changes the time app style.                                                                         | 0-6                                                | 1       |
 | `CHCOL`       | string/array of ints      | Calendar header color of the time app.                                                              | RGB array or hex color                             |`#FF0000`|
 | `CBCOL`       | string/array of ints      | Calendar body color of the time app.                                                                | RGB array or hex color                             |`#FFFFFF`|
 | `CTCOL`       | string/array of ints      | Calendar text color in the time app.                                                                | RGB array or hex color                             |`#000000` |
@@ -418,45 +418,45 @@ You can adjust each property in the JSON object according to your preferences. I
 - "thunder"  
 - "frost"  
 
-**Timeformats:**  
-```bash  
-%H:%M:%S     13:30:45  
-%l:%M:%S     1:30:45  
-%H:%M        13:30  
-%H %M        13.30 with blinking colon  
-%l:%M        1:30  
-%l %M        1:30 with blinking colon  
-%l:%M %p     1:30 PM  
-%l %M %p     1:30 PM with blinking colon  
-```
+#### **Available Time Formats:**  
+| Format       | Example    | Description                                |
+|--------------|------------|--------------------------------------------|
+| `%H:%M:%S`   | `13:30:45` | 24-hour time with seconds                 |
+| `%l:%M:%S`   | `1:30:45`  | 12-hour time with seconds                 |
+| `%H:%M`      | `13:30`    | 24-hour time                              |
+| `%H %M`      | `13.30`    | 24-hour time with blinking colon          |
+| `%l:%M`      | `1:30`     | 12-hour time                              |
+| `%l %M`      | `1:30`     | 12-hour time with blinking colon          |
+| `%l:%M %p`   | `1:30 PM`  | 12-hour time with AM/PM indicator         |
+| `%l %M %p`   | `1:30 PM`  | 12-hour time with blinking colon and AM/PM|
 
-**Dateformats:**  
-```bash  
-%d.%m.%y     16.04.22  
-%d.%m        16.04  
-%y-%m-%d     22-04-16  
-%m-%d        04-16  
-%m/%d/%y     04/16/22  
-%m/%d        04/16  
-%d/%m/%y     16/04/22  
-%d/%m        16/04  
-%m-%d-%y     04-16-22  
-```  
-
-**Transition effects:**  
-```bash  
-0 - Random
-1 - Slide
-2 - Dim
-3 - Zoom
-4 - Rotate
-5 - Pixelate
-6 - Curtain
-7 - Ripple
-8 - Blink
-9 - Reload
-10 - Fade 
-```
+#### **Available Date Formats:**  
+| Format       | Example    | Description            |
+|--------------|------------|------------------------|
+| `%d.%m.%y`   | `16.04.22` | Day.Month.Year (short) |
+| `%d.%m`      | `16.04`    | Day.Month              |
+| `%y-%m-%d`   | `22-04-16` | Year-Month-Day         |
+| `%m-%d`      | `04-16`    | Month-Day              |
+| `%m/%d/%y`   | `04/16/22` | Month/Day/Year         |
+| `%m/%d`      | `04/16`    | Month/Day              |
+| `%d/%m/%y`   | `16/04/22` | Day/Month/Year         |
+| `%d/%m`      | `16/04`    | Day/Month              |
+| `%m-%d-%y`   | `04-16-22` | Month-Day-Year         |
+
+#### **Available Transition Effects:**  
+| Code | Effect      |
+|------|-------------|
+| `0`  | Random      |
+| `1`  | Slide       |
+| `2`  | Dim         |
+| `3`  | Zoom        |
+| `4`  | Rotate      |
+| `5`  | Pixelate    |
+| `6`  | Curtain     |
+| `7`  | Ripple      |
+| `8`  | Blink       |
+| `9`  | Reload      |
+| `10` | Fade        |
 
 ## Update
 

docs/apps.md

@@ -1,9 +1,119 @@
-# Apps
+# Native Apps
+## Time
+The native Time app offers extensive customization options. Almost everything can be configured via the API, and most settings can also be adjusted through the AWTRIX3 app.   
+The time format can be customized to your preferences. By default, it is set to `HH:mm`.   
+If the selected format doesn't fit on the screen, it will automatically revert to this default.   
+You might notice some lines at the bottom of the screen. These lines represent the weekdays, with the current day highlighted brighter.   
+You can also customize the colors for the calendar icon, the weekday bar and also the textcolor with the [SettingsAPI](https://blueforcer.github.io/awtrix3/#/api?id=change-settings) or the mobile App.    
 
-The AWTRIX 3 system comes equipped with several built-in applications, including Time, Date, Temperature, Humidity, and Battery status.  
-As it is designed to integrate seamlessly with your smart home ecosystem, additional applications can be created using MQTT or HTTP requests.
+The `TMODE` setting determines the layout and style of the Time App. 
 
-!> In AWTRIX, the term 'Apps' does not refer to traditional smartphone apps that you download and install. Instead, in AWTRIX, CustomApps function more like dynamic pages that rotate within the Apploop rotation of the display. These pages do not store or execute their own logic; instead, they display content that is sent from an external system, such as a smarthome. This content must be transmitted using MQTT or HTTP protocols via the [CustomApp API](https://blueforcer.github.io/awtrix3/#/api?id=custom-apps-and-notifications).  
+ **TMODE=0**  
+<img src="https://raw.githubusercontent.com/Blueforcer/awtrix3/main/docs/assets/TMODE0.png" style="max-height:70px;">  
+Displays the time along with a weekday bar at the bottom of the screen.  
+
+**TMODE=1**  
+<img src="https://raw.githubusercontent.com/Blueforcer/awtrix3/main/docs/assets/TMODE1.png" style="max-height:70px;">   
+Shows the time with the weekday bar on the bottom and a calendar box that highlights the current day of the month.  
+
+**TMODE=2**  
+<img src="https://raw.githubusercontent.com/Blueforcer/awtrix3/main/docs/assets/TMODE2.png" style="max-height:70px;">   
+Similar to `TMODE=1`, but places the weekday bar at the top.   
+
+**TMODE=3**  
+<img src="https://raw.githubusercontent.com/Blueforcer/awtrix3/main/docs/assets/TMODE3.png" style="max-height:70px;">   
+Displays the time with the weekday bar at the bottom and a different calendar icon.  
+
+**TMODE=4**  
+<img src="https://raw.githubusercontent.com/Blueforcer/awtrix3/main/docs/assets/TMODE4.png" style="max-height:70px;">   
+Similar to `TMODE=2`, but places the weekday bar at the top.    
+
+**TMODE=5**  
+<img src="https://raw.githubusercontent.com/Blueforcer/awtrix3/main/docs/assets/TMODE5.png" style="max-height:70px;">   
+Introduces a "big time" display, utilizing a large font for the time.  
+If a 32x8 GIF named `bigtime.gif` exists in the root directory, it will be played in the background.  
+Please note: Once the GIF is displayed in BigTime mode, it cannot be directly replaced because the file is in use.  
+To replace the icon, switch the mode to TMODE first, and then you'll be able to update the GIF.    
+If no GIF is found, the global textcolor is used.     
+
+**TMODE=6**  
+<img src="https://raw.githubusercontent.com/Blueforcer/awtrix3/main/docs/assets/TMODE6.png" style="max-height:70px;">   
+Displays the time in **binary format**:  
+The top row shows the hour, the middle row shows the minutes, and the bottom row shows the seconds.  
+Each row has six dots, where lit dots represent binary "1" and white dots represent binary "0".  
+To read the time, convert the lit dots in each row to a decimal number.     
+
+#### **Available Time Formats:**  
+| Format       | Example    | Description                                |
+|--------------|------------|--------------------------------------------|
+| `%H:%M:%S`   | `13:30:45` | 24-hour time with seconds                 |
+| `%l:%M:%S`   | `1:30:45`  | 12-hour time with seconds                 |
+| `%H:%M`      | `13:30`    | 24-hour time                              |
+| `%H %M`      | `13.30`    | 24-hour time with blinking colon          |
+| `%l:%M`      | `1:30`     | 12-hour time                              |
+| `%l %M`      | `1:30`     | 12-hour time with blinking colon          |
+| `%l:%M %p`   | `1:30 PM`  | 12-hour time with AM/PM indicator         |
+| `%l %M %p`   | `1:30 PM`  | 12-hour time with blinking colon and AM/PM|
+
+---
+## Date
+<img src="https://raw.githubusercontent.com/Blueforcer/awtrix3/main/docs/assets/DATE.png" style="max-height:100px;">  
+
+The Dateapp shows the current date of course. There are several dateformats 'DFORMAT' you can choose from:  
+
+#### **Available Date Formats:**  
+| Format       | Example    | Description            |
+|--------------|------------|------------------------|
+| `%d.%m.%y`   | `16.04.22` | Day.Month.Year (short) |
+| `%d.%m`      | `16.04`    | Day.Month             |
+| `%y-%m-%d`   | `22-04-16` | Year-Month-Day         |
+| `%m-%d`      | `04-16`    | Month-Day             |
+| `%m/%d/%y`   | `04/16/22` | Month/Day/Year         |
+| `%m/%d`      | `04/16`    | Month/Day             |
+| `%d/%m/%y`   | `16/04/22` | Day/Month/Year         |
+| `%d/%m`      | `16/04`    | Day/Month             |
+| `%m-%d-%y`   | `04-16-22` | Month-Day-Year         |
+
+---
+## Temperature  
+
+<img src="https://raw.githubusercontent.com/Blueforcer/awtrix3/main/docs/assets/TEMP.png" style="max-height:100px;">  
+
+The Temperature App displays the current reading from the integrated temperature sensor.  
+However, due to the sensor's placement inside the housing, the measurement may not be entirely accurate.   
+Factors such as the power board, LED matrix, brightness, color, and the number of lit pixels can affect the temperature reading.  
+For more precise messurement, you can utilize the [dev.json](https://blueforcer.github.io/awtrix3/#/dev) to calibrate the temperature with the `temp_offset` key. 
+
+---
+## Humidity  
+
+<img src="https://raw.githubusercontent.com/Blueforcer/awtrix3/main/docs/assets/HUM.png" style="max-height:100px;">  
+
+The humidity App displays the current reading from the integrated humidity sensor.  
+However, due to the sensor's placement inside the housing, the measurement may not be entirely accurate.   
+Factors such as the power board, LED matrix, brightness, color, and the number of lit pixels can affect the humidity reading.  
+For more precise messurement, you can utilize the [dev.json](https://blueforcer.github.io/awtrix3/#/dev) to calibrate the temperature with the `hum_offset` key. 
+
+---
+## Battery  
+
+<img src="https://raw.githubusercontent.com/Blueforcer/awtrix3/main/docs/assets/BAT.png" style="max-height:100px;">  
+
+The Battery App displays the current charge level of the integrated battery.  
+Due to differences in battery batches and the degradation of the cheap battery over time, you may need to calibrate it manually.
+
+1. Use the [Status API](https://blueforcer.github.io/awtrix3/#/api?id=status-retrieval) to retrieve the `bat_raw` readings.  
+2. Open the [dev.json](https://blueforcer.github.io/awtrix3/#/dev) file to configure the `min_battery` and `max_battery` values:  
+   - **`min_battery`**: Enter the `bat_raw` value when the battery is empty.  
+   - **`max_battery`**: Enter the `bat_raw` value when the battery is fully charged.  
+
+
+---
+# Custom Apps
+
+Besides the native apps, AWTRIX3 is designed to integrate seamlessly with your smart home ecosystem, additional applications can be created using MQTT or HTTP requests.
+
+!> In AWTRIX, the term 'Custom Apps' does not refer to traditional smartphone apps that you download and install. Instead, in AWTRIX, CustomApps function more like dynamic pages that rotate within the Apploop rotation of the display. These pages do not store or execute their own logic; instead, they display content that is sent from an external system, such as a smarthome. This content must be transmitted using MQTT or HTTP protocols via the [CustomApp API](https://blueforcer.github.io/awtrix3/#/api?id=custom-apps-and-notifications).  
 It is important to note that all the logic for managing the content displayed in these CustomApps needs to be handled by your external system. AWTRIX only provides the platform for displaying the information. You have the flexibility to update the content shown on your CustomApps in real-time at any moment, making it a versatile tool for displaying personalized information in your smarthome setup.
 
 There are numerous benefits to this approach:

docs/icons.md

@@ -1,6 +1,6 @@
 # Icons
 
-To personalize your custom page or notification with your favorite icon, you can use one of these simple methods:
+To personalize your custom app or notification with your favorite icon, you can use one of these simple methods:
 
 ### Downloading an Icon
 
@@ -13,7 +13,7 @@ You can explore and find LaMetric icons at [LaMetric Icon Gallery](https://devel
 
 ### AWTRIX 3 App
 
-With the AWTRIX 3 app, available for both Android and iOS, you gain exclusive access to the official AWTRIX database, featuring over 1500 icons and animations in 8x8 and 32x8 formats. The app also allows you to create your own icons and to upload them directly to your AWTRIX device or to the cloud database.
+With the AWTRIX 3 app, available for both Android and iOS, you gain exclusive access to the official AWTRIX database, featuring over 1800 icons and animations in 8x8 and 32x8 formats. The app also allows you to create your own icons and to upload them directly to your AWTRIX device or to the cloud database.
 
 ### Custom Icons
 

docs/index.html

@@ -15,10 +15,12 @@
   <div id="app">Loading ...</div>
   <script>
     window.$docsify = {
-      name: '',
+       name: "AWTRIX 2",
+        logo: "assets/icon.png",
       loadSidebar: true,
       coverpage: true,
       loadNavbar: true,
+      sidebarDisplayLevel: 1,
       mergeNavbar: true,
       repo: 'https://github.com/Blueforcer/awtrix3',
       share: {
@@ -37,6 +39,8 @@
   <script src="//unpkg.com/docsify-share/build/index.min.js"></script>
   <script src="//cdn.jsdelivr.net/npm/prismjs@1.22/components/prism-json.min.js"></script>
   <script src="//unpkg.com/prismjs/components/prism-json.min.js"></script>
+  <script src="//cdn.jsdelivr.net/npm/docsify-sidebar-collapse/dist/docsify-sidebar-collapse.min.js"></script>
+
 
 </body>
 

docs/onscreen.md

@@ -5,7 +5,7 @@ Press and hold the middle button for 2 seconds to access the menu.
 Navigate through the items with the left and right buttons and choose the submenu with a push on the middle button.  
 Hold down the middle button for 2s to exit the current menu and to save your setting.  
 
-!>  You can easily turn your AWTRIX matrix on or off by simply double-pressing the middle button if your not in Menu.
+!>  You can easily turn your AWTRIX matrix on or off by simply double-pressing the middle button if youre not in Menu.
 
 | Menu Item | Description |
 | --- | --- |

lib/home-assistant-integration/src/HADevice.cpp

@@ -18,6 +18,14 @@ HADevice::HADevice() :
 
 }
 
+void HADevice::setConfigurationUrl(const char* url)
+{
+    _serializer->set(
+        AHATOFSTR(HADeviceConfigurationUrlProperty),
+        url
+    );
+}
+
 HADevice::HADevice(const char* uniqueId) :
     _uniqueId(uniqueId),
     HADEVICE_INIT

lib/home-assistant-integration/src/HADevice.h

@@ -27,6 +27,13 @@ class HADevice
      */
     HADevice(const char *uniqueId);
 
+    /**
+     * Sets the "configuration URL" property that's going to be used by the Home Assistant.
+     *
+     * @param url Configuration URL to publish.
+     */
+    void setConfigurationUrl(const char *url);
+
     /**
      * Constructs HADevice using the given byte array as the unique ID.
      * It works in the same way as HADevice::setUniqueId method.

lib/home-assistant-integration/src/utils/HADictionary.cpp

@@ -35,6 +35,7 @@ const char HASerializerUnderscore[] PROGMEM = {"_"};
 const char HADeviceIdentifiersProperty[] PROGMEM = {"ids"};
 const char HADeviceManufacturerProperty[] PROGMEM = {"mf"};
 const char HADeviceModelProperty[] PROGMEM = {"mdl"};
+const char HADeviceConfigurationUrlProperty[] PROGMEM = {"cu"};
 const char HADeviceSoftwareVersionProperty[] PROGMEM = {"sw"};
 const char HANameProperty[] PROGMEM = {"name"};
 const char HAIPProperty[] PROGMEM = {"cu"};

lib/home-assistant-integration/src/utils/HADictionary.h

@@ -36,6 +36,7 @@ extern const char HADeviceIdentifiersProperty[];
 extern const char HADeviceManufacturerProperty[];
 extern const char HADeviceModelProperty[];
 extern const char HAIPProperty[];
+extern const char HADeviceConfigurationUrlProperty[];
 extern const char HADeviceSoftwareVersionProperty[];
 extern const char HANameProperty[];
 extern const char HAUniqueIdProperty[];

platformio.ini

@@ -16,7 +16,6 @@ framework = arduino
 board_build.f_cpu = 240000000L
 upload_speed = 921600
 monitor_speed = 115200
-target_firm = env.ElfToHex(join("$BUILD_DIR", "${PROGNAME}"), target_elf)
 monitor_filters = esp32_exception_decoder
 lib_deps = 
 	bblanchon/ArduinoJson@^6.20.0

src/Apps.cpp

@@ -109,25 +109,27 @@ void TimeApp(FastLED_NeoMatrix *matrix, MatrixDisplayUiState *state, int16_t x,
     CURRENT_APP = "Time";
     currentCustomApp = "";
     const char *timeformat = getTimeFormat();
-    if (TIME_MODE == 5)
+    static File BIGTIME_BG_GIF;
+    static bool BIGTIME_BG_ISGIF = false;
+    if (BIGTIME_BG_GIF && TIME_MODE != 5)
     {
+        BIGTIME_BG_GIF.close();
 
+        BIGTIME_BG_ISGIF = false;
+    }
+    if (TIME_MODE == 5)
+    {
         char t[20];
         strftime(t, sizeof(t), timeformat, timer_localtime());
 
-        static bool BIGTIME_BG_CHECKED = false;
-        static bool BIGTIME_BG_ISGIF = false;
-        static File BIGTIME_BG_GIF;
         static uint16_t BIGTIME_BG_CURRENTFRAME = 0;
-        if (!BIGTIME_BG_CHECKED)
+        if (!BIGTIME_BG_ISGIF)
         {
             if (LittleFS.exists("/bigtime.gif"))
             {
                 BIGTIME_BG_GIF = LittleFS.open("/bigtime.gif");
                 BIGTIME_BG_ISGIF = true;
             }
-
-            BIGTIME_BG_CHECKED = true;
         }
 
         if (BIGTIME_BG_ISGIF)
@@ -477,7 +479,7 @@ void ShowCustomApp(String name, FastLED_NeoMatrix *matrix, MatrixDisplayUiState
                 ca->isGif = isGifFlags[i];
                 ca->icon = LittleFS.open(filePath);
                 ca->currentFrame = 0;
-                break; 
+                break;
             }
         }
     }