Soracom

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

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

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

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

AssemblyScript

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

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

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

• log(message: string): void: ログを出力します。文字列のみサポートします。ログは最大 7 日間保管されます。
• getInputBuffer(): Uint8Array: WASM モジュールへの入力データ を Uint8 の配列として取得します。
• getInputBufferAsString(): string: WASM モジュールへの入力データ を文字列として取得します。
• getTagValue(name: string): string: データ送信元 (IoT SIM) の タグ の値を取得します。タグ名が見つからない場合は空白文字列を返します。
• setTagValue(name: string, value: string): void: データ送信元 (IoT SIM) のタグを作成、または更新します。
• deleteTag(name: string): void: データ送信元 (IoT SIM) のタグを削除します。
• getSourceValue(name: string): string: データ送信元 (IoT SIM) に関する値を取得します。name には、WASM モジュールへの入力 の source に含まれるプロパティのいずれか (例: resourceType) を指定できます。なお、値が見つからない場合は空白文字列を返します。
• getLocation(): Location: 簡易位置測位機能が利用可能な IoT SIM (plan-KM1) を利用している場合は Location オブジェクト ({lat: f64, lon: f64}) を返します。利用できない場合は NaN が返ります。
• getTimestamp(): i64: 入力データのタイムスタンプ (Orbit がデータを受信したタイミング) を取得します。
• getUserdata(): string: メタデータサービスのユーザーデータ を取得します。
• getOriginalRequest(): string: デバイスから SORACOM に送信したデータを取得します。uplink() で getInputBufferAsString() を呼び出したときと同じデータを取得できます。
• setOutputJSON(json: string): void: WASM モジュールの処理結果として出力する JSON をセットします。

Rust

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

use soracom_orbit_sdk as orbit;

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

• log(message: &str): ログを出力します。文字列のみサポートします。ログは最大 7 日間保管されます。
• get_input_buffer() -> Vec<u8>: WASM モジュールへの入力データ を u8 のベクターとして取得します。
• get_tag_value(name: &str) -> String: データ送信元 (IoT SIM) の タグ の値を取得します。タグ名が見つからない場合は空白文字列を返します。
• set_tag_value(name: &str, value: &str): データ送信元 (IoT SIM) のタグを作成、または更新します。
• delete_tag(name: &str): データ送信元 (IoT SIM) のタグを削除します。
• get_source_value(name: &str) -> String: データ送信元 (IoT SIM) に関する値を取得します。name には、WASM モジュールへの入力 の source に含まれるプロパティのいずれか (例: resourceType) を指定できます。なお、値が見つからない場合は空白文字列を返します。
• get_location() -> Option<Location>: 簡易位置測位機能が利用可能な IoT SIM (plan-KM1) を利用している場合は Location オブジェクト ({lat: f64, lon: f64}) を返します。利用できない場合は None が返ります。
• get_timestamp() -> i64: 入力データのタイムスタンプ (Orbit がデータを受信したタイミング) を取得します。
• get_userdata() -> String: メタデータサービスのユーザーデータ を取得します。
• get_original_request() -> String: デバイスから SORACOM に送信したデータを取得します。uplink() で get_input_buffer() を呼び出したときと同じデータを取得できます。
• set_output_json(json_str: &str): WASM モジュールから出力する JSON をセットします。

サンプル

データに含まれるデバイス ID をキーに追加する

同一の IoT SIM から、デバイスごとに異なる以下のような JSON 形式のデータが送信される場合に、Orbit で JSON のキーを変更できます。

デバイス 1234A から送信されるデータ:

{ "device_id": "1234A", "value": 5.67 }

デバイス 5678B から送信されるデータ:

{ "device_id": "5678B", "value": 9.01 }

Orbit で変換したあとのデータ:

{ "value_1234A": 5.67 }

{ "value_5678B": 9.01 }

上記の変換を実現するサンプルコード:

#[macro_use] extern crate serde_derive;
use soracom_orbit_sdk as orbit;
use std::collections::HashMap;

type Error = Box<dyn std::error::Error + Send + Sync + 'static>;

#[repr(i32)]
#[derive(Debug)]
pub enum ErrorCode {
    Ok = 0,
    ExecError = -1,
}

#[derive(Deserialize)]
struct Input {
    axis: f32,
    device_id: String
}

#[no_mangle]
pub fn uplink() -> ErrorCode {
    let buf = orbit::get_input_buffer();
    let output = process_uplink(buf);
    if let Err(e) = output {
        orbit::log(format!("{}", e).as_str());
        return ErrorCode::ExecError;
    }
    let output = output.unwrap();

    orbit::set_output_json(output.as_str());

    ErrorCode::Ok
}

fn process_uplink(buf: Vec<u8>) -> Result<String, Error> {
    let input: Input = serde_json::from_slice(buf.as_ref())?;

    let mut output = HashMap::new();
    let key = format!("axis_{}", input.device_id);
    output.insert(key, input.axis);

    let output_json = serde_json::to_string(&output)?;

    Ok(output_json)
}

C/C++

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

#include "soracom/orbit.h"

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

• void soracom_log(const char* fmt, ...): ログを出力します。文字列のみサポートします。ログは最大 7 日間保管されます。
• int32_t soracom_get_input_buffer_as_string(const char** buf, size_t* siz): WASM モジュールへの入力データ を取得します。入力データを使い終わったら *buf のポインタは次の soracom_release_buffer() で解放してください。
• (deprecated) void soracom_release_input_buffer(const char* buf): 確保されたメモリを解放します。soracom_release_buffer() を使用してください。
• (deprecated) void soracom_release_userdata(const char* buf): 確保されたメモリを解放します。soracom_release_buffer() を使用してください。
• void soracom_release_buffer(const char* buf): 確保されたメモリを解放します。
• int32_t soracom_get_tag_value(const char* name, size_t name_len, const char** value, size_t* value_len): データ送信元 (IoT SIM) の タグ の値を取得します。タグ名が見つからない場合は空白文字列を返します。
• void soracom_set_tag_value(const char* name, const char* value): データ送信元 (IoT SIM) のタグを作成、または更新します。
• void soracom_delete_tag(const char* name): データ送信元 (IoT SIM) のタグを削除します。
• int32_t soracom_get_source_value(const char* name, size_t name_len, const char** value, size_t* value_len): データ送信元 (IoT SIM) に関する値を取得します。name には、WASM モジュールへの入力 の source に含まれるプロパティのいずれか (例: resourceType) を指定できます。なお、値が見つからない場合は空白文字列を返します。
• int32_t soracom_get_userdata_as_string(const char** buf, size_t* siz): メタデータサービスのユーザーデータ を取得します。
• int32_t soracom_get_original_request_as_string(const char** buf, size_t* siz): デバイスから SORACOM に送信したデータを取得します。uplink() で soracom_get_input_buffer_as_string() を呼び出したときと同じデータを取得できます。
• void soracom_set_json_output(const char* buf, size_t siz): WASM モジュールから出力する JSON をセットします。

TinyGo

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

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

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

• func Log(msg string): ログを出力します。文字列のみサポートします。ログは最大 7 日間保管されます。

• func GetInputBuffer() ([]byte, error): WASM モジュールへの入力データ を取得します。

  • error は以下のいずれかです。
    • ErrNoInputBuffer: 入力データが取得できない。
    • ErrInvalidInputBufferLength: 入力データの長さが不正。

• func GetTagValue(name string) ([]byte, error): データ送信元 (IoT SIM) の タグ の値を取得します。

  • error は以下のいずれかです。
    • ErrNoTagValue: タグの値を取得できない。WASM モジュールへの入力 に tags を利用するには、SIM グループ設定の [SORACOM Orbit 設定] → [メタデータ] にチェックを入れます。詳しくは、通信で WASM モジュールが使用されるように SIM グループを設定する を参照してください。
    • ErrInvalidTagValueLength: タグの値の長さが不正。

• func SetTagValue(name string, value string): データ送信元 (IoT SIM) のタグを作成、または更新します。

• func DeleteTag(name string): データ送信元 (IoT SIM) のタグを削除します。

• func GetSourceValue(name string) ([]byte, error): データ送信元 (IoT SIM) に関する値を取得します。name には、WASM モジュールへの入力 の source に含まれるプロパティのいずれか (例: resourceType) を指定できます。なお、値が見つからない場合は空白文字列を返します。

  • error は以下のいずれかです。
    • ErrNoSourceValue: ソース値を取得できない。
    • ErrInvalidSourceValueLength: ソース値の長さが不正。

• func GetUserdata() ([]byte, error): メタデータサービスのユーザーデータ を取得します。

  • error は以下のいずれかです。
    • ErrNoUserData: ソース値を取得できない。
    • ErrInvalidLength: ソース値の長さが不正。

• func GetOriginalRequest() ([]byte, error): デバイスから SORACOM に送信したデータを取得します。uplink() で GetInputBuffer() を呼び出したときと同じデータを取得できます。

  • error は以下のいずれかです。
    • ErrNoOriginalRequest: ソース値の長さが不正。
    • ErrInvalidLength: ソース値の長さが不正。

• func SetOutputJSON(out string): WASM モジュールから出力する JSON をセットします。

位置情報を取得

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

• func GetLocation() (*Location, error):

  • Location は以下の構造体です。

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

  • error は以下のとおりです。

    • ErrNoLocationInformation: 位置情報を取得できない。WASM モジュールへの入力 に location を利用するには、SIM グループ設定の [SORACOM Orbit 設定] → [簡易位置測位機能] にチェックを入れます。詳しくは、通信で WASM モジュールが使用されるように SIM グループを設定する を参照してください。

タイムスタンプ取得

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

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