Actcast アプリケーションの概略 #

Actcast アプリケーションは Docker コンテナ内で動く通常の Linux アプリケーションです。 典型的なアプリケーションはカメラからの入力を得て Act Log を出力します。

ネットワーク機能など一部の OS の機能は制限されており、IoT 機器向け機能としての死活管理・設置確認のために以下の項目の実装が求められます。

• Heartbeat 機能
• TakePhoto 機能

アプリケーションのパッケージングと配布 #

開発したアプリケーションは actdk コマンドにより Docker のコンテナイメージになり、モデルやアプリケーションの説明などと共に Actcast サーバへとアップロードされます。 エンドユーザがアプリケーションを Act としてデバイスにインストールすると、デバイスの Actcast agent は Actcast サーバから Docker イメージを取得して実行します。

アプリケーションの制約 #

開発したアプリケーションは Docker コンテナとして動作するので原則としてファイルシステムなどのデバイスのホスト環境へのアクセスはできません。 アプリケーションのマニフェストを書くことでデバイスファイルやネットワークへのアクセスを許可することができます。

アプリケーションの構成 #

Actcast アプリケーションでは app ディレクトリに、以下の 2 つのファイルを必ず作成する必要があります。

• main
• healthchecker

mainはアプリケーションのエントリポイントとなるプログラムです。 実行可能などのような形式でも実装可能です。

healthcheckerはアプリの正常な動作を監視するためのスクリプトです。 Docker の実行の仕組みを利用しています。

これら 2 つのファイルを作成すると、以下のようなディレクトリ構造になります。

application-root
└── app
   ├── main
   └── healthchecker

アプリケーションのユーザ設定 #

アプリケーションはユーザから設定を受け取ることができます。

ユーザから設定を受け取るには setting_schema.json を用意します。 このスキーマに基いて Web UI 上で設定入力フォームが作られます。 アプリのユーザはデバイスごとに設定を与えられます。 デバイスにアプリがインストールされ、実行されるときにこのユーザの設定がアプリに渡されます。 設定は JSON ファイルとして ACT_SETTINGS_PATH 環境変数の指すファイルに置かれます。 このファイルを読み出すことでユーザからの設定を取り出せます。

アプリケーションと Actcast Agent の相互連携 #

アプリケーションとデバイス上で動く Actcast Agent のやりとりはいくつかあります。

• ソケットを通じた通信
• 環境変数
• Act Log

ソケットを通じた通信 #

UNIX ドメインソケットを使って Actcast Agent から写真を撮る命令を受け取ったり、 Actcast Agent に署名を依頼したりできます。 詳細は アプリケーション - Actcast エージェント間通信についてを参照下さい。

Python ライブラリの actfw を使って開発している場合はライブラリの関数を呼び出すことでこれらの機能を利用できます。

環境変数 #

アプリケーションが起動するときにいくつかの環境変数が渡されます。

• ACTCAST_PROTOCOL_VERSION

  Minimum Supported ACTCAST_PROTOCOL_VERSION: 1.0.0

  Actcast agent とアプリケーションのやりとりの version。

  Semantic Versioning に従い、かつ正規表現 \d+\.\d+\.\d+ にマッチする。 破壊的変更などにより major が上がる。 「環境変数やアプリケーション-Actcast デバイスエージェント間通信のプロトコルのコマンドなどが増えたとき」に minor が上がる。 現時点では patch が上がるシチュエーションはない。 この環境変数が設定されていない場合、アプリケーションはこの値を "0.0.0" として扱うべきである。

• ACTCAST_DEVICE_ID

  Minimum Supported ACTCAST_PROTOCOL_VERSION: 1.0.0

  Act が動いているデバイスのデバイス ID。

  actsim ではデバイス固有のダミーの値が設定される。

• ACTCAST_GROUP_ID

  Minimum Supported ACTCAST_PROTOCOL_VERSION: 1.2.0

  デバイスが所属しているグループの ID。

  actsim ではランダムなダミーの値が設定される。

• ACTCAST_ACT_ID

  Minimum Supported ACTCAST_PROTOCOL_VERSION: 1.0.0

  Act の ActId。

  actsim ではランダムなダミーの値が設定される。

• ACTCAST_INSTANCE_ID

  Minimum Supported ACTCAST_PROTOCOL_VERSION: 1.0.0

  Act 起動ごとに新しく生成される ID。

  format: UUIDv4

  actsim ではランダムなダミーの値が設定される。

• ACTCAST_DEVICE_TYPE

  Minimum Supported ACTCAST_PROTOCOL_VERSION: 1.1.0

  デバイスのデバイスタイプ。 RSPi3BPlus, JetsonXavierNX, Unknown などの値を取る。

• ACTCAST_FIRMWARE_TYPE

  Minimum Supported ACTCAST_PROTOCOL_VERSION: 1.3.0

  Act が動いているホストのファームウェアタイプ。 raspberrypi, raspberrypi-buster などの値を取る。

• ACT_SETTINGS_PATH

  Minimum Supported ACTCAST_PROTOCOL_VERSION: 1.0.0

  Act の設定値を表す JSON ファイルへのパス。

  中身は setting_schema.json に従う。

  詳細は アプリケーションの各種スキーマを参照。

• DEVICE_SUPPLY_PATH

  Minimum Supported ACTCAST_PROTOCOL_VERSION: 1.3.0

  Manifesto に基いて Act に渡されたデバイスの内容を表わす JSON ファイルへのパス。

  詳細は アプリケーション内でのデバイスの扱いを参照

• ACTCAST_COMMAND_SOCK

  Minimum Supported ACTCAST_PROTOCOL_VERSION: 1.0.0

  Take Photo などのコマンドのためのソケットへのパス。

  詳細は アプリケーション - Actcast エージェント間通信についてを参照。

• ACTCAST_SERVICE_SOCK

  Minimum Supported ACTCAST_PROTOCOL_VERSION: 1.0.0

  RS256 などのサービスのためのソケットのパス。

  actsim における挙動は Actcast agent とは異なることに注意。

  詳細は アプリケーション - Actcast エージェント間通信についてを参照。

• ACTCAST_SOCKS_SERVER

  Minimum Supported ACTCAST_PROTOCOL_VERSION: 1.0.0

  デバイスマニフェストでネットワークアクセスを許可されている場合に使用する SOCKS サーバのアドレス。 マニフェストで許可されていない場合は設定されない。

  format: <ip-address>:<port-number>

• ACTCAST_AGENT_SIMULATOR

  Minimum Supported ACTCAST_PROTOCOL_VERSION: 1.1.0

  Actcast agent では設定されない。actsim でのみ設定される。 固定文字列 "actsim". アプリケーションの開発用途での利用を想定している。

Act Log #

アプリケーションの標準出力は Act Log として処理され、サーバへと送られます。 そのため、標準出力は全て data_schema.json に書かれたフォーマットに適合する JSON である必要があります。 このとき送信するデータは 1KB に満たないものを想定しています。 大きなデータを送りたい場合は ネットワークマニフェストを利用して下さい。

Python ライブラリの actfw を使って開発している場合は actfw.notify を使うことで標準出力を意識せずにプログラミングを行えます。