WASM モジュールの開発とテスト

開発

WASM モジュールのライフサイクル

WASM モジュールは Orbit の WASM ランタイムで実行されます。
- Orbit は WASM モジュールの実行時に都度グループ設定で定義したバージョンの WASM モジュールをロードします。
- uplink() (デバイスから SORACOM プラットフォーム方向) / downlink() (転送先からデバイス方向) 関数が WASM モジュールのエントリポイントとして Orbit から呼び出されます。いずれも引数を取らず、i32 型の結果を返す関数として定義してください。
- 結果の値が 0 (ゼロ) 以上であれば関数の処理が成功したことを、負の値であれば関数の処理が失敗したことを Orbit に伝えることができます。数値は任意に決めてください。
- サポートされていない処理を実行した場合や意図せず WASM モジュールが異常終了した場合は Orbit からエラーが返されます。
- バイナリパーサーが有効になっている場合は、バイナリパーサーの実行結果が WASM モジュールに渡されます。
WASM モジュールの実行は独立しています。
- 過去の実行結果を参照できません。例えば x 回分のデータを溜めて処理するようなことはできません。
- 他の WASM モジュールを起動できません。
WebAssembly System Interface (WASI) をサポートしていないためファイルシステムやネットワークアクセスなどシステムコールを伴う処理を実行できません。外部とのインタフェースは Orbit SDK に定義されています。例えば、デバイスから送信されたデータや SIM カードのタグ情報を SDK の関数経由で取得できます。詳細や制限事項をリファレンスセクションで確認してください。

各言語共通

vscode を一旦終了して再度開く場合は、起動時に表示されるプロンプトの Reopen in Container をクリックしてください。
構成ファイルが変更され Docker イメージの再構築が必要になった場合は以下のようなプロンプトが表示されます。 Rebuild をクリックしてください。
```
Configuration file(s) changed: devcontainer.json. The container might need to be rebuild to apply the changes.

Source: Remote - Containers (Extension)
```

言語別

AssemblyScript
Rust
C/C++
TinyGo

assembly/index.ts ファイルにサンプル実装があります。assembly/index.ts の内容を参考に vscode で編集してください。

uplink() (デバイスからクラウドへのデータを処理する) / downlink() (クラウドからデバイスへのデータを処理する) のいずれかまたは両方をエクスポートしてください。
```
// For processing uplink (UE to SORACOM)
export function uplink(): i32 {
  /* code  */
}

// For processing downlink (SORACOM to UE)
export function downlink(): i32 {
  /* code */
}
```

編集が完了したら以下のいずれかの方法で assembly/index.ts を WASM にコンパイルします。結果は build/soralet.wasm に出力されます。コンパイルエラーが出た場合は適宜修正してください。

NPM Scripts ビューを開き build を実行
統合ターミナルを開き npm run build コマンドを実行
コマンドパレット (⇧⌘P) から Run Build Task を実行
上記のショートカット ⇧⌘B

src/lib.rs ファイルにサンプル実装があります。src/lib.rs の内容を参考に vscode で編集してください。

uplink() (デバイスからクラウドへのデータを処理する) / downlink() (クラウドからデバイスへのデータを処理する) のいずれかまたは両方を pub 関数として定義してください。#[no_mangle] マクロをつけることで、Orbit の実行系がこのコードの uplink() / downlink() 関数を見つけることができるようになります。
```
// For processing uplink (UE to SORACOM)
#[no_mangle]
pub fn uplink() -> i32 {
  /* code */
}
// For processing downlink (SORACOM to UE)
#[no_mangle]
pub fn downlink() -> i32 {
  /* code */
}
```

編集が完了したら以下のいずれかの方法で src/lib.rs を WASM にコンパイルします。結果は target/wasm32-unknown-unknown/debug/soralet.wasm に出力されます。コンパイルエラーが出た場合は適宜修正してください。

統合ターミナルを開き cargo build コマンドを実行
コマンドパレット (⇧⌘P) から Run Build Task を実行
上記のショートカット ⇧⌘B

src/main.cpp ファイルにサンプル実装があります。main.cpp の内容を参考に vscode で編集してください。

uplink() (デバイスからクラウドへのデータを処理する) / downlink() (クラウドからデバイスへのデータを処理する) のいずれかまたは両方をエクスポートしてください。EMSCRIPTEN_KEEPALIVE マクロをつけて関数を宣言することで、コンパイラによる最適化を抑止し Orbit の実行系がこのコードの uplink() 関数を見つけることができるようになります。C++ を使う場合は extern "C" { ... } でこれらの関数を囲み、名前のマングル化を抑制してください。
```
// For processing uplink (UE to SORACOM)
EMSCRIPTEN_KEEPALIVE
int32_t uplink()
{
    return 0;
}

// For processing downlink (SORACOM to UE)
EMSCRIPTEN_KEEPALIVE
int32_t downlink()
{
    return 0;
}
```

編集が完了したら以下のいずれかの方法で src/main.cpp を WASM にコンパイルします。結果は build/soralet.wasm に出力されます。コンパイルエラーが出た場合は適宜修正してください。

統合ターミナルを開き make build コマンドを実行
コマンドパレット (⇧⌘P) から Run Build Task を実行
上記のショートカット ⇧⌘B

ビルド時に、Orbit が提供するいくつかの関数 (orbit_log orbit_get_input_buffer など orbit_ の接頭辞で始まる関数) のシンボルが未定義であるという警告が表示されますが、これは実行時に Orbit の処理系から提供される関数なのでコンパイル時に未定義でも問題ありません。

src/main.go ファイルにサンプル実装があります。main.go の内容を参考に vscode で編集してください。 orbit-sdk-tinygo は GitHub で公開しており examples ディレクトリにもサンプルがあります。

uplink() (デバイスからクラウドへのデータを処理する) / downlink() (クラウドからデバイスへのデータを処理する) のいずれかまたは両方を実装してください。それぞれの関数のコメント //export uplink|downlink でエクスポートされます。 // の後に空白を入れないよう注意してください。
```
import sdk github.com/soracom/orbit-sdk-tinygo

// For processing uplink (UE to SORACOM)
//export uplink
func uplink() sdk.ErrorCode {
  sdk.Log("hello world, uplink")
  return 0
}

// For processing downlink (SORACOM to UE)
//export downlink
func downlink() sdk.ErrorCode {
  sdk.Log("hello world, downlink")
  return 0
}
```

編集が完了したら以下のいずれかの方法で src/main.go を WASM にコンパイルします。結果は build/soralet.wasm に出力されます。コンパイルエラーが出た場合は適宜修正してください。

統合ターミナルを開き make build コマンドを実行
コマンドパレット (⇧⌘P) から Run Build Task を実行
上記のショートカット ⇧⌘B

開発環境でのテスト

AssemblyScript
Rust
C/C++
TinyGo

任意の方法でテストいただけますが、サンプルとして Jest を利用したスナップショットテスト (テストの対象の出力をスナップショットとして保存し、コードの変更によってスナップショットに変更が生じているかどうかを検出するテスト方式) を構成しています。

このテストは Development container 内の Node.js 上で動作する Orbit ランタイム互換の実行環境を用いてテストしますので、 SORACOM プラットフォームへのデプロイとテストセクションで説明する WASM モジュールのアップロード (soralet upload) やテスト(soralet exec) とは異なりお手元の環境でテストを実施いただけます。

tests/inputs.ts にテストケースを定義します。
以下のいずれかの方法でテストを実行してください。
- NPM Scripts ビューを開き test を実行
- 統合ターミナルを開き npm test コマンドを実行
- コマンドパレット (⇧⌘P) から Run Test Task を実行
- F5 キー (ただし、AssemblyScript にはブレイクポイントを設定できません)
新しいテストケースを定義し初めて実行した場合 tests/__snapshots__/ ディレクトリのスナップショットが更新されます。
WASM モジュール実装を変更し出力結果が変わった場合は tests/__snapshots__/ ディレクトリのスナップショットとの差分がエラーとなります。結果が意図したものである場合は test:updateSnapshot を実行しスナップショットを更新してください。

スナップショットテストを実行すると tests/inputs/ ディレクトリに JSON ファイルが出力されます。このファイルは

WASM モジュールのテストセクションで説明する soracom soralet exec コマンドの入力ファイルとして利用できます。

現時点でテストのサンプルはありません。

各言語で提供するテスト機能やライブラリなどをご利用ください。

現時点でテストのサンプルはありません。

各言語で提供するテスト機能やライブラリなどをご利用ください。

現時点でテストのサンプルはありません。

各言語で提供するテスト機能やライブラリなどをご利用ください。