v0.17.0 🎉 (#407)

.github/getWorkflowMatrix.py

@@ -33,9 +33,10 @@ def get(info: GettableInfo):
                     returnArray.add(line.split('=')[1].strip())
                     break
     elif info == GettableInfo.FLAGS:
-        with open('docs/firmware/osw_os.md') as f:
+        with open('docs/firmware/flags.md') as f:
             for line in f:
-                match = re.match(r'^`(.+)` \| .+ \| (.+)$', line)
+                # this parses a row with the format: "| `flag` | description | requirements |"
+                match = re.match(r'^\| `(.+)`\s+\| .+ \| (.+) \|$', line)
                 if match is None:
                     continue
                 feature = match.group(1).strip()
@@ -75,4 +76,4 @@ def get(info: GettableInfo):
     ap.add_argument('info', type=GettableInfo)
     args = ap.parse_args()
 
-    print(json.dumps(list(get(args.info))))
+    print(json.dumps(list(get(args.info))))

.github/workflows/test-OSW.yml

@@ -88,5 +88,22 @@ jobs:
         uses: actions/upload-artifact@v3
         with:
           name: firmwares
-          path: |
-            *.bin
+          path: "*.bin"
+
+  # do this last step seperately to avoid race conditions with firmware upload
+  create-release:
+    runs-on: ubuntu-latest
+    needs: build-OSW
+    if: startsWith(github.ref, 'refs/tags/v')
+    steps:
+      - uses: actions/download-artifact@v3
+        with:
+          pattern: "*.bin"
+          merge-multiple: true
+      - name: Create release and upload firmware to it
+        uses: softprops/action-gh-release@v2
+        with:
+          files: "firmwares/*.bin"
+          draft: true
+          prerelease: true
+          generate_release_notes: true

.gitignore

@@ -1,5 +1,5 @@
 .pio
-.vscode
+/.vscode/*.json
 .DS_Store
 screenshots
 /build

.gitmodules

@@ -20,6 +20,9 @@
 	path = lib/LUA
 	url = https://github.com/lua/lua.git
 	branch = v5.3
+[submodule "lib/BMI270-API"]
+	path = lib/BMI270-API
+	url = https://github.com/Open-Smartwatch/BMI270-Sensor-API.git
 [submodule "emulator/lib/ArduinoJson"]
 	path = emulator/lib/ArduinoJson
 	url = https://github.com/bblanchon/ArduinoJson.git
@@ -42,3 +45,6 @@
 [submodule "emulator/lib/ImGUI_TestEngine"]
 	path = emulator/lib/ImGUI_TestEngine
 	url = https://github.com/ocornut/imgui_test_engine.git
+[submodule "lib/BMP581-API"]
+	path = lib/BMP581-API
+	url = https://github.com/boschsensortec/BMP5-Sensor-API.git

README.md

@@ -6,15 +6,19 @@
 
 1. Install [PlatformIO Core](https://docs.platformio.org/en/latest/core/installation.html) or [PlatformIO IDE](https://docs.platformio.org/en/latest/integration/ide/vscode.html#ide-vscode) (which installs PlatformIO core automatically), as well as the packages specified in `scripts/requirements.txt` (e.g. `pip install -r scripts/requirements.txt`).
 2. **For LUA-scripting support (see env:LIGHT_EDITION_DEV_LUA)**: Install [SWIG](http://www.swig.org/Doc4.0/SWIGDocumentation.html#Preface_installation) (also available in most package managers, e.g. `brew install swig` or `apt install swig`)
-3. Then clone this repository:
+3. **As this repository contains binary data (e.g. schematics or images), make sure to have `git-lfs` installed!** Cloning this repository without `git-lfs` will result in missing or broken files.
+4. Then clone this repository:
     ```bash
     $ git clone --recurse-submodules https://github.com/Open-Smartwatch/open-smartwatch-os.git
     ```
-    **As this repository contains binary data (e.g. schematics or images), make sure to have `git-lfs` installed!** Cloning this repository without `git-lfs` will result in missing or broken files.
-4. To update the sources later on, run:
+5. To update the sources / packages later on, run:
     ```bash
+    # pull new changes and update submodules
     $ git pull
-    $ git submodule update --init --recursive
+    $ git submodule sync # make sure to propagate origin-changes
+    $ git submodule update --init --recursive # update / create theis commits
+    # update the PlatformIO packages
+    $ pio pkg update # use the small terminal-icon in the bottom left corner of VSCode
     ```
 
 ## Build
@@ -36,7 +40,7 @@ Open the cloned repo in VSCode:
 $ code open-smartwatch-os
 ```
 
-You may rename the file `include/config.h.example` to `include/config.h` and adapt the values according to your requirements. That config is *only applied once* after you wiped the flash of the watch or changed the config-version numer in `osw_config.h` (...).
+You may rename the file `include/config.h.example` to `include/config.h` and adapt the values according to your requirements. That config is *only applied once* after you wiped the flash of the watch or changed the config-version number in `osw_config.h` (...).
 
 ### CLI
 
@@ -145,6 +149,10 @@ $ ./emulator.run
 
 You also may extend the `cmake`-command with `-DCMAKE_BUILD_TYPE=Release` to get an even faster and smaller binary.
 
+#### Debugging with VSCode
+
+Take alook into the `.vscode` folder - there should be a `launch.json.sample` file. Copy it to `launch.json` and adjust the paths (if you are using Windows) to your needs. Then you can start debugging the emulator with VSCode via "Run and Debug".
+
 ### With Docker
 If a library is unavailable, you can still use the emulator using docker (e.g. on Ubuntu 20.04 SDL2 is too old). Proceed with a typical docker installation. Showing an application running in docker requires some additional steps:
 

docs/config.yml

@@ -1,11 +1,12 @@
 # This file is similar to the mkdocs.nav configuration option, but it will be mounted under mkdocs.nav.Firmware only!
 
-- 'OSW-OS':
-  - firmware/getting_started.md
-  - firmware/osw_os.md
-  - firmware/troubleshooting.md
-- 'Applications':
-  - 'Watchfaces': 'firmware/apps/watchfaces.md'
-  - 'Tools': 'firmware/apps/tools.md'
-  - 'Games': 'firmware/apps/games.md'
-  - 'OSW Weather': 'firmware/apps/OswWeather.md'
+- "OSW-OS":
+    - firmware/getting_started.md
+    - firmware/flags.md
+    - firmware/troubleshooting.md
+    - firmware/support.md
+- "Applications":
+    - "Watchfaces": "firmware/apps/watchfaces.md"
+    - "Tools": "firmware/apps/tools.md"
+    - "Games": "firmware/apps/games.md"
+    - "OSW Weather": "firmware/apps/OswWeather.md"

docs/firmware/apps/OswWeather.md

@@ -6,9 +6,9 @@ Author: [@LorenzoSciacca](https://github.com/Lorenzosciacca)
 Add the flag `OSW_FEATURE_WEATHER` to the file `platformio.ini`:
 ```ini
 ; Example code block (make sure to use the one from the platformio config!)
-[env:LIGHT_EDITION_V3_2]
+[env:LIGHT_EDITION_V3_3]
 build_flags =
-	-D OSW_TARGET_PLATFORM_HEADER='"platform/LIGHT_EDITION_V3_2.h"'
+	-D OSW_TARGET_PLATFORM_HEADER='"platform/LIGHT_EDITION_V3_3.h"'
 	-D OSW_FEATURE_STATS_STEPS
 	-D OSW_FEATURE_WIFI ; ADD THIS LINE
 build_type = debug
@@ -32,7 +32,7 @@ It's possible to configure the app from both the web UI and the configuration fi
 4. Save
 
 ### Without web UI
-If you want to configure the app without using the web UI you can set the followings values in config_defaults.h:
+If you want to configure the app without using the web UI you can set the following values in config_defaults.h:
 - `OPENWEATHERMAP_APIKEY`, the api key
 - `OPENWEATHERMAP_CITY`, city name
 - `OPENWEATHERMAP__STATE_CODE`, the two letter iso code of the country of your interest
@@ -170,7 +170,7 @@ Visit [this link](https://openweathermap.org/weather-conditions#Weather-Conditio
 </table>
 
 ## Using the emulator
-To use this app while using the OSW emulator, in order to retireve the data, it is necessary to perform the API request using the browser and to save the response in `file_weather.json` in the  `/build` folder.
+To use this app while using the OSW emulator, in order to retrieve the data, it is necessary to perform the API request using the browser and to save the response in `file_weather.json` in the  `/build` folder.
 
 
 

docs/firmware/apps/watchfaces.md

@@ -81,7 +81,7 @@ Steps are shown as a hexadecimal number at side of the screen.
 <img src="/assets/apps/watchfaces/watchface_monotimer_osw.png" width="256px" style="float:left; margin-right:20px"/>
 The default Monotimer watchface.
 
-Since a monotimer-clock has only a single hand, you read both the hours and minutes from the position of it. First, you read the hours by finding the nearest hour from the left (clockwise) of the hand. Then you read the Minutes by looking at the ticks between the hour tick and the hand. The smallest tick stands for a 5 minute intervall, the next bigger one for 15 minutes and the biggest one for 30 minutes (see image). For example, the clock from the image shows the time between 9:25 and 9:30.
+Since a monotimer-clock has only a single hand, you read both the hours and minutes from the position of it. First, you read the hours by finding the nearest hour from the left (clockwise) of the hand. Then you read the Minutes by looking at the ticks between the hour tick and the hand. The smallest tick stands for a 5 minute interval, the next bigger one for 15 minutes and the biggest one for 30 minutes (see image). For example, the clock from the image shows the time between 9:25 and 9:30.
 
 The steps are displayed in the center of the clock. If the daily step goal is reached, the text color changes from InfoColor to SucessColor.
 

docs/firmware/flags.md

@@ -0,0 +1,46 @@
+# Feature Flags
+The table below list all currently available features of the OSW-OS. These features can be manually enabled (or disabled) by modifying the `platformio.ini` and adding (or removing) their `-D`-Define lines.
+
+| Flag                         | Description                                                                          | Requirements                       |
+| ---------------------------- | ------------------------------------------------------------------------------------ | ---------------------------------- |
+| `OSW_FEATURE_STATS_STEPS`    | Enable step history (displayed on the watchfaces)                                    | -                                  |
+| `OSW_FEATURE_WIFI`           | Enable all wifi related functions (services, webinterface)                           | -                                  |
+| `OSW_FEATURE_WIFI_ONBOOT`    | Allow the user to enable the wifi on boot                                            | `OSW_FEATURE_WIFI`                 |
+| `OSW_FEATURE_BLE_MEDIA_CTRL` | Enables media control via BLE                                                        | -                                  |
+| `OSW_FEATURE_LUA`            | Enable LUA scripting support for apps                                                | `LUA_C89_NUMBERS`                  |
+| `SERVICE_BLE_COMPANION=1`    | Enables the BLE Companion Service (unstable, requires custom smartphone application) | -                                  |
+| `DEBUG=1`                    | Enables debug logging to the console & additional utilities                          | -                                  |
+| `GPS_EDITION`                | Configure the build for use with GPS (including apps, api, sensors)                  | `PROGMEM_TILES`, `BOARD_HAS_PSRAM` |
+| `GPS_EDITION_ROTATED`        | Replacement for `GPS_EDITION` to work with flipped boards                            | -                                  |
+
+## Example Flags
+
+You want to know how to use some example code or see it in action? These flags enable various features that are not enabled by default - just search inside the source code for the flag to see how it works and what it does.
+
+| Flag                  | Description                                                           | Requirements |
+| --------------------- | --------------------------------------------------------------------- | ------------ |
+| `OSW_SERVICE_EXAMPLE` | Enable the example code to demonstrate how to write on services.      | -            |
+| `OSW_APPS_EXAMPLES`   | Enable the example code to demonstrate how to write own apps (v1/v2). | -            |
+
+## Experimental Flags
+
+These flags should be available on all models. Because they are experimental, they are not enabled by default any may won't work or even compile.
+
+| Flag                         | Description                                                                                                                                                                                                                                             | Requirements       |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ |
+| `RAW_SCREEN_SERVER`          | Capture the watchface and save it as a `*.png` file.                                                                                                                                                                                                    | `OSW_FEATURE_WIFI` |
+| `ANIMATION`                  | Animation can be used as the background of the watchface.                                                                                                                                                                                               | -                  |
+| `OSW_FEATURE_BLE_MEDIA_CTRL` | See `OswAppBLEMediaCtrl.cpp` a tech demo to use the OSW as an external keyboard. OSW Light `v3.x` has insufficient memory, <br>`OswHal::getInstance()->disableDisplayBuffer()` is called to free memory <br>but slows down redraw speeds significantly. | -                  |
+| `OSW_FEATURE_WEATHER`        | You can monitor the weather through an OpenWeatherAPI.                                                                                                                                                                                                  | `OSW_FEATURE_WIFI` |
+| `GIF_BG`                     | Enable GIF support for the background of some watchfaces.                                                                                                                                                                                               | -                  |
+
+## Supported Flags per Device
+The table below lists which features are available in which version of the OS by default. It is always our goal to also support older hardware revisions, but not all features can run properly using the old schematics.
+
+| Flag                      | `LIGHT_EDITION_V4_0` | `LIGHT_EDITION_V3_3` | `LIGHT_EDITION_DEV_LUA` | `GPS_EDITION_V3_1` | `GPS_EDITION_DEV_ROTATED` |
+| ------------------------- | -------------------- | -------------------- | ----------------------- | ------------------ | ------------------------- |
+| `OSW_FEATURE_STATS_STEPS` | ✓                    | ✓                    | ❌                       | ✓                  | ✓                         |
+| `OSW_FEATURE_WIFI`        | ✓                    | ✓                    | ❌                       | ✓                  | ✓                         |
+| `OSW_FEATURE_WIFI_APST`   | ❌                    | ❌                    | ❌                       | ✓                  | ✓                         |
+| `OSW_FEATURE_WIFI_ONBOOT` | ✓                    | ❌                    | ❌                       | ✓                  | ✓                         |
+| `OSW_FEATURE_LUA`         | ❌                    | ❌                    | ✓                       | ❌                  | ❌                         |

docs/firmware/getting_started.md

@@ -28,6 +28,9 @@ The following Youtube tutorial will guide you through this step: [https://youtu.
 
 ### USB Serial Drivers for WCH340E
 
+!!! note "Tip"
+    Most Linux distributions already have the drivers shipped with the kernel, so you don't need to install them manually. In newer Ubuntu versions you may need to uninstall the `brltty` package to get the serial port working.
+
 The Open-Smartwatch uses a `WCH340E` USB to serial controller. If your device is not detected as `COM?` or `/dev/cu.usbserial-?` or similar, please install the drivers from the manufacturer: [http://www.wch-ic.com/downloads/CH341SER_ZIP.html](http://www.wch-ic.com/downloads/CH341SER_ZIP.html)
 
 Please also see the trouble shooting section below if your device is not connected.
@@ -38,14 +41,10 @@ Open git bash in your desired folder and clone the source code repository **recu
 
     git clone --recurse-submodules https://github.com/Open-Smartwatch/open-smartwatch-os.git
 
-If you have cloned the repo without the recurse option, run `git submodule update`.
+If you have cloned the repo without the recurse option, run `git submodule update --init`.
 
 !!! note "Tip"
-    After changing or updating/pulling a branch, run the command again to also update dependencies:
-    ```bash
-    git pull
-    git submodule update --init --recursive
-    ```
+    After changing or updating/pulling a branch, run the commands notes inside the `README.md` to update the submodules and the PlatformIO packages.
 
 Then, open the directory with Visual Studio Code.
 
@@ -68,4 +67,4 @@ Generally, you won't need to worry about GPIO assignment and initialisation as t
 
 **Keep in mind the PCB is flipped when inserted into the watch, EN/Reset is at the top left in this case:**
 
-<img src="/assets/uploading.jpg" width="512px"/>
+<img src="/assets/uploading.jpg" width="512px"/>