Initial public release

Co-authored-by: Takashi Oguma <oguma@soracom.jp>
soracom · Dec 22, 2023 · 745c8b7 · 745c8b7
commit 745c8b7
Show file tree

Hide file tree

Showing 19 changed files with 835 additions and 0 deletions.
diff --git a/.cargo/config b/.cargo/config
@@ -0,0 +1,5 @@
+[net]
+git-fetch-with-cli = true
+
+[build]
+target = "wasm32-unknown-unknown"
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1,2 @@
+target/
+Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -0,0 +1,13 @@
+[package]
+name = "soracom-orbit-sdk"
+version = "1.0.0"
+authors = ["SORACOM"]
+edition = "2021"
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[dependencies]
+serde = "^1"
+serde_derive = "^1"
+serde_json = "^1"
+wee_alloc = "0.4"
diff --git a/LICENSE b/LICENSE
@@ -0,0 +1,7 @@
+Copyright (c) 2023 SORACOM, INC.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
diff --git a/README.md b/README.md
@@ -0,0 +1,35 @@
+# SORACOM Orbit SDK for Rust
+
+This is the SDK for Rust programming language for SORACOM Orbit.
+
+Please use it to generate WASM modules for data transformation processing in SORACOM Orbit from Rust language source code.
+
+## Prerequisites
+
+To compile the SDK itself, as well as programs using the SDK, [Rust](https://www.rust-lang.org/) toolchain is required. Please install it in advance.
+
+After installing Rust, please install the required WASM target:
+
+```console
+rustup target add wasm32-unknown-unknown
+```
+
+## Usage
+
+The `src` directory in this repository contains the SDK's source code. For more specific usage, please refer to each sample in the `examples` directory.
+
+## Examples
+
+The `examples` directory in this repository includes the following samples:
+
+- [`lte-m-button`](./examples/lte-m-button/)
+
+  A sample that adds auxiliary information to the data sent from the SORACOM LTE-M Button series ([SORACOM LTE-M Button Plus](https://soracom.jp/store/5207/) and [SORACOM LTE-M Button for Enterprise](https://soracom.jp/store/5206/)) and transmits it.
+
+- [`sensit`](./examples/sensit/)
+
+  A sample for working with data sent from [https://support.sigfox.com/docs/sens'it-v2-user-guide](https://soracom.jp/store/5235/).
+
+## License
+
+This SDK is released under the MIT License. For details, please see the [LICENSE](./LICENSE) file.
diff --git a/README_ja.md b/README_ja.md
@@ -0,0 +1,35 @@
+# SORACOM Orbit SDK for Rust
+
+SORACOM Orbit のための Rust 言語の SDK です。
+
+SORACOM Orbit でデータ変換処理を行うための WASM モジュールを Rust 言語のソースコードから生成する際にご利用ください。
+
+## 前提条件
+
+SDK 自体のコンパイル、および SDK を使ったプログラムのコンパイルには [Rust](https://www.rust-lang.org/) を利用します。事前にインストールしておいてください。
+
+Rust をインストールした後、以下のように WASM ターゲットをインストールしてください。
+
+```console
+rustup target add wasm32-unknown-unknown
+```
+
+## 利用方法
+
+このリポジトリの `src` ディレクトリに SDK のソースコードが含まれています。具体的な利用方法は `examples` ディレクトリの各サンプルをご参照ください。
+
+## 利用例
+
+このリポジトリの `examples` ディレクトリには以下のサンプルが含まれています。
+
+- [`lte-m-button`](./examples/lte-m-button/)
+
+  SORACOM LTE-M Button シリーズ ([SORACOM LTE-M Button Plus](https://soracom.jp/store/5207/) および [SORACOM LTE-M Button for Enterprise](https://soracom.jp/store/5206/)) から送られてくるデータに補助的な情報を追加して送信するサンプルです。
+
+- [`sensit`](./examples/sensit/)
+
+  [Sens'it](https://soracom.jp/store/5214/) から送られてくるデータを取り扱うサンプルです。
+
+## ライセンス
+
+この SDK は MIT ライセンスの下で公開されています。詳細については [LICENSE](./LICENSE) ファイルをご覧ください。
diff --git a/examples/lte-m-button/.cargo/config b/examples/lte-m-button/.cargo/config
@@ -0,0 +1,5 @@
+[net]
+git-fetch-with-cli = true
+
+[build]
+target = "wasm32-unknown-unknown"
diff --git a/examples/lte-m-button/Cargo.toml b/examples/lte-m-button/Cargo.toml
@@ -0,0 +1,16 @@
+[package]
+name = "lte-m-button"
+version = "0.1.0"
+authors = ["SORACOM"]
+edition = "2021"
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[lib]
+crate-type = ["cdylib"]
+
+[dependencies]
+serde = "^1"
+serde_derive = "^1"
+serde_json = "^1"
+soracom-orbit-sdk = { path = "../../" }
diff --git a/examples/lte-m-button/Makefile b/examples/lte-m-button/Makefile
@@ -0,0 +1,21 @@
+soralet_id ?= lte-m-button
+soracom_profile ?= default
+output = target/wasm32-unknown-unknown/release/lte_m_button.wasm
+
+.PHONY: create-soralet
+create-soralet:
+	soracom --profile $(soracom_profile) soralets create --soralet-id $(soralet_id)
+
+.PHONY: upload
+upload:
+	soracom --profile $(soracom_profile) soralets upload --soralet-id $(soralet_id) --content-type application/octet-stream --body @$(output)
+
+payload = '{"batteryLevel":1,"clickType":1,"clickTypeName":"SINGLE"}'
+
+.PHONY: test
+test:
+	soracom --profile $(soracom_profile) soralets exec --soralet-id $(soralet_id) --version "\$$LATEST" --direction uplink --content-type "application/json" --payload $(payload) --body @test-uplink.json
+
+.PHONY: log
+log:
+	soracom --profile $(soracom_profile) soralets get-logs --soralet-id $(soralet_id)
diff --git a/examples/lte-m-button/README.md b/examples/lte-m-button/README.md
@@ -0,0 +1,97 @@
+# SORACOM Orbit SDK for Rust - Sample for SORACOM LTE-M Button Series
+
+## Overview
+
+This is a sample code for processing data sent from the SORACOM LTE-M Button series ([SORACOM LTE-M Button Plus](https://soracom.jp/store/5207/) and [SORACOM LTE-M Button for Enterprise](https://soracom.jp/store/5206/)) using [SORACOM Orbit](https://soracom.jp/services/orbit/).
+
+Normally, the following JSON is sent from the SORACOM LTE-M Button series:
+
+```json
+{
+    "clickType":1,
+    "clickTypeName":"SINGLE",
+    "batteryLevel":1,
+    "binaryParserEnabled":true
+}
+```
+
+This sample code adds IMSI and name for identifying the SIM, and location information obtained through the [Simple Positioning Feature](https://users.soracom.io/ja-jp/docs/air/get-location-info/#%e3%83%87%e3%83%90%e3%82%a4%e3%82%b9%e3%81%ae%e7%b0%a1%e6%98%93%e7%9a%84%e3%81%aa%e4%bd%8d%e7%bd%ae%e6%83%85%e5%a0%b1-%e7%b0%a1%e6%98%93%e4%bd%8d%e7%bd%ae%e6%b8%ac%e4%bd%8d%e6%a9%9f%e8%83%bd-%e3%82%92%e9%80%81%e4%bf%a1%e3%81%99%e3%82%8b-plan-km1-%e3%81%ae%e3%81%bf) to transform it into the following JSON:
+
+```json
+{
+    "clickType":1,
+    "clickTypeName":"SINGLE",
+    "batteryLevel":1,
+    "binaryParserEnabled":true,
+    "imsi":"001019999999999",
+    "name":"test name",
+    "location":{
+        "lat":43.12345,
+        "lon":138.112233,
+    },
+    "time": 1702958495084,
+    "userdata": ""
+}
+```
+
+## How to Run
+
+1. Compile the source code.
+   ```
+   cargo build --release
+   ```
+
+2. Create a Soralet to be a container for the uploaded code (only for the first time).
+   ```
+   make create-soralet
+   ```
+   You need to create a SORACOM account and install [soracom-cli](https://github.com/soracom/soracom-cli) in advance.
+   If you want to use a profile other than the default, specify it as an argument:
+   ```
+   make create-soralet soracom_profile=${profile_name}
+   ```
+   By default, a Soralet with the ID `lte-m-button` is created. If you want to use a different ID, specify it like this:
+   ```
+   make create-soralet soralet_id=${soralet_id}
+   ```
+   You can specify both `soralet_id` and `soracom_profile` at the same time.
+
+3. Upload the compiled code.
+   ```
+   make upload
+   ```
+   To override the profile or Soralet ID, follow the same method as in step 3.
+
+4. Test the uploaded code.
+   ```
+   make test
+   ```
+   If you see the following result, it's successful:
+   ```json
+   {
+        "body": "{\"clickType\":1,\"clickTypeName\":\"SINGLE\",\"batteryLevel\":1,\"imsi\":\"001019999999999\",\"name\":\"test name\",\"location\":{\"lat\":43.12345,\"lon\":138.112233},\"timestamp\":1702958495084,\"userdata\":\"\"}",
+        "contentType": "application/json",
+        "encodingType": "plain",
+        "resultCode": 0
+   }
+   ```
+
+5. If it doesn’t work, check the logs.
+   ```
+   make log
+   ```
+   The log will be displayed like the following. You can check how far it has been executed or the values stored in variables by comparing it with the messages output by the `log()` function in the sample code.
+   ```json
+   [
+        {
+            "createdTime": 1702958495320,
+            "message": "hello, orbit!",
+            "operatorId": "OP00xxxxxxxx",
+            "soraletId": "lte-m-button",
+            "version": 2
+        },
+   ...
+   ]
+   ```
+
+6. Once you have confirmed the operation, link the uploaded Soralet to the LTE-M button group settings, and try pressing the button in reality. For details, please refer to the [User Documentation](https://developers.soracom.io/en/docs/orbit/configuration/).
diff --git a/examples/lte-m-button/README_ja.md b/examples/lte-m-button/README_ja.md
@@ -0,0 +1,99 @@
+# SORACOM Orbit SDK for Rust - SORACOM LTE-M Button シリーズ向けのサンプル
+
+## 概要
+
+SORACOM LTE-M Button シリーズ ([SORACOM LTE-M Button Plus](https://soracom.jp/store/5207/) および [SORACOM LTE-M Button for Enterprise](https://soracom.jp/store/5206/)) から送られてくるデータを [SORACOM Orbit](https://soracom.jp/services/orbit/) を使って加工するためのサンプルコードです。
+
+SORACOM LTE-M Button シリーズからは通常以下のような JSON が送られてきます。
+
+```json
+{
+    "clickType":1,
+    "clickTypeName":"SINGLE",
+    "batteryLevel":1,
+    "binaryParserEnabled":true
+}
+```
+
+ここに SIM を特定するための IMSI や名前を追加したり、[簡易位置即位機能](https://users.soracom.io/ja-jp/docs/air/get-location-info/#%e3%83%87%e3%83%90%e3%82%a4%e3%82%b9%e3%81%ae%e7%b0%a1%e6%98%93%e7%9a%84%e3%81%aa%e4%bd%8d%e7%bd%ae%e6%83%85%e5%a0%b1-%e7%b0%a1%e6%98%93%e4%bd%8d%e7%bd%ae%e6%b8%ac%e4%bd%8d%e6%a9%9f%e8%83%bd-%e3%82%92%e9%80%81%e4%bf%a1%e3%81%99%e3%82%8b-plan-km1-%e3%81%ae%e3%81%bf) により取得した位置情報を追加して、以下のような JSON に変換します。
+
+```json
+{
+    "clickType":1,
+    "clickTypeName":"SINGLE",
+    "batteryLevel":1,
+    "binaryParserEnabled":true,
+    "imsi":"001019999999999",
+    "name":"test name",
+    "location":{
+        "lat":43.12345,
+        "lon":138.112233,
+    },
+    "time": 1702958495084,
+    "userdata": ""
+}
+```
+
+## 実行方法
+
+1. ソースコードをコンパイルします。
+   ```
+   cargo build --release
+   ```
+
+2. コンパイルしたコードをアップロードするための受け皿となる Soralet を作成します。（最初の一度のみ）
+   ```
+   make create-soralet
+   ```
+   事前に SORACOM のアカウントを作成し、[soracom-cli](https://github.com/soracom/soracom-cli) をインストールしておく必要があります。
+   default 以外のプロファイルを使用したい場合は、
+   ```
+   make create-soralet soracom_profile=${profile_name}
+   ```
+   のように引数に指定します。
+
+   デフォルトでは `lte-m-button` という ID の Soralet を作成します。異なる ID を使用したい場合は
+   ```
+   make create-soralet soralet_id=${soralet_id}
+   ```
+   のように指定します。
+   `soralet_id` と `soracom_profile` は両方とも指定することもできます。
+
+3. コンパイルしたコードをアップロードします。
+   ```
+   make upload
+   ```
+   プロファイルや Soralet ID をオーバーライドしたい場合は 3. と同様です。
+
+4. アップロードしたコードをテストします。
+   ```
+   make test
+   ```
+   以下のような結果が表示されたら成功です。
+   ```json
+   {
+        "body": "{\"clickType\":1,\"clickTypeName\":\"SINGLE\",\"batteryLevel\":1,\"imsi\":\"001019999999999\",\"name\":\"test name\",\"location\":{\"lat\":43.12345,\"lon\":138.112233},\"timestamp\":1702958495084,\"userdata\":\"\"}",
+        "contentType": "application/json",
+        "encodingType": "plain",
+        "resultCode": 0
+   }
+   ```
+
+5. うまく行かない場合はログを確認します。
+   ```
+   make log
+   ```
+   以下のようにログが表示されます。サンプルコードの中の `log()` 関数で出力しているメッセージと見比べて、どこまで実行されているかを調べたり、変数の中に格納されている値を確認することができます。
+   ```json
+   [
+        {
+            "createdTime": 1702958495320,
+            "message": "hello, orbit!",
+            "operatorId": "OP00xxxxxxxx",
+            "soraletId": "lte-m-button",
+            "version": 2
+        },
+   ...
+   ```
+
+6．動作確認ができたら、LTE-M ボタンのグループ設定から今アップロードした Soralet を関連付け、実際にボタンを押してみましょう。詳細は [ユーザードキュメント](https://users.soracom.io/ja-jp/docs/orbit/running/) を参照してください。