Skip to content

Commit

Permalink
update 7948cff
Browse files Browse the repository at this point in the history
  • Loading branch information
GHA committed Dec 6, 2023
0 parents commit 2af003f
Show file tree
Hide file tree
Showing 227 changed files with 11,254 additions and 0 deletions.
4 changes: 4 additions & 0 deletions .buildinfo
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
# Sphinx build info version 1
# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
config: 7c1cccbc9b07fcc5ab0a2891b3ff1abf
tags: 645f666f9bcd5a90fca523b33c5a78b7
Empty file added .nojekyll
Empty file.
Binary file added _images/summary.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
82 changes: 82 additions & 0 deletions _sources/api.rst.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,82 @@

RDFM Server API Reference
-------------------------

API Authentication
~~~~~~~~~~~~~~~~~~

By default, the RDFM server expects all API requests to be authenticated.
Depending on the type of the API, this can be either:

* Device Token
* Management Token

In either case, the server expects the token to be passed as part of the request, in the HTTP Authorization header.
An example authenticated request is shown below:

.. sourcecode:: http

GET /api/v1/groups HTTP/1.1
Host: rdfm-server:5000
User-Agent: python-requests/2.31.0
Accept-Encoding: gzip, deflate
Accept: */*
Connection: keep-alive
Authorization: Bearer token=eyJhbGciOiJSUzI1NiIsInR5cC<...truncated...>RpPonb7-IAsk89YpGayxg

Any request that was not successfully authenticated (because of a missing or otherwise invalid token) will return the 401 Unauthorized status code.
Additionally, in the case of management tokens, if the given token does not provide sufficient access to the requested resource, the request will be rejected with a 403 Forbidden status code.
This can happen if the token does not claim all scopes required by the target endpoint (for example: trying to upload a package using a read-only token).

Error Handling
~~~~~~~~~~~~~~

Should an error occur during the handling of an API request, either because of incorrect request data or other endpoint-specific scenarios, the server will return an error structure containing a user-friendly description of the error.
An example error response is shown below:

.. sourcecode:: json

{
"error": "delete failed, the package is assigned to at least one group"
}


Packages API
~~~~~~~~~~~~

.. autoflask:: rdfm_mgmt_server:app
:modules: api.v1.packages
:undoc-static:
:order: path

Group API
~~~~~~~~~

.. autoflask:: rdfm_mgmt_server:app
:modules: api.v1.groups
:undoc-static:
:order: path

Update API
~~~~~~~~~~

.. autoflask:: rdfm_mgmt_server:app
:modules: api.v1.update
:undoc-static:
:order: path

Device Management API
~~~~~~~~~~~~~~~~~~~~~

.. autoflask:: rdfm_mgmt_server:app
:modules: api.v1.devices
:undoc-static:
:order: path

Device Authorization API
~~~~~~~~~~~~~~~~~~~~~~~~

.. autoflask:: rdfm_mgmt_server:app
:modules: api.v1.auth
:undoc-static:
:order: path
16 changes: 16 additions & 0 deletions _sources/index.md.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
# {{project}}

```{toctree}
:maxdepth: 2

introduction
system_overview
rdfm_linux_device_client
rdfm_android_device_client
rdfm_artifact
rdfm_manager
rdfm_mgmt_server
rdfm_ota_manual
server_operation
api
```
14 changes: 14 additions & 0 deletions _sources/introduction.md.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
# Introduction

RDFM - Remote Device Fleet Manager - is an open-source ecosystem of tools that enable Over-The-Air (OTA) update delivery and fleet management for systems of embedded devices.

This manual describes the main components of RDFM. It is divided into the following chapters:

- System Architecture - a short overview of the system architecture, and how each component of the system interacts with the other
- RDFM Linux Device Client - build instructions and manual for the Linux RDFM Client, used for installing updates on a device
- RDFM Android Device Client - integration guide and user manual for the RDFM Android Client/app used for providing OTA updates via RDFM on embedded Android devices
- RDFM Artifact utility - instruction manual for the `rdfm-artifact` utility used for generating update packages for use with the RDFM Linux device client
- RDFM Manager utility - instruction manual for the `rdfm-mgmt` utility, which allows management of devices connected to the RDFM server
- RDFM Management Server - build instructions and deployment manual for the RDFM Management Server
- RDFM Server API Reference - comprehensive reference of the HTTP APIs exposed by the RDFM Management Server
- RDFM OTA Manual - introduces key concepts of the RDFM OTA system and explains it's basic operation principles
121 changes: 121 additions & 0 deletions _sources/rdfm_android_device_client.md.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,121 @@
# RDFM Android Device Client

## Introduction

The RDFM Android Device Client allows for integrating an Android-based device with the RDFM server.
Currently, only OTA update functionality is implemented.

## Integrating the app

This app is **not meant to be built separately** (i.e in Android Studio), but as part of the source tree for an existing device.
The app integrates with the Android UpdateEngine to perform the actual update installation, which requires it to be a system app.
Some configuration is required to the existing system sources.

### Copying the sources

First, copy the sources of the app to the root directory of the AOSP source tree.
After cloning this repository, run the following:
```
mkdir -v -p <path-to-aosp-tree>/vendor/antmicro/rdfm
cd devices/android-client/
cp -r app/src/main/* <path-to-aosp-tree>
```

### Configuring the device Makefile

The [product Makefile](https://source.android.com/docs/setup/create/new-device#build-a-product) must be configured to build the RDFM app into the system image.
To do this, add `rdfm` to the `PRODUCT_PACKAGES` variable in the target device Makefile:
```
PRODUCT_PACKAGES += rdfm
```

### Building the app

Afterwards, [the usual Android build procedure](https://source.android.com/docs/setup/build/building) can be used to build just the app.
From an already configured build environment, run:
```
mma rdfm
```
The resulting signed APK is in `out/target/product/<product-name>/system/app/rdfm/rdfm.apk`.

## System versioning

The app performs update check requests to the configured RDFM server.
The build version and device type are retrieved from the system properties:
- `ro.build.version.incremental` - the current software version (matches `rdfm.software.version`)
- `ro.build.product` - device type (matches `rdfm.hardware.devtype`)

When uploading an OTA package to the RDFM server, currently these values must be **manually** extracted from the update package, and passed as arguments to `rdfm-mgmt`:
```
rdfm-mgmt packages upload --path ota.zip --version <ro.build.version.incremental> --device <ro.build.product>
```

You can extract the values from the [package metadata file](https://source.android.com/docs/core/ota/tools#ota-package-metadata) by unzipping the OTA package.

## Configuring the app

The application will automatically start on system boot.
Available configuration options are shown below.

### Build-time app configuration

The default build-time configuration can be modified by providing a custom `conf.xml` file in the `app/src/main/res/values/` folder, similar to the one shown below:

```xml
<?xml version="1.0" encoding="utf-8"?>
<resources>
<!--
This is an example overlay configuration file for the RDFM app.
To modify the default server address, you can do:

<string name="default_rdfm_server_address">http://rdfm.example.local:6000/</string>

Likewise, overlaying the default update check interval can be done similarly:

<string name="default_update_check_interval_seconds">240</string>

NOTE: These settings are only used during the app's first startup. To change them afterwards,
you must delete the existing configuration file.
-->
</resources>
```

This build-time configuration is applied **only once, at first startup of the app**, as the main use case for this is first-time configuration for newly provisioned devices.
Modifying it afterwards (for example, via an update containing a new version of the RDFM app) will not result in the change of existing configuration.

### Runtime app configuration

It is possible to change the app's configuration at runtime by simply starting the RDFM app from the drawer and selecting `Settings` from the context menu.

### Update check interval

Currently, the app has a hardcoded update check interval of 4 minutes.
This will be extended in the future to allow configuring it in a similar way as shown above in the server address case.

## Development

The provided Gradle files can be used for development purposes, simply open the `devices/android-client` directory in Android Studio.
Missing references to the `UpdateEngine` class are expected, but they do not prevent regular use of the IDE.

Do note however that **the app is not buildable from Android Studio**, as it requires integration with the aforementioned system API.
To test the app, an existing system source tree must be used.
Copy the modified sources to the AOSP tree, and re-run the [application build](#building-the-app).
The modified APK can then be uploaded to the device via ADB by running:
```
adb install <path-to-rdfm.apk>
```

### Restarting the app

With the target device connected via ADB, run:
```
adb shell am force-stop com.antmicro.update.rdfm
adb shell am start -n com.antmicro.update.rdfm/.MainActivity
```

### Fetching app logs

To view the application logs, run:
```
adb logcat --pid=`adb shell pidof -s com.antmicro.update.rdfm`
```
85 changes: 85 additions & 0 deletions _sources/rdfm_artifact.md.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,85 @@
# RDFM Artifact utility

## Introduction

The RDFM Artifact tool (`rdfm-artifact`) allows for easy creation and modification of RDFM Linux client-compatible artifacts containing rootfs partition images.
A basic RDFM artifact consists of a rootfs image, as well as its checksum, metadata and compatibility with certain device types.

Additionally, `rdfm-artifact` allows for the generation of delta updates, which contain only the differences between two versions of an artifact rather than the entire artifact itself.
This can be useful for reducing the size of updates and improving the efficiency of the deployment process.

## Getting started

In order to support robust updates and rollback, the RDFM Client requires proper partition layout and integration with the U-Boot bootloader. To make it easy to integrate the RDFM Client into your Yocto image-building project, it's recommended to use the [meta-rdfm](https://github.com/antmicro/meta-antmicro/tree/master/meta-rdfm) Yocto layer when building the BSPs.

## Building from source

### Requirements

* Go compiler
* C Compiler
* liblzma-dev and libglib2.0-dev packages

### Steps

To build `rdfm-artifact` on a device from source, clone the repository and build the binary using `make`:

```
git clone https://github.com/antmicro/rdfm.git && cd tools/rdfm-artifact/
make
```

## Basic usage

The basic functionality of writing an artifact is available with the `write` subcommand:

```
NAME:
rdfm-artifact write - Allows creation of RDFM-compatible artifacts

USAGE:
rdfm-artifact write command [command options] [arguments...]

COMMANDS:
rootfs-image Create a full rootfs image artifact
delta-rootfs-image Create a delta rootfs artifact

OPTIONS:
--help, -h show help
```

### Creating a full-rootfs artifact

For example, to create a simple rootfs artifact for a given system image:

```
rdfm-artifact write rootfs-image \
--file "my-rootfs-image.img" \
--artifact-name "my-artifact-name" \
--device-type "my-device-type" \
--output-path "path-to-output.rdfm"
```

### Creating a delta rootfs artifact

For creating a delta artifact, you should have already created two separate full-rootfs artifacts:

- base artifact - the rootfs image that the deltas will be applied on top of, or in other words: the currently running rootfs on the device
- target artifact - the updated rootfs image that will be installed on the device

Given these two artifacts, a delta artifact can be generated like this:

```
rdfm-artifact write delta-rootfs-image \
--base-artifact "base.rdfm" \
--target-artifact "target.rdfm" \
--output-path "base-to-target.rdfm"
```

## Running tests

To run `rdfm-artifact` tests, use the `test` Makefile target:

```
make test
```
68 changes: 68 additions & 0 deletions _sources/rdfm_linux_device_client.md.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
# RDFM Linux Device Client

## Introduction

The RDFM Linux Device Client (`rdfm-client`) integrates an embedded Linux device with the RDFM Server.
This allows for performing robust Over-The-Air (OTA) updates of the running system and remote management of the device.

`rdfm-client` runs on the target Linux device and handles the process of checking for updates in the background along with maintaining a connection to the RDFM Management Server.

## Getting started

In order to support robust updates and rollback, the RDFM Client requires proper partition layout and integration with the U-Boot bootloader. To make it easy to integrate the RDFM Client into your Yocto image-building project, it's recommended to use the [meta-rdfm](https://github.com/antmicro/meta-antmicro/tree/master/meta-rdfm) Yocto layer when building the BSPs.

## Installing from source

### Requirements

* C compiler
* Go compiler
* liblzma-dev, libssl-dev and libglib2.0-dev packages

### Steps

To install an RDFM client on a device from source, first clone the repository and build the binary:
```
git clone https://github.com/antmicro/rdfm.git && cd devices/linux-client/
make
```

Then run the install command:
```
make install
```

### Installation notes

Installing `rdfm` this way does not offer a complete system updater.
System updates require additional integration with the platform's bootloader and a dual-root partition setup for robust updates.
For this, it's recommended to build complete BSPs containing `rdfm` using the [meta-rdfm](https://github.com/antmicro/meta-antmicro/tree/master/meta-rdfm) Yocto layer.

## Building using Docker

All build dependencies for compiling the RDFM Client are included in a dedicated Dockerfile. To build a development container image, you can use:

```
git clone https://github.com/antmicro/rdfm.git && cd devices/linux-client/
sudo docker build -t rdfmbuilder .
```

This will create a Docker image that can be later used to compile the RDFM binary:

```
sudo docker run --rm -v <rdfm-dir>:/data -it rdfmbuilder
cd data/devices/linux-client
make
```

## Developer Guide

### Running tests

Use the `test` make target to run the unit tests:

```
make test
```

Additionally, run the scripts available in the `scripts/test-docker` directory. These scripts test basic functionality of the RDFM client.
Loading

0 comments on commit 2af003f

Please sign in to comment.