Document Service and boot_completed intent filter

ThomasFarstrike · ThomasFarstrike · commit 5dc72d79c17f · 2026-05-31T22:33:13.000+02:00
diff --git a/docs/apps/app-lifecycle.md b/docs/apps/app-lifecycle.md
@@ -413,6 +413,45 @@ class NetworkAwareActivity(Activity):
 ❌ Don't assume the activity is still visible after async operations  
 ❌ Don't store references to LVGL objects after `onDestroy()`  
 
+## Services — Background Components
+
+Alongside Activities, MicroPythonOS provides **Services** for background work that runs without a user interface. Unlike Activities, Services have no screen lifecycle — they are created, started, and destroyed by intent actions (e.g., `boot_completed`).
+
+### Service Lifecycle
+
+```
+┌────────────┐
+│  onCreate  │  ← One-time initialization
+└─────┬──────┘
+      │
+      ▼
+┌────────────┐
+│  onStart   │  ← Receive intent, begin work
+└─────┬──────┘
+      │
+      ▼
+┌────────────┐
+│ onDestroy  │  ← Cleanup
+└────────────┘
+```
+
+### Service vs. Activity Comparison
+
+| Method | Activity | Service |
+|--------|----------|---------|
+| `onCreate()` | Build UI, set up screen | Initialize resources |
+| `onStart()` | Screen about to become visible | Start background work (receives Intent) |
+| `onDestroy()` | Activity removed from stack | Stop threads, cancel tasks |
+
+### When to Use a Service
+
+- Starting WiFi auto-connect at boot
+- Launching a background web server
+- Running a periodic update check
+- Starting an async REPL task
+
+Services are declared either programmatically (system services) or via `"services"` in the app's `MANIFEST.JSON`. See the [Service documentation](../frameworks/service.md) for a complete reference.
+
 ## Lifecycle Comparison with Android
 
 | MicroPythonOS | Android | Notes |
@@ -435,3 +474,4 @@ class NetworkAwareActivity(Activity):
 - [AppManager](../frameworks/app-manager.md) - App management and launching
 - [Intent System](../frameworks/app-manager.md#intent-resolution) - Intent-based navigation
 - [TaskManager](../frameworks/task-manager.md) - Async task management
+- [Service](../frameworks/service.md) - Background services for boot-time and long-running tasks
diff --git a/docs/apps/creating-apps.md b/docs/apps/creating-apps.md
@@ -69,6 +69,34 @@ In `MANIFEST.JSON`, put:
 }
 ```
 
+### Services
+
+Apps can also declare **services** — background components that run at boot time with no user interface. Services are defined in the `"services"` array of the manifest:
+
+```json
+"services": [
+  {
+    "entrypoint": "assets/my_boot_service.py",
+    "classname": "MyBootService",
+    "intent_filters": [
+      {
+        "action": "boot_completed"
+      }
+    ]
+  }
+]
+```
+
+Each service entry has:
+
+| Field | Description |
+|-------|-------------|
+| `entrypoint` | Path to the Python file (relative to the app root) |
+| `classname` | Name of the `Service` subclass in that file |
+| `intent_filters` | Array of `{ "action": "..." }` objects. Use `"boot_completed"` to run at startup |
+
+Services that subscribe to `"boot_completed"` are started automatically during system boot, after the launcher is displayed. See the [Service documentation](../frameworks/service.md) for details on writing and using services.
+
 ## Icon
 
 The icon is a [simple 64x64 pixel PNG image](https://github.com/MicroPythonOS/MicroPythonOS/blob/main/internal_filesystem/builtin/apps/com.micropythonos.launcher/res/mipmap-mdpi/icon_64x64.png), which you can create with any tool, such as GIMP.
diff --git a/docs/architecture/boot-sequence.md b/docs/architecture/boot-sequence.md
@@ -12,11 +12,16 @@ MicroPythonOS consists of several core components that initialize and manage the
     - Mounts the freezefs into /builtin/
     - Loads the com.micropythonos.settings
     - Initializes the user interface.
-    - Starts the WiFi autoconnect thread
     - Launches the `launcher` app that shows the icons
-    - Starts the asyncio REPL
+    - Runs auto-start apps (`auto_start_app_early`, `auto_start_app`)
+    - Starts **boot services** — all services that subscribe to the `boot_completed` intent are instantiated and receive `onStart()`:
+        - `WifiBootService` — auto-connects WiFi in a background thread
+        - `WebServerBootService` — starts the HTTP web server
+        - `AIOReplService` — starts the asyncio REPL task
+        - App-specific services (e.g., `OSUpdateService`)
     - Marks the current boot as successful (cancel rollback)
-    - Starts the TaskManager
+    - Starts the TaskManager (asyncio event loop)
 
 See [Filesystem Layout](filesystem.md) for where apps and data are stored.
 
+See [Service](../frameworks/service.md) for details on writing boot services.
diff --git a/docs/frameworks/app-manager.md b/docs/frameworks/app-manager.md
@@ -14,6 +14,7 @@ AppManager provides:
 - **Version management** - Compares versions and detects available updates
 - **Intent resolution** - Resolves activities that handle specific intents (Android-inspired)
 - **Launcher management** - Finds and restarts the system launcher
+- **Service management** - Registers, resolves, and starts boot services
 
 ## Quick Start
 
@@ -606,6 +607,54 @@ Stop all activities and restart launcher.
   2. Starts launcher app
   3. Useful for returning to home screen
 
+### Service Management
+
+**`register_service(action, service_cls, fullname=None)`**
+
+Register a service class to handle an intent action (programmatic registration, used by system services).
+
+- **Parameters:**
+  - `action` (str): Intent action (e.g., `"boot_completed"`)
+  - `service_cls` (type): Service subclass
+  - `fullname` (str, optional): App fullname to associate with the service
+
+- **Example:**
+  ```python
+  from mpos.content.app_manager import AppManager
+  from mpos import Service
+
+  class MyBootService(Service):
+      def onStart(self, intent):
+          print("Boot service started")
+
+  AppManager.register_service("boot_completed", MyBootService, fullname="com.example.myapp")
+  ```
+
+**`get_services_for_action(action)`**
+
+Resolve all services (manifest-declared and programmatically registered) that handle a given intent action.
+
+- **Parameters:**
+  - `action` (str): Intent action (e.g., `"boot_completed"`)
+
+- **Returns:** `list[(str, type)]` - List of `(app_fullname, ServiceClass)` tuples
+
+- **Behavior:**
+  1. Scans all installed apps' manifests for matching service entries
+  2. Imports each service module and extracts the class
+  3. Merges with programmatically registered services from `_service_registry`
+
+**`start_boot_services()`**
+
+Start all services that subscribe to the `boot_completed` intent. Called once during system boot after the launcher is displayed.
+
+- **Behavior:**
+  1. Calls `get_services_for_action("boot_completed")` to discover all boot services
+  2. For each service: instantiate, set `appFullName`, call `onCreate()`, then `onStart(boot_intent)`
+  3. Handles errors per-service so one failing service does not block others
+
+- **Called by:** `main.py` during system boot sequence
+
 ## Best Practices
 
 ### Do's
@@ -731,3 +780,4 @@ if app:
 - [Activity Framework](../apps/app-lifecycle.md) - Activity lifecycle and management
 - [Intent System](../architecture/intents.md) - Intent-based app communication
 - [Frameworks Overview](../architecture/frameworks.md) - All available frameworks
+- [Service](../frameworks/service.md) - Background services and boot-time execution
diff --git a/docs/frameworks/service.md b/docs/frameworks/service.md
diff --git a/mkdocs.yml b/mkdocs.yml
