Skip to content

Commit 1038dd8

Browse files
ThomasFarstrikeThomasFarstrike
committed
Update CLAUDE.md
1 parent 5dd2409 commit 1038dd8

File tree

1 file changed

+83
-0
lines changed

1 file changed

+83
-0
lines changed

‎CLAUDE.md‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -483,6 +483,8 @@ Current stable version: 0.3.3 (as of latest CHANGELOG entry)
483483
- Intent system: `internal_filesystem/lib/mpos/content/intent.py`
484484
- UI initialization: `internal_filesystem/main.py`
485485
- Hardware init: `internal_filesystem/boot.py`
486+
- Task manager: `internal_filesystem/lib/mpos/task_manager.py` - see [docs/frameworks/task-manager.md](../docs/docs/frameworks/task-manager.md)
487+
- Download manager: `internal_filesystem/lib/mpos/net/download_manager.py` - see [docs/frameworks/download-manager.md](../docs/docs/frameworks/download-manager.md)
486488
- Config/preferences: `internal_filesystem/lib/mpos/config.py` - see [docs/frameworks/preferences.md](../docs/docs/frameworks/preferences.md)
487489
- Audio system: `internal_filesystem/lib/mpos/audio/audioflinger.py` - see [docs/frameworks/audioflinger.md](../docs/docs/frameworks/audioflinger.md)
488490
- LED control: `internal_filesystem/lib/mpos/lights.py` - see [docs/frameworks/lights-manager.md](../docs/docs/frameworks/lights-manager.md)
@@ -572,6 +574,8 @@ def defocus_handler(self, obj):
572574
- **Connect 4** (`apps/com.micropythonos.connect4/assets/connect4.py`): Game columns are focusable
573575

574576
**Other utilities**:
577+
- `mpos.TaskManager`: Async task management - see [docs/frameworks/task-manager.md](../docs/docs/frameworks/task-manager.md)
578+
- `mpos.DownloadManager`: HTTP download utilities - see [docs/frameworks/download-manager.md](../docs/docs/frameworks/download-manager.md)
575579
- `mpos.apps.good_stack_size()`: Returns appropriate thread stack size for platform (16KB ESP32, 24KB desktop)
576580
- `mpos.wifi`: WiFi management utilities
577581
- `mpos.sdcard.SDCardManager`: SD card mounting and management
@@ -581,6 +585,85 @@ def defocus_handler(self, obj):
581585
- `mpos.audio.audioflinger`: Audio playback service - see [docs/frameworks/audioflinger.md](../docs/docs/frameworks/audioflinger.md)
582586
- `mpos.lights`: LED control - see [docs/frameworks/lights-manager.md](../docs/docs/frameworks/lights-manager.md)
583587

588+
## Task Management (TaskManager)
589+
590+
MicroPythonOS provides a centralized async task management service called **TaskManager** for managing background operations.
591+
592+
**📖 User Documentation**: See [docs/frameworks/task-manager.md](../docs/docs/frameworks/task-manager.md) for complete API reference, patterns, and examples.
593+
594+
### Implementation Details (for Claude Code)
595+
596+
- **Location**: `lib/mpos/task_manager.py`
597+
- **Pattern**: Wrapper around `uasyncio` module
598+
- **Key methods**: `create_task()`, `sleep()`, `sleep_ms()`, `wait_for()`, `notify_event()`
599+
- **Thread model**: All tasks run on main asyncio event loop (cooperative multitasking)
600+
601+
### Quick Example
602+
603+
```python
604+
from mpos import TaskManager, DownloadManager
605+
606+
class MyActivity(Activity):
607+
def onCreate(self):
608+
# Launch background task
609+
TaskManager.create_task(self.download_data())
610+
611+
async def download_data(self):
612+
# Download with timeout
613+
try:
614+
data = await TaskManager.wait_for(
615+
DownloadManager.download_url(url),
616+
timeout=10
617+
)
618+
self.update_ui(data)
619+
except asyncio.TimeoutError:
620+
print("Download timed out")
621+
```
622+
623+
### Critical Code Locations
624+
625+
- Task manager: `lib/mpos/task_manager.py`
626+
- Used throughout OS for async operations (downloads, WebSockets, sensors)
627+
628+
## HTTP Downloads (DownloadManager)
629+
630+
MicroPythonOS provides a centralized HTTP download service called **DownloadManager** for async file downloads.
631+
632+
**📖 User Documentation**: See [docs/frameworks/download-manager.md](../docs/docs/frameworks/download-manager.md) for complete API reference, patterns, and examples.
633+
634+
### Implementation Details (for Claude Code)
635+
636+
- **Location**: `lib/mpos/net/download_manager.py`
637+
- **Pattern**: Module-level singleton (similar to `audioflinger.py`, `battery_voltage.py`)
638+
- **Session management**: Automatic lifecycle (lazy init, auto-cleanup when idle)
639+
- **Thread-safe**: Uses `_thread.allocate_lock()` for session access
640+
- **Three output modes**: Memory (bytes), File (bool), Streaming (callbacks)
641+
- **Features**: Retry logic (3 attempts), progress tracking, resume support (Range headers)
642+
643+
### Quick Example
644+
645+
```python
646+
from mpos import DownloadManager
647+
648+
# Download to memory
649+
data = await DownloadManager.download_url("https://api.example.com/data.json")
650+
651+
# Download to file with progress
652+
async def on_progress(percent):
653+
print(f"Progress: {percent}%")
654+
655+
success = await DownloadManager.download_url(
656+
"https://example.com/file.bin",
657+
outfile="/sdcard/file.bin",
658+
progress_callback=on_progress
659+
)
660+
```
661+
662+
### Critical Code Locations
663+
664+
- Download manager: `lib/mpos/net/download_manager.py`
665+
- Used by: AppStore, OSUpdate, and any app needing HTTP downloads
666+
584667
## Audio System (AudioFlinger)
585668

586669
MicroPythonOS provides a centralized audio service called **AudioFlinger** for managing audio playback.

0 commit comments

Comments
 (0)