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 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 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(json_str: &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 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-tinygoFunction 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 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:
- Data sent from the device to Soracom.
- Data sent from the device to Soracom that has been processed by the Binary Parser.
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 callgetOriginalRequest().