アプリケーション開発
Actcast SDKリファレンスマニュアル
アプリの仕様

アプリの仕様

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。

  • ACTCAST_GROUP_ID

    Minimum Supported ACTCAST_PROTOCOL_VERSION: 1.2.0

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

  • ACTCAST_ACT_ID

    Minimum Supported ACTCAST_PROTOCOL_VERSION: 1.0.0

    Act の ActId。

  • ACTCAST_INSTANCE_ID

    Minimum Supported ACTCAST_PROTOCOL_VERSION: 1.0.0

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

    format: UUIDv4

  • 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-bullseye, raspberrypi-bookworm などの値を取る。

  • 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 などのサービスのためのソケットのパス。

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

  • ACTCAST_SOCKS_SERVER

    Minimum Supported ACTCAST_PROTOCOL_VERSION: 1.0.0

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

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

Act Log

アプリケーションが送信する各 Act Log は、data_schema.json に適合する JSON である必要があります。

送信するデータは 1KB 未満であることを想定しています。大きなデータを送信する場合は、ネットワークマニフェスト を利用してください。

標準出力での送信

送信する Act Log を配列に入れ ([] で囲み)、1 行で標準出力へ出力してください。それぞれが 1 件の Act Log として扱われます。

例えば、次の出力では 1 件の Act Log が送信されます。

[{"temperature": 20}]

配列に複数の Act Log を入れると、一度にまとめて送信されます。

actfw_core.notify での送信

Python ライブラリの actfw_core を使う場合は、送信する Act Log を表す Dict を List に入れて、actfw_core.notify に渡してください。それぞれが 1 件の Act Log として扱われます。

次の例では、1 回の呼び出しで 2 件の Act Log が送信されます。

import actfw_core

actfw_core.notify([
    {"temperature": 20},
    {"temperature": 21},
])
最終更新日