Soracom

Users

ドキュメント
フィードバック
Home ドキュメント SORACOM Orbit リファレンス

SORACOM 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: データ送信元 (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: メタデータサービスのユーザーデータ を取得します。
  • 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: データ送信元 (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: メタデータサービスのユーザーデータ を取得します。
  • 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() の実装を参考にしてください。

サンプル

サンプルコードの利用について
  • サンプルコードは、Orbit の使いかたを紹介することを目的として提供されています。SORACOM サポートではサポートを行いません。
  • サンプルコードを実行したことによる利用者自身、もしくは第三者が被った損害に対して、直接的、間接的を問わず、株式会社ソラコムは責任を負いかねます。

データに含まれるデバイス 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, ...): ログを出力します。
  • 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): データ送信元 (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): メタデータサービスのユーザーデータ を取得します。
  • 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() の実装を参考にしてください。

位置情報を取得

簡易位置測位機能が利用可能な IoT 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): データ送信元 (IoT SIM) のタグの値を取得します。error は以下の通りです。

    • ErrNoTagValue: タブの値を取得できない
    • ErrInvalidTagValueLength: タグの値の長さが不正

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

    error は以下のいずれかです。

    • ErrNoSourceValue: ソース値を取得できない
    • ErrInvalidSourceValueLength: ソース値の長さが不正

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

位置情報を取得

簡易位置測位機能が利用可能な IoT 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 : 入力データのタイムスタンプを取得します。
© 2015-2024 SORACOM
最終更新日: 2024-04-18
そのほかの使いかた : Visual Studio Code 拡張機能と SORACOM API Sandbox の利用
リファレンス : SORACOM Resource Name (SRN)
会社概要 プレスルーム お問い合わせ プライバシー 商標 特定商取引法 契約約款
Facebook Twitter Speaker Deck YouTube Blog