@alwaysai/device-agent

v2.0.0

Published

18 days ago

The alwaysAI Device Agent

Downloads

149

0High
0Medium
0Low

alwaysai typescript nodejs

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 Bookworm, Bullseye
- Ubuntu 24.04, 23.10, 22.04, 20.04
- NVIDIA JetPack 5.1.1, 5.1
Supported target architecture
- amd64
- aarch64
docker >= 19.03
docker-compose >= 1.29.0
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 and sbin/shutdown for the current user, run sudo visudo and add the following lines to the end of the file:

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

On a linux system username can be obtained by typing whoami into the terminal. Similarly, if you don't know your hostname you can simply type hostname.

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

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

First, you must publish analytics from your application using publish_analytics. Whenever this command is used, it will publish the contents of the analytics message to the analytics endpoints you have enabled. 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 any 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)

Next, the ALWAYSAI_CONNECT_TO_DEVICE_AGENT environment variable must be set. There are a few options:

Using the alwaysAI Console

Once an app has been deployed to a device, you can add, modify, and remove environment variables using the environment variable tab of the app details panel. Add a new environment variable called ALWAYSAI_CONNECT_TO_DEVICE_AGENT and set it to 1.

In a docker-compose.yaml

Add the following section to the service for your app in a docker-compose.yaml file. If you don't yet have a docker-compose.yaml file in your app source, you can generate a template one to edit by running the aai app generate docker-compose command. Note that this will only take effect in production deployments.

environment:
  - ALWAYSAI_CONNECT_TO_DEVICE_AGENT=1

Enable Publishing to Cloud

The application analytics configuration can be set either in the app source when you publish it or once the app has been deployed to a device using the alwaysAI Console.

In your app source

To enable cloud publishing in your app configurations run the following commands in your app directory:

$ aai app enable-cloud-publish
$ aai app publish

This can be added to the app release process so that cloud publishing is always enabled for production deployments.

From the alwaysAI Console

In the alwaysAI Console, navigate to the device the application has been deployed to and open the configuration tab in the app panel. In the app config, add an analytics section that looks like the following:

"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
  }
}

Press "Update" to update the application configuration on the device.

Capture the Analytics Stream

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
   app get-analytics-cfg : Get analytics configuration for an application
   app set-analytics-cfg : Set analytics configuration for an application. Note that this resets the config so all desired options must be set
   app get-shadow        : Get the current shadow
   app update-shadow     : Update the shadow with the current application configuration
   device init           : Initialize device
   device get-info       : Get device info
   device clean          : Remove all provisioning files
   device restart        : Restart the device
   get-model-package     : Download and unpack a model package

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:

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    │
└────┴────────────────────┴──────────┴──────┴───────────┴──────────┴──────────┘

Run the following commands where <id> is the ID for aai-agent.

$ pm2 stop <id>
$ pm2 delete 0
$ pm2 flush
$ pm2 unstartup

Remove the device configuration

Open a new terminal and run aai-agent device clean.

Uninstall the 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.

Remove the device from the alwaysAI Dashboard

Go to the Devices tab, find the device in question, and remove the device using the trashcan icon.