Soracom

Users

ドキュメント

独自のアルゴリズムを開発する

S+ Camera シリーズ では、エッジコンピューターで撮影した画像や動画を処理するアプリケーションを「アルゴリズム」と呼びます。

アルゴリズム開発に必要なファイル 

サンプルアルゴリズムの アーカイブ には次のファイルが含まれます。

  • info.json: バージョン情報ファイル
  • CameraApp0: 実行モジュール
  • CameraApp.py: アルゴリズムの本体
  • PreSetup: アルゴリズム実行前に実行するスクリプト
Public Beta 以降は CameraApp0_custom_oma.xml は不要となりました。

CameraApp0.py 以外のファイル名は必ずサンプルと同一の物をご利用ください。ファイル名を変更した場合には、デバイスでアルゴリズムが実行されません。

info.json には以下の値を設定する必要があります。

  • PkgApp: CameraApp0 (固定値なので必ずこの名前をご利用ください。)
  • PkgName: 任意の名前を設定してください。
  • PkgVersion: 任意のバージョンを設定してください。
  • PkgIdentifier: 任意のアルゴリズムの識別情報を設定してください。
  • サンプル:
{
  "PkgApp": "CameraApp0",
  "PkgName": "CameraApp0 Sample",
  "PkgVersion": "1.0.0",
  "PkgIdentifier": "io.soracom.CameraApp0"
}

デバイスでは CameraApp0 が実行されるので、実行ファイル名はかならず CameraApp0 にしてください。アルゴリズムに Python を利用する場合には一行目に次のように記述をすることで利用可能になります。

#!/opt/soracom/python/bin/python

サンプルアルゴリズムでは、CameraApp0 から CameraApp.py をインクルードすることによって、アルゴリズム本体を CameraApp.py に記述しています。

PreSetup はアルゴリズムの実行前に実行されるスクリプトです。サンプルのように pip freeze を実行することで、現在インストールされている Python のパッケージのリストを出力し Download logs ボタンをクリックして、出力されたリストを確認できます。PreSetup はアルゴリズム起動時に毎回実行されます。

Python Module をインストールする場合には、pip install xxx -t ./ などにより、Python のパッケージを予めアルゴリズムのアーカイブに含むことで、アルゴリズム実行時に毎回パッケージダウンロードをする必要がなくなります。

カメラへのアクセス方法 

デバイスのカメラは API を呼び出して操作できます。詳しくは、S+ Camera Basic が提供する API を参照してください。

PC を用いたアルゴリズムの開発 

S+ Camera シリーズ のカメラ画像は、デバイスの REST API 経由で取得できます。こちらを利用することによってご自身の PC へ S+ Camera シリーズ の画像を取り込んで、アルゴリズムを開発できます。なお PC への画像の取り込みは通信料が発生いたします。

PC の開発環境の構築 

ご自身の PC でアルゴリズムの開発する場合、pyenv と venv を利用して、S+ Camera シリーズ と同様の python の runtime 環境を事前に準備してください。pyenv と venv を使用しての runtime 環境の構築は次の様にして行います (venv を構築するディレクトリは必要に応じて変更してください)。

以下では macOS を利用した際のコマンド実行手順を記載しております。Windows での開発の際は、Windows Subsystem for Linux (WSL) をお使いいただければ同様のコマンドで開発環境の構築ができます。
# pyenvの環境を構築
git clone https://github.com/yyuu/pyenv.git $HOME/.pyenv
export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"

# python 3.7.3をインストール
pyenv install 3.7.3
pyenv local 3.7.3
pyenv rehash

# venvの環境を構築
sudo mkdir -p /opt/soracom/python/
self=$(whoami)
sudo chown -R $self /opt/soracom/
python -m venv /opt/soracom/python/
source /opt/soracom/python/bin/activate

Python の runtime 環境の構築完了後、SORACOM Mosaic に必要な Python のモジュールをインストールします。Python のモジュールのリストは、SORACOM Mosaic Python module 一覧 を参照してください。こちらを pip を用いてインストールしてください。

次に、アルゴリズムをデプロイするための環境を準備します。最初に jq コマンド をインストールしてください。次に SORACOM CLI のインストール SORACOM CLI 利用ガイド を参照して、soracom-cli のインストールと初期設定をしてください。最後に SORACOM Mosaic のデプロイツールを こちら からダウンロードして、適切な場所で解凍してください。解凍したディレクトリで、次のコマンドが実行できることを確認してください。

$ soracom
A command line tool to invoke SORACOM API
省略

$ jq
jq - commandline JSON processor [version 1.x]

$ mosaic_deploy.sh
Please set the parameters.
Example. mosaic_deploy.sh /git/surplus/CameraApp/CameraApp0

以上で開発環境の構築は終了です。

遠隔から画像を取り込む 

遠隔から S+ Camera シリーズ の画像を取り込むためには、SORACOM Napter (月額費用別途 ) の設定が必要です。次の手順で、Mosaic のコンソールより、SORACOM Napter を設定してください。

  1. Mosaic コンソールより、Enable remote access を選択。

    リモートアクセス

  2. デバイスのポートを 8080 に設定し Confirm を押す。

    リモートアクセス設定

  3. HTTP(s) に表示されている URL をコピーしてください。

    URL確認

SORACOM Napter の詳細については SORACOM Napter を参照ください。

SORACOM Napter の設定が終了したら、任意のブラウザなどで、http://{コピーした URL}/v1/startCameraCapture アクセスしてください。こちらは S+ Camera シリーズ の画像取得を有効にするためだけの API なので、実行してもブラウザの画面には何も表示されません。この設定をしたのちに http://{コピーした URL}/v1/cameraJpegImage へアクセスすると、カメラの画像がブラウザ上に表示されます。

アルゴリズムの開発 

定期的に SORACOM Harvest Files に画像をアップロードするサンプルアルゴリズムを用いて PC 環境でのアルゴリズムの開発方法を説明します。サンプルアルゴリズムは こちら からダウンロードしてください。

環境変数 DEVICE_INTERFACE_URI に、カメラ画像の確認で使用した Napter の URL を設定してください。

# 環境変数の設定
export DEVICE_INTERFACE_URI = https://{Napter で設定した URL}

# 先ほどダウンロードしたサンプルのディレクトリに移動
cd ${sample_dir}

# カメラアプリを実行する。
./CameraApp0

# 画像の確認
/tmp ディレクトリに定期的にカメラ画像が保存されます。
DEBUG_MONITOR を有効にした場合、ディスプレイに画像が表示されます。

アルゴリズムのデプロイメント 

開発したアルゴリズムは次の様にして S+ Camera シリーズ にデプロイできます。

  • アルゴリズムの tgz ファイルの作成
  • アルゴリズムの tgz ファイルを Harvest Files へアップロード
  • デバイスへのインストール
  • アルゴリズム、または、SORACOM Inventory Agent のリスタート

PC の開発環境の構築 でダウンロードした開発用の CLI を利用することによって、これらを自動化できます。先ほどダウンロードした開発用のアルゴリズムを S+ Camera シリーズ にデプロイしてみましょう。

  • ダウンロードした開発用 CLI のディレクトリに移動
  • CameraAPP.pyDEBUG_MODE を False に設定して保存します。
  • ./mosaic_deploy.sh -d {デバイス ID} {ダウンロードしたアルゴリズムへのパス}

{デバイス ID} は、Mosaic のコンソールに表示されている DEVICE ID を指定ください。{ダウンロードしたアルゴリズムへのパス} は、アルゴリズムを格納したディレクトリをフルパスで指定ください。任意のファイルを追加する場合には、. (ドット) で始まるファイルは使用しないでください。システム側で上書きされる場合がございます。

例えば /opt/soracom/bin/mosaic_deploy.sh があり、/var/tmp/CameraApp_Devel をデプロイしたい場合には次の様なコマンドになります (デバイス ID を指定しなかった場合には、コマンドを実行した端末の /tmp ディレクトリに、アルゴリズムの tgz ファイルが作成されます。)。

cd /opt/soracom/bin
./mosaic_deploy.sh -d {デバイス ID} /var/tmp/CameraApp_Devel

次の様に出力されればデプロイは完了です (アルゴリズムは Harvest Files の /SORACOM-Mosaic/CameraApp0/ にアップロードされます)。

Show PkgName.
PkgName="CameraApp Devel"
Show PkgVersion
PkgVersion="1.0.0"
Restart application

デプロイが成功すると SORACOM Mosaic の APP(CAMERAAPP0) メニュー にも同様の情報が表示されます。SORACOM Mosaic から Harvest Data をクリックすると、デプロイしたアルゴリズムがアップロードした情報を確認できます。同様に Harvest Files の /cap/{MOSAIC ID} 以下から、定期的にアップロードされる画像を確認できます (webp ファイルは Chrome 等のブラウザから確認できます)。SORACOM Harvest Files, SORACOM Harvest Data および SORACOM Napter には別途費用が発生いたします。検証後は APP(CAMERAAPP0) メニュー からアルゴリズムの Uninstall および、SORACOM Harvest Files, SORACOM Harvest Data にアップロードされたデータの削除を行ってください。

SORACOM Harvest Files, SORACOM Harvest Data を使うサンプルアプリケーションは、継続してデータ送信を行うため、検証後必ず Uninstall してください。また SORACOM Harvest Files, SORACOM Harvest Data および SORACOM Napter には別途費用が発生いたします。

アルゴリズムに渡すパラメータ 

アルゴリズムの環境変数として、決められた値を渡すことができます。パラメータとして渡すことのできる最大の文字数は 255 文字になります。例えば SORACOM_ENV_FREE_PARAMjson を渡して、アルゴリズム内で利用する方法は次の様になります。

{ "upload_begin_time": 0, "upload_end_time": 24 }
FREE_PARAM = os.getenv('SORACOM_ENV_FREE_PARAM', {})
FREE_PARAM_OBJECT = json.loads(FREE_PARAM)
UPLOAD_TIME_LIMIT_JST_BEGIN = FREE_PARAM_OBJECT.get('upload_begin_time', 0)
UPLOAD_TIME_LIMIT_JST_END = FREE_PARAM_OBJECT.get('upload_end_time', 24)

アルゴリズム開発の参考になるレシピ 

アルゴリズム開発の参考になるレシピをご用意しております。

トラブルシューティング 

デバイス内部の “/tmp/io.soracom.mosaic.debug.CameraApp0” にファイルを作成することで、次回アルゴリズム起動時、 “/tmp/io.soracom.mosaic.debug.CameraApp0.log” に Download logs と同様のログが出力される様になります。アルゴリズムは Device control の Restart Inventory Agent ボタン、またはまたはデバイス内で sudo systemctl restart soracom-inventoryagent をすることで再起動できます。"/tmp/io.soracom.mosaic.debug.CameraApp0" はデバイス再起動時に消えてしまうので、再度設定が必要です。ファイルに出力される最大出力サイズは 10MB になります。 具体的には、SORACOM Napter 経由でデバイスにログインいただき以下のコマンドを実行ください。

touch /tmp/io.soracom.mosaic.debug.CameraApp0
sudo systemctl restart soracom-inventoryagent.service
touch /tmp/io.soracom.mosaic.debug.CameraApp0.log
tail -f /tmp/io.soracom.mosaic.debug.CameraApp0.log

アルゴリズムをデプロイ後、IoT SIM はオンラインなのに、デバイスがオフラインになってしまった場合、SORACOM Napter を利用して、デバイス内で次のコマンドを実行して、アルゴリズムの削除を行ってください。

sudo systemctl stop soracom-inventoryagent
sudo rm /opt/soracom/data/InventoryAgent/CameraApp0_custom_oma.md5
sudo rm /opt/soracom/data/InventoryAgent/CameraApp0_custom_oma_params.json
sudo rm /opt/soracom/data/InventoryAgent/state.json
sudo rm -r /opt/soracom/bin/CameraApp0/

アルゴリズムのアップデートに 10 分以上かかる場合にはタイムアウトによりアルゴリズムの更新が失敗します。その場合には一部ファイルを Presetup スクリプトでダウンロードするなどして、アルゴリズムの tgz ファイルのサイズを小さくしてください。

サンプルアルゴリズム一覧 

現在提供されているサンプルアルゴリズムについては サンプルアルゴリズム一覧 を参照してください。