Soracom Orbit

SDK Reference

You can find the latest version of the Soracom Orbit SDK in the Downloads section.

AssemblyScript

The orbit-sdk-assemblyscript module contains the Orbit AssemblyScript SDK. Import the module into your code in order to use the methods.

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

Function Signatures

Function Returns Description
log(message: string) void Output a string to the log. The logs are retained for up to 7 days.
getInputBuffer() Uint8Array Get the input data as an array of Uint8.
getInputBufferAsString() string Get the input data as a character string.
getTagValue(name: string) string Get the value of a tag from the data source (SIM). Returns an empty string if the tag name is not found.
setTagValue(name: string, value: string) void Create or update a tag from the data source (SIM).
deleteTag(name: string) void Delete a tag from the data source (SIM).
getSourceValue(name: string) string Get the value of an attribute from the data source (SIM). For name, specify one of the properties included in the source of the input to the WASM module (e.g., resourceType). Returns an empty string if the attribute is not found.
getLocation() Location: { lat: f64, lon: f64 } Get the Location object when using a plan-KM1 SIM. Returns NaN if the location is not available.
getTimestamp() i64 Get the timestamp when Orbit received input data.
getUserdata() string Get the userdata attribute of the Metadata Service.
getOriginalRequest() string Get request data from device. It retrieves the same data as when getInputBufferAsString() is called within uplink().
setOutputJSON(json: string) void Return JSON data to Orbit as the WASM module output data.

The SDK also includes functions that begin with the orbit_ prefix, which provide lower level functionality. These functions are wrapped in the methods above, which should be sufficient for most cases, however you can access these functions if you want to output in a format other than JSON:

Function Returns Description
orbit_set_output(json: i32, len: i32) void Return the data located in memory indicated by the pointer and length to Orbit as the WASM module output data.
orbit_set_output_content_type(type: i32, len: i32) void Return the data located in memory indicated by the pointer and length to Orbit as the WASM module output Content-Type.

Refer to the SDK implementation for how to use the setOutputJSON() function.

Rust

The orbit-sdk-rust crate contains the Orbit Rust SDK. Include it in your code in order to use the methods.

use soracom_orbit_sdk as orbit;

Function Signatures

Function Returns Description
log(message: &str) — Output a string to the log. The logs are retained for up to 7 days.
get_input_buffer() Vec<u8> Get the input data as a u8a vector.
get_tag_value(name: &str) String Get the value of a tag from the data source (SIM). Returns an empty string if the tag name is not found.
set_tag_value(name: &str, value: &str) — Create or update a tag from the data source (SIM).
delete_tag(name: &str) — Delete a tag from the data source (SIM).
get_source_value(name: &str) String Get the value of an attribute from the data source (SIM). For name, specify one of the properties included in the source of the input to the WASM module (e.g., resourceType). Returns an empty string if the attribute is not found.
get_location() Option<Location>: { lat: f64, lon: f64 } Get the Location object when using a plan-KM1 SIM. Returns None if the location is not available.
get_timestamp() i64 Get the timestamp when Orbit received input data.
get_userdata() String Get the userdata attribute of the Metadata Service.
get_original_request() String Get request data from device. It retrieves the same data as when get_input_buffer() is called within uplink().
set_output_json(jsonstr: &str_) — Return JSON data to Orbit as the WASM module output data.

The SDK also includes functions that begin with the orbit_ prefix, which provide lower level functionality. These functions are wrapped in the methods above, which should be sufficient for most cases, however you can access these functions if you want to output in a format other than JSON:

Function Returns Description
orbit_set_output(ptr: i32, len: i32) — Return the data located in memory indicated by the pointer and length to Orbit as the WASM module output data.
orbit_set_output_content_type(ptr: i32, len: i32) — Return the data located in memory indicated by the pointer and length to Orbit as the WASM module output Content-Type.

Refer to the SDK implementation for how to use the set_output_json() function.

C/C++

The orbit-sdk-c library contains the Orbit C/C++ SDK. Include it in your code in order to use the methods.

#include "soracom/orbit.h"

Function Signatures

Return Type Function Description
void soracom_log(const char* fmt, ...) Output a string to the log. The logs are retained for up to 7 days.
int32_t soracom_get_input_buffer_as_string(const char** buf, size_t* siz) Get the input data as a buffer. When you have finished using the input data, release the buffer using soracom_release_input_buffer() with the *buf pointer.
void soracom_release_input_buffer(const char* buf) deprecated Frees the memory allocated. Use soracom_release_buffer instead
void soracom_release_userdata(const char* buf) deprecated Frees the memory allocated. Use soracom_release_buffer instead
void soracom_release_buffer(const char* buf) Frees the memory allocated.
int32_t soracom_get_tag_value(const char* name, size_t name_len, const char** value, size_t* value_len) Get the value of a tag from the data source (SIM). Returns an empty string if the tag name is not found.
void soracom_set_tag_value(const char* name, const char** value) Create or update a tag from the data source (SIM).
void soracom_delete_tag_value(const char* name) Delete a tag from the data source (SIM).
int32_t soracom_get_source_value(const char* name, size_t name_len, const char** value, size_t* value_len) Get the value of an attribute from the data source (SIM). For name, specify one of the properties included in the source of the input to the WASM module (e.g., resourceType). Returns an empty string if the attribute is not found.
int32_t orbit_has_location() Check if the location information of a plan-KM1 SIM can be obtained. Returns 1 if it can be obtained, and 0 if it cannot.
double orbit_get_location_lat() Get the latitude value of the location information. Returns undefined if the location is not available.
double orbit_get_location_lon() Get the longitude value of the location information. Returns undefined if the location is not available.
int64_t orbit_get_timestamp() Get the timestamp when Orbit received input data.
int32_t soracom_get_userdata_as_string(const char** buf, size_t* siz) Get the userdata attribute of the Metadata Service.
int32_t soracom_get_original_request_as_string(const char** buf, size_t* siz) Get request data from device. It retrieves the same data as when soracom_get_input_buffer_as_string() is called within uplink().
void soracom_set_json_output(const char* buf, size_t siz) Return JSON data to Orbit as the WASM module output data.

The SDK also includes functions that begin with the orbit_ prefix, which provide lower level functionality. These functions are wrapped in the methods above, which should be sufficient for most cases, however you can access these functions if you want to output in a format other than JSON:

Return Type Function Description
void orbit_set_output(const char* buf, size_t siz) Return the data located in memory indicated by the pointer and length to Orbit as the WASM module output data.
void orbit_set_output_content_type(const char* buf, size_t siz) Return the data located in memory indicated by the pointer and length to Orbit as the WASM module output Content-Type.

Refer to the SDK implementation for how to use the soracom_set_json_output() function.

TinyGo

The Orbit TinyGo SDK is provided at soracom/orbit-sdk-tinygo. Import it in your code in order to use the methods.

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

Function Signatures

Function Returns Description
Log(msg string) — Output a string to the log. The logs are retained for up to 7 days.
GetInputBuffer() ([]byte, error) Get the input data as a buffer. Returns ErrNoInputBuffer or ErrInvalidInputBufferLength if error occurred.
GetTagValue(name string) ([]byte, error) Get the value of a tag from the data source (SIM). Returns ErrNoTagValue or ErrInvalidTagValueLength if error occurred.
SetTagValue(name string, value string) — Create or update a tag from the data source (SIM).
DeleteTag(name string) — Delete a tag from the data source (SIM).
GetSourceValue(name string) ([]byte, error) Get the value of an attribute from the data source (SIM). For name, specify one of the properties included in the source of the input to the WASM module (e.g., resourceType). Returns an empty string if the attribute is not found. Returns ErrNoSourceValue or ErrInvalidSourceValueLength if error occurred.
GetUserdata() ([]byte, error) Get the value of an attribute from the data source (SIM). Returns ErrNoUserData or ErrInvalidLength if error occurred.
GetOriginalRequest() ([]byte, error) Get request data from device. It retrieves the same data as when GetInputBuffer() is called within uplink().
GetLocation() (*Location, error) Get the Location object when using a plan-KM1 SIM. Location struct should be { Lat: _float64_, Lon: _float64_ }. Returns ErrNoLocationInformation if the location is not available.
GetTimestamp() int64 Get the timestamp when Orbit received input data.
SetOutputJSON(out string) — Return JSON data to Orbit as the WASM module output data.

Reference

Input Data

Input data from Soracom to the WASM module can be retrieved using the Orbit SDK.

Note that the data obtained by calling a "function to retrieve input data for the WASM module" (e.g., getInputBuffer() or getInputBufferAsString() in AssemblyScript) differs depending on whether it is called from within uplink() or downlink().

When called by uplink()

uplink() is a function that transforms data sent from the device to Soracom.

When a function to retrieve input data for the WASM module is called within uplink(), one of the following types of data may be obtained:

When called by downlink()

downlink() is a function that transforms data being sent from the destination back to the device.

When a function to retrieve input data for the WASM module is called within downlink(), it returns the data received from the destination.

The Binary Parser cannot process data being sent from the destination back to the device.

You can also retrieve data that was sent from the device to Soracom within downlink(). For example, in AssemblyScript, you can call getOriginalRequest().