@alwaysai/device-agent

alwaysAI Device Agent

The alwaysAI Device Agent enables provisioning devices and managing devices and applications in production deployments of alwaysAI Computer Vision applications. Once installed and running, it connects to the alwaysAI Cloud to enable remotely controlling the device and applications from the alwaysAI Dashboard.

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 & Prerequisites

• Supported OS:
  • Debian Bullseye, Buster
  • Ubuntu 20.04, 18.04
  • NVIDIA Jetpack 4.6.x
• Supported target architecture
  • amd64
  • aarch64
  • armv7hf
• docker version >= 19.03
• curl installed (required to download provisioning scripts)
• Passwordless sudo for npm if using pm2
• Passwordless sudo for /sbin/shutdown for device restart functionality

To enable passwordless sudo for npm for the current user, run sudo visudo and add the following line to the end of the file:

<username> <hostname> = (root) NOPASSWD: /usr/bin/npm

Provision Device

Install the alwaysAI Device Agent and dependencies

On the target device, run:

$ curl -fsSL https://artifacts.alwaysai.co/device-agent/install-device-agent.sh | sudo -E bash -

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

Provision the device

Provisioning the device performs the following:

• Create the device in the alwaysAI Cloud
• Obtain device credentials to connect to alwaysAI Cloud
• Run the alwaysAI Device Agent in the background

Run the following command on the target device to provision it:

$ curl -fsSL https://artifacts.alwaysai.co/device-agent/provision.sh | bash -s -- --email <email> --password <password> [--device-name <device_name>]

Where:

• email is the email associated with your alwaysAI account.
• password is the password for your alwaysAI account.
• device_name is an optional device name, which will be displayed on the devices page of the alwaysAI Dashboard. If a device name is not provided, one will be generated for you and logged to the console for reference.

Important note: If your password contains one or more special characters and you receive an error message that your password does not match your username but you are sure that it is correctly entered, please try preceding every special character in your password with a backslash, and re-running the provisioning command. You can also reset your password at https://console.alwaysai.co/dashboard by logging out, navigating to the sign in page, and clicking 'Forgot Password?'.

Confirm the Device Agent is running with the following command:

$ pm2 list
┌────┬────────────────────┬──────────┬──────┬───────────┬──────────┬──────────┐
│ id │ name               │ mode     │ ↺    │ status    │ cpu      │ memory   │
├────┼────────────────────┼──────────┼──────┼───────────┼──────────┼──────────┤
│ 0  │ aai-agent          │ fork     │ 15   │ online    │ 0%       │ 2.8mb    │
└────┴────────────────────┴──────────┴──────┴───────────┴──────────┴──────────┘

To restart and update the Device Agent run the following command:

$ pm2 restart aai-agent
Use --update-env to update environment variables
[PM2] Applying action restartProcessId on app [aai-agent](ids: [ 0 ])
[PM2] [aai-agent](0) ✓
┌────┬────────────────────┬──────────┬──────┬───────────┬──────────┬──────────┐
│ id │ name               │ mode     │ ↺    │ status    │ cpu      │ memory   │
├────┼────────────────────┼──────────┼──────┼───────────┼──────────┼──────────┤
│ 0  │ aai-agent          │ fork     │ 16   │ online    │ 0%       │ 2.6mb    │
└────┴────────────────────┴──────────┴──────┴───────────┴──────────┴──────────┘

If you'd like to only provision the device, but not start the Device Agent in the background (skip step 3), run with the --provision-only flag:

$ curl -fsSL https://artifacts.alwaysai.co/device-agent/provision.sh | bash -s -- --email <email> --password <password> [--device-name <device_name>] --provision-only

When the script completes, the device will be provisioned but the Device Agent will not be running in the background.

Run an alwaysAI application on your 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. The application release will now show up on the project page of the alwaysAI Dashboard as well!

Now you can deploy to your device from the alwaysAI Dashboard.

Enable Analytics through the alwaysAI Device Agent

Configure the Device Agent

You can send information from your device to the alwaysAI cloud securely using the Device Agent. These instructions assume you have provisioned your device using the default script parameters and have the Device agent running (i.e. the provisioning script was not run with the --provision-only flag set).

First, the Device Agent must be configured to enable Analytics Pass-through support. Confirm that the ALWAYSAI_ANALYTICS_PASSTHROUGH environment variable is set:

$ pm2 env 0 | grep ALWAYSAI
ALWAYSAI_ANALYTICS_PASSTHROUGH: 1
ALWAYSAI_LOG_TO_CONSOLE: 
ALWAYSAI_LOG_LEVEL: debug
ALWAYSAI_DEVICE_AGENT_MODE: cloud

Then confirm the RabbitMQ container is up and running:

$ docker ps
CONTAINER ID   IMAGE           COMMAND                  CREATED          STATUS          PORTS                                                                    NAMES
596157124a4b   rabbitmq:3.11   "docker-entrypoint.s…"   32 minutes ago   Up 21 minutes   4369/tcp, 5671/tcp, 15691-15692/tcp, 25672/tcp, 0.0.0.0:5672->5672/tcp   alwaysAIRabbitMQContainer

Configure the Application

From the application side, the ALWAYSAI_CONNECT_TO_DEVICE_AGENT environment variable must be set. There are a few options:

In the app source

In your app.py file, make sure the top of your import statements looks like this:

import os
os.environ['ALWAYSAI_CONNECT_TO_DEVICE_AGENT']='1'
import edgeiq

You can import any other modules after edgeiq, but the other orders must be maintained.

In the Dockerfile

ENV ALWAYSAI_CONNECT_TO_DEVICE_AGENT=1

In a docker-compose.yaml

Add the following section to the service for your app:

environment:
  - ALWAYSAI_CONNECT_TO_DEVICE_AGENT=1

Enable Publishing to Cloud

To enable cloud publishing for your application you can either run aai app enable-cloud-publish, or update your alwaysai.app.json by adding the following component in addition to any models or scripts components:

"analytics: {
  "enable_cloud_publish": true
}

So, a valid alwaysai.app.json for publishing analytics might look like this:

{
  "scripts": {
    "start": "python app.py"
  },
  "models": {
    "alwaysai/mobilenet_ssd": 4
  },
  "analytics": {
    "enable_cloud_publish": true
  }
}

Finally, add a command to publish analytics to your app.py. Whenever this command is used, it will publish the contents of the analytics message to the cloud -- you can choose to call this every frame, or once every event occurrence, however your app is designed. Each core computer vision service has it's own publish_analytics method, which is called on the instance of the class. Or, you can published a JSON-serializable message with edgeiq.publish_analytics(). For instance, to publish object detection results you can use:

results = obj_detect.detect_objects(frame, confidence_level=.5)
try:
    obj_detect.publish_analytics(results, tag=frame_count)
except edgeiq.PublishError as e:
    print(e)

Finally, make sure to save all of your changes, and publish your application with

$ aai app publish

You can test that analytics are being viewed with wscat, using your application's project ID and a secure API key:

$ wscat -c "wss://analytics.alwaysai.co?projectId=[PROJECT_ID]&apiKey=[API_KEY]"

Please contact the alwaysAI team if you need a secure API key.

The alwaysAI Device Agent Command Line interface

The Device Agent can also be used directly on the device with it's command line interface.

$ aai-agent --help
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 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 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 get-all-envs   : Get environment variables for an application
   app set-env        : Set environment variables for a service
   device init        : Initialize device
   device get-info    : Get device info
   device clean       : Remove all provisioning files
   get-model-package  : Download and unpack a model package

To see the output logs, run the following command:

$ export ALWAYSAI_LOG_TO_CONSOLE=1

Install the application on the device

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])

Manually download a model package

To download a model package from the alwaysAI cloud and unpack to a specific directory, run:

$ aai-agent get-model-package <model ID> [--path <destination path>]

For example, to download alwaysai/yolo_v3 to ~/alwaysai run:

$ aai-agent get-model-package alwaysai/yolo_v3 --path ~/alwaysai

Once the command completes, you'll see the model package in the ~/alwaysai/models/alwaysai/yolo_v3 directory.

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.

$ aai-agent app set-env <key=val> --project <project_id> [--service <service>]

For example, to set the 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 Cleaning and Uninstalling

In order to fully clean the device and uninstall the agent, use the following steps:

1. Stop PM2 instance of the device agent

Using pm2 list, display the list of current pm2 instances. The output should look like this:

$ pm2 list
┌────┬────────────────────┬──────────┬──────┬───────────┬──────────┬──────────┐
│ id │ name               │ mode     │ ↺    │ status    │ cpu      │ memory   │
├────┼────────────────────┼──────────┼──────┼───────────┼──────────┼──────────┤
│ 0  │ aai-agent          │ fork     │ 15   │ online    │ 0%       │ 2.8mb    │
└────┴────────────────────┴──────────┴──────┴───────────┴──────────┴──────────┘

Start with pm2 stop <id> where <id> is the id of the aai-agent. Then, run pm2 delete 0. Follow it with these two commands: pm2 flush, pm2 unstartup

2. Remove alwaysAI Provisioned Device

Open a new terminal. Run aai-agent device clean

3. Uninstall aai Device Agent from the device

Run sudo npm uninstall -g @alwaysai/device-agent Verify successful removal by running aai-agent. You should see a response similar to -bash: /usr/bin/aai-agent: No such file or directory.

4. Remove the device from the aai Dashboard

Go to https://console.alwaysai.co/dashboard/devices, Go to Devices, find the device in question, and remove the device using the trashcan icon.