SORACOM Mosaic を用いたアルゴリズムの更新
ここでは、SORACOM Mosaic を利用して、S+ Camera Basic で動作するアルゴリズムの更新方法を説明します。
アルゴリズムの更新手順
予め用意されたサンプルアルゴリズムを用いて、アルゴリズムの更新方法について説明していきます。
最初のサンプルアルゴリズム（CameraApp0_Null）は、アルゴリズムに設定された変数を表示し、一定期間ごとに現在の時間をログに出力します。
- デバイス詳細画面の App(CameraApp0) ボタンをクリック
こちらの CameraApp0_Null へのリンクを Install ボタンをクリックして PACKAGE URL へ設定し、Confirm ボタンをクリックしてください。デバイスが offline -> online になればアルゴリズムの更新は終了です。サンプルはデバイスからしかダウンロードできないため、内容を確認する場合は、Remote access などを利用して一度デバイスでダウンロードしたものを参照してください。
- アルゴリズムが正しく更新されると、PACKAGE NAME や PACKAGE VERSION などに値が表示され、図の様なパラメータを設定する画面が表示されます。
VALUE に任意の値をいれて Apply ボタンを押すと、与えられた値を環境変数及び SORACOM_EXEC_PARAM を引数としてアルゴリズムが再実行されます。
- Download logs をクリックすると、アルゴリズムの実行ログをダウンロードできます。ログを解凍すると設定した値が出力されていることが確認できると思います。
CameraAPP0 は SORACOM_ENV_WAIT 毎に SORACOM Harvest Files に画像をアップロードします。同時に SORACOM Harvest Data へ画像のメタ情報を送信するため SORACOM Harvest Data を有効にしてください。SORACOM Mosaic から Harvest Data をクリックすると、デプロイしたアルゴリズムがアップロードした情報を確認できます。
- CameraAPP0 では、SORACOM_ENV_MODE に応じて、動作を切り替えることが可能です。SORACOM_ENV_MODE とアルゴリズムの対応は以下の通りです。Harvest Files ボタンをクリックすると、結果の画像を確認できます。
| Mode | 説明 | Harvest Files への保存場所 |
|---|---|---|
| 0 | SORACOM_ENV_WAIT 間隔で画像をアップロード | /cap/{Mosaic ID} |
| 100 | SORACOM_ENV_WAIT 間隔で人物の顔を検出した場合、画像をアップロード | /face/{Mosaic ID} |
| 101 | SORACOM_ENV_WAIT 間隔で人物を検出した場合、目線にモザイクをいれてアップロード | /face/{Mosaic ID} |
アルゴリズム開発に必要なファイル
サンプルアルゴリズムのアーカイブには次のファイルが含まれます。
- info.json: バージョン情報ファイル
- CameraApp0: 実行モジュール
- CameraApp.py: アルゴリズムの本体
- PreSetup: アルゴリズム実行前に実行するスクリプト
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 のパッケージを予めアルゴリズムのアーカイブに含むことで、アルゴリズム実行時に毎回パッケージダウンロードをする必要がなくなります。
カメラへのアクセス方法
デバイスのカメラへは REST API を通じて制御できます。REST API へはデバイス内部からはhttp://127.0.0.1:8080, 遠隔からアクセする場合は SORACOM Napter を利用して 8080 ポートへの接続作成してください。SORACOM Napter は Remote access ボタンで作成可能です。
デバイスのカメラには次の様な API が用意されています。
- カメラの状態取得 GET: /v1/cameraState
| モード | 説明 | 備考 |
|---|---|---|
| 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
- カメラの設定値を変更 PATCH(PUT):/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}'
それぞれの解像度についてはこちらの画像を参考にしてください。
- カメラの撮影の有効化 GET: /v1/startCameraCapture 有効後 2 秒以上たってから、画像の取得してください。
curl --verbose http://127.0.0.1:8080/v1/startCameraCapture
- カメラの撮影の無効化 GET: /v1/stopCameraCapture 無効後は 3 秒以上経過してからカメラ API へアクセスしてください。
curl --verbose http://127.0.0.1:8080/v1/stopCameraCapture
- カメラ画像の取得 GET: /v1/cameraImage width x height x RGB の非圧縮データの取得。
curl http://127.0.0.1:8080/v1/cameraImage
- Jpeg 画像取得 GET: /v1/cameraJpegImage quality で指定した圧縮率の Jpeg 画像取得。
curl -o /tmp/cameraJpegImage.jpg http://127.0.0.1:8080/v1/cameraJpegImage
- カメラ画像 Webp 取得 API GET:/v1/cameraWebpImage quality で指定した圧縮率の Webp 画像取得。
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 を設定してください。
Mosaic コンソールより、Remote access を選択。
デバイスのポートを 8080 に設定し Confirm を押す。
HTTP(s) に表示されている URL をコピーしてください。
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 にデプロイできます。
- アルゴリズムの tgz ファイルの作成
- アルゴリズムの tgz ファイルを Harvest Files へアップロード
- デバイスへのインストール
- アルゴリズム、または、SORACOM Inventory Agent のリスタート
PC の開発環境の構築でダウンロードした開発用の CLI を利用することによって、これらを自動化できます。先ほどダウンロードした開発用のアルゴリズムを S+ Camera Basic にデプロイしてみましょう。
- ダウンロードした開発用 CLI のディレクトリに移動
- CameraAPP.py の DEBUG_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 にアップロードされたデータの削除を行ってください。
アルゴリズムに渡すパラメータ
アルゴリズムの環境変数として、決められた値を渡すことができます。パラメータとして渡すことのできる最大の文字数は 255 文字になります。例えば SORACOM_ENV_FREE_PARAM に json を渡して、アルゴリズム内で利用する方法は次の様になります。
{"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 には別途費用が発生いたします。
