Table of contents
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}
.
Info |
---|
This tutorial only supports SDK ver.2.00 or later. Please note that it cannot be used with SDK ver.2.00 or lower. |
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
Info |
---|
The operation confirmation method for both the C version and Python version of the application is almost the same. I will explain using the C version as an example, and the different parts will be explained as appropriate. Also, the application path is as follows, so please read it as appropriate. C version app path Python version app path |
Launch Visual Studio Code directly under [SDK folder].
Code Block |
---|
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.
Info |
---|
This document uses Azure Container Registry administrator login credentials to speed up development and testing. In production environments, we recommend using least-privilege authentication options like service principals or repository-scoped tokens. Please see here for details. |
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").Code Block "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.Code Block "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.Code Block 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.
Code Block |
---|
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.
Code Block |
---|
${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.
Code Block |
---|
${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".
Code Block |
---|
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.
Code Block |
---|
docker login iprocv5xcontainerregistry.azurecr.io |
Then enter the Username and Password that are displayed. Enter the container registry user name and password.
Code Block |
---|
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.
Code Block |
---|
$ 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.
Info |
---|
The runtime status will be "Error" for a while after deployment. It takes time to become "running". However, the amount of time required to become "running" depends on the app. |
Check the operation of the app
Access the URL below with a PC that can connect to the camera.
Code Block |
---|
http://[Camera local IP address]/cgi-bin/cadam.cgi?methodName=getApplicationList |
The camera response will be displayed. Below is an example.
Code Block |
---|
{ "appCount": "1", "limitationMode": "Shared", "maxAppCount": "9", "appList": [ { "appType": "0", "funcId": "0000FF01", "appInfo": { "installId": "124B569A", (中略) } |
Use the information marked "installId": "124B569A",
.
Access the URL below.
Code Block |
---|
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.
Code Block |
---|
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.
Info |
---|
$edgeAgent and $edgeHub are the default containers for operating as an Azure IoT Edge Device. |
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”.
Info |
---|
Setting values are read-only. |
Setting the operation schedule
Use ModuleTwin to set the time zone in which the application will run.
Info |
---|
The Container version of AdamApp cannot be controlled using the camera's schedule settings. |
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.
Code Block |
---|
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.
item | meaning | format | note |
---|---|---|---|
Day of the week setting | Specify the days of the week when the app will run. | Set one of the following. “every-day” “Sun” “Mon” “Tue” “Wed” “Thu” “Fri” “Sat” | By setting the inference start time to "00:00" and the inference end time to "23:59", it is possible to operate 24 hours a day within the specified day. |
Inference start time | Specify the time when the app starts working. | “hh:mm” | Can be set from 00:00 to 23:59. |
Inference end time | Specify the time when the app's operation ends. | “hh.mm” | Can be set from 00:00 to 23:59. The end timing is determined at a timing outside of this time. (Example: If it is set to 02:15, it will stop after 2:16:00.) |
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
Sending telemetry data
Telemetry data can be sent from the device via cloud communication by calling the ADAM_SendTelemetry() function, which is valid only for Container AdamApp.
Please specify values in JSON format for the arguments of this API. Please see the API specification for details.
Device-to-cloud communication has a limit on the number of times it can communicate depending on the Azure IoT Hub settings. Please check here for more details.
To control communication, sending is set to OFF by default. In order to send to the cloud, you must first turn on the sending function.
There are two ways to turn on the transmission function: Module direct method and Module twin desired property. Please see below.
How to turn on using module direct method
Select the target Container Adamapp in Azure IoT Explorer.
Select "Module direct method" from the left menu. You can send a direct method on the screen below.
Enter the method name “setTelemetry” in the Method name field.
Enter the transmission data in JSON format in the Payload field as follows.
Code Block |
---|
{"telemetry": true} |
When you press "Invoke method", a direct method will be executed for the camera.
The results will be displayed in a pop-up. If the status is 200, it is successful.
How to set with Module twin desired property
Display the Module twin of the target Container Adamapp in Azure IoT Explorer.
Set as follows in “properties”.”desired”.”aplField”.
Code Block |
---|
"aplField": { "telemetry": true } |
Click “Save” at the top of the screen to apply the changes.
Info |
---|
|
How to check the settings
Setting values can be checked with Module twin.
Check the value of “properties”.”reported”.”aplField”.”azureSettings”.”telemetry”.
Checking received telemetry data
Select the target Container Adamapp in Azure IoT Explorer.
Select "Telemetry" from the left menu.
Press the "Start" button. The device will be waiting to receive telemetry data.
When the app receives telemetry sent with ADAM_SendTelemetry(), it will be displayed in the window.
The string set in ADAM_SendTelemetry will be set as the value of the payload key.
How to check the log
App log
You can check messages output by ADAM_DEBUG_PRINT() within the app and logs output by libraries linked from the app. You can also check if there is an error.
Log in to Azure portal(Cloud Computing Services | Microsoft Azure).
Select the target IoT Hub.
Select the target camera from "Device Management" and "IoT Edge" on the left.
From the list of modules below, click the "Runtime Status" link for the app name you want to view logs for.
Note |
---|
Container Adamapp logs cannot be checked with UDPLog. |
camera pflog
By checking the log in the camera, you can also analyze the behavior when Container Adamapp is not working properly. Logs can be obtained by clicking the execution button below.
Among the multiple log files, we will introduce the log files that are most related to Container Adamapp.
cadam (files with file names starting with pf_cadam, pf_cadamCgi) cadam is a process that manages Container Adamapp.
Azure IoT Edge runtime (files whose names start with pf_aziot-certd, pf_aziot-edged, pf_aziot-identityd, pf_aziot-keyd)Azure IoT Edge runtime communicates with Azure IoT Hub.
Docker (files with file names starting with pf_docker, pf_containerd, pf_opa) Logs related to Docker operations. opa is used for security checks, and if the created deployment manifest contains content that violates the camera's security policy, a log will be output to this file.
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.
Code Block 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