Merge branch 'develop' into master

.github/workflows/test-EMULATOR.yml

@@ -31,10 +31,13 @@ jobs:
       uses: nschloe/[email protected]
       with:
         submodules: recursive
+        lfs: 'true'
     - name: Update packages
-      run: sudo apt-get update && sudo apt-get upgrade -y
+      run: sudo apt-get update
     - name: Install packages
-      run: sudo apt-get -y install gcc g++ cmake libsdl2-dev libsdl2-image-dev
+      run: sudo apt-get -y install gcc g++ cmake libsdl2-dev libsdl2-image-dev python3 python3-pip
+    - name: Install python packages
+      run: pip3 install --user -r scripts/requirements.txt
     - name: Create build directory
       run: mkdir build
     - name: CMake ${{ matrix.build-configuration }}

.github/workflows/test-FEATURE.yml

@@ -28,6 +28,7 @@ jobs:
         uses: nschloe/[email protected]
         with:
           submodules: recursive
+          lfs: 'true'
       - id: get-flag
         run: |
           echo "feature=$(python3 .github/getWorkflowMatrix.py all_flags)" >> $GITHUB_OUTPUT
@@ -56,6 +57,7 @@ jobs:
       uses: nschloe/[email protected]
       with:
         submodules: recursive
+        lfs: 'true'
     - name: Cache pip
       uses: actions/cache@v3
       with:

.github/workflows/test-OS.yml

@@ -15,6 +15,7 @@ jobs:
         uses: nschloe/[email protected]
         with:
           submodules: recursive
+          lfs: 'true'
       - uses: dorny/[email protected]
         id: filter
         with:
@@ -49,6 +50,7 @@ jobs:
       uses: nschloe/[email protected]
       with:
         submodules: recursive
+        lfs: 'true'
     - name: Cache pip
       uses: actions/cache@v3
       with:

.github/workflows/test-OSW.yml

@@ -29,6 +29,7 @@ jobs:
         uses: nschloe/[email protected]
         with:
           submodules: recursive
+          lfs: 'true'
       - uses: dorny/[email protected]
         id: filter
         with:
@@ -62,6 +63,7 @@ jobs:
       uses: nschloe/[email protected]
       with:
         submodules: recursive
+        lfs: 'true'
     - name: Cache pip
       uses: actions/cache@v3
       with:

.gitmodules

@@ -38,4 +38,7 @@
 [submodule "lib/open-smartwatch-web"]
 	path = lib/open-smartwatch-web
 	url = https://github.com/Open-Smartwatch/open-smartwatch-web.git
-	branch = dist
+	branch = dist
+[submodule "emulator/lib/ImGUI_TestEngine"]
+	path = emulator/lib/ImGUI_TestEngine
+	url = https://github.com/ocornut/imgui_test_engine.git

CMakeLists.txt

@@ -1,4 +1,4 @@
-cmake_minimum_required (VERSION 3.10)
+cmake_minimum_required (VERSION 3.12)
 project (OSW-OS-Emulator)
 
 set(CMAKE_CXX_STANDARD 20)
@@ -46,8 +46,8 @@ add_library(ImGUI
     emulator/lib/ImGUI/imgui_draw.cpp
     emulator/lib/ImGUI/imgui_widgets.cpp
     emulator/lib/ImGUI/imgui_tables.cpp
-    emulator/lib/ImGUI/backends/imgui_impl_sdl.cpp
-    emulator/lib/ImGUI/backends/imgui_impl_sdlrenderer.cpp
+    emulator/lib/ImGUI/backends/imgui_impl_sdl2.cpp
+    emulator/lib/ImGUI/backends/imgui_impl_sdlrenderer2.cpp
     emulator/lib/ImGUI/misc/cpp/imgui_stdlib.cpp
 )
 target_include_directories(ImGUI PUBLIC
@@ -60,13 +60,50 @@ target_link_libraries(ImGUI LINK_PUBLIC
     ${SDL2IMAGE_LIBRARIES}
 )
 
+# ImGUI testing engine
+add_library(ImGUI_TestEngine
+    emulator/lib/ImGUI_TestEngine/imgui_test_engine/imgui_te_engine.cpp
+    emulator/lib/ImGUI_TestEngine/imgui_test_engine/imgui_capture_tool.cpp
+    emulator/lib/ImGUI_TestEngine/imgui_test_engine/imgui_te_context.cpp
+    emulator/lib/ImGUI_TestEngine/imgui_test_engine/imgui_te_coroutine.cpp
+    emulator/lib/ImGUI_TestEngine/imgui_test_engine/imgui_te_exporters.cpp
+    emulator/lib/ImGUI_TestEngine/imgui_test_engine/imgui_te_perftool.cpp
+    emulator/lib/ImGUI_TestEngine/imgui_test_engine/imgui_te_ui.cpp
+    emulator/lib/ImGUI_TestEngine/imgui_test_engine/imgui_te_utils.cpp
+
+)
+target_include_directories(ImGUI_TestEngine PUBLIC
+    emulator/lib/ImGUI_TestEngine/imgui_test_engine/
+)
+target_link_libraries(ImGUI_TestEngine LINK_PUBLIC
+    ImGUI
+)
+add_compile_definitions(
+  IMGUI_ENABLE_TEST_ENGINE=1
+  IMGUI_TEST_ENGINE_ENABLE_COROUTINE_STDTHREAD_IMPL=1
+)
+
+# OSW custom prebuild-scripts
+find_package(Python3 REQUIRED COMPONENTS Interpreter)
+file(GLOB_RECURSE INCLUDE_OSW_ASSETS ./include/assets/img/** ./include/assets/www/**)
+add_custom_target(
+    osw_script_prebuild_assets ALL
+    WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
+    COMMAND ${PYTHON_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/scripts/build/prebuild_assets.py --output-asset-path ${CMAKE_CURRENT_SOURCE_DIR}/include/assets
+    BYPRODUCTS ${INCLUDE_OSW_ASSETS}
+    COMMENT "Generating OSW assets..."
+)
+
 # Emulator
 file(GLOB_RECURSE SOURCES_OSW ./src/*.cpp)
 file(GLOB_RECURSE SOURCES_OSW_EMULATOR ./emulator/src/*.cpp)
 add_executable(emulator.run
     ${SOURCES_OSW}
     ${SOURCES_OSW_EMULATOR}
 )
+add_dependencies(emulator.run
+    osw_script_prebuild_assets
+)
 target_include_directories(emulator.run PUBLIC
     ./emulator/include
     ./include
@@ -83,6 +120,7 @@ target_link_libraries(emulator.run LINK_PUBLIC
     ${SDL2_LIBRARY}
     ${SDL2IMAGE_LIBRARIES}
     ImGUI
+    ImGUI_TestEngine
     cmdline
     utest
 )
@@ -99,8 +137,11 @@ target_compile_definitions(emulator.run PUBLIC
     $<$<CONFIG:Release>:
       NDEBUG=1
     >
+    # Uncomment the following line to use a different locale (only for the emulator, for the whole OS use the config variable!)
+    # LOCALE="locales/en-US.h"
     # Comment these as you wish...
     OSW_FEATURE_STATS_STEPS
+    OSW_APPS_EXAMPLES=1
     GAME_SNAKE=1
     GAME_BRICK_BREAKER=1
     TOOL_FLASHLIGHT=1

CONTRIBUTING.md

@@ -1,26 +1,26 @@
 # How to contribute to Open-smartwatch
 
-In case the `develop` branch is ahead of the `master` branch and the `develop` branch is stabile enough, we periodically merge it into the `master`.
+In case the `develop` branch is ahead of the `master` branch and the `develop` branch is stable enough, we periodically merge it into the `master`.
 
 In order to contribute new or updated documentation, you must first create a GitHub account and fork the original repository to your own account. You can make changes, save them in your repository and then create a pull request against this repository.
 
 Unless you are opening a pull request which only makes small corrections (for instance correcting a typo), you are more likely to get traction for your changes if you open an issue first to discuss the proposed changes. 
 
-**IMPORTANT** If you want to create a pull request, please work based on the `develop` branch - so we don't have to rebase it...
+**IMPORTANT** If you want to create a pull request, please work based on the most recent `develop` branch - so we don't have to rebase it...
 
 If you are reading this page, you are possibly interested in contributing to our project 😄 . We have an active (and friendly) developer group and would love to get your help! Some common ways you can support us are:
 
 * Testing the code
-* Filing issues on GitHub, if you see a problem (or adding detail to existing issues that effect you)
+* Reporting issues on GitHub, if you see a problem (or adding detail to existing issues that also affect you)
 * Fixing issues 😁
 * Adding new features
-* Reviewing existing pull requests and possibly also contributing to them.
-* Translation. Always a good idea...
+* Reviewing existing pull requests and possibly also contributing to them
+* Translations are always a good idea...
 
 ## How to make a good bug report
 
 Submit according to the bug report form. Attach the debug log if necessary. [Read more here!](https://open-smartwatch.github.io/howto/contribute/#how-to-open-an-issue)
 
 ## Submitting patches
 
-Please also see our [wiki](https://open-smartwatch.github.io/howto/contribute/) article for that.
+Please also see our [wiki](https://open-smartwatch.github.io/howto/contribute/) article for that.

README.md

@@ -147,5 +147,28 @@ $ docker run --net=host -e DISPLAY -v /tmp/.X11-unix -d --name OSW -p 22:22 -it
 $ xauth add <'xauth list' command result>
 ```
 
+## Testing
+After making some changes to the code, you should test the application by running our unit and UI tests. 
+
+Note: our tests do not cover 100% of the application. If you want to see which parts are covered by tests take a look at `emulator/src/unitTests` and `emulator/src/uiTests`.
+
+### Unit tests
+Run all unit tests:
+```bash
+$ ./emulator.run --unit_tests
+``` 
+List all unit tests, one per line:
+```bash
+$ ./emulator.run --list_tests
+```
+
+### UI tests
+Run the emulator with UI tests window:
+```bash
+$ ./emulator.run --ui_tests
+```
+
+***IMPORTANT**: If you add some new features, it is strongly recommended to write unit and UI tests for them.*
+
 ## License
 Everything in this repository is under a GPL-3.0 license, see [here](./LICENSE) for more details.

docs/firmware/getting_started.md

@@ -2,6 +2,9 @@
 
 This page describes which software you'll need and how to manually flash the firmware.
 
+!!! note "Tip"
+    In case you won't or can't compile the (latest) firmware yourself, you can download the latest pre-compiled firmware from the [releases page](https://github.com/Open-Smartwatch/open-smartwatch-os/releases) (in case we did not forget to upload it there). In case you want to take a look into what is coming with the next release, checkout the [GitHub Actions](https://github.com/Open-Smartwatch/open-smartwatch-os/actions) (you have to login to download anything). To then flash the firmware to the watch use something like the [ESPHome Flasher](https://github.com/esphome/esphome-flasher), be aware that this flasher will also erase the watches memory every time! An alternative (although not tested) would be the [NodeMCU Flasher](https://github.com/marcelstoer/nodemcu-pyflasher).
+
 ## Required Software
 
 - [GIT](https://git-scm.com)
@@ -39,7 +42,10 @@ If you have cloned the repo without the recurse option, run `git submodule updat
 
 !!! note "Tip"
     After changing or updating/pulling a branch, run the command again to also update dependencies:
-    `git submodule update`
+    ```bash
+    git pull
+    git submodule update --init --recursive
+    ```
 
 Then, open the directory with Visual Studio Code.
 

docs/firmware/troubleshooting.md

@@ -13,8 +13,11 @@ Check the driver insertion.
 You did not clone the repository with the `--recursive-submodules` flag.
 
 !!! note "Tip"
-    After changing the branch, follow the command :
-    `git submodule update`
+    After changing or updating/pulling a branch, run the command again to also update dependencies:
+    ```bash
+    git pull
+    git submodule update --init --recursive
+    ```
 
 ## Failed to connect to ESP32: Timed out waiting for packet header
 

emulator/include/Emulator.hpp

@@ -8,6 +8,8 @@
 #include <variant>
 #include <list>
 #include <map>
+#include <hal/buttons.h>
+#include <osw_pins.h> // for button definitions
 
 #include "Jzon.h"
 
@@ -46,8 +48,8 @@ class OswEmulator {
     void run();
     void exit();
 
-    void setButton(unsigned id, bool state);
-    bool getButton(unsigned id);
+    void setButton(Button id, bool state);
+    bool getButton(Button id);
     uint8_t getBatteryRaw();
     bool isCharging();
 
@@ -67,8 +69,8 @@ class OswEmulator {
     SDL_Surface* mainSurface = nullptr; // Only used in headless mode
     SDL_Renderer* mainRenderer = nullptr;
     std::atomic_bool running = true;
-    std::array<std::atomic_bool, 3> buttons; // TODO This length should come from the platform itself!
-    std::array<bool, 3> buttonCheckboxes = { false, false, false }; // These are just state caches of the buttons for their respective checkboxes!
+    std::array<std::atomic_bool, BTN_NUMBER> buttons;
+    std::array<bool, BTN_NUMBER> buttonCheckboxes; // These are just state caches of the buttons for their respective checkboxes!
     bool buttonResetAfterMultiPress = true;
     uint8_t batRaw = 0;
     bool charging = true;
@@ -100,4 +102,8 @@ class OswEmulator {
     void doCleanup();
     void renderGUIFrameEmulator();
     void addGUIHelp(const char* msg);
+
+    // For UI Tests (to access and test private members)
+    // Note: such friend classes are the only changes in production code related to testing
+    friend class TestEmulator;
 };

emulator/include/RtcDS3231.h

@@ -13,7 +13,7 @@ class RtcDateTime {
     RtcDateTime() {};
     virtual ~RtcDateTime() {};
 
-    void InitWithEpoch32Time(time_t time);
+    void InitWithUnix32Time(time_t time);
 
     uint32_t Hour();
     uint32_t Minute();