Update docs

ThomasFarstrike · ThomasFarstrike · commit 2564e0ba218c · 2026-07-02T11:09:54.000+02:00
diff --git a/docs/apps/appstore.md b/docs/apps/appstore.md
@@ -2,14 +2,25 @@
 
 The MicroPythonOS App Store allows users to download and install new apps to extend system functionality.
 
-App discovery is currently done by downloading the app list from [apps.micropythonos.com](https://apps.micropythonos.com).
+## Backends
+
+The AppStore app can pull apps from more than one source:
+
+- **BadgeHub.eu** — the community appstore for event badges and community-built apps at [badgehub.eu](https://badgehub.eu). On supported firmware builds this is the default backend. See [BadgeHub Apps](badgehub.md) for details on publishing there.
+- **MicroPythonOS Apps** — the curated, manually reviewed app index at [apps.micropythonos.com](https://apps.micropythonos.com).
+
+Use the backend selector in the AppStore UI to switch between sources.
 
 ## Example Apps
 
 - **Hello World**: A sample app demonstrating basic functionality.
 - **Camera**: Captures images and scans QR codes.
 - **Image Viewer**: Displays images stored in `/data/images/`.
-- **IMU**: Visualize data from the Intertial Measurement Unit, also known as the accellerometer.
+- **IMU**: Visualize data from the Inertial Measurement Unit, also known as the accelerometer.
+- **Nostr**: A decentralized chat client using the Nostr protocol, shipped as a Python package.
+- **Sorter**: A puzzle game where you sort items into the right bins.
+- **The Free Lantern Player**: A media player app.
+- **Breakout**: A classic brick-breaking game that uses a native C extension module.
 
 ## Image Viewer
 
@@ -34,4 +45,4 @@ The **Image Viewer** app displays images stored in `/data/images/`. See [Support
 
 ## Developing Apps
 
-Apps are written in MicroPython and installed in `/apps/`. See [Filesystem Layout](../architecture/filesystem.md) for the app directory structure.
+Apps are written in MicroPython and installed in `/apps/`. See [Filesystem Layout](../architecture/filesystem.md) for the app directory structure, [Bundling Apps](bundling-apps.md) for packaging, and [Native C/C++ Apps](native-apps.md) for apps that need compiled extensions.
diff --git a/docs/apps/badgehub.md b/docs/apps/badgehub.md
@@ -0,0 +1,54 @@
+# BadgeHub.eu Apps
+
+[BadgeHub.eu](https://badgehub.eu) is a community appstore for event badges and MicroPythonOS devices. MicroPythonOS ships with a BadgeHub backend in the AppStore app, so users can browse, install, and update BadgeHub-published apps directly on their device.
+
+## What is BadgeHub?
+
+BadgeHub hosts `.mpk` packages and exposes a JSON API that MicroPythonOS queries for app listings, project details, and downloadable releases. It is particularly useful for:
+
+- conference or camp badge apps
+- community-built utilities
+- distributing apps without going through the curated MicroPythonOS app index
+
+## Backend endpoints
+
+The BadgeHub backend uses API version 3:
+
+- `https://badgehub.eu/api/v3/project-summaries` — list of all published projects with summary metadata.
+- `https://badgehub.eu/api/v3/projects/<slug>` — full project details, including releases, icons, and descriptions.
+
+Each project maps to one MicroPythonOS app package. The project's slug becomes the app identifier in the store.
+
+## Project metadata
+
+A project detail response contains fields such as:
+
+- `name` — display name in the AppStore.
+- `description` / `long_description` — short and long descriptions.
+- `icon_url` — URL to a 64×64 or larger app icon.
+- `publisher` — author or organization.
+- `releases` — list of published releases, each with a version and a download URL.
+- `main_executable` — optional flag indicating the primary app executable for this project.
+
+The AppManager uses the latest release's download URL to fetch the `.mpk`.
+
+## Releasing an app on BadgeHub
+
+1. Build your `.mpk` following the [Bundling Apps](bundling-apps.md) guide. The top-level folder in the ZIP must match the app's `fullname` exactly.
+2. Ensure the archive contains a valid `MANIFEST.JSON`.
+3. Upload the `.mpk` to your BadgeHub project.
+4. MicroPythonOS will detect the new release the next time the AppStore refreshes the BadgeHub backend.
+
+## Version handling
+
+Releases on BadgeHub should use [semantic versioning](https://semver.org/) strings (for example, `1.2.3`). The AppStore compares the installed version against the latest BadgeHub release and offers an update when the BadgeHub version is newer.
+
+## Switching backends in the AppStore app
+
+The AppStore app can switch between the curated MicroPythonOS backend and the BadgeHub backend. On supported firmware builds, BadgeHub is the default backend. Tap the backend selector in the AppStore UI to switch sources.
+
+## See also
+
+- [Bundling Apps](bundling-apps.md) — creating `.mpk` packages
+- [Creating Apps](creating-apps.md) — writing an app from scratch
+- [App Lifecycle](app-lifecycle.md) — `Activity` and `Service` lifecycle
diff --git a/docs/apps/bundling-apps.md b/docs/apps/bundling-apps.md
@@ -21,7 +21,7 @@ MicroPythonOS validates this layout while extracting, and rejects packages that
 
 From the parent directory that contains your app folder, create a stored (uncompressed) ZIP that includes the top-level folder. It's recommended to make the `.mpk` deterministic by setting file timestamps to a fixed value, sorting entries, and excluding extra file attributes:
 
-```
+```bash
 cd internal_filesystem/apps/
 find com.micropythonos.helloworld -exec touch -t 202501010000.00 {} \;
 (find com.micropythonos.helloworld -type d; find com.micropythonos.helloworld -type f) | sort | TZ=CET zip -X -r -0 /tmp/com.micropythonos.helloworld_0.0.2.mpk -@
@@ -34,8 +34,43 @@ This:
 - uses `-X` to exclude extra file attributes
 - places `com.micropythonos.helloworld/` as the first entry
 
+## Python packages
+
+An app can also be shipped as a proper Python package. This lets you split an app into many modules, use relative imports, and import shared code cleanly.
+
+To opt in, the app folder must contain an `__init__.py` file, and **every directory on the path to each entrypoint** must also contain an `__init__.py` (or compiled `__init__.mpy`). The AppManager then imports the entrypoint as part of the package. The module name becomes the package fullname dotted with the entrypoint path, for example `com_micropythonos_nostr.chat_list_activity`.
+
+Example `com_micropythonos_nostr` layout:
+
+```
+com_micropythonos_nostr/
+com_micropythonos_nostr/__init__.py
+com_micropythonos_nostr/MANIFEST.JSON
+com_micropythonos_nostr/icon_64x64.png
+com_micropythonos_nostr/chat_list_activity.py
+com_micropythonos_nostr/nostr_service.py
+com_micropythonos_nostr/...
+```
+
+The `MANIFEST.JSON` still declares `chat_list_activity.py` as the entrypoint; the framework detects the `__init__.py` and loads it as a package automatically.
+
+Relative imports work as usual inside the package:
+
+```python
+from . import nostr_service
+from .nostr_service import NostrService
+```
+
+## Native modules
+
+Apps can include native C/C++ extension modules compiled as MicroPython `.native.mpy` files. Place the compiled `.mpy` in the app folder and import it like a normal module. For build instructions and an example, see [Native C/C++ Apps](native-apps.md).
+
 ## AppStore bundling
 
 The apps at https://apps.MicroPythonOS.com are a curated, manually reviewed, vetted collection, often created and maintained by the MicroPythonOS core team.
 
 These are bundled into an [`app_index.json`](https://github.com/MicroPythonOS/apps/blob/main/app_index.json) using [`scripts/bundle_apps.sh`](https://github.com/MicroPythonOS/MicroPythonOS/blob/main/scripts/bundle_apps.sh) and then pushed to the [apps repo](https://github.com/MicroPythonOS/apps).
+
+## BadgeHub.eu publishing
+
+For community and event-badge publishing, MicroPythonOS also supports the [BadgeHub.eu](https://badgehub.eu) appstore backend. See [BadgeHub Apps](badgehub.md) for how to publish an `.mpk` there.
diff --git a/docs/apps/index.md b/docs/apps/index.md
@@ -3,4 +3,9 @@
 MicroPythonOS is built around an app-centric model, with built-in apps for core functionality and an App Store for additional apps.
 
 - [Built-in Apps](built-in-apps.md): Core apps included with the OS.
-- [App Store](appstore.md): Download and install new apps.
+- [App Store](appstore.md): Download and install new apps, including BadgeHub.eu community apps.
+- [Creating Apps](creating-apps.md): Write an app from scratch.
+- [App Lifecycle](app-lifecycle.md): Activity and Service lifecycle.
+- [Bundling Apps](bundling-apps.md): Package apps as `.mpk` files, including Python packages.
+- [Native C/C++ Apps](native-apps.md): Add compiled native modules to an app.
+- [BadgeHub Apps](badgehub.md): Publish apps on BadgeHub.eu.
diff --git a/docs/apps/native-apps.md b/docs/apps/native-apps.md
@@ -0,0 +1,93 @@
+# Native C/C++ Apps
+
+Most MicroPythonOS apps are written in MicroPython, but apps can also include native extension modules written in C or C++. These modules are compiled to MicroPython `.native.mpy` files and bundled inside the app's `.mpk` like any other module.
+
+## When to use native code
+
+Use a native module when:
+
+- You need more CPU performance than pure MicroPython can provide (for example, a game loop or signal processing).
+- You need to call C libraries that have no MicroPython equivalent.
+- You want to reuse existing C/C++ code.
+
+For everything else, prefer plain MicroPython — native modules add build complexity and are architecture-specific.
+
+## How native modules work
+
+MicroPython supports [native machine code modules](https://docs.micropython.org/en/latest/develop/natmod.html) (often called *natmods*). A natmod is a self-contained `.mpy` file that contains compiled machine code and a MicroPython module descriptor. At runtime it is imported just like a `.py` file:
+
+```python
+import breakout
+breakout.start()
+```
+
+MicroPythonOS places the `.mpy` file in the app folder when the `.mpk` is installed. The AppManager's import path then finds it automatically.
+
+## Example: `com.micropythonos.breakout`
+
+The built-in **Breakout** game uses a native C module for the game logic. Its source lives in `c_mpos/breakout/` in the main repository.
+
+Project layout:
+
+```
+c_mpos/breakout/
+├── Makefile
+├── build.sh
+└── breakout.c
+```
+
+`Makefile`:
+
+```makefile
+MPY_DIR = ../../lvgl_micropython/lib/micropython/
+
+MOD = breakout
+SRC = breakout.c
+LINK_RUNTIME = 1
+ARCHES = x64 xtensawin
+
+ifeq ($(ARCH),)
+.PHONY: all $(ARCHES)
+
+all: $(ARCHES)
+
+$(ARCHES):
+	$(MAKE) -f $(lastword $(MAKEFILE_LIST)) ARCH=$@ MOD=$(MOD)_$@
+else
+include $(MPY_DIR)/py/dynruntime.mk
+endif
+```
+
+This builds two artifacts:
+
+- `breakout_x64.native.mpy` — for the desktop simulator.
+- `breakout_xtensawin.native.mpy` — for ESP32-S3 devices.
+
+The `build.sh` script sets up the Espressif toolchain and then copies the resulting `.mpy` files into the app's folder at `internal_filesystem/apps/com.micropythonos.breakout/`.
+
+## Bundling a native module
+
+1. Write your C/C++ source and a `Makefile` based on the MicroPython `dynruntime.mk` rules.
+2. Build the module for every architecture you want to support.
+3. Rename or place the output `.mpy` file in the app folder so its import name matches what your MicroPython code imports. For Breakout, the `xtensawin` build is named `breakout.mpy` inside the app folder.
+4. Build the `.mpk` normally. The native `.mpy` is packaged alongside the Python files.
+
+```
+com.micropythonos.breakout/
+├── MANIFEST.JSON
+├── icon_64x64.png
+├── main.py
+└── breakout.mpy      # native module, imported by main.py
+```
+
+## Limitations
+
+- Native modules must be compiled separately for each target architecture (for example, `x64` for desktop and `xtensawin` for ESP32).
+- The MicroPython natmod ABI can change between releases, so rebuild modules when the `lvgl_micropython` submodule is updated.
+- Native code has the same filesystem and memory constraints as the rest of the app.
+
+## See also
+
+- [Bundling Apps](bundling-apps.md) — packaging apps as `.mpk` files
+- [MicroPython Native Module Documentation](https://docs.micropython.org/en/latest/develop/natmod.html)
+- [Creating Apps](creating-apps.md) — writing an app from scratch
diff --git a/docs/frameworks/audiomanager.md b/docs/frameworks/audiomanager.md
@@ -121,6 +121,27 @@ AudioManager.record_wav_adc(
 )
 ```
 
+### Desktop WAV Playback
+
+On Linux and macOS desktop builds, WAV playback uses an external audio player subprocess instead of I2S hardware. `AudioManager` automatically detects one of the following players in order of preference:
+
+1. `ffplay` (FFmpeg)
+2. `aplay` (ALSA)
+3. `paplay` (PulseAudio)
+4. `afplay` (macOS)
+
+If none is installed, the player still runs in "timing simulation" mode so apps can test playback flow without sound.
+
+```bash
+# Ubuntu/Debian
+sudo apt install ffmpeg
+
+# macOS
+# afplay is pre-installed
+```
+
+Priority and volume controls apply conceptually on desktop, although the external player handles the actual output.
+
 ## Audio Focus Priority
 
 AudioManager implements a 3-tier priority-based audio focus system inspired by Android:
@@ -240,7 +261,7 @@ Set or get the global volume (0–100).
 | **Fri3d 2024 Badge** | ✅ | ✅ | ❌ | ✅ | Full audio support |
 | **Fri3d 2026 Badge** | ✅ | ❌ | ✅ | ✅ | ADC mic via `adc_mic` |
 | **Waveshare ESP32-S3** | ✅ | ❌ | ❌ | ❌ | I2S output only |
-| **Linux/macOS** | ❌ | ✅ (simulated) | ✅ (simulated) | ❌ | Simulated recording for testing |
+| **Linux/macOS** | ✅ (external player) | ✅ (simulated) | ✅ (simulated) | ❌ | WAV playback via `ffplay`/`aplay`/`paplay`/`afplay` |
 
 ## Troubleshooting
 
diff --git a/docs/frameworks/file-explorer-activity.md b/docs/frameworks/file-explorer-activity.md
@@ -99,6 +99,13 @@ The system then resolves the file to the appropriate viewer using the manifest-d
 
 Long-pressing a file or folder opens an action bar with **Delete**, **Rename**, and **Cancel** options. Delete shows a confirmation dialog; Rename launches `RenameActivity`.
 
+### Deleting directories
+
+Deleting a folder removes it recursively, including all files and subdirectories inside it. A confirmation dialog is shown before any deletion begins.
+
+!!! warning
+    Directory deletion cannot be undone. Use the confirmation dialog carefully, especially when deleting paths under `/data/` or `/apps/`.
+
 ## Example: image picker
 
 ```python
diff --git a/docs/frameworks/focus.md b/docs/frameworks/focus.md
@@ -44,6 +44,19 @@ if focusgroup:
 
 `add_focus_border` only draws the visual feedback; it does **not** add the widget to the focus group.
 
+### Touch-aware behavior
+
+On devices that are primarily controlled with a touchscreen, the focus border is intentionally hidden until the user first navigates with a directional input (keyboard, hardware buttons, or a rotary encoder). This keeps touch-only screens clean while still making focused elements obvious once physical navigation begins.
+
+If you want a widget to reveal the focus border immediately, ensure it is added to the default focus group and focus it programmatically:
+
+```python
+focusgroup = lv.group_get_default()
+if focusgroup:
+    focusgroup.add_obj(btn)
+    focusgroup.focus_obj(btn)
+```
+
 ## Examples
 
 ### Basic usage
diff --git a/docs/frameworks/font-manager.md b/docs/frameworks/font-manager.md
@@ -91,6 +91,8 @@ Return a font object suitable for use with `set_style_text_font()`.
 
 **Returns:** `lv.font_t` — the requested font, possibly wrapped with emoji support.
 
+If the requested `family` is not available, FontManager falls back to Montserrat, then to the first available built-in font, and finally to `lv.font_montserrat_12`.
+
 **Example:**
 
 ```python
@@ -202,6 +204,10 @@ builtin/res/emojis/
 
 Files are named by their Unicode codepoint(s) in uppercase hex, with multiple codepoints joined by `-` (e.g. `1F600.png` for 😀, `1F3CE-FE0F.png` for 🏎️, `1F1F8-1F1FB.png` for 🇸🇻). FontManager scans the directory at runtime and builds a `{codepoint: path}` map.
 
+### Missing emoji fallback
+
+If the exact PNG for an emoji is not bundled, FontManager tries visually similar emoji before giving up. For example, several kissing-face variants can substitute for each other. This keeps text readable even when only a small emoji set is included in the firmware.
+
 ### Adding new emoji
 
 1. Add a PNG named `<CODEPOINT_HEX>.png` to `32x32/`:
diff --git a/docs/frameworks/notification-manager.md b/docs/frameworks/notification-manager.md
@@ -63,6 +63,29 @@ Notification.PRIORITY_MAX     =  3
 
 The drawer sorts notifications by priority, then by most recent update time.
 
+## Notification sounds
+
+When a new notification arrives, the system can play a short RTTTL ringtone on the device's buzzer output. The sound is stored as an RTTTL string in the Settings app's `SharedPreferences` under the key `notification_sound`.
+
+Available sounds:
+
+| Label | RTTTL string |
+|-------|--------------|
+| `None` | (empty string, no sound) |
+| `Coin` | `coin:d=8,o=6,b=200:16b5,e6` |
+| `Scale up` | `scale_up:d=32,o=5,b=100:c,c#,d#,e,f#,g#,a#,b` |
+| `Superhappy` | `superhappy:d=8,o=5,b=635:c,e,g,c,e,g,c,e,g,c6,e6,g6,c6,e6,g6,c7,e7,g7,c7,e7,g7,c7,e7,g7` |
+
+The default sound is `Coin`. If no buzzer output is available, the notification posts silently. Apps can change the sound programmatically:
+
+```python
+from mpos import SharedPreferences
+
+prefs = SharedPreferences("com.micropythonos.settings")
+prefs.put_string("notification_sound", "coin:d=8,o=6,b=200:16b5,e6")
+prefs.commit()
+```
+
 ## NotificationManager API
 
 All methods are class methods. `NotificationManager` initializes itself lazily on first use.
diff --git a/docs/getting-started/supported-hardware.md b/docs/getting-started/supported-hardware.md
diff --git a/mkdocs.yml b/mkdocs.yml
