アプリケーションの各種スキーマについて #

ここでは、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`	string	Yes	JSON Schema の記述形式を指定する
`type`	string	Yes	`"object"` のみ
`properties`	object	Yes	設定の各プロパティを指定する
`required`	array	Yes	必須プロパティを指定する
`propertyOrder`	array	No	プロパティを Web UI に表示する際の順番を指定する

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

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

properties #

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

フィールド名	型	必須	内容
`description`	string	Yes	フィールドの説明
`descriptions`	object	No	フィールドの英語以外の言語での説明
`type`	string	Yes	フィールドの型
`title`	string	No	フィールドの名前
`default`		No	フィールドに値がない場合のデフォルト値
`minimum`	number	No	（ `type` が number の場合のみ）フィールドの最小値
`maximum`	number	No	（ `type` が number の場合のみ）フィールドの最大値
`minLength`	number	No	（ `type` が string の場合のみ）フィールドの最小長
`maxLength`	number	No	（ `type` が string の場合のみ）フィールドの最大長
`enum`	array	No	（ `type` が string の場合のみ）フィールドの可能な値の列挙
`x-ui-type`	string	No	Web UI で表示する方法

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

一度アプリケーションをアップロードした後は property のキーを維持したまま type だけを変更しないでください。
デバイスが正常に動作しなくなり、再セットアップが必要になります。
  "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 には以下の項目が書けます。

値	説明
`"boolean"`	真偽値
`"integer"`	整数値
`"number"`	数値
`"string"`	文字列

x-ui-type #

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

値	説明
`"textarea"`	テキストエリア
`"password"`	パスワード

`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 に書ける各フィールドは以下のようになっています。

フィールド名	型	必須	内容
`$schema`	string	Yes	JSON Schema の記述形式を指定する
`type`	string	Yes	`"array"` のみ
`items`	object	Yes	配列の中身を指定する

items #

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

フィールド名	型	必須	内容
`type`	string	Yes	`"object"` のみ
`properties`	object	Yes	データの各プロパティを指定する
`required`	array	Yes	必須プロパティを指定する

properties #

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

フィールド名	型	必須	内容
description	string	Yes	プロパティの説明
descriptions	object	No	プロパティの英語以外の言語での説明
type	string	Yes	プロパティの型
title	string	No	プロパティの名前
enum	array	No	（`type` が string の場合のみ）可能な値の列挙
items	object	No	（`type` が array の場合のみ）配列の要素のスキーマ
properties	object	No	（`type` が object の場合のみ）オブジェクトのスキーマ

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

type #

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

値	説明
`"boolean"`	真偽値
`"integer"`	整数値
`"number"`	数値
`"string"`	文字列
`"array"`	配列
`"object"`	オブジェクト

`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) #

Actcast Agent のバージョン 1.6.0 以降で利用可能です。

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" には以下のボードを指定できます。

notation	description
`RSPi1A`	Raspberry Pi 1 Model A
`RSPi1B`	Raspberry Pi 1 Model B
`RSPi1APlus`	Raspberry Pi 1 Model A+
`RSPi1BPlus`	Raspberry Pi 1 Model B+
`RSPi2B`	Raspberry Pi 2 Model B
`RSPiAlpha`	Raspberry Pi Alpha (early prototype)
`RSPiCM1`	Raspberry Pi Compute Module 1 (CM1)
`RSPi3B`	Raspberry Pi 3 Model B
`RSPiZero`	Raspberry Pi Zero
`RSPiCM3`	Raspberry Pi Compute Module 3 (CM3)
`RSPiZeroW`	Raspberry Pi Zero W
`RSPi3BPlus`	Raspberry Pi 3 Model B+
`RSPi3APlus`	Raspberry Pi 3 Model A+
`RSPiCM3Plus`	Raspberry Pi Compute Module 3+ (CM3+)
`RSPi4B`	Raspberry Pi 4
`RSPiCM4`	Raspberry Pi Compute Module 4
`RSPiZero2W`	Raspberry Pi Zero 2 W

devices #

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

フィールド名	型	必須	デフォルト	内容
`type`	string	Yes	N/A	要求するデバイス種
`device`	array	No	N/A	対応するデバイスファイルのリスト
`required`	bool	No	true	デバイスの存在が必須かどうか

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

タイプ名	ファイルの省略可否	説明
`"camera"`	Yes	カメラデバイス
`"videocore"`	Yes	VideoCore
`"display"`	Yes	ディスプレイ
`"framebuffer"`	No	フレームバッファ
`"gpio"`	No	GPIO ピンを用いるデバイス
`"sound"`	No	マイク・スピーカ
`"other"`	No	上記にあてはまらないデバイス

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

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

以下に例を挙げます。

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

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

networks #

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

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

allow_all_networks #

アプリを外部と無制限に通信させたい場合に指定します。

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

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

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

published_ports #

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

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"
    }
  ]
}

`manifesto/*.json` (Manifesto V1) #

V1 は非推奨です。V2 を利用してください。

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" には以下のボードを指定できます。

notation	description
`RSPi1A`	Raspberry Pi 1 Model A
`RSPi1B`	Raspberry Pi 1 Model B
`RSPi1APlus`	Raspberry Pi 1 Model A+
`RSPi1BPlus`	Raspberry Pi 1 Model B+
`RSPi2B`	Raspberry Pi 2 Model B
`RSPiAlpha`	Raspberry Pi Alpha (early prototype)
`RSPiCM1`	Raspberry Pi Compute Module 1 (CM1)
`RSPi3B`	Raspberry Pi 3 Model B
`RSPiZero`	Raspberry Pi Zero
`RSPiCM3`	Raspberry Pi Compute Module 3 (CM3)
`RSPiZeroW`	Raspberry Pi Zero W
`RSPi3BPlus`	Raspberry Pi 3 Model B+
`RSPi3APlus`	Raspberry Pi 3 Model A+
`RSPiCM3Plus`	Raspberry Pi Compute Module 3+ (CM3+)
`RSPi4B`	Raspberry Pi 4
`RSPiCM4`	Raspberry Pi Compute Module 4
`RSPiZero2W`	Raspberry Pi Zero 2 W

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

devices #

フィールド名	型	必須	デフォルト	内容
`type`	string	Yes	N/A	要求するデバイス種
`device`	array	Yes	N/A	対応するデバイスファイルのリスト
`required`	bool	No	true	デバイスの存在が必須かどうか

"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 #

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

アプリケーションの各種スキーマについて #

setting_schema.json #

Setting Schema に書ける項目 #

properties #

descriptions #

type #

x-ui-type #

data_schema.json #

Data Schema に書ける項目 #

items #

properties #

type #

act_settings.json #

manifesto/*.json (Manifesto V2) #

version #

target_type #

boards #

devices #

networks #

allow_all_networks #

published_ports #

manifesto/*.json (Manifesto V1) #

boards #

devices #

networks #

`setting_schema.json` #

`data_schema.json` #

`act_settings.json` #

`manifesto/*.json` (Manifesto V2) #

`manifesto/*.json` (Manifesto V1) #