アプリケーションの各種スキーマ

ここでは、Actcast アプリケーションを開発する際に記述するスキーマファイルについて詳しく説明します。

アプリケーションスキーマは次の 3 つです。

• Setting Schema: 動作環境の設定の雛形 (setting_schema.json)
• Data Schema: アプリケーションから送信されるデータの雛形 (data_schema.json)
• Manifesto: アプリケーションの実行時に必要となるリソース情報を記述

また、act_settings.jsonを用意することで Data Schema をテストできます。

setting_schema.json

Setting Schema はアプリケーションと共に利用される設定の形式を定義します。

アプリケーションは、スキーマに従った設定ファイルを環境変数ACT_SETTINGS_PATHを経由して利用します。 アプリケーション起動時に ACT_SETTINGS_PATH に JSON ファイルのパスがバインドされ、通常の JSON ファイルを利用するのと同様に利用できます。

Setting Schema は上記の JSON を記述するものです。setting_schema.json という名前のファイルに JSON Schema[^json schema] で記述します。 例えば以下のような記述をします。

{
  "$schema": "https://actcast.io/schema/v7/setting_schema_schema.json",
  "type": "object",
  "properties": {
    "display": {
      "title": "display",
      "description": "output video to HDMI display",
      "type": "boolean",
      "default": false
    },
    "threshold": {
      "title": "probability threshold",
      "description": "notify when over this threshold",
      "type": "number",
      "default": 0.9,
      "minimum": 0.0,
      "maximum": 1.0
    }
  },
  "required": [],
  "propertyOrder": ["display", "threshold"]
}

この記述には例えば以下のような JSON が適合します。

{
  "display": true,
  "threshold": 0.7
}

この JSON がアプリケーションへと渡されます。

Setting Schema に書ける項目

Setting Schema に書ける各フィールドは以下のようになっています。

$schema には "https://actcast.io/schema/v7/setting_schema_schema.json" を、 type には "object" を書きます。

propertyOrder が省略された場合は Actcast へアップロードする際に properties に書かれた順となるように propertyOredr が挿入されます。

properties

properties には以下の項目が書けます。

title と default については必須ではありませんが可能な限り付与することを推奨します。

  "properties": {
    "display": {
      "title": "display",
      "description": "output video to HDMI display",
      "type": "boolean", -> boolean 以外に変更するとデバイスが正常に動作しなくなります
      "default": false
    },
  }

descriptions

descriptions には英語以外の言語での説明を書きます。オブジェクトのプロパティ名にはISO 639-1 で指定された言語コードを、値にその言語での説明を書きます。

例えば以下のような記述をします。

{
  "ja": "これはフィールドの説明です",
  "eo": "Ĉi tiu estas la ekspliko de la areno"
}

type

type には以下の項目が書けます。

x-ui-type

x-ui-type には以下の項目が書けます。

data_schema.json

Data Schema ではアプリケーションの出力の形式を定義します。

Data Schema は Cast で利用され、例えば「信頼度スコアが 90%を超えたときに所定の場所にデータを POST する」という振る舞いを記述するために用いられます。 Actcast アプリケーションの標準出力は、各行が Data Schema に従う必要があります。 標準出力にプリントされた文字列は Act Log として Actcast に転送されます。

Data Schema は data_schema.json という名前のファイルに JSON Schema で記述します。

例えば以下のような記述をします。

{
  "$schema": "https://actcast.io/schema/v7/data_schema_schema.json",
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "prob": {
        "title": "probability",
        "description": "matching score",
        "type": "number",
        "minimum": 0.0,
        "maximum": 1.0
      },
      "label": {
        "title": "label",
        "description": "the most matching class name",
        "type": "string"
      }
    },
    "required": ["prob", "label"]
  }
}

これには以下のような JSON が適合します。

[
  {
    "prob": 0.3,
    "label": "cat"
  },
  {
    "prob": 0.7,
    "label": "dog"
  }
]

アプリケーションはこのような JSON を出力することになります。

Data Schema に書ける項目

Data Schema に書ける各フィールドは以下のようになっています。

items

items には以下の項目が書けます。

properties

properties には以下の項目が書けます。

items と properties にはそれぞれ items と properties の内容が再帰的に書けます。 descriptions は Setting Schema のものと同じものが書けます。

type

type には以下の項目が書けます。

act_settings.json

作業用ディレクトリに存在するact_settings.jsonは自動的に転送されアプリから利用されます。 この JSON ファイルはsetting_schema.jsonに従った形式である必要があります。

下記コマンドを実行すると、act_settings.json、setting_schema.jsonおよびdata_schema.jsonの検査を行います。

$ actdk validate-json

このコマンドと同等の検査は、actdk runコマンドを実行すると自動で行われます。

manifesto/*.json (Manifesto V2)

Manifesto にはアプリケーションの実行時に必要となるリソースを記述します。 Manifesto はデバイスごとに異なる設定を記述することができます。 その際は別々のファイルに設定を記述することになります。

actdk は初期化時にいくつかの Manifesto を生成します。 例えば以下に示すマニフェストファイルは Raspberry Pi 4 に適用され、 カメラと VideoCore のアクセスを許可し、 特別なネットワークアクセスを許可しない標準的な設定です。

{
  "version": 2,
  "target_type": "raspberrypi-buster",
  "boards": [
    "RSPi4B"
  ],
  "devices": [
    {"type": "camera"},
    {"type": "videocore"}
  ]
}

version

"version" にはバージョンを表わす数値を入れます。このプロパティは将来の拡張性のために存在し、Manifesto V2 では 2 です。

"version" のないマニフェストは Manifesto V1 と呼ばれます。Manifesto V2 は Manifesto V1 と同時に利用はできません。

target_type

"target_type" にはそのマニフェストを適用するターゲットタイプを記述します。このプロパティは将来の拡張性のために存在し、現時点では "raspberrypi-buster" のみを受け付けます。

boards

"boards" にはそのマニフェストを適用するボードのリストを記述します。

アプリを起動する際、Actcast デバイスエージェントは manifesto/*.json の "boards" と "target_type" を見てどの manifesto を適用するべきかを決定します。そのため、ある "target_type" に対して "boards" の指定が重複してはいけません。例えば manifesto/a.json と manifesto/b.json の両方に "target_type" として raspberrypi-buster が指定されている場合、その両方の "boards" に RSPi4B を含んではいけません。

"boards" には以下のボードを指定できます。

devices

"devices" にはアプリケーションが要求するデバイスのリストを指定することができます。リストの要素は以下のようなフィールドを持ったオブジェクトとして記述します。

"type" に指定可能なデバイスの種類は以下の通りです。

"device" を指定しなかった場合、Agent が "type" を元に自動でデバイスファイルをマウントします。その際にマウントされたファイルは アプリケーション内でのデバイスの扱い によってアプリケーションに通知されます。

"mode"に指定可能なモードは以下の通りです。

hotplugモードは"camera"と"sound"のデバイスタイプでのみ指定可能です。hotplugモードのデバイスが存在する場合、ホストマシンの/dev全体がマウントされます。

required が true であることは、そのデバイスがアプリケーションの動作に必須であることを表します。あるデバイスが必須と指定された場合、そのアプリケーションを使用する Act の起動時に、デバイスファイルが存在することがチェックされます。 もし対応するデバイスファイルが存在しない場合、Act のインストールはエラーとなり、起動に失敗します。

以下に例を挙げます。

"devices": [
  {
    "type": "camera",
    "required": true
  }
]

この設定ではカメラが"required":trueと指定されているため、Act の起動時にカメラに関連するデバイスファイルの存在がチェックされます。

network_mode

アプリが使うネットワークのモードを指定することができます。以下の値から指定することができます。

• bridge: 外部との通信に制限がないブリッジネットワークを利用します
  • ポートを公開する場合はpublished_portsによる指定が必要となります
  • UDP multicast を利用する場合、networksに別途記述が必要になります
• host: ホストシステムのネットワークをそのまま使います。ポートの公開も制限なく行えますが、アプリの脆弱性がホストシステムに影響がある可能性があります
  • networksやpublished_portsによる記述は無視されます
• socks: SOCKS プロキシを経由することで外部との通信をnetworksで指定したもののみに限定します
  • published_portsは利用できません

networks

network_modeが指定されていない、もしくはsocksが指定されている場合、アプリと外部と通信させたい接続先をネットワークマニフェストとして記述することで弊社が提供する SOCKS プロキシ経由で外部と通信できるようになります。 また、UDP multicast をbridgeモードで利用する場合もこちらの記述が必要になります。

詳細は ネットワークマニフェスト をご覧下さい。

allow_all_networks

アプリを外部と無制限に通信させたい場合に指定します。network_modeがbridgeである状態と同じです。 network_modeが指定されている場合、このフィールドは使うことができません。

SOCKS プロキシを経由せずに外部と通信できるようになります。

• この設定が有効な場合 networks の設定は無視されます。
• TCP/UDP どちらも許可されます。

{
  "version": 2,
  "target_type": "raspberrypi-buster",
  "boards": ["RSPi4B"],
  "devices": [],
  "allow_all_networks": true
}

published_ports

アプリケーションが外部からアクセス可能なポートを指定します。 アプリ内でサーバを立てて外部ネットワークからアクセスできるようになる機能です。 ポートの指定はコンテナ内のポート番号（container_port）、ホスト側で実際に使われるポート番号（host_port）、使用するプロトコル（protocol）の３つのフィールドを含むオブジェクトの配列によって行われます。

• network_modeがbridgeまたはallow_all_networks が true の場合のみ使えます
• host_portとして有効なポートは 1024-65535 の範囲です
  • ただし 8000 は actdk で利用しているため利用できません
• プロトコルには “tcp”, “udp” または “sctp” が指定できます

{
  "version": 2,
  "target_type": "raspberrypi-buster",
  "boards": ["RSPi4B"],
  "devices": [],
  "allow_all_networks": true,
  "published_ports": [
    {
      "container_port": 80,
      "host_port": 8080,
      "protocol": "tcp"
    }
  ]
}

hailort_version

アプリケーションが利用する HailoRT のバージョンを指定します。 現時点では以下の制約があります。

• actdk のバージョン 1.30.0 以降で利用できます
• target_type が raspberrypi-bullseye でのみ利用できます
• hailort_version に指定できるのは 4.10.0、 4.14.0 または 4.21.0 のみです
• hailort_version が 4.14.0 の場合は actcastos 3.3.0 以降のデバイスでのみ動作します
• hailort_version が 4.21.0 の場合は actcastos 3.22.0 以降のデバイスでのみ動作します
  • 4.21.0 は libatomic1 に依存しているため .actdk/dependencies.json に追加してください

{
  "version": 2,
  "target_type": "raspberrypi-bullseye",
  "boards": ["RSPiCM4"],
  "devices": [
    {
      "type": "other",
      "device": ["/dev/hailo0"]
    }
  ],
  "hailort_version": "4.10.0"
}

manifesto/*.json (Manifesto V1)

Manifesto にはアプリケーションの実行時に必要となるリソースを記述します。 Manifesto はデバイスごとに異なる設定を記述することができます。 その際は別々のファイルに設定を記述することになります。

actdk は初期化時にいくつかの Manifesto を生成します。 例えば以下に示す default.json は VideoCore IV を搭載する全ての Raspberry Pi シリーズに適用され、 カメラと VideoCore のアクセスを許可し、 特別なネットワークアクセスを許可しない標準的な設定です。

{
  "boards": [
    "RSPi1A",
    "RSPi1B",
    "RSPi1APlus",
    "RSPi1BPlus",
    "RSPi2B",
    "RSPiAlpha",
    "RSPiCM1",
    "RSPi3B",
    "RSPiZero",
    "RSPiCM3",
    "RSPiZeroW",
    "RSPi3BPlus",
    "RSPi3APlus",
    "RSPiCM3Plus",
    "RSPiZero2W"
  ],
  "devices": [
    {
      "type": "camera",
      "device": ["/dev/video0"]
    },
    {
      "type": "videocore",
      "device": [
        "/dev/vcsm",
        "/dev/vcio",
        "/dev/vc-mem",
        "/dev/vchiq",
        "/dev/gpiomem"
      ]
    },
    {
      "type": "framebuffer",
      "device": ["/dev/fb0"]
    }
  ]
}

boards

"boards" には以下のボードを指定できます。

アプリを起動する際、Actcast デバイスエージェントは manifesto/*.json の boards を見て、動作しているボードに対してどの manifesto を適用するべきかを決定します。 そのため、manifesto/*.json において boards は重複してはいけません。 (例えば manifesto/a.json と manifesto/b.json の両方の boards に RSPi4B を含んではいけません。)

devices

"devices" にはアプリケーションが要求するデバイスのリストを指定することができます。リストの要素は以下のようなフィールドを持ったオブジェクトとして記述します。

"type" に指定可能なデバイスの種類は以下の通りです。

• "camera": カメラデバイス
• "videocore": VideoCore
• "framebuffer": フレームバッファ
• "gpio": GPIO ピンを用いるデバイス
• "sound": マイク・スピーカ
• "other": 上記にあてはまらないデバイス

required が true であることは、そのデバイスがアプリケーションの動作に必須であることを表します。あるデバイスが必須と指定された場合、そのアプリケーションを使用する Act の起動時に、指定されたデバイスファイルが存在することがチェックされます。 もし対応するデバイスファイルが存在しない場合、Act のインストールはエラーとなり、起動に失敗します。

以下に例を挙げます。

"devices": [
  {
    "type": "camera",
    "device": [
      "/dev/video0"
    ],
    "required": true
  }
]

この設定では"/dev/video0"がrequired:trueと指定されているため、Act の起動時にデバイスファイルの存在がチェックされます。

networks

アプリを外部と通信させたい場合はネットワークマニフェストとして許可する接続先を記述することで弊社が提供する SOCKS プロキシ経由で外部と通信できるようになります。

詳細は ネットワークマニフェスト をご覧下さい。