怎麼做 AkiraOS WASM 應用

這篇教你在 Zephyr RTOS 上建立、編譯、燒錄與 OTA 更新 AkiraOS 的 WebAssembly 應用。

這篇給想在支援板子上試用 AkiraOS 的嵌入式開發者看，目標是把應用和韌體分開管理，減少反覆重刷整包韌體的成本。照著做完，你會拿到可用的本機建置環境、一個可執行的 WASM 範例，以及部署到裝置的完整流程。

AkiraOS 是建立在 Zephyr RTOS 之上的開源平台，核心做法是把系統底層與應用隔離開來，讓應用可以獨立更新。這種架構適合需要沙箱、裝置隔離與較穩定底層韌體的團隊。

開始之前

• Git 2.40+
• Python 3.11+
• CMake 3.20+
• Ninja 1.11+
• Zephyr SDK 0.16+，或以 AkiraOS 文件列出的版本為準
• Node.js 20+，如果應用 UI 或工具鏈會用到網頁資產
• 一塊支援的板子，例如 ESP32-S3、ESP32-C6、ESP32-H2、nRF54L15 或 STM32 目標板
• 一條 USB 線，若要測 OTA，還需要可連到板子的 Wi-Fi 網路
• GitHub 帳號，用來複製來源碼與回報平台問題

先打開 AkiraOS 官方文件與 GitHub repository，後續所有板子支援、SDK 版本與燒錄步驟都以那裡為準。第一次遇到版本差異時，不要猜，直接回文件核對。

Step 1: 複製 AkiraOS 原始碼

這一步的目的，是先拿到完整的專案樹，讓你能找到 Zephyr 應用、執行階段與板子設定檔。

把主 repository 複製到本機，並確認頂層目錄結構。

git clone https://github.com/akiraos/akiraos.git
cd akiraos
ls

你應該看到對應系統核心、runtime、文件與範例的目錄或檔案。若 repository 名稱或結構有變，以官方文件標示的 canonical source 為準。

Step 2: 安裝 Zephyr 建置工具鏈

這一步的目的，是建立可交叉編譯 MCU 目標與本機模擬器的環境。

先建立 Python 虛擬環境，再安裝 west 與建置工具，最後確認工具都能被 shell 找到。

python3 -m venv .venv
. .venv/bin/activate
pip install -U pip west
west --version
cmake --version
ninja --version

你應該看到每個工具的版本輸出，而且不會出現 command not found。若專案提供鎖定版 requirements 檔，優先用那個檔案安裝。

Step 3: 建置 native 模擬映像

這一步的目的，是先用桌面模擬器快速驗證建置流程，不必先燒錄真實硬體。

先用 native simulation target 做第一次建置，確認 build system、runtime 與 app packaging 都正常，再切到實體板子。

west build -b native_sim path/to/akiraos/app
west build -t run

你應該看到模擬器啟動，並輸出 Zephyr 與 AkiraOS 的開機紀錄。若建置成功但應用沒有跑起來，回文件確認 sample 名稱或 board overlay。

Step 4: 編譯 WASM 應用封裝

這一步的目的，是產出可被 AkiraOS 安裝的沙箱化 .wasm 檔，而不是整包韌體。

使用 AkiraOS SDK 建置一個範例應用，目標是生成只申請必要 API 的 WebAssembly 模組。

cd path/to/akiraos-sdk
mkdir -p build
cmake -S samples/hello -B build -G Ninja
cmake --build build

你應該在 build 目錄看到 .wasm 輸出，或看到帶有 app bundle 的產物。如果 SDK 的範例路徑不同，就改用文件中的 hello、shell 或 widgets 範例。

Step 5: 燒錄支援的 MCU 板子

這一步的目的，是把 AkiraOS 跑到真機上，方便測試儲存、BLE、網路與應用隔離。

選一塊支援板子，例如 ESP32-S3-DevKitM-1、nRF54L15 平台或文件列出的 STM32 kit，然後用專案指定的 board target 燒錄，再開序列埠看開機流程。

west flash
west debug

你應該看到 Zephyr 開機訊息，接著是 AkiraOS 啟動紀錄，以及 shell 或管理提示字元。若燒錄失敗，先核對文件中的 board 名稱，再檢查 USB driver 與主機權限。

Step 6: 透過網路安裝與更新應用

這一步的目的，是驗證 WASM 應用可以獨立更新，而不用重刷底層韌體。

用 web 介面、手機 app 或 shell 上傳 .wasm 封裝，執行安裝與啟動，然後再推第二版同名應用，確認更新流程不會碰到底層 OS。

curl -F file=@build/hello.wasm http://device.local/api/apps
curl -X POST http://device.local/api/apps/hello/run

你應該在管理介面看到應用出現，接著在裝置端看到它啟動與回報狀態。若更新失敗，先檢查 Wi-Fi、app manifest，以及目標板是否有足夠儲存空間。

常見錯誤

• 板子 target 選錯。修法：先在文件確認你的裝置是 Tier 1 還是 Tier 2，再用完全一致的 board 名稱重建。
• 跳過 SDK 版本鎖定。修法：安裝 AkiraOS 建議的 Zephyr SDK 版本，不要直接升到未驗證的新版本。
• 上傳的是原始 binary，不是 WASM 封裝。修法：一定要用 AkiraOS SDK 產出 app artifact 與 manifest，管理器才會接受。

接下來可以看什麼

下一步可以接著做 shell、檔案瀏覽器與管理介面，進一步測 OTA、監控多台裝置，並在同一塊板子上切換多個應用。