# OTA updates

Out of the box, Glass Enterprise isn't equipped to perform Over The Air (OTA) updates. However, it's
possible for you to configure basic OTA updates. The EE2 OTA updates functionality gives the device
owner complete control of Over the Air (OTA) updates as follows:

- To control where the update is stored.
- To control when the update happens.
- To control what build the update targets.

**Note:** For more complex OTA updates, review the documentation for [Android UpdateEngine API](https://android.googlesource.com/platform/bootable/recovery/+/master/updater_sample/README.md).

## Configuration

In order to allow for OTA updates in EE2 devices you need server-side and client-side
configurations.

### Server-side configuration

You need to host the OTA update file to be downloaded in a server that's accessible on your
network. The update file should be downloaded from the [System images](https://developers.google.com/glass-enterprise/guides/system-images) page.

You also need to host a JSON file, which drives the update flow. It needs to be formatted just
as the [updater sample.json](https://android.googlesource.com/platform/bootable/recovery/+/master/updater_sample/res/raw/sample.json) example. The file contains information such as the payload size, binary
length, and other metadata that's needed by the update engine to accept the OTA binaries.
**Note:** Only streaming updates are accepted. If the metadata JSON states that the update type is non-streaming, the daemon logs an error message and doesn't start the update procedure. You must force a slot switch if this occurs.

### Client-side configuration

In order for a device to check for OTA updates, you need to setup the OTA URL and polling
interval. You can use an intent to start an activity that sets them up. The name of the activity
is `com.google.android.glass.otaservice/.OtaSettingsActivity`.

There are 2 supported actions:

- `com.google.android.glass.otaservice.UPDATE_LOCATION_ACTION`
  - The URL of the JSON metadata file that the daemon polls and examines.
  - Append a string with the following key: `com.google.android.glass.otaservice.UPDATE_LOCATION`
- `com.google.android.glass.otaservice.UPDATE_FREQUENCY_ACTION`
  - The interval at which the OTA daemon wakes to poll in milliseconds.
  - Append a number with the following key: `com.google.android.glass.otaservice.UPDATE_FREQUENCY`
  - This intent also starts an OTA check immediately if one isn't already running.
  - A number greater than 900,000 milliseconds is required
  - If an OTA is already in progress, the frequency interval is updated after the current check has been completed. This is required, otherwise Android Doze might interrupt the service.

The intent can be sent by a `startActivityForResult`. A response is sent back to the
`onActivityResult` callback with either a `RESULT_OK` on success or
`RESULT_CANCELLED` on failure. A message is then piped to the device logs for
troubleshooting purposes.

The intent can also be sent by adb commands as follows:

```
adb shell am start \
-a com.google.android.glass.otaservice.UPDATE_LOCATION_ACTION \
--es com.google.android.glass.otaservice.UPDATE_LOCATION "some_URL_for_json_file" \
-n com.google.android.glass.otaservice/.OtaSettingsActivity
adb shell am start \
-a com.google.android.glass.otaservice.UPDATE_FREQUENCY_ACTION \
--el com.google.android.glass.otaservice.UPDATE_FREQUENCY 1800000 \
-n com.google.android.glass.otaservice/.OtaSettingsActivity
```

The OTA daemon runs as a `JobService` every 15 minutes or more, depending on the
frequency setting. The `JobService` runs on boot and continues to run until an updated
payload has been accepted and verified.

The background service only polls if Wi-Fi is online and connected. However, Wi-Fi doesn't need
to have internet access, only LAN.

All processing takes place in the background. No user input is required during processing.
A notification shows up on the notification drawer and the OS is updated automatically when
the next reboot occurs.

## Update Steps

Follow these steps to test OTA updates:

1. Download and manually flash the device with *current update*.
2. The Glass Settings device Info card should show: *current update*.
3. Connect to a Wi-Fi network.
4. Execute adb commands to point to your json file to update to the next update:

   ```
   adb shell am start \

   -a com.google.android.glass.otaservice.UPDATE_LOCATION_ACTION \

   --es com.google.android.glass.otaservice.UPDATE_LOCATION "your_json_file_location" \

   -n com.google.android.glass.otaservice/.OtaSettingsActivity

   adb shell am start \

   -a com.google.android.glass.otaservice.UPDATE_FREQUENCY_ACTION \

   --el com.google.android.glass.otaservice.UPDATE_FREQUENCY 900000 \

   -n com.google.android.glass.otaservice/.OtaSettingsActivity
   ```
5. The notification regarding OTA in progress appears
6. The OTA notification disappears
7. On the next manual device bootup, the device should have updated and the Glass Settings device info card should show: *new update*

## Update flow

Here's the standard process by which the OTA update is performed:

1. Upon boot, the OTA daemon schedules its first execution, which is determined by the specified interval. If no interval has ever been provided, it defaults to 15 minutes.
2. The daemon polls the web server to download the metadata file. If no URL was provided, the daemon exits and waits until the next execution interval.
3. The daemon runs preliminary checks on the metadata file to ensure that the proper flags have been set. If there's an error, the daemon exits and prints the output to the logs. The daemon then waits until the next scheduled execution.
4. The daemon compares the entries in the JSON file with those pulled from the current build
   that's running on the device. If a mismatch is detected for any of these entries, an OTA
   download begins. Content from the metadata file are passed to the AOSP update engine.

   The update can't be paused. It continues until it succeeds, fails, or a timeout occurs.
5. The daemon downloads the OTA package in the background automatically.
6. If the OTA package was downloaded and successfully verified, the daemon stops polling for new updates. Upon reboot, the update actually takes effect. A notification appears to inform the user that the update will be applied upon the next reboot.
7. If the OTA download fails, the daemon polls the web server after the specified interval has elapsed again.

## Application updates

Application updates in EE2 should be handled as standard Android updates. There are two main
options:

1. Use an MDM solution or build your own device owner application and update the application silently. You can use the Android API [PackageInstaller](https://developer.android.com/reference/android/content/pm/PackageInstaller) to do this.
2. Use the Android API [PackageInstaller](https://developer.android.com/reference/android/content/pm/PackageInstaller) directly from your application to have it update itself. A system dialog appears in this case.