Version: v1.1

AOS Cloud — Unit Lifecycle

Overview

An AOS Cloud unit represents a physical vehicle/device managed by the platform. Each unit goes through a defined lifecycle: it is created and provisioned, assigned to unit-sets for grouping and policy application, exposes nodes that can be individually managed, and holds certificates that must be periodically renewed.

┌─────────────────────────────────────────────────────────────┐
│  OEM / Fleet                                                │
│                                                             │
│  Unit (NEW → PROVISIONED)                                   │
│   ├── UnitNodes  (UNPROVISIONED → PROVISIONED / PAUSED)     │
│   ├── UnitCertificates  (ISSUED → RENEW_DONE)               │
│   └── UnitSets  (grouping, auto-provisioning, campaigns)    │
└─────────────────────────────────────────────────────────────┘

1. Unit Creation and Provisioning

1.1 Concept

Before a physical device can connect to AOS Cloud it must be created (registered in the database) and then provisioned (cryptographic identity established, certificates issued, secure data exchanged).

1.2 Unit Status

Status	Meaning
`NEW`	Registered in the cloud, not yet provisioned
`PROVISIONED`	Provisioning complete; unit is operational

1.3 Provisioning Flow

1. Cloud operator creates Unit record
        POST /units/
        Body: system_uid, model, oem, fleet, …

2. Device calls provisioning endpoint
        POST /units/provisioning/
        Body: CSRs (offline + online), secure_data, provisioning_tool_version, …

3. Cloud validates the request
   • Checks provisioning tool version (SUPPORTED_PROVISIONING_SOFT)
   • Validates secure_data format (AosUnitSecretsData)
   • Checks unit limit per OEM
   • Verifies auto_provisioning permission if applicable

4. Cloud generates certificates
   • Offline cert  → CN: {system_uid}-offline
   • Online cert   → CN: {system_uid}-online
   • Additional usage certs if CSRs provided (UM, SM, CM, IAM, …)

5. Cloud finalises provisioning
   • Unit.status → PROVISIONED
   • UnitCertificate records created for each cert
   • Unit associated with default fleet
   • Encrypted secure_data returned to device

6. Unit is ready
   • Connects via MQTT / WebSocket
   • Nodes become discoverable
   • May be auto-assigned to unit-sets

1.4 Key Endpoints

Method	Path	Description
`POST`	`/units/`	Create unit record
`GET`	`/units/{unit_id}`	Get unit details
`PATCH`	`/units/{unit_id}`	Update unit properties
`DELETE`	`/units/{unit_id}`	Delete unit
`POST`	`/units/provisioning/`	Provision unit (called by device)
`POST`	`/units/provisioning/validate-unit/`	Validate provisioning request
`GET`	`/units/provisioning/encryption-certificate/`	Fetch encryption cert chain
`GET`	`/units/provisioning/supported-software/`	List supported provisioning tools

1.5 Unit Online Status

After provisioning the unit reports its connection state:

Status	Meaning
`Offline`	Not connected
`Connected`	Connection established
`Online`	Actively communicating

2. Unit-Sets (Grouping)

2.1 Concept

A unit-set is a named group of units within a fleet. Unit-sets are the primary way to:

Apply update campaigns to a subset of units
Enable auto-provisioning of new nodes
Mark a set as a verification set (like canary group for staged rollouts)
Define update strategies and campaign tags

2.2 Unit-Set Properties

Property	Type	Description
`title`	string	Unique name within the fleet
`is_verification_set`	bool	Whether this set is used as a verification group
`allow_unknown_components`	bool	Allow components not in the approved list
`auto_provision_new_nodes`	bool	Automatically provision newly discovered nodes
`update_strategy`	enum	`MinimizeRestarts` or `MinimizeDownloadTraffic`
`tag`	enum	Campaign tag: `small`, `big`, `blue`, `rollout`

2.3 Verification Sets

When is_verification_set = true the unit-set is used unconditional rollout. Updates are first applied to the verification set; a manual approval step gates rollout to remaining sets. This prevents regressions from reaching the full fleet.

2.4 Auto-Provisioning Nodes

When auto_provision_new_nodes = true:

Any new non-primary node discovered on a unit that belongs to this set is provisioned automatically without a manual operator action.
Requires the auto_provisioning permission on the account.
This setting is evaluated at the unit-set level and applies to all member units.

2.5 Update Strategies

Strategy	Behaviour
`MinimizeRestarts`	Prefer update sequences that reduce the number of service restarts
`MinimizeDownloadTraffic`	Prefer delta/cached updates to minimise bandwidth

2.6 Key Endpoints

Method	Path	Description
`GET`	`/unit-sets/`	List all unit-sets
`POST`	`/unit-sets/`	Create unit-set
`GET`	`/unit-sets/{set_id}`	Get unit-set details
`PATCH`	`/unit-sets/{set_id}`	Update unit-set
`DELETE`	`/unit-sets/{set_id}`	Delete unit-set
`GET`	`/unit-sets/{set_id}/units/`	List units in set
`POST`	`/unit-sets/{set_id}/units/`	Add units to set
`DELETE`	`/unit-sets/{set_id}/units/{unit_id}`	Remove unit from set

3. Unit Node Management

3.1 Concept

A unit node is an isolated execution environment on the physical device (e.g. a VM, container, or hardware partition). Each unit exposes one or more nodes. The primary node (MainNode attribute) represents the main environment and cannot be provisioned or deprovisioned via the cloud API — it is managed at the unit level. All other nodes are managed individually.

3.2 Node States

UNPROVISIONED
    │  [operator starts provisioning]
    ▼
UNPROVISIONED_WAIT_START
    │  [device receives message]
    ▼
UNPROVISIONED_PROVISIONING
    │  [provisioning completes on device]
    ▼
PROVISIONED ◄─────────────────────────────────────┐
    │  [operator pauses]                          │
    ▼                                             │
PAUSING                                           │
    │  [device pauses services]                   │
    ▼                                             │
PAUSED                                            │
    │  [operator resumes]                         │
    ▼                                             │
RESUMING                                          │
    │  [services resume]                          │
    └────────────────────────────────────────────►┘

PROVISIONED
    │  [operator starts unprovisioning]
    ▼
PROVISIONED_WAIT_START_UNPROVISIONING
    │  [device receives message]
    ▼
PROVISIONED_UNPROVISIONING
    │  [unprovisioning complete]
    ▼
UNPROVISIONED

Any state → ERROR (on failure)

3.3 State Transitions Reference

Action	From State(s)	To State	Trigger
Start provisioning	`UNPROVISIONED`	`UNPROVISIONED_WAIT_START`	Operator API call
Device starts provisioning	`UNPROVISIONED_WAIT_START`	`UNPROVISIONED_PROVISIONING`	Device firmware
Provisioning complete	`UNPROVISIONED_PROVISIONING`	`PROVISIONED`	Device status update
Pause	`PROVISIONED`	`PAUSING`	Operator API call
Pause complete	`PAUSING`	`PAUSED`	Device status update
Resume	`PAUSED`	`RESUMING`	Operator API call
Resume complete	`RESUMING`	`PROVISIONED`	Device status update
Start unprovisioning	`PROVISIONED`	`PROVISIONED_WAIT_START_UNPROVISIONING`	Operator API call
Device starts unprovisioning	`PROVISIONED_WAIT_START_UNPROVISIONING`	`PROVISIONED_UNPROVISIONING`	Device firmware
Unprovisioning complete	`PROVISIONED_UNPROVISIONING`	`UNPROVISIONED`	Device status update

3.4 Messaging Protocol

The cloud sends provisioning/unprovisioning commands to the device using one of two protocols depending on the device protocol version:

Protocol	Transport	Message type
V7	WebSocket	`AosStartProvisioningRequestV7` / `AosDeProvisioningRequestV7`

Both carry a nodeId and a randomly generated one-time password for the operation.

3.5 Key Endpoints

Method	Path	Description
`GET`	`/units/{unit_id}/nodes/`	List nodes
`GET`	`/units/{unit_id}/nodes/{node_id}`	Get node details
`PATCH`	`/units/{unit_id}/nodes/{node_id}/`	Rename node
`POST`	`/units/{unit_id}/nodes/{node_id}/provisioning/`	Start node provisioning
`POST`	`/units/{unit_id}/nodes/{node_id}/unprovisioning/`	Start node unprovisioning
`POST`	`/units/{unit_id}/nodes/{node_id}/pause/`	Pause node
`POST`	`/units/{unit_id}/nodes/{node_id}/resume/`	Resume paused node

4. Unit Certificate Management

4.1 Concept

Each unit holds one or more X.509 certificates used for authentication and secure communication. Certificates are issued during provisioning and must be renewed periodically to remain valid.

4.2 Certificate Usage Types

Type	Purpose
`offline`	Unit identification when not connected to cloud
`online`	Active cloud communication
`um`	Update Manager
`sm`	Service Manager
`cm`	Component Manager
`iam`	Identity & Access Management
`host-device`	Host device authentication
`remote-device`	Remote device authentication
`azure-iot`	Azure IoT Hub integration

4.3 Certificate Lifecycle

ISSUED_ON_PROVISIONING
    │  [operator or system requests renewal]
    ▼
RENEW_REQUESTED
    │  [renewal notification sent to device]
    ▼
RENEW_REQUESTED_SENT
    │  [device generates new CSR; cloud signs it]
    ▼
ISSUED_ON_RENEW
    │  [renewal confirmed]
    ▼
RENEW_DONE

On failure:
RENEW_FAILED  →  (retry renewal, re-enters RENEW_REQUESTED)

Superseded certs:
ARCHIVED

Status groups:

Group	Statuses
In use	`ISSUED_ON_PROVISIONING`, `RENEW_DONE`
In progress	`RENEW_REQUESTED`, `RENEW_REQUESTED_SENT`
Renewal allowed	`ISSUED_ON_PROVISIONING`, `RENEW_REQUESTED`, `RENEW_FAILED`

4.4 Renewal Process

Eligibility check — certificate must be in an allowed state and the minimum timeout (UNIT_RENEW_CERTIFICATE_TIMEOUT) must have elapsed since the last attempt.
Status update — certificate transitions to RENEW_REQUESTED.
Notification sent — cloud sends a renewal notification to the device:
- V5/V6: RabbitMQ AosUnitMessage containing type, serial, nodeId, validTill.
- V7: WebSocket AosRenewCertsNotificationV7 with full certificate identification and updated unit_secrets.
Device action — device generates a new CSR and submits it to the cloud.
Cloud signs — cloud issues a new certificate (ISSUED_ON_RENEW) and marks it RENEW_DONE.
Old certificate — previous certificate is archived.

Both single-certificate and bulk renewal are supported.

4.5 Key Endpoints

Method	Path	Description
`GET`	`/units/{unit_id}/unit-certificates/`	List certificates
`GET`	`/units/{unit_id}/unit-certificates/{cert_id}`	Get certificate details
`POST`	`/units/{unit_id}/unit-certificates/{cert_id}/renew/`	Renew single certificate
`POST`	`/units/{unit_id}/unit-certificates/renew/`	Renew all eligible certificates

5. Entity Relationships

Fleet
 ├── Unit (many)
 │    ├── UnitNode (many)
 │    │    └── NodeStatusEnum state machine
 │    ├── UnitCertificate (many)
 │    │    └── UnitCertificateStatus state machine
 │    └── UnitSet (many-to-many)
 │
 └── UnitSet (many)
      └── Campaign (many-to-many)

OEM
 ├── Unit (many)
 └── UnitModel (many)

6. Summary of State Machines

Unit

NEW  →  PROVISIONED

Node

UNPROVISIONED  →  UNPROVISIONED_WAIT_START  →  UNPROVISIONED_PROVISIONING  →  PROVISIONED
PROVISIONED  →  PAUSING  →  PAUSED  →  RESUMING  →  PROVISIONED
PROVISIONED  →  PROVISIONED_WAIT_START_UNPROVISIONING  →  PROVISIONED_UNPROVISIONING  →  UNPROVISIONED
* → ERROR

Certificate

ISSUED_ON_PROVISIONING  →  RENEW_REQUESTED  →  RENEW_REQUESTED_SENT  →  ISSUED_ON_RENEW  →  RENEW_DONE
RENEW_FAILED  →  RENEW_REQUESTED  (retry)
RENEW_DONE / ISSUED_ON_PROVISIONING  →  ARCHIVED  (superseded)

Overview​

1. Unit Creation and Provisioning​

1.1 Concept​

1.2 Unit Status​

1.3 Provisioning Flow​

1.4 Key Endpoints​

1.5 Unit Online Status​

2. Unit-Sets (Grouping)​

2.1 Concept​

2.2 Unit-Set Properties​

2.3 Verification Sets​

2.4 Auto-Provisioning Nodes​

2.5 Update Strategies​

2.6 Key Endpoints​

3. Unit Node Management​

3.1 Concept​

3.2 Node States​

3.3 State Transitions Reference​

3.4 Messaging Protocol​

3.5 Key Endpoints​

4. Unit Certificate Management​

4.1 Concept​

4.2 Certificate Usage Types​

4.3 Certificate Lifecycle​

4.4 Renewal Process​

4.5 Key Endpoints​

5. Entity Relationships​

6. Summary of State Machines​

Unit​

Node​

Certificate​