MENU

Soracom

Users

アルゴリズムの更新方法

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

アルゴリズムの更新手順

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

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

  • デバイス詳細画面の App(CameraApp0) タブから、Install new algorithm… ボタンをクリックすると以下のようにアルゴリズムを選択するダイアグラムが表示されます。Check Environment settings を選択肢、Install ボタンをクリックしてアルゴリズムをインストールしてください。

アルゴリズムの更新

デバイスが offline -> online になればアルゴリズムの更新は終了です。サンプルアルゴリズムの内容を確認する場合は、Remote access などを利用して一度デバイスでダウンロードしたものを参照してください。

  • アルゴリズムが正しく更新されると図の様なパラメータを設定する画面が表示されます。 VALUE に任意の値をいれて Apply ボタンを押すと、与えられた値を環境変数及び SORACOM_EXEC_PARAM を引数としてアルゴリズムが再実行されます。

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

  • Download logs をクリックすると、アルゴリズムの実行ログをダウンロードできます。ログを解凍すると設定した値が出力されていることが確認できます。

ログダウンロード

  • Periodical Image UploadSORACOM_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 への保存場所
0SORACOM_ENV_WAIT 間隔で画像をアップロード/cap/{Mosaic ID}
100SORACOM_ENV_WAIT 間隔で人物の顔を検出した場合、画像をアップロード/face/{Mosaic ID}
101SORACOM_ENV_WAIT 間隔で人物を検出した場合、目線にモザイクをいれてアップロード/face/{Mosaic ID}

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

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

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

カメラへのアクセス方法

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

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

  • カメラの状態取得 GET: /v1/cameraState
curl --verbose http://127.0.0.1:8080/v1/cameraState
モード説明備考
capturingカメラのステータス0: 撮影をしていない
1: 撮影中
widthカメラ画像の幅
heightカメラ画像の高さ
framerateフレームレート
sharpnessシャープネス
contrastコントラスト
brightness明るさ
saturation彩度
ISOISO 感度
shutter_speedシャッタースピード
videoStabilisation画像安定化
exposureCompensation露出補正
exposureMode露出モード
exposureMeterMode測光モード
imageEffectイメージエフェクト
awbModeホワイトバランス
awb_gains_rホワイトバランス R ゲイン
awb_gains_bホワイトバランス B ゲイン

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

  • カメラの設定値を変更 PATCH(PUT):/v1/cameraState

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

モード説明備考
widthカメラ画像の横幅以下の解像度が設定可能
1640x1232
1640x922
1280x720
640x480
heightカメラ画像の高さ
framerateフレームレート
sharpnessシャープネス
contrastコントラスト
brightness明るさ
saturation彩度
ISOISO 感度
shutter_speedシャッタースピード
videoStabilisation画像安定化
exposureCompensation露出補正
exposureMode露出モード
exposureMeterMode測光モード
imageEffectイメージエッフェクト
awbModeホワイトバランス
awb_gains_rホワイトバランス R ゲイン
awb_gains_bホワイトバランス 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/deviceState
curl --verbose http://127.0.0.1:8080/v1/deviceState
モード説明
DeviceIDデバイス ID
Serial_Numberシリアル番号
Hardware_Versionハードウェアバージョン
Endpointエンドポイント
IMEIIMEI
IMSIIMSI
SIM_SerialSIM のシリアル番号
ICCIDICCID
mem_armメモリ容量 (Bytes)
Memory_Free空きメモリ容量 (Bytes)
Radio_Signal_Strength受信信号強度
Cell_IDCell ID
SMNCServing Mobile Network Code
SMCCServing Mobile Country Code
throttledRaspberry pi の CPU スロットル状態
measure_tempCPU 温度
measure_clock_armCPU 周波数
measure_volts_coreCPU 動作電圧 (Core)
measure_volts_sdram_cCPU 動作電圧 (SDRAM controller)
measure_volts_sdram_iCPU 動作電圧 (SDRAM I/O)
measure_volts_sdram_pCPU 動作電圧 (SDRAM physical)
  • カメラの撮影の有効化 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 を構築するディレクトリは必要に応じて変更してください)。

以下では 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 のモジュールのリストは こちら になります。こちらを 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 Basic の画像を取り込むためには、SORACOM Napter ( 月額費用別途)の設定が必要です。次の手順で、Mosaic のコンソールより、SORACOM Napter を設定してください。

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

    リモートアクセス

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

    リモートアクセス設定

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

    URL確認

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 にデプロイできます。

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

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

  • ダウンロードした開発用 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 にアップロードされたデータの削除を行ってください。

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

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