Soracom

Users

ドキュメント
Home ドキュメント SORACOM Orbit 開発者ガイド

WASM モジュールを開発 / テストする

Visual Studio Code (以下、VS Code) を利用した WASM モジュール開発環境 で、WASM モジュールを開発 / テストします。

WASM モジュールについて

  • デバイスから送信されたデータ / デバイスに送信したデータに対して WASM モジュールが使用されるときは、Orbit の WASM ランタイムで実行されます。
  • WASM モジュールでは、uplink() と、downlink() を定義してください。この 2 つが WASM モジュールのエントリポイントとして Orbit から呼び出されます。いずれも引数を取らず、i32 (整数) 型の結果を返す関数として定義してください。データの入出力は、Orbit SDK を使用します。
    関数説明
    uplink()デバイスから SORACOM に送信したデータを変換する関数です。
    downlink()データ送信先 (SORACOM サービスや外部システム) からデバイスに戻すデータを変換する関数です。
  • WASM モジュールから Orbit に対して処理の成功 / 失敗を伝えるには、関数の戻り値を使います。
    • 処理が成功したときは、0 (ゼロ) 以上の任意の整数を返します。
    • 処理が失敗したときは、任意の負の整数を返します。
  • サポートされていない処理を実行した場合や意図せず WASM モジュールが異常終了した場合は、Orbit からエラーが返されます。
WASM モジュールは実行ごとに独立して動作します
  • Orbit は、WASM モジュールを実行するたびに、SIM グループで指定したバージョンの WASM モジュールをロードします。
  • 過去の実行結果を参照できません。たとえば x 回分のデータを溜めて処理するようなことはできません。
  • WASM モジュールから、他の WASM モジュールを起動できません。
WebAssembly System Interface (WASI) をサポートしていません

Orbit では、ファイルシステムやネットワークアクセスなどシステムコールを伴う処理を実行できません。外部とのインターフェースは Orbit SDK に定義されています。たとえば、デバイスから送信されたデータや IoT SIM の タグ情報 を、Orbit SDK の関数経由で取得できます。詳細や制限事項については、Orbit SDK リファレンス を参照してください。

WASM モジュールを開発する

WASM モジュールを開発するには、開発環境をインストールする で準備した Development container を使います。

VS Code で Development container を開き直す

VS Code を終了した場合や、Development container を閉じた場合は、VS Code で Development container を開き直します。

  1. VS Code を起動して、[File][Open Folder...] の順にクリックし、WASM モジュールの開発環境assemblyscript/rust/c/tinygo/ ディレクトリ (フォルダ) を開きます。

  2. [Reopen in Container] をクリックします。

    Development container が起動して、VS Code の左下に Dev Conatiner: SORACOM Orbit Development Container と表示されます。

Development container の起動に失敗したときは

SORACOM CLI をインストールして認証情報を保存していない場合は、Development container の起動に失敗し、以下のようなエラーメッセージが表示されます。SORACOM CLI をインストールする を参照して、認証情報を保存してください。

[xxxx ms] Command failed: /usr/share/code/code --ms-enable-electron-run-as-node /home/xxxxxx/.vscode/extensions/ms-vscode-remote.remote-containers-0.327.0/dist/spec-node/devContainersSpecCLI.js up --user-data-folder /home/xxxxxx/.config/Code/User/globalStorage/ms-vscode-remote.remote-containers/data --container-session-data-folder /tmp/devcontainers-91fff8de-1741-4d5f-9451-d123dd9984371705993527790 --workspace-folder /home/xxxxxx/orbit-development-environment-2023-12/rust --workspace-mount-consistency cached --id-label devcontainer.local_folder=/home/xxxxxx/orbit-development-environment-2023-12/rust --id-label devcontainer.config_file=/home/xxxxxx/orbit-development-environment-2023-12/rust/.devcontainer/devcontainer.json --log-level debug --log-format json --config /home/xxxxxx/orbit-development-environment-2023-12/rust/.devcontainer/devcontainer.json --default-user-env-probe loginInteractiveShell --mount type=volume,source=vscode,target=/vscode,external=true --mount type=bind,source=/run/user/1000/wayland-0,target=/tmp/vscode-wayland-b29bb7e5-cc94-4d97-81b0-e08d656515c1.sock --skip-post-create --update-remote-user-uid-default on --mount-workspace-git-root

.devcontainer/devcontainer.json を編集した結果、Development container の再構築が必要になった場合は、以下のような確認画面が表示されます。[Rebuild] をクリックしてください。

Configuration file(s) changed: devcontainer.json. The container might need to be rebuild to apply the changes.

Source: Remote - Containers (Extension)

WASM モジュールのソースコードを編集してコンパイルする

言語ごとにサンプル実装があります。サンプル実装の内容を参考に、VS Code でソースコードを編集します。

  1. サンプル実装と Orbit SDK リファレンスの AssemblyScript の内容を参考に、VS Code でソースコードを編集します。

    参考になるサンプル実装は、以下のとおりです。

    uplink() (デバイスから SORACOM に送信するデータを変換する関数) と、downlink() (データ送信先からデバイスに戻すデータを変換する関数) をエクスポートし、各関数にデータ変換処理を記述します。

    /**
     * process uplink (device -> SORACOM) message
     */
    export function uplink(): i32 {
      /* code  */
    }
    
    /**
     * process downlink (device <- SORACOM) message
     */
    export function downlink(): i32 {
      /* code */
    }
    
  2. 以下のいずれかの方法で assembly/index.ts をコンパイルし、build/soralet.wasm を出力します。

    • NPM Scripts ビューを開き build スクリプトを実行する

      VS Code の Explorer を開き、[…][NPM Scripts] の順にクリックし、[NPM SCRIPTS][package.json][build][Run] をクリックします。

    • 統合ターミナルを開き npm run build コマンドを実行する

      VS Code で [Terminal][New Terminal] の順にクリックし、npm run build コマンドを実行します。

    • コマンドパレットを開き Tasks: Run Build Task を実行する

      VS Code で [View][Command Palette...] の順にクリックし、Tasks: Run Build Task をクリックします。

  1. サンプル実装と SORACOM Orbit SDK リファレンスの Rust の内容を参考に、VS Code でソースコードを編集します。

    参考になるサンプル実装は、以下のとおりです。

    uplink() (デバイスから SORACOM へのデータを処理する) / downlink() (SORACOM からデバイスへのデータを処理する) のいずれかまたは両方を 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 */
    }
    
  2. 編集が完了したら、統合ターミナルを開き cargo build コマンドを実行して src/lib.rs を WASM にコンパイルします。

    結果は target/wasm32-unknown-unknown/debug/soralet.wasm に出力されます。コンパイルエラーが出た場合は適宜修正してください。

  1. サンプル実装と SORACOM Orbit SDK リファレンスの C/C++ の内容を参考に、VS Code でソースコードを編集します。

    参考になるサンプル実装は、以下のとおりです。

    • src/main.cpp ファイル
    • WASM モジュール開発環境の orbit-sdk-c/examples/ ディレクトリ

    uplink() (デバイスから SORACOM へのデータを処理する) / downlink() (SORACOM からデバイスへのデータを処理する) のいずれかまたは両方をエクスポートしてください。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;
    }
    
  2. 編集が完了したら以下のいずれかの方法で src/main.cpp を WASM にコンパイルします。結果は build/soralet.wasm に出力されます。コンパイルエラーが出た場合は適宜修正してください。

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

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

  1. サンプル実装と SORACOM Orbit SDK リファレンスの TinyGo の内容を参考に、VS Code でソースコードを編集します。

    参考になるサンプル実装は、以下のとおりです。

    uplink() (デバイスから SORACOM へのデータを処理する) / downlink() (SORACOM からデバイスへのデータを処理する) のいずれかまたは両方を実装してください。それぞれの関数のコメント //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
    }
    
  2. 編集が完了したら以下のいずれかの方法で src/main.go を WASM にコンパイルします。結果は build/soralet.wasm に出力されます。コンパイルエラーが出た場合は適宜修正してください。

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

Development container で WASM モジュールをテストする

Development container で動作する Orbit ランタイム互換の実行環境を利用して、WASM モジュールの動作をテストできます。

サンプルとして Jest を利用した スナップショットテスト を用意しています。スナップショットテストは、テスト対象の出力をスナップショットとして保存し、コードの変更によって出力に変更が生じたことを検出するテスト方式です。

  1. tests/inputs.ts にテストケースを定義します。

    SoraletPayload[] に指定するオブジェクトの各プロパティは以下のとおりです。

    プロパティ説明
    codeSrn仮の SRN を指定します。変更しないでください。
    directionuplink または downlink。処理するデータの送信方向を指定します。
    contentTypeWASM モジュールが受け取るデータの種類を指定します。例: application/json
    bodyWASM モジュールが受け取るデータを指定します。
    source.resourceTypeデータの送信元の種類を指定します。例: Subscriber
    source.resourceIdデータの送信元を識別する ID を指定します。例: 440529999999950 (IMSI)
    tagsWASM モジュールが Orbit SDK を使って取得する IoT SIM のタグを指定します。name: "test1" と指定した場合は、name タグに値 test1 が設定されているようにテストが実行されます。
    locationWASM モジュールが Orbit SDK を使って取得する位置情報 (簡易位置測位機能 で取得した位置情報) を指定します。
    timestampOrbit がデータを受信したときのタイムスタンプ (UNIX 時間 (ミリ秒)) を指定します。
  2. 以下のいずれかの方法で test スクリプトを実行します。

    • NPM Scripts ビューを開き test スクリプトを実行する

      VS Code の Explorer を開き、[…][NPM Scripts] の順にクリックし、[NPM SCRIPTS][package.json][test][Run] をクリックします。

    • 統合ターミナルを開き npm run test コマンドを実行する

      VS Code で [Terminal][New Terminal] の順にクリックし、npm run test コマンドを実行します。

    • コマンドパレットを開き Tasks: Run Test Task を実行する

      VS Code で [View][Command Palette...] の順にクリックし、Tasks: Run Test Task をクリックします。

    • デバッグを開始する (ただし、AssemblyScript にはブレイクポイントを設定できません)

      VS Code で [Run][Start Debugging] の順にクリックします。

  3. WASM モジュールの実装を変更した結果、出力が変わり tests/__snapshots__/ ディレクトリのスナップショットとの差分が生じた場合は、エラーが発生します。意図した出力だった場合は、以下のいずれかの方法で test:updateSnapshot スクリプトを実行してスナップショットを更新します。

    • NPM Scripts ビューを開き test:updateSnapshot スクリプトを実行する

      VS Code の Explorer を開き、[…][NPM Scripts] の順にクリックし、[NPM SCRIPTS][package.json][test:updateSnapshot][Run] をクリックします。

    • 統合ターミナルを開き npm run test:updateSnapshot コマンドを実行する

      VS Code で [Terminal][New Terminal] の順にクリックし、npm run test:updateSnapshot コマンドを実行します。

  • 新しいテストケースを定義して test スクリプトを実行すると、tests/__snapshots__/ ディレクトリのスナップショットが更新されます。
  • test スクリプトを実行すると tests/inputs/ ディレクトリに JSON ファイルが出力されます。この JSON ファイルは、SORACOM にアップロードしたあとで WASM モジュールをテスト するときに、soracom soralets exec コマンドの入力ファイルとして利用できます。

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

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

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

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

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

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