@alwaysai/device-agent v1.4.0

alwaysAI Device Agent

The alwaysAI Device Agent is a tool that runs on an alwaysAI device provisioned for production remote deployment. It enables management of one or more alwaysAI apps on a particular device via a command line interface.

Note that the Device Agent is still in an experimental phase and these commands are likely to change. This guide will be updated with the latest usage as things change.

System Requirements

• Recent version of Debian or Ubuntu
• npm >= 7.0.0
• node >= 16.0.0
• Recent version of docker with user access
  • On Linux: $ sudo usermod -aG docker $USER
• Recent version of docker-compose
• curl installed.

Provision Device

Create an alwaysAI device

On any machine running the alwaysAI CLI you can create a new production device in the alwaysAI cloud:

$ aai generate-production-device --name test-dev-1 --description "Device for testing alwaysAI Device Agent"
✔ Create new production device
✔ Write device credentials to /home/alwaysai/abc8fbbf-5d7f-4e49-92b7-8feedffeedbf
Created test-dev-1: device ID=abc8fbbf-5d7f-4e49-92b7-8feedffeedbf

Note down the device ID for use with Device Agent commands. The device credentials are also stored locally for you to keep in a safe place, but you won't need those since the Device Agent will update them automatically for you.

Provision the device

If you're system already meets all the system requirements, you can simply install the device agent via npm:

sudo npm install -g @alwaysai/device-agent@latest

Otherwise, you can run the provision script to install the agent and its dependencies:

curl -fsSL https://alwaysai-artifacts-prod.s3.us-west-1.amazonaws.com/device-agent/install-device-agent.sh | sudo -E bash -

The Device Agent will be available in the terminal as aai-agent.

Next, log in to the Device Agent with the following command:

aai-agent login --email <username> --password <password> --device <device_id>

Run an alwaysAI application on your device

Publish an application release and install on device

First, you must publish your application to the alwaysAI cloud. From the root of your application directory (where the alwaysai.app.json file is) on your development host:

aai app configure
aai app publish

The output of the final command will give you the release hash that was published. You can run aai release list --project <project_id> to list all release versions for the project, where project ID can be found in the alwaysai.project.json file.

Now you can install the application on the device using the device agent. Run the following on the device where the Device Agent is installed:

aai-agent app install --project <project_id> [--release <release_hash>]

Control the application

Run the following commands on the device where the Device Agent is installed:

Get application status:

aai-agent app status --project <project_id>

Start the application:

aai-agent app start --project <project_id>

Show the application logs:

aai-agent app logs --project <project_id>

Stop the application:

aai-agent app stop --project <project_id>

Uninstall the application:

aai-agent app uninstall --project <project_id>

Manage application models

There are several ways to manage the models for your application.

Update models to new version of the same model ID

If a new version of a model is published for an existing model ID, and an application is already configured to be using that model ID, updating to the new model can simply be done with:

aai-agent app stop --project <project_id>
aai-agent app update-models --project <project_id>
aai-agent app start --project <project_id>

Replace models for an application for new ID

If you'd like to install an entirely new model to an application, replacing the model the app was originally configured with, run the following command:

aai-agent app stop --project <project_id>
aai-agent app replace-models --project <project_id> --models <model_id_1> [<model_id_2> ...]
aai-agent app start --project <project_id>

If you plan on using this method, you can make your application source model ID agnostic by providing the model ID to edgeIQ in the following way:

Select the first model in the config list:

obj_detect = edgeiq.ObjectDetection(edgeiq._globals.MODEL_ID_LIST[0])

Set and update environment variables

The Device Agent enables you to set and update environment variables for all services or a single service of you application. For example, set teh following environment variable for the alwaysai service run the following command on the device:

aai-agent app set-env TEST_ENV=1 --project <project_id> --service alwaysai

Device Agent Commands

$ aai-agent --help
Starting alwaysAI Device Agent
Usage: aai-agent <subcommand> ...

   Manage your alwaysAI production device

Subcommands:

   login                   : Login to alwaysAI (this is meant for scripted environments)
   app list                : List all installed apps
   app list-releases       : List all releases for a given app
   app list-latest-release : List the latest release hash for a given app
   app install             : Install an alwaysAI app from a project
   app status              : Get the status of an installed alwaysAI app
   app start               : Start an installed alwaysAI app
   app stop                : Stop a running alwaysAI app
   app restart             : Restart running alwaysAI app
   app logs                : Get logs for an application
   app uninstall           : Remove an alwaysAI app
   app rollback            : Rollback an alwaysAI app to the previous version
   app show-models         : Show the application models
   app add-model           : Add a model to an alwaysAI app
   app remove-model        : Remove a model from an alwaysAI app
   app replace-models      : Replace all models of an alwaysAI app with new models
   app update-models       : Update all models for an alwaysAI app
   app get-all-envs        : Get environment variables for an application
   app set-env             : Set environment variables for a service
   get-device-info         : Get device info