Merge remote-tracking branch 'origin/dev' into release-candidate

.github/workflows/docs.yml

@@ -0,0 +1,56 @@
+name: 'Generate documentation with Doxygen'
+
+on:
+  push:
+    branches:
+      - dev
+
+env:
+  TARGETS: f7
+  DEFAULT_TARGET: f7
+
+jobs:
+  doxygen:
+    if: ${{ !github.event.pull_request.head.repo.fork }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: 'Wipe workspace'
+        run: find ./ -mount -maxdepth 1 -exec rm -rf {} \;
+
+      - name: 'Checkout code'
+        uses: actions/checkout@v4
+        with:
+          submodules: true
+          fetch-depth: 1
+          ref: ${{ github.event.pull_request.head.sha }}
+
+      - name: 'Get commit details'
+        id: names
+        run: |
+          if [[ ${{ github.event_name }} == 'pull_request' ]]; then
+            TYPE="pull"
+          elif [[ "${{ github.ref }}" == "refs/tags/"* ]]; then
+            TYPE="tag"
+          else
+            TYPE="other"
+          fi
+          python3 scripts/get_env.py "--event_file=${{ github.event_path }}" "--type=$TYPE"
+
+      - name: 'Generate documentation'
+        uses: mattnotmitt/[email protected]
+        with:
+          working-directory: 'documentation/'
+          doxyfile-path: './doxygen/Doxyfile-awesome.cfg'
+
+      - name: 'Upload documentation'
+        uses: jakejarvis/[email protected]
+        env:
+          AWS_S3_BUCKET: "${{ secrets.FW_DOCS_AWS_BUCKET }}"
+          AWS_ACCESS_KEY_ID: "${{ secrets.FW_DOCS_AWS_ACCESS_KEY }}"
+          AWS_SECRET_ACCESS_KEY: "${{ secrets.FW_DOCS_AWS_SECRET_KEY }}"
+          AWS_REGION: "${{ secrets.FW_DOCS_AWS_REGION }}"
+          SOURCE_DIR: "./documentation/doxygen/build/html"
+          DEST_DIR: "${{steps.names.outputs.branch_name}}"
+        with:
+          args: "--delete"
+

.gitmodules

@@ -37,4 +37,7 @@
 	url = https://github.com/STMicroelectronics/stm32wbxx_hal_driver
 [submodule "lib/stm32wb_copro"]
 	path = lib/stm32wb_copro
-	url = https://github.com/flipperdevices/stm32wb_copro.git
+    url = https://github.com/flipperdevices/stm32wb_copro.git
+[submodule "documentation/doxygen/doxygen-awesome-css"]
+	path = documentation/doxygen/doxygen-awesome-css
+	url = https://github.com/jothepro/doxygen-awesome-css.git

.vscode/ReadMe.md

@@ -1,4 +1,4 @@
-# Visual Studio Code workspace for Flipper Zero
+# Visual Studio Code workspace for Flipper Zero {#vscode}
 
 ## Setup
 

ReadMe.md

@@ -11,14 +11,15 @@
 - [Flipper Zero Official Website](https://flipperzero.one). A simple way to explain to your friends what Flipper Zero can do.
 - [Flipper Zero Firmware Update](https://update.flipperzero.one). Improvements for your dolphin: latest firmware releases, upgrade tools for PC and mobile devices.
 - [User Documentation](https://docs.flipperzero.one). Learn more about your dolphin: specs, usage guides, and anything you want to ask.
+- [Developer Documentation](https://developer.flipper.net/flipperzero/doxygen). Dive into the Flipper Zero Firmware source code: build system, firmware structure, and more.
 
 # Contributing
 
 Our main goal is to build a healthy and sustainable community around Flipper, so we're open to any new ideas and contributions. We also have some rules and taboos here, so please read this page and our [Code of Conduct](/CODE_OF_CONDUCT.md) carefully.
 
 ## I need help
 
-The best place to search for answers is our [User Documentation](https://docs.flipperzero.one). If you can't find the answer there, check our [Discord Server](https://flipp.dev/discord) or our [Forum](https://forum.flipperzero.one/).
+The best place to search for answers is our [User Documentation](https://docs.flipperzero.one). If you can't find the answer there, check our [Discord Server](https://flipp.dev/discord) or our [Forum](https://forum.flipperzero.one/). If you want to contribute to the firmware development, or modify it for your own needs, you can also check our [Developer Documentation](https://developer.flipper.net/flipperzero/doxygen).
 
 ## I want to report an issue
 
@@ -95,7 +96,8 @@ Make sure your Flipper is on, and your firmware is functioning. Connect your Fli
 - [Hardware combos and Un-bricking](/documentation/KeyCombo.md) - recovering your Flipper from the most nasty situations
 - [Flipper File Formats](/documentation/file_formats) - everything about how Flipper stores your data and how you can work with it
 - [Universal Remotes](/documentation/UniversalRemotes.md) - contributing your infrared remote to the universal remote database
-- And much more in the [documentation](/documentation) folder
+- [Firmware Roadmap](/documentation/RoadMap.md)
+- And much more in the [Developer Documentation](https://developer.flipper.net/flipperzero/doxygen)
 
 # Project structure
 

applications/debug/unit_tests/datetimelib/datetimelib_test.c

@@ -112,7 +112,7 @@ MU_TEST_SUITE(test_datetime_validate_datetime) {
 
 MU_TEST(test_datetime_timestamp_to_datetime_min) {
     uint32_t test_value = 0;
-    DateTime min_datetime_expected = {0, 0, 0, 1, 1, 1970, 0};
+    DateTime min_datetime_expected = {0, 0, 0, 1, 1, 1970, 4};
 
     DateTime result = {0};
     datetime_timestamp_to_datetime(test_value, &result);
@@ -122,7 +122,7 @@ MU_TEST(test_datetime_timestamp_to_datetime_min) {
 
 MU_TEST(test_datetime_timestamp_to_datetime_max) {
     uint32_t test_value = UINT32_MAX;
-    DateTime max_datetime_expected = {6, 28, 15, 7, 2, 2106, 0};
+    DateTime max_datetime_expected = {6, 28, 15, 7, 2, 2106, 7};
 
     DateTime result = {0};
     datetime_timestamp_to_datetime(test_value, &result);
@@ -141,10 +141,26 @@ MU_TEST(test_datetime_timestamp_to_datetime_to_timestamp) {
     mu_assert_int_eq(test_value, result);
 }
 
+MU_TEST(test_datetime_timestamp_to_datetime_weekday) {
+    uint32_t test_value = 1709748421; // Wed Mar 06 18:07:01 2024 UTC
+
+    DateTime datetime = {0};
+    datetime_timestamp_to_datetime(test_value, &datetime);
+
+    mu_assert_int_eq(datetime.hour, 18);
+    mu_assert_int_eq(datetime.minute, 7);
+    mu_assert_int_eq(datetime.second, 1);
+    mu_assert_int_eq(datetime.day, 6);
+    mu_assert_int_eq(datetime.month, 3);
+    mu_assert_int_eq(datetime.weekday, 3);
+    mu_assert_int_eq(datetime.year, 2024);
+}
+
 MU_TEST_SUITE(test_datetime_timestamp_to_datetime_suite) {
     MU_RUN_TEST(test_datetime_timestamp_to_datetime_min);
     MU_RUN_TEST(test_datetime_timestamp_to_datetime_max);
     MU_RUN_TEST(test_datetime_timestamp_to_datetime_to_timestamp);
+    MU_RUN_TEST(test_datetime_timestamp_to_datetime_weekday);
 }
 
 MU_TEST(test_datetime_datetime_to_timestamp_min) {

applications/drivers/subghz/cc1101_ext/cc1101_ext.h

@@ -1,6 +1,6 @@
 /**
- * @file furi_hal_subghz.h
- * SubGhz HAL API
+ * @file cc1101_ext.h
+ * @brief External CC1101 transceiver access API.
  */
 
 #pragma once

applications/examples/example_apps_assets/README.md

@@ -1,7 +1,11 @@
-# Apps Assets folder Example
+# Apps Assets folder Example {#example_app_assets}
 
 This example shows how to use the Apps Assets folder to store data that is not part of the application itself, but is required for its operation, and that data is provided with the application.
 
+## Source code
+
+Source code for this example can be found [here](https://github.com/flipperdevices/flipperzero-firmware/tree/dev/applications/examples/example_apps_assets).
+
 ## What is the Apps Assets Folder?
 
 The **Apps Assets** folder is a folder where external applications unpack their assets.

applications/examples/example_apps_assets/example_apps_assets.c

@@ -1,3 +1,7 @@
+/**
+ * @file example_apps_assets.c
+ * @brief Application assets example.
+ */
 #include <furi.h>
 #include <storage/storage.h>
 #include <toolbox/stream/stream.h>

applications/examples/example_apps_data/README.md

@@ -1,7 +1,11 @@
-# Apps Data folder Example
+# Apps Data folder Example {#example_app_data}
 
 This example demonstrates how to utilize the Apps Data folder to store data that is not part of the app itself, such as user data, configuration files, and so forth.
 
+## Source code
+
+Source code for this example can be found [here](https://github.com/flipperdevices/flipperzero-firmware/tree/dev/applications/examples/example_apps_data).
+
 ## What is the Apps Data Folder?
 
 The **Apps Data** folder is a folder used to store data for external apps that are not part of the main firmware. 

applications/examples/example_apps_data/example_apps_data.c

@@ -1,3 +1,7 @@
+/**
+ * @file example_apps_data.c
+ * @brief Application data example.
+ */
 #include <furi.h>
 #include <storage/storage.h>
 

applications/examples/example_ble_beacon/ble_beacon_app.h

@@ -1,3 +1,7 @@
+/**
+ * @file ble_beacon_app.h
+ * @brief BLE beacon example.
+ */
 #pragma once
 
 #include "extra_beacon.h"

applications/examples/example_custom_font/example_custom_font.c

@@ -1,3 +1,7 @@
+/**
+ * @file example_custom_font.c
+ * @brief Custom font example.
+ */
 #include <furi.h>
 #include <furi_hal.h>
 

applications/examples/example_images/ReadMe.md

@@ -1,11 +1,21 @@
-# Application icons
+# Application icons {#example_app_images}
+
+## Source code
+
+Source code for this example can be found [here](https://github.com/flipperdevices/flipperzero-firmware/tree/dev/applications/examples/example_images).
+
+## General principle
+
 To use icons, do the following:
-* add a line to the application manifest: `fap_icon_assets="folder"`, where `folder` points to the folder where your icons are located
-* add `#include "application_id_icons.h"` to the application code, where `application_id` is the appid from the manifest
-* every icon in the folder will be available as a `I_icon_name` variable, where `icon_name` is the name of the icon file without the extension
+
+* Add a line to the application manifest: `fap_icon_assets="folder"`, where `folder` points to the folder where your icons are located
+* Add `#include "application_id_icons.h"` to the application code, where `application_id` is the appid from the manifest
+* Every icon in the folder will be available as a `I_icon_name` variable, where `icon_name` is the name of the icon file without the extension
 
 ## Example
+
 We have an application with the following manifest:
+
 ```
 App(
     appid="example_images",
@@ -17,6 +27,7 @@ App(
 So the icons are in the `images` folder and will be available in the generated `example_images_icons.h` file.
 
 The example code is located in `example_images_main.c` and contains the following line:
+
 ```
 #include "example_images_icons.h"
 ```

applications/examples/example_images/example_images.c

@@ -1,3 +1,7 @@
+/**
+ * @file example_images.c
+ * @brief Custom images example.
+ */
 #include <furi.h>
 #include <furi_hal.h>
 

applications/examples/example_plugins/example_plugins.c

@@ -1,5 +1,7 @@
-/* 
- * An example of a plugin host application.
+/**
+ * @file example_plugins.c
+ * @brief Plugin host application example.
+ *
  * Loads a single plugin and calls its methods.
  */
 

applications/examples/example_plugins/example_plugins_multi.c

@@ -1,5 +1,7 @@
-/*
- * An example of an advanced plugin host application.
+/**
+ * @file example_plugins_multi.c
+ * @brief Advanced plugin host application example.
+ *
  * It uses PluginManager to load all plugins from a directory
  */
 

applications/examples/example_plugins/plugin1.c

@@ -1,4 +1,9 @@
-/* A simple plugin implementing example_plugins application's plugin interface */
+/**
+ * @file plugin1.c
+ * @brief Plugin example 1.
+ *
+ * A simple plugin implementing example_plugins application's plugin interface
+ */
 
 #include "plugin_interface.h"
 

applications/examples/example_plugins/plugin2.c

@@ -1,4 +1,9 @@
-/* Second plugin implementing example_plugins application's plugin interface */
+/**
+ * @file plugin2.c
+ * @brief Plugin example 2.
+ *
+ * Second plugin implementing example_plugins application's plugin interface
+ */
 
 #include "plugin_interface.h"
 

applications/examples/example_plugins/plugin_interface.h

@@ -1,7 +1,11 @@
+/**
+ * @file plugin_interface.h
+ * @brief Example plugin interface.
+ *
+ * Common interface between a plugin and host application
+ */
 #pragma once
 
-/* Common interface between a plugin and host application */
-
 #define PLUGIN_APP_ID "example_plugins"
 #define PLUGIN_API_VERSION 1
 

applications/examples/example_plugins_advanced/app_api.h

@@ -1,9 +1,12 @@
-#pragma once
-
-/* 
+/**
+ * @file app_api.h
+ * @brief Application API example.
+ *
  * This file contains an API that is internally implemented by the application
  * It is also exposed to plugins to allow them to use the application's API.
  */
+#pragma once
+
 #include <stdint.h>
 
 #ifdef __cplusplus

applications/examples/example_plugins_advanced/plugin1.c

@@ -1,4 +1,7 @@
-/*
+/**
+ * @file plugin1.c
+ * @brief Plugin example 1.
+ *
  * This plugin uses both firmware's API interface and private application headers.
  * It can be loaded by a plugin manager that uses CompoundApiInterface,
  * which combines both interfaces.

applications/examples/example_plugins_advanced/plugin2.c

@@ -1,4 +1,7 @@
-/*
+/**
+ * @file plugin2.c
+ * @brief Plugin example 2.
+ *
  * This plugin uses both firmware's API interface and private application headers.
  * It can be loaded by a plugin manager that uses CompoundApiInterface,
  * which combines both interfaces.

applications/examples/example_plugins_advanced/plugin_interface.h

@@ -1,7 +1,11 @@
+/**
+ * @file plugin_interface.h
+ * @brief Example plugin interface.
+ *
+ * Common interface between a plugin and host application
+ */
 #pragma once
 
-/* Common interface between a plugin and host application */
-
 #define PLUGIN_APP_ID "example_plugins_advanced"
 #define PLUGIN_API_VERSION 1
 

applications/examples/example_thermo/README.md

@@ -1,8 +1,14 @@
-# 1-Wire Thermometer
+# 1-Wire Thermometer {#example_thermo}
+
 This example application demonstrates the use of the 1-Wire library with a DS18B20 thermometer. 
 It also covers basic GUI, input handling, threads and localisation.
 
+## Source code
+
+Source code for this example can be found [here](https://github.com/flipperdevices/flipperzero-firmware/tree/dev/applications/examples/example_thermo).
+
 ## Electrical connections
+
 Before launching the application, connect the sensor to Flipper's external GPIO according to the table below:
 | DS18B20 | Flipper |
 | :-----: | :-----: |
@@ -15,12 +21,14 @@ Before launching the application, connect the sensor to Flipper's external GPIO
 *NOTE 2*: For any other pin than 17, connect an external 4.7k pull-up resistor to pin 9.
 
 ## Launching the application
+
 In order to launch this demo, follow the steps below:
 1. Make sure your Flipper has an SD card installed.
 2. Connect your Flipper to the computer via a USB cable.
 3. Run `./fbt launch APPSRC=example_thermo` in your terminal emulator of choice.
 
 ## Changing the data pin
+
 It is possible to use other GPIO pin as a 1-Wire data pin. In order to change it, set the `THERMO_GPIO_PIN` macro to any of the options listed below:
 
 ```c

applications/examples/example_thermo/example_thermo.c

@@ -1,4 +1,7 @@
-/*
+/**
+ * @file example_thermo.c
+ * @brief 1-Wire thermometer example.
+ *
  * This file contains an example application that reads and displays
  * the temperature from a DS18B20 1-wire thermometer.
  *