Soracom

Users

ドキュメント

Orbit SDK リファレンス

WASM モジュールの uplink() および downlink() で使用できる関数を説明します。

WASM モジュールへの入力データについて

SORACOM プラットフォームから WASM モジュールへの入力データは、Orbit SDK を使用して取得します。

ただし、「WASM モジュールへの入力データを取得するための関数」を呼び出しても、uplink() で呼び出す場合と、downlink() で呼び出す場合では、取得できるデータが以下のように異なります。

関数説明
uplink()

デバイスから SORACOM プラットフォームに送信したデータを変換する関数です。

WASM モジュールへの入力データを取得するための関数を呼び出すと、以下のいずれかのデータが取得できます。

  • デバイスから送信したデータ
  • デバイスから送信したデータを バイナリパーサー で処理した結果のデータ
downlink()

データ送信先からデバイスに戻すデータを変換する関数です。

WASM モジュールへの入力データを取得するための関数を呼び出すと、データ送信先からのデータが取得できます。

バイナリパーサーはデータ送信先からデバイスに戻すデータを処理できません。

AssemblyScript

orbit-sdk-assemblyscript モジュールが SDK を提供します。必要に応じてインポートしてご利用ください。

import {
  log,
  getInputBuffer,
  getInputBufferAsString,
  getTagValue,
  getSourceValue,
  getLocation,
  getTimestamp,
  getUserdata,
  setOutputJSON,
} from "orbit-sdk-assemblyscript";

それぞれの関数のシグネチャは以下の通りです。

  • log(message: string): void: ログを出力します。文字列のみサポートします。
  • getInputBuffer(): Uint8Array: WASM モジュールへの入力データを Uint8 の配列として取得します。
  • getInputBufferAsString(): string: WASM モジュールへの入力データを文字列として取得します。
  • getTagValue(name: string): string: データ送信元 (SIM) のタグの値を取得します。タグ名が見つからない場合は空白文字列を返します。
  • getSourceValue(name: string): string: データ送信元 (SIM) に関する値を取得します。見つからない場合は空白文字列を返します。
  • getLocation(): Location: 簡易位置測位機能が利用可能な SIM (plan-KM1) を利用している場合は Location オブジェクト ({lat: f64, lon: f64}) を返します。利用できない場合は NaN が返ります。
  • getTimestamp(): i64: 入力データのタイムスタンプ (Orbit がデータを受信したタイミング) を取得します。
  • getUserdata(): string: メタデータサービスのユーザーデータ を取得します。
  • setOutputJSON(json: string): void: WASM モジュールの処理結果として出力する JSON をセットします。

関数名が orbit_ で始まる、よりローレベルな機能を提供する関数も利用可能です。これらの関数は上で説明した関数によって使いやすい形に wrap されているため通常は利用する必要はありませんが、JSON 以外の形式での出力をしたい場合は以下の 2 つの関数を利用することができます。

  • orbit_set_output(json: i32, len: i32): void : ポインタと長さで示されたメモリ上のデータを出力データとして Orbit に伝えます。
  • orbit_set_output_content_type(type: i32, len: i32): void; : ポインタと長さで示されたメモリ上のデータを出力データの Content-Type として Orbit に伝えます。

これらの関数の使い方は、SDK の setOutputJSON() の実装を参考にしてください。

Rust

orbit-sdk-rust crate が SDK を提供します。

use soracom_orbit_sdk as orbit;

提供する関数のシグネチャは以下の通りです。

  • log(message: &str): ログを出力します。
  • get_input_buffer() -> Vec<u8>: WASM モジュールへの入力データを u8 のベクターとして取得します。
  • get_tag_value(name: &str) -> String: データ送信元 (SIM) のタグの値を取得します。タグ名が見つからない場合は空白文字列を返します。
  • get_source_value(name: &str) -> String: データ送信元 (SIM) に関する値を取得します。見つからない場合は空白文字列を返します。
  • get_location() -> Option<Location>: 簡易位置測位機能が利用可能な SIM (plan-KM1) を利用している場合は Location オブジェクト ({lat: f64, lon: f64}) を返します。利用できない場合は None が返ります。
  • get_timestamp() -> i64: 入力データのタイムスタンプ (Orbit がデータを受信したタイミング) を取得します。
  • get_userdata() -> String: メタデータサービスのユーザーデータ を取得します。
  • set_output_json(json_str: &str): WASM モジュールから出力する JSON をセットします。

関数名が orbit_ で始まる、よりローレベルな機能を提供する関数も利用可能です。これらの関数は上で説明した関数によって使いやすい形に wrap されているため通常は利用する必要はありませんが、JSON 以外の形式での出力をしたい場合は以下の 2 つの関数を利用することができます。

  • orbit_set_output(ptr: i32, len: i32) : ポインタと長さで示されたメモリ上のデータを出力データとして Orbit に伝えます。
  • orbit_set_output_content_type(ptr: i32, len: i32) : ポインタと長さで示されたメモリ上のデータを出力データの Content-Type として Orbit に伝えます。

これらの関数の使い方は、SDK の set_output_json() の実装を参考にしてください。

C/C++

orbit-sdk-c が SDK を提供します。

#include "soracom/orbit.h"

提供する関数のシグネチャは以下の通りです。

  • void soracom_log(const char* fmt, ...): ログを出力します。
  • int32_t soracom_get_input_buffer_as_string(const char** buf, size_t* siz): WASM モジュールへの入力データを取得します。入力データを使い終わったら *buf のポインタは次の soracom_release_input_buffer() で解放してください。
  • void soracom_release_input_buffer(const char* buf): soracom_get_input_buffer_as_string() で確保されたメモリを解放します。
  • int32_t soracom_get_tag_value(const char* name, size_t name_len, const char** value, size_t* value_len): データ送信元 (SIM) のタグの値を取得します。タグ名が見つからない場合は空白文字列を返します。
  • int32_t soracom_get_source_value(const char* name, size_t name_len, const char** value, size_t* value_len): データ送信元 (SIM) に関する値を取得します。見つからない場合は空白文字列を返します。
  • int32_t soracom_get_userdata_as_string(const char** buf, size_t* siz): メタデータサービスのユーザーデータ を取得します。
  • void soracom_set_json_output(const char* buf, size_t siz): WASM モジュールから出力する JSON をセットします。

関数名が orbit_ で始まる、よりローレベルな機能を提供する関数も利用可能です。これらの関数は上で説明した関数によって使いやすい形に wrap されているため通常は利用する必要はありませんが、いくつかの操作はローレベルな関数を使用する必要があります。

JSON 以外の形式での出力

以下の 2 つの関数を利用することで、出力データの Content Type を任意に設定できます。

  • void orbit_set_output(const char* buf, size_t siz) : ポインタと長さで示されたメモリ上のデータを出力データとして Orbit に伝えます。
  • void orbit_set_output_content_type(const char* buf, size_t siz) : ポインタと長さで示されたメモリ上のデータを出力データの Content-Type として Orbit に伝えます。

これらの関数の使い方は、SDK の soracom_set_json_output() の実装を参考にしてください。

位置情報を取得

簡易位置測位機能が利用可能な SIM (plan-KM1) を利用している場合、以下の 3 つの関数を利用することで位置情報を取得することができます。

  • int32_t orbit_has_location() : 位置情報が取得可能かどうかを調べます。取得可能な場合は 1、取得できない場合は 0 が返ります。
  • double orbit_get_locatoin_lat() : 緯度の値を取得します。-90 ~ 90 の範囲の値を返します。正の値は北緯、負の値は南緯です。位置情報が存在しない場合の戻り値は不定です。
  • double orbit_get_locatoin_lon() : 経度の値を取得します。-180 ~ 180 の範囲の値を返します。正の値は東経、負の値は西経です。位置情報が存在しない場合の戻り値は不定です。

タイムスタンプ取得

入力データを受信したタイミングのタイムスタンプを取得することができます。

  • int64_t orbit_get_timestamp() : 入力データのタイムスタンプを取得します。

TinyGo

soracom/orbit-sdk-tinygo が SDK を提供します。

import sdk github.com/soracom/orbit-sdk-tinygo

提供する関数のシグネチャは以下の通りです。

  • func Log(msg string): ログを出力します。
  • func GetInputBuffer() ([]byte, error): WASM モジュールへの入力データを取得します。error は以下の通りです。
    • ErrNoInputBuffer: 入力データが取得できない
    • ErrInvalidInputBufferLength: 入力データの長さが不正
  • func GetTagValue(name string) ([]byte, error): データ送信元 (SIM) のタグの値を取得します。error は以下の通りです。
    • ErrNoTagValue: タブの値を取得できない
    • ErrInvalidTagValueLength: タグの値の長さが不正
  • func GetSourceValue(name string) ([]byte, error): データ送信元 (SIM) に関する値を取得します。見つからない場合は空白文字列を返します。error は以下の通りです。
    • ErrNoSourceValue: ソース値を取得できない
    • ErrInvalidSourceValueLength: ソース値の長さが不正
  • func SetOutputJSON(out string): WASM モジュールから出力する JSON をセットします。

位置情報を取得

簡易位置測位機能が利用可能な SIM (plan-KM1) を利用している場合、以下の 3 つの関数を利用することで位置情報を取得することができます。

  • func GetLocation() (*Location, error): error は以下の通りです。
    • ErrNoLocationInformation: 位置情報を取得できない

Location は以下の構造体です。

type Location struct {
	Lat float64 `json:"lat"`
	Lon float64 `json:"lon"`
}

タイムスタンプ取得

入力データを受信したタイミングのタイムスタンプを取得することができます。

  • func GetTimestamp() int64 : 入力データのタイムスタンプを取得します。