SORACOM Users

SORACOM Mosaic を用いたアルゴリズムの更新

ここでは、SORACOM Mosaic を利用して、S+ Camera Basic で動作するアルゴリズムの更新方法を説明します。

アルゴリズムの更新手順

予め用意されたサンプルアルゴリズムを用いて、アルゴリズムの更新方法について説明していきます。

最初のサンプルアルゴリズム(CameraApp0_Null)は、アルゴリズムに設定された変数を表示し、一定期間ごとに現在の時間をログに出力します。

こちらの CameraApp0_Null へのリンクを Install ボタンをクリックして PACKAGE URL へ設定し、Confirm ボタンをクリックしてください。デバイスが offline -> online になればアルゴリズムの更新は終了です。サンプルはデバイスからしかダウンロードできないため、内容を確認する場合は、Remote access などを利用して一度デバイスでダウンロードしたものを参照してください。

アルゴリズムの更新

アルゴリズムのパラメータ表示

VALUE に任意の値をいれて Apply ボタンを押すと、与えられた値を環境変数及び SORACOM_EXEC_PARAM を引数としてアルゴリズムが再実行されます。

変数の適用

ログダウンロード

Mode 説明 Harvest Files への保存場所
0 SORACOM_ENV_WAIT 間隔で画像をアップロード /cap/{Mosaic ID}
100 SORACOM_ENV_WAIT 間隔で人物の顔を検出した場合、画像をアップロード /face/{Mosaic ID}
101 SORACOM_ENV_WAIT 間隔で人物を検出した場合、目線にモザイクをいれてアップロード /face/{Mosaic ID}

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

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

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

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

{
    "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 のパッケージを予めアルゴリズムのアーカイブに含むことで、アルゴリズム実行時に毎回パッケージダウンロードをする必要がなくなります。

カメラへのアクセス方法

デバイスのカメラへは REST API を通じて制御できます。REST API へはデバイス内部からはhttp://127.0.0.1:8080, 遠隔からアクセする場合は SORACOM Napter を利用して 8080 ポートへの接続作成してください。SORACOM Napter は Remote access ボタンで作成可能です。

デバイスのカメラには次の様な API が用意されています。

モード 説明 備考
capturing カメラのステータス 0: 撮影をしていない
1: 撮影中
width カメラ画像の幅
height カメラ画像の高さ
framerate フレームレート
sharpness シャープネス
contrast コントラスト
brightness 明るさ
saturation 彩度
ISO ISO 感度
shutter_speed シャッタースピード
videoStabilisation 画像安定化
exposureCompensation 露出補正
exposureMode 露出モード
exposureMeterMode 測光モード
imageEffect イメージエフェクト
awbMode ホワイトバランス
awbgainsr ホワイトバランス R ゲイン
awbgainsb ホワイトバランス B ゲイン

各値の詳細はこちらを参照してください。

curl --verbose http://127.0.0.1:8080/v1/cameraState

設定値の変更前に必ず /v1/stopCameraCapture を実行してください。

モード 説明 備考
width カメラ画像の横幅 以下の解像度が設定可能
1640x1232
1640x922
1280x720
640x480
height カメラ画像の高さ
framerate フレームレート
sharpness シャープネス
contrast コントラスト
brightness 明るさ
saturation 彩度
ISO ISO 感度
shutter_speed シャッタースピード
videoStabilisation 画像安定化
exposureCompensation 露出補正
exposureMode 露出モード
exposureMeterMode 測光モード
imageEffect イメージエッフェクト
awbMode ホワイトバランス
awbgainsr ホワイトバランス R ゲイン
awbgainsb ホワイトバランス B ゲイン
curl --verbose http://127.0.0.1:8080/v1/cameraState -X PATCH -H "Content-Type: application/json" -d '{"width":640, "height":480}'

それぞれの解像度についてはこちらの画像を参考にしてください。

解像度

curl --verbose http://127.0.0.1:8080/v1/startCameraCapture
curl --verbose http://127.0.0.1:8080/v1/stopCameraCapture
curl http://127.0.0.1:8080/v1/cameraImage
curl -o /tmp/cameraJpegImage.jpg http://127.0.0.1:8080/v1/cameraJpegImage
curl -o /tmp/cameraWebpImage.webp http://127.0.0.1:8080/v1/cameraWebpImage

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

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

PC の開発環境の構築

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

# 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 のモジュールのリストはこちらになります。こちらを pip を用いてインストールしてください。

次に、アルゴリズムをデプロイするための環境を準備します。最初に jq コマンドをインストールしてください。次に 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 Basic の画像を取り込むためには、SORACOM Napter(月額費用別途)の設定が必要です。次の手順で、Mosaic のコンソールより、SORACOM Napter を設定してください。

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

SORACOM Napter の設定が終了したら、任意のブラウザーなどで、http://{コピーした URL}/v1/startCameraCapture へアクセシスてください。こちらは S+ Camera Basic の画像取得を有効にするためだけの 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 Basic にデプロイできます。

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

{デバイス 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 にアップロードされたデータの削除を行ってください。

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

アルゴリズムの環境変数として、決められた値を渡すことができます。パラメータとして渡すことのできる最大の文字数は 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

アルゴリズムをデプロイ後、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 ファイルのサイズを小さくしてください。

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

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

備考

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

参考資料

pagetop