Soracom

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

ここでは、PC を利用して独自のアルゴリズムを開発する手順を説明します。

独自アルゴリズムの開発環境を準備する

S⁺ Camera シリーズ にインストールされている Python の実行環境を PC に再現します。これを「独自アルゴリズムの開発環境」と呼びます。

必要なソフトウェア (パッケージ) をインストールする

あらかじめ、以下のソフトウェア (パッケージ) をインストールしてください。

• cmake
• git
• g++
• jq
• make
• zlib1g-dev
• libffi-dev または libffi-devel
• libbz2-dev
• libreadline-dev
• libssl-dev
• libsqlite3-dev
• libwebp-dev

$ sudo apt update
$ sudo apt install cmake git g++ jq make zlib1g-dev libffi-dev libbz2-dev libreadline-dev libssl-dev libsqlite3-dev libwebp-dev

Python 3.7.3 をインストールする

# 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 --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 モジュールをインストールする

S⁺ Camera シリーズ の Python の実行環境にインストールされているモジュールを、開発環境にインストールします。モジュールのリストは、SORACOM Mosaic Python module 一覧 を参照してください。このリストを requirements.txt という名前で現在のディレクトリに保存すると、以下のコマンドで一括インストールできます。

$ pip install --upgrade pip
$ pip install setuptools --upgrade
$ pip install -r requirements.txt

開発環境を再起動したときは

開発環境を再起動すると、pip などが利用できなくなります。以下のコマンドを実行すると開発環境が再び利用できます。

$ source /opt/soracom/python/bin/activate

アルゴリズムをインストールするための環境を構築する

次に、アルゴリズムをインストールするための環境を準備します。

1. SORACOM CLI をインストールします。

   デプロイツールで、default プロファイルを使用します。SORACOM CLI を実行するために必要な認証情報は、default.json に保存してください。

   • 認証情報は、以下の権限を持った SAM ユーザーの認証情報を使用します。

     {
       "statements": [
         {
           "api": [
             "Device:readDeviceResource",
             "Device:executeDeviceResource",
             "Device:writeDeviceResource",
             "FileEntry:putFile"
           ],
           "effect": "allow"
         }
       ]
     }
     

   • 認証情報を保存する際は、「カバレッジタイプ」で 2 (特定地域向け IoT SIM (日本カバレッジ) のサブスクリプション (plan-D など) を利用する IoT SIM を管理する) を指定します。

   操作について詳しくは、SORACOM CLI 利用ガイド を参照してください。

2. SORACOM Mosaic のデプロイツール (deploy.zip) にアクセスし、[ダウンロード] をクリックして、保存します。

3. deploy.zip を解凍します。

   deploy.zip が Downloads ディレクトリにダウンロードされた場合は、以下のコマンドで解凍できます。

   $ unzip Downloads/deploy.zip
   

   Archive:  Downloads/deploy.zip
      creating: deploy/
     inflating: deploy/mosaic_deploy.sh  
     inflating: deploy/mosaic_deploy_apicall.sh  
   

4. unzip コマンドを実行したディレクトリで、次のコマンドが実行できることを確認してください。

   $ cd deploy
   $ soracom
   

   A command line tool to invoke SORACOM API
   
   Usage:
     soracom [command]
   
   Available Commands:
     audit-logs           Retrieve audit logs.
       :
   

   $ jq
   

   jq - commandline JSON processor [version 1.x]
   
   Usage:	jq [options] <jq filter> [file...]
       :
   

   $ ./mosaic_deploy.sh
   

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

   このディレクトリ (deploy ディレクトリ) を「デプロイツールのディレクトリ」と呼びます。

独自アルゴリズムのひな型を準備する

Python で動作する独自アルゴリズムのひな型を用意しています。以下の手順に従って、ひな型を準備します。

1. 独自アルゴリズムのひな型 (CameraApp0.tgz) にアクセスし、[ダウンロード] をクリックして、保存します。

2. CameraApp0.tgz を解凍します。

   CameraApp0.tgz が Downloads ディレクトリにダウンロードされた場合は、以下のコマンドで解凍できます。

   $ tar -zxvf ~/Downloads/CameraApp0.tgz
   

   ._CameraApp0
   CameraApp0/
   CameraApp0/._CameraApp.py
   CameraApp0/CameraApp.py
   CameraApp0/._fisheye_correction.py
   CameraApp0/fisheye_correction.py
   CameraApp0/._haarcascade_frontalface_alt2.xml
   CameraApp0/haarcascade_frontalface_alt2.xml
   CameraApp0/._CameraApp0
   CameraApp0/CameraApp0
   CameraApp0/._haarcascade_eye.xml
   CameraApp0/haarcascade_eye.xml
   CameraApp0/._soracom_harvest_files.py
   CameraApp0/soracom_harvest_files.py
   CameraApp0/.___init__.py
   CameraApp0/__init__.py
   CameraApp0/._PreSetup
   CameraApp0/PreSetup
   CameraApp0/._soracom_image_util.py
   CameraApp0/soracom_image_util.py
   CameraApp0/._info.json
   CameraApp0/info.json
   CameraApp0/._soracom_device_interface.py
   CameraApp0/soracom_device_interface.py
   CameraApp0/._soracom_harvest_data.py
   CameraApp0/soracom_harvest_data.py
   

   Public Beta 以降は CameraApp0_custom_oma.xml は不要となりました。

   CameraApp0.py 以外のファイル名は変更しないでください

   ファイル名を変更すると、エッジコンピューターで独自アルゴリズムが実行されません。

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

独自アルゴリズムのひな型に含まれる以下のファイルを編集します。

• info.json: バージョン情報ファイル
• CameraApp0: 実行モジュール
• PreSetup: アルゴリズム実行前に実行されるスクリプト
• CameraApp.py: アルゴリズムの本体

info.json: バージョン情報ファイル

独自アルゴリズムのバージョン情報を設定します。

info.json の例:

{
    "PkgApp": "CameraApp0",
    "PkgName": "CameraApp0 Sample",
    "PkgVersion": "1.0.0",
    "PkgIdentifier": "io.soracom.CameraApp0"
}

CameraApp0: 実行モジュール

S⁺ Camera シリーズ はアルゴリズムとして CameraApp0 を実行します。Python 3.7.3 で CameraApp0 を実行するために CameraApp0 の一行目は、以下のように記述してください。

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

import CameraApp

def main():
    CameraApp.Interval()

if __name__ == '__main__':
    main()

PreSetup: アルゴリズム実行前に実行されるスクリプト

PreSetup は、アルゴリズム実行前に実行されるスクリプトです。具体的には、以下のタイミングで PreSetup およびアルゴリズムが実行されます。

• OS 起動後
• アルゴリズムのインストール後
• アルゴリズムの環境変数変更後
• アルゴリズム異常終了後
• SORACOM Inventory Agent の再起動後

PreSetup の例:

#!/bin/bash

echo PreSetup
pip freeze

$ sudo ls /opt/soracom/container/container0/opt/soracom/bin/CameraApp0/

/opt/soracom/bin/CameraApp0

CameraApp.py: アルゴリズムの本体

CameraApp.py に独自アルゴリズムの本体を記述します。

開発環境 (PC) が正しく準備されていることを確認する

ダウンロードしたアルゴリズムのひな型に含まれる CameraApp.py には、S⁺ Camera シリーズ にアクセスし、定期的に Harvest Files にカメラ画像 (静止画・WebP 形式データ) をアップロードし、Harvest Data にカメラ画像に関するデータをアップロードするアルゴリズムが記述されています。

開発環境が正しく準備されていることを確認するために、このアルゴリズムを開発環境で実行します。

1. S⁺ Camera シリーズ の電源を入れます。

2. S+ Camera シリーズが提供する API を外部から利用するためにリモートアクセスする場合 の操作に従って、API にリモートアクセスするための HTTP(s) URL (https://xxx-xxx-xxx-xxx.napter.soracom.io:yyyyy) をクリップボードにコピーします。

   ただし、[露出させるポート] は 8080 を指定してください。

3. 以下のコマンドを実行して、URL を環境変数 DEVICE_INTERFACE_URI に代入します。

   ${surplusRemoteAccessURL} には、手順 2 でリモートアクセスを有効にしたときに [HTTP(S)] に表示された URL をペースト (入力) してください。

   export DEVICE_INTERFACE_URI=${surplusRemoteAccessURL}
   

4. そのほかの環境変数を設定します。

   export DEBUG_FILE_SAVE=True
   

   環境変数	説明
   DEBUG_FILE_SAVE	True: ダウンロードした画像データを開発環境の /tmp ディレクトリに保存します。一般に、開発環境からは Harvest Files にアップロードできないため、True に設定してください。

5. サンプルアルゴリズムのディレクトリに移動します。

   $ cd CameraApp0
   

6. サンプルアルゴリズムを実行します。

   $ ./CameraApp0
   

   /tmp ディレクトリに定期的にカメラ画像が保存されます。

   例: /tmp/cap_zzzzzzzzzz_2021-12-17T10-02-43-552962.webp

   • S⁺ Camera シリーズ からは非圧縮データがダウンロードされ、開発環境で WebP 形式に変換されています。そのため、非圧縮データのダウンロードに関して、データ通信料が発生します。一方、アルゴリズムを S⁺ Camera シリーズ にインストールした場合は、S⁺ Camera シリーズ で WebP 形式に変換されるため、WebP 形式データのアップロードに関して、データ通信量が発生します。
   • 開発環境で IoT SIM を利用している場合は、Harvest Data/Files にもデータがアップロードされます。

7. 画像が保存されていることを確認します。

   $ ls /tmp | grep cap.*\.webp
   

   cap_zzzzzzzzzz_2021-12-17T09-59-09-781983.webp
   cap_zzzzzzzzzz_2021-12-17T09-59-52-122476.webp
   cap_zzzzzzzzzz_2021-12-17T10-00-35-289352.webp
   cap_zzzzzzzzzz_2021-12-17T10-01-17-435684.webp
   cap_zzzzzzzzzz_2021-12-17T10-01-59-941113.webp
   cap_zzzzzzzzzz_2021-12-17T10-02-43-552962.webp
   

8. Ctrl+C キーを押して、サンプルアルゴリズムを終了します。

独自のアルゴリズムをエッジコンピューターにインストールする

開発したアルゴリズム (CameraApp0) を S⁺ Camera シリーズ にインストールします。

1. Mosaic コンソール にアクセスし、エッジコンピューターのデバイス ID をメモします。

2. デプロイツールのディレクトリ (deploy ディレクトリ) に移動します。

   $ cd ~/deploy
   

3. インストールします。

   $ ./mosaic_deploy.sh -d {デバイス ID} {開発したアルゴリズムのフルパス}
   

   例:

   $ ./mosaic_deploy.sh -d d-xxxxxxxxxxxxxxxxxxxx ~/deploy/CameraApp0
   

       :
   Show PkgName.
   PkgName="CameraApp Sample"
   Show PkgVersion
   PkgVersion="1.0.0"
   Restart InventoryAgent
   

   独自アルゴリズムが S⁺ Camera シリーズ と Harvest Files (/SORACOM-Mosaic/CameraApp0/) にインストールされ、最後に上記のように表示されます。

   デバイス ID は、d- で始まる ID です。一方、15 桁の番号 (IMEI) で始まる ID (例: 123456789012345_DN0123456789012) は、MOSAIC ID です。ここでは、d- ではじまる デバイス ID を指定します。

   Upload Package で終了した場合は

   以下の表示で終了した場合は、SORACOM CLI の default プロファイルに登録された SAM ユーザーの権限が足りません。SAM ユーザーの権限を確認し、認証情報が default プロファイルに登録されていることを確認してください。

       :
   Upload Package.
   

   ファイルサイズが大きすぎる場合は

   ファイルサイズが大きいためにアルゴリズムのインストールに 10 分以上かかる場合は、S⁺ Camera シリーズ に設定されているタイムアウトによって、アルゴリズムのインストールに失敗します。

   一部のファイルを PreSetup スクリプトでダウンロードするなどして、アルゴリズムの tgz ファイルのサイズを小さくしてください。

4. Mosaic コンソール にアクセスし、独自のアルゴリズムをインストールするエッジコンピューターのデバイス ID をクリックします。

5. [アルゴリズム] をクリックし、「現在のアルゴリズム」に「CameraApp Sample」と表示されていることを確認します。

   この表示は、サンプルアルゴリズムが、S⁺ Camera シリーズ で動作していることを表しています。

   次に、同じアルゴリズムが Harvest Files にもアップロードされていることを確認します。

6. [開く] → [Harvest Files で開く] の順にクリックします。

   Harvest Files が表示されます。

7. [SORACOM-Mosaic/] → [CameraApp0/] → [1.0.0/] → アップロードした日時の順にクリックし、「CameraApp0.tgz」が表示されていることを確認します。

   必要に応じて、ダウンロードしてください。次に、アルゴリズムが Harvest Files にアップロードした画像を確認します。

8. [root] をクリックします。

9. [cap/] → [{MOSAIC ID}/] → アルゴリズムが動作した年月日を順にクリックします。

   必要に応じて、画像をダウンロードしてください。WebP 形式の画像データは、Chrome などのブラウザから確認できます。

10. あらためて Mosaic コンソール にアクセスし、エッジコンピューターのデバイス ID をクリックします。

11. [アルゴリズム] → [開く] → [Harvest Data で開く] の順にクリックします。

    Harvest Data が表示されます。

サンプルアルゴリズム動作時の料金について

Harvest Data/Files および Napter の利用には料金が発生します。

特に、Harvest Data/Files にデータを送信するサンプルアルゴリズムは、継続して料金が発生します。不要になった場合は、以下の設定を行って、料金がかからないようにすることをおすすめします。

• アルゴリズムをアンインストールする。

• SIM グループの Harvest Data/Files を無効化する、または SIM グループから IoT SIM を解除 (離脱) する。

  SIM グループの設定は、ステップ 3: S+ Camera シリーズを Mosaic コンソールに登録する で行いました。このページを参考に、設定を解除したりオフにしたりしてください。

Tips

独自のアルゴリズムを開発する際に有用な情報を紹介します。

参考になるアルゴリズムについて

現在提供されているサンプルアルゴリズムについては アルゴリズム一覧 を参照してください。サンプルアルゴリズムをインストールする画面で [ダウンロード] をクリックすると、サンプルアルゴリズムをダウンロードできます。

また、以下のレシピも参考にしてください。

• SORACOM レシピ：AI カメラで来客分析
• エッジ AI カメラ「S+ Camera Basic」でソラコムサンタを検知する

任意の Python モジュールを利用するには

S⁺ Camera シリーズ の Python の実行環境にインストールされていないモジュールを利用する場合は、独自アルゴリズムのアーカイブにモジュールを含めます。

具体的には、CameraApp0 が保存されているディレクトリで以下のコマンドを実行してください。

$ pip install {module name} -t ./

開発環境 (PC) でカメラ画像をダウンロードするには

サンプルアルゴリズムのひな型では、定期的にカメラ画像 (静止画・非圧縮データ) をダウンロードしています。その方法でも開発環境にカメラ画像をダウンロードできますが、ここでは、アルゴリズムを実行せずに、カメラ画像 (静止画・WebP 形式データ) を取得する方法を説明します。

1. S+ Camera シリーズが提供する API を外部から利用するためにリモートアクセスする場合 の操作に従って、API にリモートアクセスするための HTTP(s) URL (https://xxx-xxx-xxx-xxx.napter.soracom.io:yyyyy) を取得します。

2. 以下のコマンドを実行して、URL を変数に代入します。

   ${surplusRemoteAccessURL} には、リモートアクセスを有効にしたときに [HTTP(S)] に表示された URL を入力してください。

   $ surplusRemoteAccessURLforCameraSettings=${surplusRemoteAccessURL}
   

3. S⁺ Camera シリーズ のカメラの撮影を有効化します。

   $ curl -X GET ${surplusRemoteAccessURLforCameraSettings}/mosaic/v1/DeviceInterface/startCameraCapture
   

4. S⁺ Camera シリーズ からカメラ画像 (静止画・WebP 形式データ) を取得します。

   $ curl -X GET ${surplusRemoteAccessURLforCameraSettings}/mosaic/v1/DeviceInterface/cameraWebpImage?quality=85 --output image.webp
   

   カメラ画像 (静止画・WebP 形式データ) がダウンロードされ、image.webp として保存されます。

5. S⁺ Camera シリーズ のカメラの撮影を無効化します。

   $ curl -X GET ${surplusRemoteAccessURLforCameraSettings}/mosaic/v1/DeviceInterface/startCameraCapture
   

パラメータを渡すには

Mosaic コンソールの [アルゴリズム] で、アルゴリズムに渡すパラメータ (最大 255 文字) を指定できます。ここで指定した値は、アルゴリズムを起動するタイミングで、S⁺ Camera シリーズ の環境変数に反映されます。

例:

{ "IForm": "webp", "IQl": 85, "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)

ログを出力するには

S⁺ Camera シリーズ 内部の /tmp/io.soracom.mosaic.debug.CameraApp0 にファイルを作成すると、次回アルゴリズム起動時から /tmp/io.soracom.mosaic.debug.CameraApp0.log にログが出力されます。

/tmp/io.soracom.mosaic.debug.CameraApp0 にファイルを作成して、アルゴリズムだけを再起動する手順は以下のとおりです。

1. SSH で S+ Camera シリーズにリモートアクセスする場合 の手順に従って、S⁺ Camera シリーズ に SSH ログインします。

2. 以下のコマンドを実行します。

   $ 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
   

アルゴリズムだけ再起動するには

Mosaic コンソールからアルゴリズムだけを再起動できます。

1. Mosaic コンソール にアクセスし、アルゴリズムを再起動するエッジコンピューターのデバイス ID をクリックします。

2. [概要] → [再起動] → [インベントリエージェントを再起動] の順にクリックします。

$ sudo systemctl restart soracom-inventoryagent

SSH でアクセスしてアルゴリズムを削除する

アルゴリズムをインストール後、IoT SIM はオンラインなのに、デバイスがオフラインになってしまった場合は、S⁺ Camera シリーズ に SSH でアクセスして、アルゴリズムを削除してください。

1. SSH で S+ Camera シリーズにリモートアクセスする場合 の手順に従って、S⁺ Camera シリーズ に SSH ログインします。

2. 以下のコマンドを実行します。

   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/