コンポーネント

自作の処理をエッジPCで動かす。画面でスクリプトを書くか、コンテナイメージを指定してコンポーネントとバージョンを登録する

標準機能では賄えない自作の処理を、現場のエッジPC上で Docker コンテナとして動かす機能です。処理の中身は次の 3 通りで用意できます。

カメラの死活監視・録画の外部ストレージへの同期・Kinesis Video Streams への取り込みは、公開コンポーネントとして最初から用意してあり、そのままデプロイできます。

コンテナの起動と停止は ThingsConnect が管理します。ThingsConnect 本体（カメラ・センサ・録画）とは独立して動くので、独自処理が落ちても本体の動作には影響しません。

AI 推論デバイスとの使い分け

「エッジで処理を動かす」機能は 2 つあります。やりたいことが AI モデルの実行だけなら、この機能は不要です。

カメラ映像に AI モデルを当てたいだけであれば AI 推論を使う を参照してください。

全体像

• コンポーネント（アプリの定義）とバージョン（実際の中身）は別物です。1 つのコンポーネントに複数バージョンをぶら下げ、どれをデプロイするか選びます。バージョンごとに、スクリプトかイメージかを選べます。
• コンポーネント詳細の「コンポーネント名」は、エッジPC 詳細の「稼働中のコンポーネント」に出る名前です。
• デプロイはエッジPC 単位、またはグループ単位です。既に動いている ThingsConnect 本体はそのままで、独自コンポーネントが加わります。

公開コンポーネント

コンポーネント一覧で 公開 の印が付いているものは、ThingsConnect が用意したコンポーネントです。すべての組織に最初から表示され、環境変数を入れてデプロイするだけで使えます。

• 公開コンポーネントは削除やバージョンの登録ができません。新しいバージョンは ThingsConnect が追加します。バージョンの状態が 準備中 の間はデプロイできません（イメージの用意が終わると選べるようになります）。
• ソースは redimpulz/thingsconnect-components（MIT ライセンス）で公開しています。イメージは public ECR に置いてあり、場所はコンポーネント詳細の「中身」の列に表示されます。
• 中身を変えたいときは、公開イメージを FROM で拡張するか Dockerfile を写して作り替え、自分のコンポーネントとして登録してください。
• どの公開コンポーネントも、実機での動作確認はまだです。 うまく動かない点があればご連絡ください。

使い始める前に

エッジPCに Docker が必要です。 どの方法で登録したコンポーネントも、エッジPC 上では Docker コンテナとして動きます。セットアップコマンドが最初から入れるので、通常は何もすることがありません。

Docker を入れずにセットアップした機体（--skip-docker を付けた場合や、古い手順で構築した場合）では、次を実行してください。Docker の導入から、ThingsConnect が Docker を使えるようにする設定までを済ませます。

wget -qO- https://<ダッシュボード>/api/edge-setup/install.sh | sudo bash

トークンは要りません（既にセットアップ済みのため）。Docker を手で入れただけでは、デプロイが Docker engine is not installed で失敗します。

コンポーネントを作る

サイドバーの「カスタム処理」→「コンポーネント」→「コンポーネントを追加」で、名前と説明（任意）を入力します。まだ中身はありません。

名前には英数字を 1 文字以上含めてください。 日本語だけの名前は登録できません。日本語を使いたい場合は「カメラ死活監視 camera-watchdog」のように英数字を混ぜてください。

バージョンを登録する

コンポーネント詳細の 「バージョンを登録」 を押し、上部のタブで 「スクリプトを書く」 か 「イメージを指定」 を選びます。バージョン番号には、直前のバージョンのパッチを 1 つ上げた番号（例: 1.0.0 の次は 1.0.1）が入った状態で開きます。環境変数・ポート・リソース上限などの実行時の設定はどちらのタブでも共通です。

スクリプトを書く

画面のエディタにコードを書き、そのまま登録します。イメージのビルドは要りません。

スクリプトは次の条件で動きます。

• 追加のライブラリは入れられません。 上の表に無いライブラリが要るときは、ランタイムのイメージを FROM で拡張して自作のイメージにします（ランタイムのソースは redimpulz/thingsconnect-components の runtimes/ にあります）。
• コードはコンテナの /app に読み取り専用で置かれます。ファイルを書くときは /tmp を使います（--read-only を付ける場合は --tmpfs=/tmp も付けます）。
• コンテナは root 以外のユーザーで動きます。
• 標準出力に書いた行が、ログに出ます。 Python のランタイムはバッファリングを切ってあります。
• ファイルは 20 個・合計 512 KB までです。最初に実行するファイル（main.py / main.js）は必須です。ファイル名に使えるのは英数字・.・_・- です。
• 常駐する処理として書きます（定期実行したい処理も、雛形のようにループさせます）。

イメージを指定する

公開されているイメージを、URI で指定して登録します。

• それ以外のレジストリ（ghcr.io・quay.io・社内のプライベートレジストリなど）は指定できません。 登録時に「対応していないレジストリです」と表示されます。
• 登録した時点の中身に固定します。 タグは登録時に digest（sha256:...）へ置き換えて保存するので、後から同じタグのイメージが差し替えられても、配る中身は変わりません。中身を更新するときは新しいバージョンとして登録し直します。
• バージョンの一覧の「中身」の列には、指定したタグ付きの名前が表示されます。

自作のイメージを CLI で送る

Dockerfile からイメージを作り込みたい場合は、手元の PC でビルドし、CLI で ThingsConnect が用意した保管場所へ送ります。AWS アカウントを自分で持つ必要はありません。

npm i -g @thingsconnect/cli
thingsconnect --version

thingsconnect login --api-url https://<API のホスト>
# API トークン: （貼り付けて Enter）

thingsconnect whoami   # 組織とスコープを確認する

export THINGSCONNECT_API_URL=https://<API のホスト>
export THINGSCONNECT_API_TOKEN=<API トークン>

thingsconnect login --api-url https://<別の API のホスト> --profile dev

thingsconnect profiles              # 保存済みの接続先を一覧表示する（* が既定）
thingsconnect use prod              # 既定の接続先を切り替える
thingsconnect --profile dev list    # そのコマンドだけ接続先を変える
thingsconnect logout --profile dev  # そのプロファイルだけ削除する

thingsconnect push --component my-edge-processor --version 1.0.0 --context .

thingsconnect register --component my-edge-processor --version 1.0.0 --image <イメージ URI>

登録したバージョンをエッジPCへ配る手順はデプロイを参照してください。

実行時の設定

バージョン登録の画面（「バージョンを登録」）または CLI のオプションで指定します。スクリプトでもイメージでも同じです。

指定できるオプション

エッジPCを保護するため、指定できるフラグは許可制です。下記以外を書くと登録時にエラーになります。

値を取るフラグは --flag=value の形で書いてください。 --flag value のように 2 つに分けると、値の側が別のフラグとして扱われエラーになります。

許可していない主なものと理由は次のとおりです。

• --privileged / --cap-add / --security-opt / --userns — 隔離そのものを弱める
• --volume / --mount / --volumes-from / --device — ホストのファイルやデバイスをコンテナに渡す（録画だけは下の「録画を読み取り専用で渡す」で受け取れます）
• --network — ホストのネットワークに直結できてしまう
• --restart / --detach — 起動・再起動は ThingsConnect が管理します

ホストのファイルを読み書きしたい、といった要件がある場合は個別にご相談ください。

録画を読み取り専用で渡す

バージョンの登録時に 「録画を読み取り専用で渡す（/recordings）」（CLI では --mount-recordings）を指定すると、エッジPC の録画がコンテナの /recordings に読み取り専用で見えます。録画はカメラごとのフォルダに、10 分ごとの MP4 ファイルとして並んでいます。書き込み・削除はできません。お客様のストレージへ録画を送るだけなら、公開コンポーネントの「録画の同期」を使えます。

データの保存先（増設ディスク・NAS）はデプロイのときに決まります。エッジPC の保存先を変えたら、コンポーネントをデプロイし直してください。

バージョンの更新と削除

• 更新: 新しいバージョン番号で登録し、改めてデプロイします。バージョンは上書きできません（同じ番号での再登録はエラーになります）。
• 前のバージョンを元にする: バージョン行の 「この版から新しい版を作る」 のアイコンを押すと、そのバージョンのスクリプト（またはイメージの指定）と実行時の設定が入った状態で登録画面が開きます。「バージョンを登録」ボタンから開いた場合は、最新のバージョンの内容が入ります。
• 削除: コンポーネント詳細でバージョンを削除、またはコンポーネントごと削除します。エッジPC やグループにデプロイ中のバージョンは削除できないので、先にデプロイから外してください。削除すると、push したイメージも消えます（同じイメージを使うバージョンが残っていれば残します）。

thingsconnect delete --component my-edge-processor --version 1.0.0

コンテナから何に触れるか

コンテナは隔離された環境で動くため、エッジPCのカメラ・センサに直接はアクセスできません。現状で届く範囲は次のとおりです。

AI アプリのイベントを受け取る

物体検出・ナンバープレート検知の詳細画面の「連携」で「すること」を カスタム処理へ渡す にしたトリガーを作ると（→ AI アプリを使う）、同じエッジPC のコンテナがイベントを受け取れます。「区域に人が入ったら社内システムに登録する」のような処理を、スクリプトに書けます。

import json
import os
import requests

URL = "http://host.docker.internal:3001/local/events"
HEADERS = {"Authorization": f"Bearer {os.environ['LOCAL_TOKEN']}"}

after = None
while True:
    params = {"waitSeconds": 25} if after is None else {"after": after, "waitSeconds": 25}
    try:
        res = requests.get(URL, headers=HEADERS, params=params, timeout=40)
        res.raise_for_status()
    except requests.RequestException as err:
        print(json.dumps({"error": str(err)}), flush=True)
        continue
    body = res.json()
    for item in body["events"]:
        event = item["event"]
        # ここに処理を書く（例: 社内システムへ登録する）。
        print(json.dumps({"trigger": item["trigger"]["name"], "type": event["eventType"], "detail": event["detail"]}, ensure_ascii=False), flush=True)
    after = body["next"]

現時点の制限

• コンテナの実行方式は Docker のみです。
• コンテナが自ら終了したときの挙動は未検証です。 常駐する処理として書いてください（終了したときに自動で起動し直されるかは確認できていません）。

困ったときは

その他の切り分けは トラブルシューティング を参照してください。