Table of contents

Overview

Here we will explain the steps to build the iPRO Camera SDK app using the Azure IoT Edge container and check its operation. Also, in this tutorial, the SDK installation directory is described as ${SDK_DIR}.

Operation confirmation procedure

Create a new IoT Edge Solution on Visual Studio Code

The following describes the case where the sample app to be referenced is skeleton_sample_app for the C version, additional_info_sample_app for the Python version, and test_app for the Edge Solution to be created. Please note that the Edge Solution name must be in all lowercase letters.

Description of C version/Python version application

Launch Visual Studio Code directly under [SDK folder].

cd ${SDK_DIR}
code .

Copy the ”${SDK_DIR}/src/adamapp/skeleton_sample_app” folder into the same folder.

Rename the copied folder to test_app.

Rename the "skeleton_sample_app" folder in [copied folder]/container/modules to test_app.

Right-click the folder (test_app) copied from Visual Studio Code's EXPLORER and select "Find in Folder..." to display the SEARCH window.

Search for "skeleton_sample_app" and replace everything with "test_app". The targets are as follows.

• ${SDK_DIR}\src\adamapp\test_app\container\deployment.template.json

• ${SDK_DIR}\src\adamapp\test_app\container\modules\test_app\module.json

Enter the information for the container registry to which you want to push the created image.

Log in to Azure portal(Cloud Computing Services | Microsoft Azure) and select the container registry you want to target. The screen below is an example.

Display "Settings" - "Access Keys" from the left menu.

Based on the information displayed, enter the following:

• ${SDK_DIR}\src\adamapp\test_app\container\deployment.template.json
  Enter “registryCredentials” in the above file as follows. "Container Registry Name" is the "Registry Name" of Azure Portal in lower case (same as the string before .azurecr.io in "Login Server").

  "registryCredentials": {
    "[container registry name]": {
      "username": "$CONTAINER_REGISTRY_USERNAME_[container registry name]",
      "password": "$CONTAINER_REGISTRY_PASSWORD_[container registry name]",
      "address": "[login server]"
    }
  }

  For example, if the container registry name is “iprocv5xcontainerregistry” and the container registry login server is “iprocv5xcontainerregistry.azurecr.io”, it will be as follows.

  

   

• ${SDK_DIR}\src\adamapp\test_app\container\modules\test_app\module.json
  Enter “repository” in the above file as follows.

  "repository": "[login server]/test_app"

  If the container registry login server is "iprocv5xcontainerregistry.azurecr.io", it will be as follows.

  

• ${SDK_DIR}\src\adamapp\test_app\container
  Create an .env file in the directory, write the container registry user name and password, and save it.

  CONTAINER_REGISTRY_USERNAME_[container registry name]=[user name]
  CONTAINER_REGISTRY_PASSWORD_[container registry name]=[password]

  An example is shown below.
  

  

Coding the app

Now code as you like on Visual Studio Code. If you copy skeleton_sample_app etc., the source file name will be the one before copying (skeletonSampleApp.cpp for skeleton_sample_app), so please rename it if necessary. Below is an example.

Before
${SDK_DIR}\src\adamapp\test_app\skeletonSampleApp.cpp
After
${SDK_DIR}\src\adamapp\test_app\testApp.cpp

Please also modify SRC_FILES in Makefile as necessary. Below is an example.

${SDK_DIR}\src\adamapp\test_app\Makefile
Before
SRC_FILES=	skeletonSampleApp.cpp
After
SRC_FILES=	testApp.cpp

Please also modify PROG_NAME in Makefile, APPLICATION in configuration.txt, and APPLICATION_NAME in deployment.template.json as necessary. Below is an example.

${SDK_DIR}\src\adamapp\test_app\Makefile
Before
PROG_NAME= SkeletonSampleApp
After
PROG_NAME= TestApp

${SDK_DIR}\src\adamapp\test_app\configuration.txt
Before
APPLICATION	SkeletonSampleApp
After
APPLICATION	TestApp

${SDK_DIR}\src\adamapp\test_app\container\deployment.template.json
Before
"APPLICATION_NAME=SkeletonSampleApp"
After
"APPLICATION_NAME=TestApp"

Build the app

When building, use the built-in functionality of the Azure IoT extension. In Visual Studio Code's Explorer Right-click on "${SDK_DIR}\src\adamapp\test_app\container\deployment.template.json" to display the build menu.

Select “Build IoT Edge Solution”. This operation only performs a build.

For your first build, you will be asked to log in to your container registry. The following is an example when the container registry is "iprocv5xcontainerregistry.azurecr.io".

ERROR: failed to solve: iprocv5xcontainerregistry.azurecr.io/cadamappbase:0.0.2: failed to authorize: failed to fetch anonymous token: unexpected status: 401 Unauthorized

At this time, enter the following command on the Visual Studio Code terminal.

docker login iprocv5xcontainerregistry.azurecr.io

Then enter the Username and Password that are displayed. Enter the container registry user name and password.

Username: [user name]
Password: [password]

Login Succeeded is displayed, the login is successful.

Next, right-click "${SDK_DIR}\src\adamapp\test_app\container\deployment.template.json" and Select “Build and Push IoT Edge Solution”. This operation builds and pushes to the container registry.

The build is done by running Docker buildx build as described in the Dockerfile.arm64v8 file located under “${SDK_DIR}\src\adamapp\test_app\”. The environment name (arm64v8) after Dockerfile. is the architecture selected in the above step. (You can see the current architecture at the bottom of Visual Studio Code)

Check the built image

If the build is successful, you can check the existence of the image with docker images. Below is an example.

$ docker images
REPOSITORY                                                             TAG             IMAGE ID       CREATED          SIZE
iprocv5xcontainerregistry.azurecr.io/azureiot/test_app  0.0.5-arm64v8   f1772ccfed77   35 minutes ago   91.4MB

Deploy to camera

Select the device you want to deploy from under "AZURE IOT HUB" in the bottom left, right-click and select "Deploy to one IoT Edge" to deploy it to the camera. What to deploy Follows "${SDK_DIR}\src\adamapp\test_app\container\deployment.template.json".

A dropdown will appear at the top of Visual Studio Code, so select the following:
${SDK_DIR}\src\adamapp\test_app\container\config\deployment.arm64v8.json

Deployment Succeeded is displayed, the deployment is successful.

Check runtime status on Azure

Log in to the Azure portal(Cloud Computing Services | Microsoft Azure) and select the IoT Edge device you added on the IoT Hub - IoT Edge screen.

Check the runtime status of the deployed app shown at the bottom of the screen. If it is "running", no error has occurred. If "Error" is displayed, an error message will be displayed when you select it, so please debug it.

Check the operation of the app

Access the URL below with a PC that can connect to the camera.

http://[Camera local IP address]/cgi-bin/cadam.cgi?methodName=getApplicationList

The camera response will be displayed. Below is an example.

{
    "appCount": "1",
    "limitationMode": "Shared",
    "maxAppCount": "9",
    "appList": [
        {
            "appType": "0",
            "funcId": "0000FF01",
            "appInfo": {
                "installId": "124B569A",
                （中略）
}

Use the information marked "installId": "124B569A",.

Access the URL below.

http://[Camera local IP address]/cgi-bin/cadam.cgi?Language=1&methodName=sendDataToAdamApplication&installId=[installId]&s_appDataType=0&s_appData=e3tMYW5ndWFnZToxfX0%3D

If the camera's IP address is 192.168.100.33, "installId": "124B569A",, it will be as follows.

http://192.168.100.33/cgi-bin/cadam.cgi?Language=1&methodName=sendDataToAdamApplication&installId=124B569A&s_appDataType=0&s_appData=e3tMYW5ndWFnZToxfX0%3D

You can check the app operation as below. Below is an example of running skeleton_sample_app.

Controlling Container version Adamapp using Azure IoT Explorer

It is possible to control and check the Container version of Adamapp using Azure IoT Explorer published by Microsoft. The following describes the installation and initial settings of Azure IoT Exporlor.

Install

Follow Install and use Azure IoT explorer - Azure IoT | Microsoft Learn and install Azure IoT Explorer on your PC.

Initial setting

When you start Azure IoT Explorer, the following initial screen will appear, so select "Connect via IoT Hub connection string".

Select “Add connection”.

Visit “Cloud Computing Services | Microsoft Azure” and select the IoT Hub you want to connect to. In the example below, CV5xIoTHub2 is selected.

Select Security Settings - Shared Access Policies from the left menu.

Click “iothubowner” from the Manage “Shared Access Policies” list.

Press the copy button to the right of Primary Connection String to copy the string to your clipboard.

Paste it into the Connection string frame of Azure IoT Explorer and press the Save button.

The IoT Hub information will be loaded and a device list will be displayed.

Select the device you want to check from the displayed device (camera) list.

Checking the setting values with ModuleTwin

The settings values listed in the app settings (AppPrefs.json) can be checked from the cloud using Azure IoT's ModuleTwin mechanism.

Please refer to Understand Azure IoT Hub module twins | Microsoft Learn for ModuleTwin.

Select the device (camera) you want to check in Azure IoT Explorer. Select “Module identities” from the left menu.

A list of containers (Modules) currently running on the camera is displayed. Click the container name whose settings you want to check.

The page for the target container will be displayed. Select “Module twin” from the left menu again.

Information about the target container is displayed in json format. The information written in appPrefs.json will be displayed in “properties”.”reported”.”aplField”.”preference”.

Setting the operation schedule

Use ModuleTwin to set the time zone in which the application will run.

Similar to the "Checking settings using ModuleTwin" chapter, the Module Twin information for the target container is displayed.
Set the schedule in “properties”.”desired”.“scheduleField” according to the following format.
The format is below. Three fields represent one setting.

Day of the week setting 1, Inference start time 1, Inference end time 1, Day of the week setting 2, Inference start time 2, Inference end time 2,...

The specifications of each item are as follows.

A setting example is shown below.

In this case, it will be set to operate from Sunday to Thursday, from 08:00:00 to 20:00:59 on Saturday, and from 03:00 to 23:59:59 on Friday.

• After entering the settings, press "Save" at the top of the screen to apply the settings to the camera.

• Up to 8 can be set.

• If it is within any of the configured times, Container AdamApp will work.

• If the inference end time is later than the inference start time, the inference end time represents the next day.

• If scheduleField is empty, it will always operate.

• If the information is incorrect, the application will not start.

• Stop/start decisions are made at 15 second intervals. Therefore, the start and stop times will be delayed by up to 15 seconds.

Sending telemetry data from the device via cloud communication

テレメトリデータの送信

• Container AdamAppのみ有効な ADAM_SendTelemetry() 関数を呼び出すことでデバイスtoクラウド通信によるテレメトリデータを送信することができます。

• このAPIの引数にはJSON形式で値を指定してください。詳細はAPI仕様書をご覧ください。

• デバイスtoクラウド通信はAzure IoT Hubの設定により通信回数に制限があります。詳細は、Azure IoT Hub クォータと調整について | Microsoft Learn をご確認ください。

• 通信を制御するために、デフォルトでは送信をOFFに設定しています。クラウドに送信するためにはまず送信機能をONにする必要があります。

• 送信機能をONにする方法は Module direct method 及び Module twin desired property の二つの方法があります。以下をご参照ください。

Module direct methodでONにする方法

Azure IoT Explorerで対象の Container Adamappを選択します。

左側メニューから「Module direct method」を選択します。以下の画面でダイレクトメソッドが送信できます。

 
Method name欄にメソッド名”setTelemetry” を入力します。
Payload欄に送信データをJSON形式で以下のように入力します。

{"telemetry": true}

「Invoke method」を押下すると、カメラに対してダイレクトメソッドが実行されます。

結果はポップアップ表示される。statusが200になっていれば成功です。

Module twin desired propertyで設定する方法

Azure IoT Explorerで対象のContainer AdamappのModule twinを表示します。

“properties”.”desired”.”aplFileld” 内に以下のように設定します。

"aplField": {
  "telemetry": true
}

画面上部の　「Save」を押下すると反映されます。

設定値を確認する方法

設定値は、Module twinで確認できます。”properties”.”reported”.”aplField”.”azureSettings”.”telemetry” の値を確認してください。

受信したテレメトリデータの確認

Azure IoT Explorerで対象のContainer Adamappを選択します。

左側のメニューから「Telemetry」を選択します。

「Start」ボタンを押下します。テレメトリデータの受信待ち状態となります。X

アプリのADAM_SendTelemetry()で送信されたテレメトリを受信すると、ウィンドウ内に表示されます。ADAM_SendTelemetryに設定した文字列は、payloadキーの値として設定されます。

ログの確認方法

アプリのログ

アプリ内でADAM_DEBUG_PRINT()によって出力されるメッセージや、アプリからリンクしているライブラリが出力するログを見ることができます。エラーとなった場合も確認が可能です。

• ホーム - Microsoft Azure にアクセスします。

• 対象のIoT Hubを選択します。

• 左側の「デバイス管理」「IoT Edge」から対象のカメラを選択します。

• 下のモジュールのリストからログを見たいアプリ名の「ランタイムの状態」のリンクをクリックします。

カメラのpflog

カメラ内のログを確認することで、Container Adamappが正しく動作していない場合の動作解析を行うこともできます。ログ取得方法は下記の実行ボタンより取得可能です。

複数あるログファイルのうち、Container Adamappに関連の高いログファイルを紹介します。

• cadam (ファイル名が pf_cadam, pf_cadamCgi から始まるファイル)
  cadamはContainer Adamappの管理をするプロセスとなります。

• Azure IoT Edgeランタイム (ファイル名が pf_aziot-certd, pf_aziot-edged, pf_aziot-identityd, pf_aziot-keyd から始まるファイル)
  Azure IoT EdgeランタイムはAzure IoT Hubとの通信を行います。

• Docker (ファイル名が pf_docker, pf_containerd, pf_opa から始まるファイル)
  Dockerの動作に関するログとなります。opaはセキュリティチェックのために使用しており、作成した配置マニフェストに、カメラのセキュリティポリシーに違反する内容が記載されていた場合、このファイルにログが出力されます。

Checkpoints if things don't work in the WSL environment

If it does not work in WSL environment, please check the following.

• The following must be enabled in the Visual Studio Code "LOCAL" extension

  • Dev Containers

  • Remote - SSH, Remote - SSH: Editing Configuration FIles, Remote - Tunnels, Remote Development, Remote Explorer

  • WSL

• The following must be enabled in Visual Studio Code's "WSL: UBUNTU-20.04" extension:

  • Azure Account

  • Azure IoT Edge

  • Azure IoT Hub

• "WSL: Ubuntu-20.04" is displayed at the bottom left of the Visual Studio Code screen.

  

• If permission denied is displayed in Build IoT Edge Solution, check whether the current user has access rights to the target directory.

  sudo chown -r ipro:ipro [development directory]
  ※ipro:ipro is an example, so please set it according to each environment.

  Run the above to change the owner.

About trademarks

We will post about the trademarks used on the site.

・Docker and the Docker logo are trademarks or registered trademarks of Docker, Inc. in the United States and/or other countries. Docker, Inc. and other parties may also have trademark rights in other terms used herein