@alwaysai/device-agent 1.3.0 → 1.3.1

package/readme.md

@@ -1,4 +1,4 @@
-# alwaysAI Device Agent
+# alwaysAI Device Agent <!-- omit from toc -->
 
 The alwaysAI Device Agent enables provisioning devices and managing devices and
 applications in production deployments of alwaysAI Computer Vision applications.
@@ -9,28 +9,60 @@ 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](#system-requirements--prerequisites)
+- [Provision Device](#provision-device)
+  - [Install the alwaysAI Device Agent and dependencies](#install-the-alwaysai-device-agent-and-dependencies)
+  - [Provision the device](#provision-the-device)
+- [Run an alwaysAI application on your device](#run-an-alwaysai-application-on-your-device)
+- [Enable Analytics through the alwaysAI Device Agent](#enable-analytics-through-the-alwaysai-device-agent)
+  - [Configure the Device Agent](#configure-the-device-agent)
+  - [Configure the Application](#configure-the-application)
+    - [Using the alwaysAI Console](#using-the-alwaysai-console)
+    - [In a docker-compose.yaml](#in-a-docker-composeyaml)
+  - [Enable Publishing to Cloud](#enable-publishing-to-cloud)
+    - [In your app source](#in-your-app-source)
+    - [From the alwaysAI Console](#from-the-alwaysai-console)
+  - [Capture the Analytics Stream](#capture-the-analytics-stream)
+- [The alwaysAI Device Agent Command Line interface](#the-alwaysai-device-agent-command-line-interface)
+  - [Install the application on the device](#install-the-application-on-the-device)
+  - [Control the application](#control-the-application)
+  - [Manage application models](#manage-application-models)
+    - [Update models to new version of the same model ID](#update-models-to-new-version-of-the-same-model-id)
+    - [Replace models for an application for new ID](#replace-models-for-an-application-for-new-id)
+    - [Manually download a model package](#manually-download-a-model-package)
+  - [Set and update environment variables](#set-and-update-environment-variables)
+- [Device Cleaning and Uninstalling](#device-cleaning-and-uninstalling)
+  - [Stop PM2 instance of the device agent](#stop-pm2-instance-of-the-device-agent)
+  - [Remove the device configuration](#remove-the-device-configuration)
+  - [Uninstall the Device Agent from the device](#uninstall-the-device-agent-from-the-device)
+  - [Remove the device from the alwaysAI Dashboard](#remove-the-device-from-the-alwaysai-dashboard)
+
+
 ## System Requirements & Prerequisites
 
 * Supported OS:
-    * Debian Bullseye, Buster
-    * Ubuntu 20.04, 18.04
-    * NVIDIA Jetpack 4.6.x
+    * Debian Bookworm, Bullseye
+    * Ubuntu 23.10, 22.04, 20.04, 18.04
+    * NVIDIA Jetpack 5.1, 4.6.x
 * Supported target architecture
     * amd64
     * aarch64
-    * armv7hf
-* `docker` version >= 19.03
+* `docker` >= 19.03
+* `docker-compose` >= 1.29.0; < 2.0.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` for the current user, run `sudo visudo`
-and add the following line to the end of the file:
+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:
 
 ```bash
 <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
@@ -122,12 +154,14 @@ 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:
+The Device Agent must be configured to enable Analytics Pass-through support.
+Confirm that the `ALWAYSAI_ANALYTICS_PASSTHROUGH` environment variable is set:
 
 ```bash
 $ pm2 env 0 | grep ALWAYSAI
@@ -147,31 +181,38 @@ CONTAINER ID   IMAGE           COMMAND                  CREATED          STATUS
 
 ### 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:
+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:
 
 ```python
-import os
-os.environ['ALWAYSAI_CONNECT_TO_DEVICE_AGENT']='1'
-import edgeiq
+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)
 ```
-You can import any other modules after `edgeiq`, but the other orders must be
-maintained.
 
-#### In the Dockerfile
+Next, the `ALWAYSAI_CONNECT_TO_DEVICE_AGENT` environment variable must be set.
+There are a few options:
 
-```bash
-ENV ALWAYSAI_CONNECT_TO_DEVICE_AGENT=1
-```
+#### 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:
+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.
 
 ```bash
 environment:
@@ -180,12 +221,31 @@ environment:
 
 ### 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:
+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:
+
+```bash
+$ 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:
 
 ```json
-"analytics: {
+"analytics": {
   "enable_cloud_publish": true
 }
 ```
@@ -206,30 +266,12 @@ So, a valid `alwaysai.app.json` for publishing analytics might look like this:
 }
 ```
 
-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:
+Press "Update" to update the application configuration on the device.
 
-```python
-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
-
-```bash
-$ aai app publish
-```
+### 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:
+You can test that analytics are being viewed with `wscat`, using your
+application's project ID and a secure API key:
 
 ```bash
 $ wscat -c "wss://analytics.alwaysai.co?projectId=[PROJECT_ID]&apiKey=[API_KEY]"
@@ -239,7 +281,8 @@ 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.
+The Device Agent can also be used directly on the device with it's command line
+interface.
 
 ```bash
 $ aai-agent --help
@@ -249,30 +292,29 @@ Usage: aai-agent <subcommand> ...
 
 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:
-
-```bash
-$ export ALWAYSAI_LOG_TO_CONSOLE=1
+   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
@@ -350,7 +392,8 @@ 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:
+To download a model package from the alwaysAI cloud and unpack to a specific
+directory, run:
 
 ```bash
 $ aai-agent get-model-package <model ID> [--path <destination path>]
@@ -380,11 +423,16 @@ service run the following command on the device:
 ```bash
 $ 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:
+### Stop PM2 instance of the device agent
+
+Using `pm2 list`, display the list of current pm2 instances. The output should
+look like this:
+
 ```bash
 $ pm2 list
 ┌────┬────────────────────┬──────────┬──────┬───────────┬──────────┬──────────┐
@@ -393,19 +441,25 @@ $ pm2 list
 │ 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`
+Run the following commands where `<id>` is the ID for `aai-agent`.
+
+```bash
+$ pm2 stop <id>
+$ pm2 delete 0
+$ pm2 flush
+$ pm2 unstartup
+```
+### Remove the device configuration
+
+Open a new terminal and run `aai-agent device clean`.
 
-### 2. Remove alwaysAI Provisioned Device
-Open a new terminal.
-Run `aai-agent device clean`
+### Uninstall the Device Agent from the device
 
-### 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`.
+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.
+### Remove the device from the alwaysAI Dashboard
 
+Go to the [Devices](https://console.alwaysai.co/dashboard/devices) tab, find the
+device in question, and remove the device using the trashcan icon.

package/src/application-control/environment-variables.test.ts

@@ -1,6 +1,10 @@
 import { AgentConfigFile } from '../infrastructure/agent-config';
 import { readDockerCompose, writeDockerCompose } from './config';
-import { getAllEnvs, setEnv } from './environment-variables';
+import {
+  convertStringEnvsToKeyVal,
+  getAllEnvs,
+  setEnv
+} from './environment-variables';
 import { isAppStarted, restartApp } from './status';
 import { buildApp, requireAppReady } from './utils';
 
@@ -132,7 +136,7 @@ describe('Test environment variable get and set', () => {
         dockerCompose: {
           services: {
             alwaysai: {
-              environment: ['TEST1=1', 'TEST2=2', 'TEST1=2']
+              environment: ['TEST1=2', 'TEST2=2']
             }
           }
         }
@@ -158,7 +162,7 @@ describe('Test environment variable get and set', () => {
         dockerCompose: {
           services: {
             alwaysai: {
-              environment: ['TEST1=3', 'TEST2=4', 'TEST1=2']
+              environment: ['TEST1=2', 'TEST2=4']
             },
             other: {
               environment: ['OTHER_TEST=1']
@@ -167,5 +171,41 @@ describe('Test environment variable get and set', () => {
         }
       });
     });
+    test('Remove one env', async () => {
+      const environment = ['TEST1=1', 'TEST2=2'];
+      const compose = {
+        services: {
+          alwaysai: { environment }
+        }
+      };
+      jest.mocked(readDockerCompose).mockResolvedValue(compose);
+
+      const envVars = { alwaysai: { TEST1: null } };
+      await setEnv({ projectId: projectId1, envVars });
+      expect(jest.mocked(readDockerCompose)).toBeCalledWith({
+        projectId: projectId1
+      });
+      expect(jest.mocked(writeDockerCompose)).toBeCalledWith({
+        projectId: projectId1,
+        dockerCompose: {
+          services: {
+            alwaysai: {
+              environment: ['TEST1=', 'TEST2=2']
+            }
+          }
+        }
+      });
+    });
+  });
+  describe('Test helpers', () => {
+    test('convertStringEnvsToKeyVal', () => {
+      const stringEnvs: string[] = ['TEST1=', 'TEST2=test2', 'TEST3=null'];
+      const envVars = convertStringEnvsToKeyVal(stringEnvs);
+      expect(envVars).toEqual({
+        TEST1: '',
+        TEST2: 'test2',
+        TEST3: 'null'
+      });
+    });
   });
 });

package/src/application-control/environment-variables.ts

@@ -4,6 +4,7 @@ import { buildApp, getAppDir, requireAppReady } from './utils';
 import { logger } from '../util/logger';
 import { AgentConfigFile } from '../infrastructure/agent-config';
 import { isAppStarted, restartApp } from './status';
+import { replaceFalseyWithNull } from '../util/parsing';
 
 export interface EnvVars {
   [service: string]: {
@@ -37,26 +38,32 @@ export async function setEnv(props: { projectId: string; envVars: EnvVars }) {
         )}`
       );
     }
-    const envVarList: string[] = [];
+
+    const service = composeParsed['services'][s];
+    const oldEnv: string[] | undefined = service['environment'];
+
+    const newEnvVarsObj = {};
+    oldEnv?.forEach((envVarStr: string) => {
+      const envVarSplit = envVarStr.split('=');
+      const key = envVarSplit[0];
+      const value = envVarSplit[1];
+      newEnvVarsObj[key] = value;
+    });
+
     for (const envVar of Object.keys(envVars[s])) {
-      envVarList.push(`${envVar}=${envVars[s][envVar]}`);
+      newEnvVarsObj[envVar] = envVars[s][envVar];
     }
-    const service = composeParsed['services'][s];
-    // The environment field overrides the env files, so by appending to
-    // the environment list we can assure the value will be used over
-    // the env_file.
-
-    // NOTE: We are only appending the new values to the end of the
-    // environment variable list, which will override but not replace
-    // previous instances of the same environment variable.
-    if ('environment' in service) {
-      const environment: string[] = service['environment'];
-      composeParsed['services'][s]['environment'] =
-        environment.concat(envVarList);
-    } else {
-      composeParsed['services'][s]['environment'] = envVarList;
+
+    const envVarList: string[] = [];
+    for (const envVar of Object.keys(newEnvVarsObj)) {
+      envVarList.push(
+        `${envVar}=${newEnvVarsObj[envVar] ? newEnvVarsObj[envVar] : ''}`
+      );
     }
+
+    service['environment'] = envVarList;
   }
+
   await writeDockerCompose({ projectId, dockerCompose: composeParsed });
 
   const appDir = getAppDir(projectId);
@@ -79,7 +86,7 @@ export async function setEnv(props: { projectId: string; envVars: EnvVars }) {
   );
 }
 
-async function convertStringEnvsToKeyVal(stringEnvs: string[]) {
+export function convertStringEnvsToKeyVal(stringEnvs: string[]) {
   const envVars = {};
   stringEnvs.forEach((env: string) => {
     const keyVal = env.split('=');
@@ -117,17 +124,20 @@ export async function getAllEnvs(props: {
           envFileLines = envFileLines.filter((v) => {
             return v !== '' && !v.includes('#');
           });
-          const newEnvVars = await convertStringEnvsToKeyVal(envFileLines);
+          const newEnvVars = convertStringEnvsToKeyVal(envFileLines);
           envVars[s] = { ...envVars[s], ...newEnvVars };
         }
       }
       if ('environment' in service) {
         const environment: string[] = service['environment'];
-        const newEnvVars = await convertStringEnvsToKeyVal(environment);
+        const newEnvVars = convertStringEnvsToKeyVal(environment);
         envVars[s] = { ...envVars[s], ...newEnvVars };
       }
     }
   }
 
+  // Device shadow needs null to delete
+  replaceFalseyWithNull(envVars, true);
+
   return envVars;
 }

package/src/application-control/install.ts

@@ -65,7 +65,7 @@ export async function installApp(props: {
     if (!(await AgentConfigFile().isAppReady({ projectId }))) {
       throw new Error('Application already has installation in progress!');
     }
-    logger.info('Application is already installed, updating');
+    logger.info('Application is already installed, updating...');
 
     // make sure the app is stopped if it's running, to clear the docker container.
     if (await isAppStarted({ projectId })) {