From 2090ab4f57ce32b62cbb0bfc8b8697ae3d85fa1f Mon Sep 17 00:00:00 2001 From: Bodong Yang <86948717+Bodong-Yang@users.noreply.github.com> Date: Wed, 22 May 2024 15:18:53 +0900 Subject: [PATCH] docs: cleanup the old out-of-date docs (#307) --- README.md | 4 - docs/INSTALLATION.md | 88 -------- docs/README.md | 395 -------------------------------- docs/SERVICES.md | 524 ------------------------------------------- 4 files changed, 1011 deletions(-) delete mode 100644 docs/INSTALLATION.md delete mode 100644 docs/README.md delete mode 100644 docs/SERVICES.md diff --git a/README.md b/README.md index ec30fdbfa..c5a57f6aa 100644 --- a/README.md +++ b/README.md @@ -24,7 +24,3 @@ When the OTA client receives an update request, it downloads a list from the OTA ## License OTA client is licensed under the Apache License, Version 2.0. - -## Document - -See [OTA client document](docs/README.md) diff --git a/docs/INSTALLATION.md b/docs/INSTALLATION.md deleted file mode 100644 index 40a478371..000000000 --- a/docs/INSTALLATION.md +++ /dev/null @@ -1,88 +0,0 @@ -# Installation - -## Install otaclient with pip to custom install location - -NOTE: upgrade `setuptools`, `setuptools-scm` and `pip` before installation - -Here we take installing otaclient to `/opt/ota/otaclient` as example. - -### 1. git clone the specific branch/tag to a temporary folder - -```bash -git clone https://github.com/tier4/ota-client -b /tmp/ota-client -``` - -### 2. prepare virtual env and activate it - -```bash -python3 -m venv /opt/ota/.venv -source /opt/ota/.venv/bin/activate -``` - -### 3. under the venv, install dependencies for otaclient with pip - -```bash -# NOTE: we will not use the otaclient install here, -# check the following instructions -pip install /tmp/ota-client -``` - -### 4. under the venv, install the otaclient package to /opt/ota - -```bash -# NOTE: --no-deps MUST be set, otherwise all dependencies -# will also be install under /opt/ota -pip install -t /opt/ota --no-deps /tmp/ota-client -# cleanup -rm -rf /opt/ota/otaclient*dist-info -rm -rf /tmp/ota-client -``` - -## Launch otaclient from custom install location - -If we install the otaclient to custom directory instead of the default location, we must indicate python the path to the install location. - -### method 1: indicate path by **PYTHONPATH** - -```bash -# we have to append the /opt/ota to the PYTHONPATH, to tell the -# python interpreter to search otaclient package under /opt/ota, instead of -# using the one install under /lib/python3.8/site-packages - -# with venv activated: -PYTHONPATH=/opt/ota python3 -m otaclient -# or -PYTHONPATH=/opt/ota python3 -m otaclient.app -``` - -### method 2: change working dir to the install location - -```bash -# change work dir to /opt/ota -cd /opt/ota - -# with venv activated: -# NOTE:python will insert current working dir at index 0 in `sys.path` -# under /opt/ota folder, so that python will first use otaclient under /opt/ota -python3 -m otaclient -# or -python3 -m otaclient.app -``` - -## Launch aws_iot_log_server from custom install location - -The same as above, we have to indicate the otaclient installation path before launching the `aws_iot_log_server`. - -```bash -source /opt/ota/.venv/bin/activate -cd /opt/ota - -# with venv enabled, under the /opt/ota folder -python3 -m aws_iot_log_server \ - --host 0.0.0.0 \ - --port {{ ota_client_log_server_port }} \ - --aws_credential_provider_endpoint ${AWS_CREDENTIAL_PROVIDER_ENDPOINT} \ - --aws_role_alias ${AWS_ROLE_ALIAS} \ - --aws_cloudwatch_log_group ${AWS_CLOUDWATCH_LOG_GROUP} \ - --greengrass_config ${AWS_GREENGRASS_CONFIG} -``` diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index a1044a2d8..000000000 --- a/docs/README.md +++ /dev/null @@ -1,395 +0,0 @@ -# OTA client - -## Overview - -This OTA client is a client software to perform over-the-air software updates for linux devices. -To enable updating of software at any layer (kernel, kernel module, user library, user application), the OTA client targets the entire rootfs for updating. -When the OTA client receives an update request, it downloads a list from the OTA server that contains the file paths and the hash values of the files, etc., to be updated, and compares them with the files in its own storage and if there is a match, that file is used to update the rootfs. By this delta mechanism, it is possible to reduce the download size even if the entire rootfs is targeted and this mechanism does not require any specific server implementation, nor does it require the server to keep a delta for each version of the rootfs. - -## Feature - -- Rootfs updating -- Delta updating -- Redundant configuration with A/B partition update -- Arbitrary files can be copied from A to B partition. This can be used to take over individual files. -- No specific server implementation is required. The server that supports HTTP GET is only required. - - TLS connection is also required. -- Delta management is not required for server side. -- To restrict access to the server, cookie can be used. -- All files to be updated are verified by the hash included in the metadata, and the metadata is also verified by X.509 certificate locally installed. -- Transfer data is encrypted by TLS -- Multiple ECU(Electronic Control Unit) support -- By the internal proxy cache mechanism, the cache can be used for the download requests to the same file from multiple ECU. - -## License - -OTA client is licensed under the Apache License, Version 2.0. - -## OTA client setup - -### Requirements - -- supported boot loader - - GRUB - - [CBoot](https://docs.nvidia.com/jetson/archives/l4t-archived/l4t-3271/index.html#page/Tegra%20Linux%20Driver%20Package%20Development%20Guide/bootflow_jetson_xavier.html#wwpID0E0JB0HA) - -- runtime - - python3.8 (or higher) - - pip - - setuptools - -### Dependency installation - -```bash -sudo python3.8 -m pip install -r otaclient/requirements.txt -``` - -Note that OTA client is run with super user privileges so `sudo` is required for the above command. - -### Partitioning - -For the GRUB system, the disk is partitioned as follows: - -```bash -$ sudo fdisk -l /dev/sda -Disk /dev/sda: 128 GiB, 137438953472 bytes, 268435456 sectors -Disk model: VBOX HARDDISK -Units: sectors of 1 * 512 = 512 bytes -Sector size (logical/physical): 512 bytes / 512 bytes -I/O size (minimum/optimal): 512 bytes / 512 bytes -Disklabel type: dos -Disk identifier: 0x6cf681a1 - -Device Boot Start End Sectors Size Id Type -/dev/sda1 * 2048 2000895 1998848 976M 83 Linux -/dev/sda2 2000896 135217151 133216256 63.5G 83 Linux -/dev/sda3 135217152 268433407 133216256 63.5G 83 Linux - -$ lsblk /dev/sda -NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINT -sda 8:0 0 128G 0 disk -├─sda1 8:1 0 976M 0 part /boot -├─sda2 8:2 0 63.5G 0 part / -└─sda3 8:3 0 63.5G 0 part -``` - -In this example, A(=active) partition is sda2 and B(=standby) partition is sda3. -And `/boot` partition is shared by A/B partitions. -Note that the disk and the sector size depend on the system, but the size of A and B should be the same, basically. - -## OTA client Configurations - -OTA client can update a single ECU or multiple ECUs and is installed for each ECU. -There are two types of ECU, Main ECU - receives user request, Secondary ECUs - receive request from Main ECU. One or multiple Secondary ECUs can also have Secondary ECUs. - -The figure below shows an example ECU structure, that shows Main ECU and 6 Secondary ECUs(A~F). -Secondary ECU A, B and C are connected to Main ECU, and D, E, F are connected to Secondary ECU A. - -```text - +----------------+ - | OTA server | - +----------------+ - | - |(internet) - | -+----------+-------------------------------------------------------+ -| |(internal ECU-to-ECU network) | -| +----------------+ +----------------+ +----------------+ | -| | Main ECU |--+--|Secondary ECU(A)|--+--|Secondary ECU(D)| | -| +----------------+ | +----------------+ | +----------------+ | -| | +----------------+ | +----------------+ | -| +--|Secondary ECU(B)| +--|Secondary ECU(E)| | -| | +----------------+ | +----------------+ | -| | +----------------+ | +----------------+ | -| +--|Secondary ECU(C)| +--|Secondary ECU(F)| | -| +----------------+ +----------------+ | -+------------------------------------------------------------------+ -``` - -### ecu\_info.yaml - -ecu_info.yaml is the setting file for ECU configuration. - -#### File path - -/boot/ota/ecu_info.yaml - -#### Entries - -- format_version (string, required) - - This field specifies the ecu_info.yaml format. - Currently this field is not used but `1` should be specified for future use. - -- ecu_id (string, required) - - This field specifies ECU id and that should be unique in all EUCs. - -- ip_addr (string, optional) - - This field specifies this OTA client's IP address. - If this field is not specified, "localhost" is used. - NOTE: this IP address is used for the local server bind address. - -- secondaries (array, optional) - - This field specifies list of **directly connected** secondary ECUs information. - If this field is not specified, it is treated as if secondary ecu doesn't exist. - - - ecu_id (string, required) - ecu id of secondary ECU - - - ip_addr (string, required) - IP address of secondary ECU. - -- available_ecu_ids (optional) - - This field specifies a list of all ECU ids to be updated. - Only the main ECU should have this information. - - NOTE: For backward-compatibility, if this `available_ecu_ids` filed does not exist, the ecu_id of the main ecu is considered the entry for available_ecu_ids. - - NOTE: for web.auto user, web.auto agent will use `available_ecu_ids` to generate update request, only ECUs listed in `available_ecu_ids` will be included in the update request list. - - NOTE: The difference between secondaries and available_ecu_ids: - - `secondaries` lists the directly connected children ECUs, available_ecu_ids consists of all children ECU ids(including directly connected, indirectly connected and itself) to be updated. - -#### The default setting - -If ecu_info.yaml doesn't exist, the default setting is used as follows: - -- format_version - - 1 - -- ecu_id - - "autoware" - -### proxy\_info.yaml - -proxy_info.yaml is the setting file for OTA proxy configuration. - -OTA proxy is the software integrated into the OTA client that access the OTA server on behalf of the OTA client. -Whether OTA proxy access the OTA server directly or indirectly depends on the configuration. - -See [OTA proxy](../ota_proxy/README.md) more details. - -#### File path - -/boot/ota/proxy_info.yaml - -#### Entries - -- enable_local_ota_proxy (boolean, default=**true**) - - This field specifies whether OTA client uses local OTA proxy or not. - If this field is set to **true**, OTA client will not download remote OTA files using local OTA proxy, it means OTA client connects to remote OTA server directly. If the local OTA proxy is enabled, the OTA client requests the remote OTA files via the local OTA proxy. - -- upper_ota_proxy (string, default=**""**) - - This field specifies the upper OTA proxy address to be use by the OTA client or local OTA proxy server. Only **HTTP** proxy is supported, like `http://192.168.20.11:8082`. If not set or set to `""`, not upper_ota_proxy will be used. - -- gateway (boolean, default=**false**) - - When the `enable_local_ota_proxy` field is true, this field specifies whether the **local OTA proxy** requests the remote OTA server directly with HTTPS or HTTP. If it is true or this config entry is not presented, HTTPS is used otherwise HTTP is used. - Note that if the ECU can't access to the remote OTA server directly, the value **MUST** be set to false, `enable_local_ota_proxy` **MUST** be set to true to enable local OTA proxy server, and a valid `upper_ota_proxy` **MUST** be set for local OTA proxy server to connect to parent ECU's OTA proxy server. - -- enable_local_ota_proxy_cache (boolean, default=**true**) - - When the `enable_local_ota_proxy` field is true, this field specifies whether the local OTA proxy caches the requests and uses the local caches to satisify the requests or not. If it is true or this config entry is not set, the local cache is used otherwise not used. - -- local_ota_proxy_listen_addr (string, default=**"0.0.0.0"**) - - When the `enable_local_ota_proxy` field is true, this field specifies the listen address for local OTA proxy. If not specified, local OTA proxy will listen on **"0.0.0.0"**. - -- local_ota_proxy_listen_port (integer, default=**8082**) - - When the `enable_local_ota_proxy` field is true, this field specifies the listen port for local OTA proxy. If not specified, port **8082** will be used. - -#### NOTE about OTA client behavior under different combination of `enable_local_ota_proxy` and `upper_ota_proxy` setting - -The behavior of OTA client under different `enable_local_ota_proxy` and `upper_ota_proxy` setting is as follow: - -| `enable_local_ota_proxy` | `upper_ota_proxy` | `behavior` | -| :---: | :---: | --- | -| (unset, default=false) | (unset, default="") | OTA client directly connects to remote without any proxy | -| true | set | OTA client connects to remote via OTA proxy, and local OTA proxy itself also uses `upper_ota_proxy` to connect to remote | -| true | (unset, default="") | OTA client connects to remote via OTA proxy, and local OTA proxy connects to remote directly | -| false | set | OTA client connects to remote via `upper_ota_proxy`, local OTA proxy is not enabled and not used | -| false | not set | OTA client directly connects to remote without any proxy | - -#### Example `proxy_info.yaml` for main ECU - -The main ECU defined here is responsible to provide OTA proxy for all child and sub child ECUs to connect to the remote OTA server. - -```yaml -# local OTA proxy for main ECU also provides proxy service for all child/sub child ECUs -enable_local_ota_proxy: true -# for main ECU that directly connects to the Internet, HTTPS should be used, so set gateway=true -gateway: true -``` - -#### Example `proxy_info.yaml` for sub ECU - -The sub ECU defines here is which has at least one parent ECU and cannot connect the Internet directly. The sub ECU requires at least one upper OTA client that provides OTA proxy, and download OTA files via this upper proxy. - -If this sub ECU also serves sub ECUs, the OTA proxy for this sub ECU MUST be enabled to provide OTA proxy for its sub ECUs(and subsub ECUs if any). - -```yaml -# local OTA proxy Must be enabled if the sub ECU also serves child ECUs, -# should be enabled if local OTA files cache is needed. -enable_local_ota_proxy: true -# a valid upper_ota_proxy MUST be set for local OTA proxy to connect to remote as sub ECU cannot -# directly connect the Internet -upper_ota_proxy: "http://192.168.20.11:8082" -# optional: if the sub ECU's disk is not so fast(like USB device), local OTA proxy cache can be disabled -# enable_local_ota_proxy_cache: false -``` - -### Note about the behavior when `proxy_info.yaml` is missing - -If `proxy_info.yaml` file is missing/not found, OTA client is expected to running on main ECU(or equivalent that directly connects to the Internet), a pre-defined `proxy_info.yaml` will be used as follow: - -```yaml -enable_local_ota_proxy: true -gateway: true -``` - -## OTA image generation - -It is not the OTA client's responsibility to prepare an OTA image, but this section describes how to create an OTA image with docker. - -### Preparation - -Create an empty working directory and clone the following two repositories. - -```bash -cd $(mktemp -d) -git clone https://github.com/tier4/ota-client -git clone https://github.com/tier4/ota-metadata -``` - -### OTA image sign and verification key generation - -OTA image is signed by the OTA image server side and verified by OTA client to make sure the image is legitimate. -This section describes how to generate sign and verification key with sample generation script. - -```bash -bash ota-client/tests/keys/gen_certs.sh -``` - -Note that the above script is a sample, so some setting might need to be changed for each product. - -The keys to be created are as follows: - - -| file name | install location |description | -| ---: | ---: | --- | -| root.pem | OTA client local | Root certificate.
This file should be installed to the ota-client/certs directory. | -| interm.pem| OTA client local | Intermediate certificate.
This file should be installed to the ota-client/certs directory. | -| sign.pem | OTA image server | Certificate file to verify OTA image.
This file is downloaded from OTA server and verified with root and intermediate certificate. | -| sign.key | OTA image generator | Key to sign OTA image.
This is only required by the OTA server when signing an OTA image. | - - -### Dockerfile - -The Dockerfile need to be prepared as follows: - -```Dockerfile -FROM ubuntu:20.04 -SHELL ["/bin/bash", "-c"] -ENV DEBIAN_FRONTEND=noninteractive -ARG KERNEL_VERSION="5.8.0-53-generic" - -RUN \ - apt-get update && apt-get install -y --no-install-recommends \ - sudo ubuntu-minimal openssh-server \ - ubuntu-desktop-minimal \ - fonts-ubuntu \ - systemd-coredump vim git \ - grub-efi-amd64 \ - linux-image-${KERNEL_VERSION} linux-headers-${KERNEL_VERSION} linux-modules-extra-${KERNEL_VERSION} \ - apt-utils python3-pip usbutils \ - gcc libc6-dev \ - dirmngr rsyslog gpg-agent initramfs-tools - -RUN git clone https://github.com/tier4/ota-client -WORKDIR /ota-client -RUN python3 -m pip install -r app/requirements.txt -# install certificates to verify sign.pem -RUN mkdir certs -COPY root.pem certs/0.root.pem -COPY interm.pem certs/0.interm.pem - -# add ota-client user -RUN useradd -m ota-client -s /bin/bash && \ - echo ota-client:ota-client | chpasswd && \ - gpasswd -a ota-client sudo -``` - -### Metadata generation - -Build the docker image with Dockerfile created above and export rootfs image from the docker instance. - -Metadata generation now support optional zstd compression, files that can be compressed(file size or compression ratio reach threshold) will be compressed and saved to another folder. Note that the original files will still be kept under main rootfs folder. - -```bash -docker build -t ota-image . -docker create -it --rm --name ota-image ota-image -docker export ota-image > ota-image.tar -mkdir rootfs -sudo tar xf ota-image.tar -C rootfs -``` - -Note: `sudo` is required to extract `ota-image.tar` since some privileged files need to be created. - -Generate metadata(with or without zstd compression) under extraced rootfs folder as follow: - -```bash -# optional zstd compression disabled -sudo python3 ota-metadata/metadata/ota_metadata/metadata_gen.py \ - --target-dir \ - --ignore-file ota-metadata/metadata/ignore.txt -# or -# optional zstd compression enabled -sudo python3 ota-metadata/metadata/ota_metadata/metadata_gen.py \ - --target-dir \ - --compressed-dir \ - --ignore-file ota-metadata/metadata/ignore.txt -``` - -Sign the generated metadata as follow: - -```bash -# if compression is not enabled for OTA image -sudo python3 ota-metadata/metadata/ota_metadata/metadata_sign.py \ - --sign-key sign.key \ - --cert-file sign.pem \ - --persistent-file persistents.txt \ - --rootfs-directory -# or -# zstd compression enabled for OTA image -sudo python3 ota-metadata/metadata/ota_metadata/metadata_sign.py \ - --sign-key sign.key \ - --cert-file sign.pem \ - --persistent-file ota-metadata/metadata/persistents.txt \ - --rootfs-directory \ - --compressed-rootfs-directory - -sudo chown -R $(whoami) rootfs -``` - -Created metadata are as follows: - -- `metadata.jwt` -- `dirs.txt` -- `symlinks.txt` -- `regulars.txt` -- `total_regular_size.txt` -- `persistents.txt` - -The OTA image consists of metadata above, `sign.pen` and `rootfs` directory and can be served by the OTA server. - -## Services - -About OTA client services, see [Services](SERVICES.md). diff --git a/docs/SERVICES.md b/docs/SERVICES.md deleted file mode 100644 index 946a5b876..000000000 --- a/docs/SERVICES.md +++ /dev/null @@ -1,524 +0,0 @@ -# Protocol Documentation - - -## Table of Contents - -- [ota_metafiles.proto](#ota_metafiles-proto) - - [DirectoryInf](#otaclient-DirectoryInf) - - [PersistentInf](#otaclient-PersistentInf) - - [RegularInf](#otaclient-RegularInf) - - [SymbolicLinkInf](#otaclient-SymbolicLinkInf) - -- [otaclient_v2.proto](#otaclient_v2-proto) - - [RollbackRequest](#OtaClientV2-RollbackRequest) - - [RollbackRequestEcu](#OtaClientV2-RollbackRequestEcu) - - [RollbackResponse](#OtaClientV2-RollbackResponse) - - [RollbackResponseEcu](#OtaClientV2-RollbackResponseEcu) - - [Status](#OtaClientV2-Status) - - [StatusProgress](#OtaClientV2-StatusProgress) - - [StatusRequest](#OtaClientV2-StatusRequest) - - [StatusResponse](#OtaClientV2-StatusResponse) - - [StatusResponseEcu](#OtaClientV2-StatusResponseEcu) - - [StatusResponseEcuV2](#OtaClientV2-StatusResponseEcuV2) - - [UpdateRequest](#OtaClientV2-UpdateRequest) - - [UpdateRequestEcu](#OtaClientV2-UpdateRequestEcu) - - [UpdateResponse](#OtaClientV2-UpdateResponse) - - [UpdateResponseEcu](#OtaClientV2-UpdateResponseEcu) - - [UpdateStatus](#OtaClientV2-UpdateStatus) - - - [FailureType](#OtaClientV2-FailureType) - - [StatusOta](#OtaClientV2-StatusOta) - - [StatusProgressPhase](#OtaClientV2-StatusProgressPhase) - - [UpdatePhase](#OtaClientV2-UpdatePhase) - - - [OtaClientService](#OtaClientV2-OtaClientService) - -- [Scalar Value Types](#scalar-value-types) - - - - -

Top

- -## ota_metafiles.proto - - - - - -### DirectoryInf - - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| mode | [int32](#int32) | | | -| uid | [int32](#int32) | | | -| gid | [int32](#int32) | | | -| path | [string](#string) | | | - - - - - - - - -### PersistentInf - - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| path | [string](#string) | | | - - - - - - - - -### RegularInf - - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| mode | [int32](#int32) | | | -| uid | [int32](#int32) | | | -| gid | [int32](#int32) | | | -| nlink | [int32](#int32) | | | -| sha256hash | [bytes](#bytes) | | | -| path | [string](#string) | | | -| size | [int64](#int64) | | | -| inode | [int64](#int64) | | | -| compressed_alg | [string](#string) | | | - - - - - - - - -### SymbolicLinkInf - - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| mode | [int32](#int32) | | | -| uid | [int32](#int32) | | | -| gid | [int32](#int32) | | | -| slink | [string](#string) | | | -| srcpath | [string](#string) | | | - - - - - - - - - - - - - - - - -

Top

- -## otaclient_v2.proto - - - - - -### RollbackRequest - - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| ecu | [RollbackRequestEcu](#OtaClientV2-RollbackRequestEcu) | repeated | | - - - - - - - - -### RollbackRequestEcu -Request - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| ecu_id | [string](#string) | | | - - - - - - - - -### RollbackResponse - - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| ecu | [RollbackResponseEcu](#OtaClientV2-RollbackResponseEcu) | repeated | | - - - - - - - - -### RollbackResponseEcu -Response - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| ecu_id | [string](#string) | | | -| result | [FailureType](#OtaClientV2-FailureType) | | | - - - - - - - - -### Status - - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| status | [StatusOta](#OtaClientV2-StatusOta) | | | -| failure | [FailureType](#OtaClientV2-FailureType) | | | -| failure_reason | [string](#string) | | failure reason string | -| version | [string](#string) | | current version string | -| progress | [StatusProgress](#OtaClientV2-StatusProgress) | | status is UPDATING, this field is valid. | - - - - - - - - -### StatusProgress - - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| phase | [StatusProgressPhase](#OtaClientV2-StatusProgressPhase) | | | -| total_regular_files | [uint64](#uint64) | | number of total regular file | -| regular_files_processed | [uint64](#uint64) | | number of the regular file processed | -| files_processed_copy | [uint64](#uint64) | | number of the regular file processed by copy | -| files_processed_link | [uint64](#uint64) | | number of the regular file processed by hard-link | -| files_processed_download | [uint64](#uint64) | | number of the regular file processed by download | -| file_size_processed_copy | [uint64](#uint64) | | total file size of the regular file processed by copy | -| file_size_processed_link | [uint64](#uint64) | | total file size of the regular file processed by hard-link | -| file_size_processed_download | [uint64](#uint64) | | total file size of the regular file processed by download | -| elapsed_time_copy | [google.protobuf.Duration](#google-protobuf-Duration) | | total elapsed time by copy | -| elapsed_time_link | [google.protobuf.Duration](#google-protobuf-Duration) | | total elapsed time by hard-link | -| elapsed_time_download | [google.protobuf.Duration](#google-protobuf-Duration) | | total elapsed time by download | -| errors_download | [uint64](#uint64) | | total number of download error | -| total_regular_file_size | [uint64](#uint64) | | total regular file size | -| total_elapsed_time | [google.protobuf.Duration](#google-protobuf-Duration) | | total elapsed time | -| download_bytes | [uint64](#uint64) | | data transfer volume during the whole OTA update process | - - - - - - - - -### StatusRequest -Status - -Request - - - - - - - - -### StatusResponse - - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| ecu | [StatusResponseEcu](#OtaClientV2-StatusResponseEcu) | repeated | **Deprecated.** list of status(v1) of all available ECUs, replaced by ecu_v2 | -| available_ecu_ids | [string](#string) | repeated | list of all available ECUs in this vehicle (see ecu_info.yml) | -| ecu_v2 | [StatusResponseEcuV2](#OtaClientV2-StatusResponseEcuV2) | repeated | list of status(v2) of all available ECUs | - - - - - - - - -### StatusResponseEcu - - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| ecu_id | [string](#string) | | ECU id respond | -| result | [FailureType](#OtaClientV2-FailureType) | | | -| status | [Status](#OtaClientV2-Status) | | | - - - - - - - - -### StatusResponseEcuV2 - - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| ecu_id | [string](#string) | | --- static ECU info: 1~10 --- // | -| firmware_version | [string](#string) | | | -| otaclient_version | [string](#string) | | | -| ota_status | [StatusOta](#OtaClientV2-StatusOta) | | --- dynamic ECU status: 11~ --- // | -| failure_type | [FailureType](#OtaClientV2-FailureType) | optional | when ota_status is FAILURE/ROLLBACK_FAILURE, failure_type, failure_reason should be set | -| failure_reason | [string](#string) | optional | | -| failure_traceback | [string](#string) | optional | | -| update_status | [UpdateStatus](#OtaClientV2-UpdateStatus) | optional | update status, set if ota_status is UPDATING | - - - - - - - - -### UpdateRequest - - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| ecu | [UpdateRequestEcu](#OtaClientV2-UpdateRequestEcu) | repeated | | - - - - - - - - -### UpdateRequestEcu -Request - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| ecu_id | [string](#string) | | ECU id to update. OTA client pickups the entry that matches their own ECU id and this ECU id. | -| version | [string](#string) | | version to update. Any version string can be used. When the update is done successfully, the OTA client saves this version as the current version. | -| url | [string](#string) | | OTA server URL. | -| cookies | [string](#string) | | cookie entries with JSON notation. | - - - - - - - - -### UpdateResponse - - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| ecu | [UpdateResponseEcu](#OtaClientV2-UpdateResponseEcu) | repeated | | - - - - - - - - -### UpdateResponseEcu -Response - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| ecu_id | [string](#string) | | EUC id responded | -| result | [FailureType](#OtaClientV2-FailureType) | | result | - - - - - - - - -### UpdateStatus - - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| update_firmware_version | [string](#string) | | --- update meta: 1~10 --- // - -update target image version | -| total_files_size_uncompressed | [uint64](#uint64) | | uncompressed size of all files in update_firmware image | -| total_files_num | [uint64](#uint64) | | total files num in the update_firmware image | -| update_start_timestamp | [uint64](#uint64) | | update start time in unix timestamp | -| phase | [UpdatePhase](#OtaClientV2-UpdatePhase) | | --- update progress: 11~30 --- // | -| total_download_files_num | [uint64](#uint64) | | - downloading phase - // - -num of files needed to be downloaded from remote | -| total_download_files_size | [uint64](#uint64) | | size(uncompressed) of all files needed to be downloaded | -| downloaded_files_num | [uint64](#uint64) | | downloaded files num during downloading | -| downloaded_bytes | [uint64](#uint64) | | network traffic during downloading | -| downloaded_files_size | [uint64](#uint64) | | size(uncompressed) of downloaded files during downloading | -| downloading_errors | [uint64](#uint64) | | | -| total_remove_files_num | [uint64](#uint64) | | - applying update phase - // - -for in-place update mode, files to be removed | -| removed_files_num | [uint64](#uint64) | | for in-place update mode, removed files during standby slot updating | -| processed_files_num | [uint64](#uint64) | | NOTE: processed_files_num/size are corresponding to total_files_num/total_image_size - -num of files processed to the standby slot during applying update | -| processed_files_size | [uint64](#uint64) | | size(uncompressed) of processed files | -| total_elapsed_time | [google.protobuf.Duration](#google-protobuf-Duration) | | --- timing --- // | -| delta_generating_elapsed_time | [google.protobuf.Duration](#google-protobuf-Duration) | | | -| downloading_elapsed_time | [google.protobuf.Duration](#google-protobuf-Duration) | | | -| update_applying_elapsed_time | [google.protobuf.Duration](#google-protobuf-Duration) | | | - - - - - - - - - - -### FailureType -Common - -| Name | Number | Description | -| ---- | ------ | ----------- | -| NO_FAILURE | 0 | | -| RECOVERABLE | 1 | | -| UNRECOVERABLE | 2 | | - - - - - -### StatusOta -Response - -| Name | Number | Description | -| ---- | ------ | ----------- | -| INITIALIZED | 0 | | -| SUCCESS | 1 | | -| FAILURE | 2 | | -| UPDATING | 3 | | -| ROLLBACKING | 4 | | -| ROLLBACK_FAILURE | 5 | | - - - - - -### StatusProgressPhase - - -| Name | Number | Description | -| ---- | ------ | ----------- | -| INITIAL | 0 | | -| METADATA | 1 | | -| DIRECTORY | 2 | | -| SYMLINK | 3 | | -| REGULAR | 4 | | -| PERSISTENT | 5 | | -| POST_PROCESSING | 6 | | - - - - - -### UpdatePhase - - -| Name | Number | Description | -| ---- | ------ | ----------- | -| INITIALIZING | 0 | | -| PROCESSING_METADATA | 1 | | -| CALCULATING_DELTA | 2 | | -| DOWNLOADING_OTA_FILES | 3 | | -| APPLYING_UPDATE | 4 | | -| PROCESSING_POSTUPDATE | 5 | | -| FINALIZING_UPDATE | 6 | set during first reboot boot switch finalizing | - - - - - - - - - -### OtaClientService -The OTA Client service definition. -Style Guide: https://developers.google.com/protocol-buffers/docs/style#message_and_field_names - -| Method Name | Request Type | Response Type | Description | -| ----------- | ------------ | ------------- | ------------| -| Update | [UpdateRequest](#OtaClientV2-UpdateRequest) | [UpdateResponse](#OtaClientV2-UpdateResponse) | `Update` service requests OTA client to start updating. The OTA client of each ECU retrieves the request that matches its own ECU id and starts it. Requests to each ECU included in the `UpdateRequest` are handled by that respective ECU and returns the response to the parent ECU. Main ECU merges the responses as UpdateResponse. After requesting `Update` and if the OTA status is `UPDATING`, the request is successful. Note that if the child ECU doesn't respond, the grandchild response is not included by `UpdateResponse`. | -| Rollback | [RollbackRequest](#OtaClientV2-RollbackRequest) | [RollbackResponse](#OtaClientV2-RollbackResponse) | NOT YET | -| Status | [StatusRequest](#OtaClientV2-StatusRequest) | [StatusResponse](#OtaClientV2-StatusResponse) | `Status` service requests OTA client to retrieve OTA client status. Note that if the child ECU doesn't respond, the grandchild response is not contained by `StatusResponse`. | - - - - - -## Scalar Value Types - -| .proto Type | Notes | C++ | Java | Python | Go | C# | PHP | Ruby | -| ----------- | ----- | --- | ---- | ------ | -- | -- | --- | ---- | -| double | | double | double | float | float64 | double | float | Float | -| float | | float | float | float | float32 | float | float | Float | -| int32 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. | int32 | int | int | int32 | int | integer | Bignum or Fixnum (as required) | -| int64 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. | int64 | long | int/long | int64 | long | integer/string | Bignum | -| uint32 | Uses variable-length encoding. | uint32 | int | int/long | uint32 | uint | integer | Bignum or Fixnum (as required) | -| uint64 | Uses variable-length encoding. | uint64 | long | int/long | uint64 | ulong | integer/string | Bignum or Fixnum (as required) | -| sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int | int32 | int | integer | Bignum or Fixnum (as required) | -| sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long | int64 | long | integer/string | Bignum | -| fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int | uint32 | uint | integer | Bignum or Fixnum (as required) | -| fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long | uint64 | ulong | integer/string | Bignum | -| sfixed32 | Always four bytes. | int32 | int | int | int32 | int | integer | Bignum or Fixnum (as required) | -| sfixed64 | Always eight bytes. | int64 | long | int/long | int64 | long | integer/string | Bignum | -| bool | | bool | boolean | boolean | bool | bool | boolean | TrueClass/FalseClass | -| string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode | string | string | string | String (UTF-8) | -| bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str | []byte | ByteString | string | String (ASCII-8BIT) |