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
- Provision Device
- Run an alwaysAI application on your device
- Enable Analytics through the alwaysAI Device Agent
- The alwaysAI Device Agent Command Line interface
- Device Cleaning and Uninstalling
- Supported OS:
- Debian Bookworm, Bullseye
- Ubuntu 23.10, 22.04, 20.04, 18.04
- NVIDIA Jetpack 5.1, 4.6.x
- Supported target architecture
- amd64
- aarch64
-
docker>= 19.03 -
docker-compose>= 1.29.0; < 2.0.0 -
curlinstalled (required to download provisioning scripts) - Passwordless
sudofornpmif usingpm2 - Passwordless
sudofor/sbin/shutdownfor 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/shutdownOn 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.
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.
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:
-
emailis the email associated with your alwaysAI account. -
passwordis the password for your alwaysAI account. -
device_nameis 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-onlyWhen the script completes, the device will be provisioned but the Device Agent will not be running in the background.
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.
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: cloudThen 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 alwaysAIRabbitMQContainerFirst, 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:
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.
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=1The 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.
To enable cloud publishing in your app configurations run the following commands in your app directory:
$ aai app enable-cloud-publish
$ aai app publishThis can be added to the app release process so that cloud publishing is always enabled for production deployments.
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.
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 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 packageNow 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>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>There are several ways to manage the models for your application.
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>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])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 ~/alwaysaiOnce the command completes, you'll see the model package in the
~/alwaysai/models/alwaysai/yolo_v3 directory.
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 alwaysaiIn order to fully clean the device and uninstall the agent, use the following steps:
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 unstartupOpen a new terminal and run aai-agent device clean.
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.
Go to the Devices tab, find the device in question, and remove the device using the trashcan icon.