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_Movie は、1 秒毎に取得した前後の画像を比較し、前後の画像に大きな変更があった画像を SORACOM_ENV_WAIT 分のアニメーションとして SORACOM Harvest Files にアップロードします。また同時に SORACOM Harvest Data へ画像のメタ情報を送信します。（サンプルアルゴリズムを止めるまではデータ通信及び SORACOM Harvest Data, SORACOM Harvest Files を継続利用するため、サンプル試用後、必要がない場合には必ずサンプルアルゴリズムを削除（Uninstall）してください）。
Harvest Files ボタンをクリックすることで、サンプルアプリケーションが取得した画像を確認できます。このサンプルアルゴリズムの画像は SORACOM Harvest Files の /animation/{Mosaic ID} へタイムスタンプ毎に保存されます。画像を確認するためには、確認したい画像を選択して、Download をクリックするとダウンロードできます。取得した Webp 形式の画像は Web ブラウザー等で開いて確認できます。
Harvest Data ボタンをクリックすると、SORACOM Harvest Data から、画像を確認できます。
CameraAPP0 では SORACOM_ENV_MODE に応じて、アルゴリズムを切り替えることが可能です。こちらも SORACOM Harvest Files へ画像を、SORACOM Harvest Data へ画像のメタ情報を送信します。SORACOM_ENV_MODE とアルゴリズムの対応は以下の通りです。
| 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_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 のパッケージを予めアルゴリズムのアーカイブに含むことで、アルゴリズム実行時に毎回パッケージダウンロードをする必要がなくなります。
アルゴリズムパッケージに CameraApp0_custom_oma.xml を含むことで、アルゴリズムのパラメータを Mosaic Console から設定することが可能になります。
カメラへのアクセス方法
デバイスのカメラへは 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 ゲイン |
各値の詳細はこちらを参照してください。
- カメラの設定値を変更 PATCH(PUT):/v1/cameraStat
設定値の変更前に必ず /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 ゲイン |
カメラの撮影の有効化 GET: /v1/startCameraCapture 有効後 2 秒以上たってから、画像の取得を行ってください。
カメラの撮影の無効化 GET: /v1/stopCameraCapture 無効後は 3 秒以上経過してからカメラ API へアクセスしてください。
カメラ画像の取得 GET: /v1/cameraImage width x height x RGB の非圧縮データの取得。
Jpeg 画像取得 GET: /v1/cameraJpegImage quality で指定した圧縮率の Jpeg 画像取得。
カメラ画像 Webp 取得 API GET:/v1/cameraWebpImage quality で指定した圧縮率の Webp 画像取得。
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 に表示されている 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 = http://{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 Data の /cap/{MOSAIC ID} 以下から、定期的にアップロードされる画像を確認できます（webp ファイルは Chrome 等のブラウザから確認できます）。SORACOM Harvest Files, SORACOM Harvest Data 及び SORACOM Napter には別途費用が発生いたします。検証後は APP(CAMERAAPP0) メニュー からアルゴリズムの Uninstall 及び、SORACOM Harvest Files, SORACOM Harvest Data にアップロードされたデータの削除を行ってください。
アルゴリズムに渡すパラメータ
CameraApp0_custom_oma.xml に定義されている値を、アルゴリズムの環境変数として渡すことができます。現状 CameraApp0_custom_oma.xml を変更することはできません。パラメータとして渡すことのできる最大の文字数は 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" はデバイス再起動時に消えてしまうので、再度設定が必要です。
アルゴリズムをデプロイ後、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 ファイルのサイズを小さくしてください。
サンプルアルゴリズム一覧
現在提供されているサンプルアルゴリズムは次のとおりです。
| サンプルアルゴリズム名 | 説明 |
|---|---|
| CameraAPP0 | 0: 定期画像アップロード、100: 顔画像アップロード、101: 目線にモザイクを入れてアップロード |
| CameraAPP0_Movie | フレーム間で差分があった場合、アニメーション画像をアップロード |
| CameraAPP0_Null | 環境変数確認用 |
備考
SORACOM Harvest Files, SORACOM Harvest Data を使うサンプルアプリケーションは、継続してデータ送信を行うため、検証後必ず Uninstall してください。また SORACOM Harvest Files, SORACOM Harvest Data 及び SORACOM Napter には別途費用が発生いたします。
