Application Development
Actcast SDK Reference Manual
Apps

Apps

Overview of apps

An Actcast application is an ordinal Linux application that runs within a docker container. Typical applications receieve inputs from camera then output Act Log.

Some OS features, e.g., networks, are restricted. Also, applications must have the following feature implementations for alive monitoring and installation.

  • Heartbeat feature
  • TakePhoto feature

Packaging and deploying applications

The application you developed is to be packaged into Docker container image using actdk command and then be uploaded to the Actcast server together with models and descriptions of the application. When endusers install the application, the Actcast Agents on their devices retrieve Docker image from the Actcast server and run it.

Restrictions for applications

As applications run as docker container, basically they cannot access the host environment such as the file system. You can write manifesto to permit applications to access the host environment such as the file sysetm or the networks.

Application Structure

Actcast applications must have the following two files in app directory.

  • main
  • healthchecker

You can use any executable file as main.

healthchecker is a script that checks whether the application is working correctly. This function utilizes HEALTHCHECK instruction of Docker.

After creating these two files, a directory structure will be like this.

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

User settings of Actcast applications

Actcast applications can receive settings from their users.

To receieve settings from user, prepare setting_schema.json. The input form for the settings is generated on Web UI based on this schema. The users of the application can give settings per devices. This settings are passed to the application when the application is installed and run on devices. The settings are put in a JSON file which locates where ACT_SETTINGS_PATH environment variable indicates. You can get user settings by reading this file.

Interaction between applications and the Actcast Agent

There are a few ways for applications to interact with the Actcast Agent on the same device.

  • Communication via socket
  • Environment variables
  • Act Log

Communication via socket

Applications can communicate with Actcast Agent via UNIX domain sockets, for example, to receive command taking photo and to request a desital signature. See Communication between applications and the Actcast Agent for more detail.

If you are developing your app using the Python library actfw, you can use the dedicated functions to implement these features.

Environment variables

Several environment variables are passed when the application starts.

  • ACTCAST_PROTOCOL_VERSION

    Minimum Supported ACTCAST_PROTOCOL_VERSION: 1.0.0

    A version of protocol for Actcast agent and application.

    It conforms to Semantic Versioning, and moreover matches a regular expression \d+\.\d+\.\d+. Major version is bumped when there are breaking changes. Minor version is bumped when an environment variable is added or a command/service is added. Patch version will never be bumped for now. If this environment variable is not set, applications should regard the value as "0.0.0".

  • ACTCAST_DEVICE_ID

    Minimum Supported ACTCAST_PROTOCOL_VERSION: 1.0.0

    Device ID of the device that the Act is running in.

    In actsim, a device-specific dummy value is set.

  • ACTCAST_GROUP_ID

    Minimum Supported ACTCAST_PROTOCOL_VERSION: 1.2.0

    Group ID that the device belongs to.

    In actsim, a random dummy value is set.

  • ACTCAST_ACT_ID

    Minimum Supported ACTCAST_PROTOCOL_VERSION: 1.0.0

    ActId of the Act.

    In actsim, a random dummy value is set.

  • ACTCAST_INSTANCE_ID

    Minimum Supported ACTCAST_PROTOCOL_VERSION: 1.0.0

    Randomely generated ID per launch of Act.

    format: UUIDv4

    In actsim, a random dummy value is set.

  • ACTCAST_DEVICE_TYPE

    Minimum Supported ACTCAST_PROTOCOL_VERSION: 1.1.0

    Device Type of the device. E.g. RSPi3BPlus, JetsonXavierNX, Unknown.

  • ACTCAST_FIRMWARE_TYPE

    Minimum Supported ACTCAST_PROTOCOL_VERSION: 1.3.0

    Firmware Type of the host. E.g. raspberrypi, raspberrypi-buster.

  • ACT_SETTINGS_PATH

    Minimum Supported ACTCAST_PROTOCOL_VERSION: 1.0.0

    Path to a JSON file of Act Settings.

    The contents conforms to setting_schema.json.

    For more details, see Application Schemas.

  • DEVICE_SUPPLY_PATH

    Minimum Supported ACTCAST_PROTOCOL_VERSION: 1.3.0

    Path to a JSON file that describes devices passed to the Act based on its manifesto.

    See Device handling in Applications for more detail.

  • ACTCAST_COMMAND_SOCK

    Minimum Supported ACTCAST_PROTOCOL_VERSION: 1.0.0

    Path to a socket for commands, e.g. Take Photo.

    For more details, see Communication between applications and the Actcast Agent.

  • ACTCAST_SERVICE_SOCK

    Minimum Supported ACTCAST_PROTOCOL_VERSION: 1.0.0

    Path to a socket for services, e.g. RS256.

    Note that the behavior differs between actsim and Actcast agent.

    For more details, see Communication between applications and the Actcast Agent.

  • ACTCAST_SOCKS_SERVER

    Minimum Supported ACTCAST_PROTOCOL_VERSION: 1.0.0

    Address of SOCKS server for network access. This environment variable is set if and only if the device manifesto allows network access.

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

  • ACTCAST_AGENT_SIMULATOR

    Minimum Supported ACTCAST_PROTOCOL_VERSION: 1.1.0

    Not set in Actcast agent, set in actsim. Fixed value "actsim". A use case is, for example, development of application.

Act Log

The standard outputs of applications are proccessed to Act Log and sent to the Actcast Server. Hence, all the standard outputs must be JSON formatted and the JSON must conform data_schema.json. These data are intended to be < 1KB. When you want to send bigger data, use Network Manifesto.

If you are using Python library actfw, you can use actfw.notify to avoid explicitly using the standard output and JSON.

Last updated on