Merge pull request #240 from peridio/spoff/eng-4060-flesh-out-doc-str…

…ucture

integration: add android

src/docs/cli.md

@@ -2,7 +2,7 @@
 title: Getting started
 ---
 
-# Peridio Command Line Interface Overview
+# Peridio command line interface overview
 
 Peridio CLI, or `peridio`, is a command-line interface to Peridio for use in your terminal or your scripts.
 
@@ -16,15 +16,15 @@ It aims to have complete support for the [Peridio Admin API](/admin-api).
 
 The CLI can upgrade itself in place via `peridio upgrade`.
 
-## Precedence of Supplied Values
+## Precedence of supplied values
 
 Options can be supplied in up to three ways, from highest to lowest precedence:
 
 1. CLI arguments
 2. Environment variables
 3. Configuration files
 
-## Configuration Files
+## Configuration files
 
 The Peridio CLI supports profile based configuration files as a means of supplying options that are relevant to many subcommands. A particular profile can be choosen explicitly via [--profile](#profile). To use this functionality you must specify at least a [config.json](#configjson) file and optionally, if you wish to specify API keys via this method, a [credentials.json](#credentialsjson) in the same directory.
 
@@ -218,11 +218,11 @@ Contains a single object of the format:
   </tbody>
 </table>
 
-## Global Options
+## Global options
 
 Global options are options that are relevant to many commands. They are supplied after `peridio` but before a command, e.g., `peridio --profile foo products list`.
 
-### API Key
+### API key
 
 `-a`, `--api-key <api-key>`, `$PERIDIO_API_KEY`
 
@@ -240,23 +240,23 @@ The base URL of the Peridio Admin API.
 
 Can be provided via configuration files.
 
-### CA Path
+### CA path
 
 `-c`, `--ca-path <ca-path>`, `$PERIDIO_CA_PATH`
 
 A path identifying a file containing PEM encoded CA certificates to additionally trust when making API requests.
 
 Can be provided via configuration files.
 
-### Config Directory
+### Config directory
 
 `-d`, `--config-directory <config-directory>`, `$PERIDIO_CONFIG_DIRECTORY`
 
 Defaults to `$HOME/Library/Application\ Support/peridio` on macOS.
 
 A path identifying the directory the CLI should look within to find Peridio CLI configuration files.
 
-### Organization Name
+### Organization name
 
 `-o`, `--organization-name <organization-name>`, `$PERIDIO_ORGANIZATION_NAME`
 
@@ -274,10 +274,10 @@ Explicitly chooses a profile within a [config.json](#configjson) to use. See [co
 
 The current version of the CLI is `1`.
 
-### Stale Configs
+### Stale configs
 
 Starting with version `0.8.0`, the CLI will halt and prompt you to upgrade your config if it is stale.
 
-### Unversioned Configs
+### Unversioned configs
 
 The very first iteration of a config file was unversioned, accordingly, that "version" is identified by a config file that does not have a `version` key.

src/docs/evk.md

@@ -10,7 +10,7 @@ To get started with the Peridio EVK you will need access to a workstation with t
 * [Peridio CLI](/cli)
 * docker
 
-## Getting Started
+## Getting started
 
 You can install the `peridio-evk` from PyPI
 
@@ -28,7 +28,7 @@ This should be an organization that you have administrative rights to create new
 
 You can generate a new API key in Peridio from the [API Authentication](https://console.peridio.com/settings/api-authentication) page. The generated token will only be displayed to you once, be sure to copy it down for the next steps.
 
-### Initializing the EVK Demo Product
+### Initializing the EVK demo product
 
 Initializing the Peridio EVK demo product is easy and can be done in a single step. From your command line execute the following
 
@@ -68,7 +68,7 @@ As the Peridio EVK program executes, you'll notice a lot of output being present
 
 Tasks are top level items, They illustrate what part of the system is currently being configured
 
-#### Sub Tasks
+#### Sub tasks
 
 ```bash
   ℹ edge-inference-os: v1.12.1
@@ -87,7 +87,7 @@ Subtasks provide more information about the data that is being used during the c
 
 Rendered any time the Peridio EVK modifies a local file. Useful for tracking where Peridio EVK is storing data.
 
-#### CLI Commands
+#### CLI commands
 
 ```bash
 ⬆️  CLI command: peridio --profile peridio-evk devices create --identifier EI-ML-0001 --product-name edge-inference --cohort-prn prn:1:70c48079-0c40-4668-a7c2-3a15e003bc6b:cohort:96686516-e2c0-4690-8405-343429cd9714 --tags canary --target arm64-v8
@@ -97,7 +97,7 @@ When Peridio EVK executes a Peridio CLI command, the command will be rendered to
 
 CLI responses will be rendered just below the CLI command. For streaming operations, such as uploading binaries to Peridio Cloud, The test will be output in realtime as the CLI executes.
 
-### EVK Demo Product Overview
+### EVK demo product overview
 
 The Peridio EVK deploys a demo product called `edge-inference` into your organization which illustrates a common way to configure Peridio Cloud for use with an embedded device. The following resources are deployed into the organization:
 
@@ -181,7 +181,7 @@ Releases:
 
 The Peridio EVK simulates an environment where you have six devices, where four of the devices are Just-In-Time-Provisioned. These devices are in the release cohort and start on release-r1001. There is a release that has been staged for the release cohort titled release-r1002. This release will update the edge-inference-service and edge-inference-model to the latest version. The release is initially staged in a disabled state, and it is configured to deploy to only devices tagged with `canary`. Once you enable the release, and start virtual devices, the `canary` devices will begin to take an update.
 
-### Running Virtual Devices
+### Running virtual devices
 
 Peridio EVK can create, launch, and attach containerized devices using docker to demonstrate device updates and test remote capabilities.
 
@@ -191,7 +191,7 @@ Testing remote access tunnels using the Peridio EVK containerized devices will r
 
 Peridio EVK will generate Identities for six devices. Two of the six devices are already known to Peridio Cloud as they are registered during the initialization process. These devices are tagged with the `canary` tag. Once the next release is "enabled" these two devices will receive the update first. The remaining four device identities were signed with an intermediate certificate that Peridio Cloud is configured with Just-In-Time-Provisioning to register these devices as they come online. This resembles a common production strategy where the certificates of devices may not be known to peridio at the time of manufacture and will instead be registered when they connect for the first time. You can observe this behavior by opening a web browser and navigating to the device list by clicking devices in the Peridio Cloud navigation.
 
-#### Starting Virtual Devices
+#### Starting virtual devices
 
 To start the virtual devices execute the following:
 
@@ -201,7 +201,7 @@ peridio-evk devices-start --tag v3.0.0-rc.4
 
 Peridio EVK will first pull the latest container image from docker-hub for `peridio/peridiod:latest` and launch six containers with unique identities. These devices will appear in Peridio Cloud device list once running. If you have already "enabled" the staged `release-r1002`, the canary devices will immediately start updating.
 
-#### Stopping Virtual Devices
+#### Stopping virtual devices
 
 To stop virtual devices execute the following command
 
@@ -211,7 +211,7 @@ peridio-evk devices-stop
 
 Peridio EVK will stop all running container images.
 
-#### Attaching to a Virtual Device Container
+#### Attaching to a virtual device container
 
 You can attach to a virtual device container to inspect the process of placing release files by executing the following:
 

src/docs/integration/android/overview.md

@@ -0,0 +1,28 @@
+# Overview
+
+Peridio can be integrated with any variant of the Android OS by programming against the Peridio [Device API](/device-api) via [direct API integration](/integration/android/reference-designs/direct-api-integration).
+
+## Reference agent
+
+The code that runs on a device that integrates with Peridio is referred to as a Peridio Agent. For a platform-agnostic overview of its optional and required capabilities, please reference the [Peridio Agent](/integration/introduction#agent) documentation.
+
+`peridiod`, the standard Peridio agent reference implementation, does not currently support Android-specific interfaces, e.g., interacting with Android APIs and libraries to:
+
+- **Install APKs**: Managing package installations directly on the device using the Android Package Manager (e.g., `PackageInstaller` API).
+- **Perform A/B updates**: Orchestrating seamless updates using the Android A/B (seamless updates) system, which involves switching between active and inactive partitions while ensuring rollback protection.
+- **Store configuration and metadata**: Persisting configuration or metadata in areas that survive across reboots, are independent of A/B partitions, and are not wiped during factory resets (e.g., storing in a device-protected storage area or using Android's Key-Value Backup or Device Owner features).
+
+These capabilities require deeper integration with Android's ecosystem than the current implementation provides.
+
+:::info
+Support for Android-specific capabilities in `peridiod` is in-progress, but not yet ready for general consumption. If you would like to participate in a private beta, please reach out.
+:::
+
+The implication of the above is that while the surface area of the Peridio Device API is intentionally small to minimize integration efforts, there will be non-repeatable engineering required to complete the last-mile of integration: the download and application of binaries served by the Peridio Device API.
+
+## Reference designs
+
+While Android-specific hardware reference designs are still in private beta, the following optionas are available:
+
+- [Direct API integration](/integration/android/reference-designs/direct-api-integration).
+- Peridio maintains opinionated reference implementations for a variety of development kits and evaluation boards with respect to Embedded Linux platforms. These will still serve as a helpful context when reasoning about system design with Peridio. For more information, refer to the [Linux reference designs](/integration/linux/overview#reference-designs).

src/docs/integration/android/reference-designs/direct-api-integration.md

@@ -0,0 +1,70 @@
+# Direct API integration
+
+Direct [Device API](/device-api) integration of Android devices with Peridio involves the following:
+
+- Authentication
+- Discover updates
+- Download updates
+- Install updates
+- Optional extensions
+
+## Authentication
+
+Devices authenticate to the Device API via mutual TLS (mTLS), sometimes referred to as mutual authentication. That is, where TLS typically requires the client to verify the server, mTLS requires the client and the server to verify eachother. mTLS is an industry standard variation of transport layer security and is not a Peridio-specific concept. For example, AWS IoT Core uses mTLS. This standardization allows devices to connect to a variety of systems using the same credentials in the same way, simplifying integration while ensuring security.
+
+In the context of Android, this requires that your devices have a device-specific identity that is
+attestable via an X.509 v3 certificate, hereafter refered to as a [device certificate](/platform/reference/device-certificates). The device certificate must be stored on device in a manner that persists in all cases, e.g., across reboots, updates, and factory resets.
+
+:::info mutable identities
+There are exceptional scenarios where one may desire the ability to mutate (delete or reset) a device's identity, which is to say delete or reset the device certificate. Such scenarios are outside the scope of this document.
+:::
+
+The device certificate is then supplied when making requests to the Device API as part of mutual authentication. How exactly this manifests in code is dependent on the client HTTP library you use. For example, when using retrofit/okhttp, reference their [client authentication](https://github.com/square/okhttp/blob/master/okhttp-tls/README.md?utm_source=chatgpt.com#client-authentication) documentation.
+
+A device correctly supplying its certificate is half of the effort, the server must also know to trust the client's certificate. This can be can be achieved in a couple of ways:
+
+- The CLI's [device-certificates create](/cli/device-certificates/create) command.
+  - Typically used in ad-hoc development contexts.
+- The Admin API's [create-a-device-certificate](/admin-api#device-certificates/operation/create-a-device-certificate) route.
+  - Typically used in ad-hoc production contexts.
+- [Just-in-time provisioning](/platform/reference/just-in-time-provisioning).
+  - Typically used in mass-manufacturing production contexts.
+
+## Discover updates
+
+Device's may check if an update is available by hitting the Device API [get-update](/device-api#devices/operation/get-update) route. This will inform them of if an update is available, as well as provide pre-signed download URLs for each of the bundle's binaries. Interaction with this API is also how the device informs Peridio of its current status, i.e., what release/bundle/version it is currently running.
+
+## Download updates
+
+After a device learns an update is available, it is free to download none, some, or all of the available binaries as it deems fit. This decision is as simple or complex as the use case demands, ranging from always downloading immediately when available, to potentially involving custom metadata configured into Peridio, environmental and operational factors like time of day and system status, and even local human operator input.
+
+In any case, it is important to consider:
+
+- How the download is performed.
+- Where the content is downloaded to.
+
+### Fast downloads
+
+Pending the size of your binaries and your operational requirements, it is common to desire "fast downloads". This effectively translates to parallel resumable downloads.
+
+#### Parallel downloads
+
+Parallel downloads involve splitting the binary into smaller chunks and downloading these chunks concurrently using multiple network connections. This approach can significantly improve download speeds, especially in high-bandwidth or low-latency environments, by maximizing network throughput and minimizing the impact of slow segments. Implementing parallel downloads requires support for HTTP range requests, which Peridio supports, and careful management of concurrent streams to avoid overwhelming the device's network stack or storage subsystem. For Android, leveraging libraries like OkHttp with custom interceptors can simplify this implementation.
+
+#### Resumable downloads
+
+Resumable downloads ensure that a download interrupted by network issues, device reboots, or other disruptions can continue from where it left off, rather than restarting from the beginning. This feature is particularly important for large binaries or devices operating in unreliable network conditions. Resumable downloads typically rely on HTTP range requests and metadata tracking to store the progress of each chunk. On Android, this can be achieved by managing state in local storage and using libraries or APIs that support partial downloads, ensuring seamless recovery and efficient use of bandwidth.
+
+## Install updates
+
+After a binary is downloaded, how you install it depends on what the binary is as well as your wider platform context. For apps you may handoff to the Package Installer API. For system updates you may handoff to the Update Engine API. For other artifact types, installation may simply be persisting the binary to a particular location.
+
+## Optional extensions
+
+Beyond OTA and connectivity information described earlier, there are other categories of functionality you may wish to optionally leverage.
+
+### Remote access tunnels
+
+Peridio supports remote access tunnels, that is, secure wireguard connections with your device. From the device's perspective these connections are outbound-initiated, so no inbound ports are required for initiation of the tunnel. The effort to support these tunnels is primarily ensuring wireguard is available on-device, either as a kernel module or a user-space implementation. Beyond that, the device must integrate with the Peridio Device WS API to support control plane operations of this functionality like discovering a tunnel is desired as well as exchanging network configuration handshakes.
+
+For integration support for remote access tunnels, please contact our support team.

src/docs/integration/introduction.md

@@ -1,9 +1,9 @@
-# System Integrations
+# System integrations
 
 Peridio provides agents and reference designs for the following systems:
 
 * [Linux](linux/overview)
-* Android (private beta)
+* [Android](android/overview)
 * RTOS (private beta)
 
 ## Agent

src/docs/integration/linux/build-tools/buildroot.md

@@ -34,7 +34,7 @@ ROOTFS="$BINARIES_DIR/rootfs.squashfs" fwup \
   -o "$BINARIES_DIR/$fw_filename"
 ```
 
-## Testing with QEmu
+## Testing with QEMU
 
 The buildroot integration can be tested using the included build configuration for qemu aarch64. Check out the latest buildroot tag and include the peridio external tree using `BR2_EXTERNAL`.