Communication Manager

Introduction

The Communication Manager (CM) is the central orchestrator running on the Main Node of an AosEdge Unit. It is the single point of connectivity between the Unit and AosCloud, and it coordinates all other components to converge the Unit toward its desired state.

CM is responsible for:

• Maintaining a persistent WebSocket connection to AosCloud
• Receiving and processing desired-state updates from the cloud
• Coordinating software (SOTA) and firmware (FOTA) update workflows
• Managing Service Manager (SM) instances across all Nodes in the Unit
• Allocating and managing network resources for service instances
• Handling Unit-level configuration

This page provides an overview of CM's architecture, subcomponents, and interfaces. Detailed documentation for each subcomponent is available on the linked child pages.

Role in the System

CM acts as the "brain" of the Unit. While SM handles the actual execution of services and IAM handles security, CM is the decision-maker that:

1. Receives instructions from AosCloud via the cloud protocol
2. Determines what needs to change by comparing the desired state against the current state
3. Orchestrates the changes by coordinating image downloads, instance deployments, and firmware updates across all Nodes
4. Reports status back to AosCloud, including monitoring data, alerts, and logs

Only one CM instance runs per Unit, always on the Main Node. Secondary Nodes communicate with CM indirectly through the Message Proxy.

Subcomponents

CM is composed of the following internal modules:

Module	Responsibility
communication	Cloud connectivity — WebSocket-based JSON protocol, service discovery, message send/receive, reconnection logic, and acknowledgment tracking
smcontroller	SM instance management — gRPC server that SM instances connect to; distributes deployment commands and collects status, monitoring, alerts, and logs
networkmanager	Network resource management — DNS server operation, IP subnet allocation, VLAN management, and firewall rule preparation for service containers
unitconfig	Unit configuration — JSON-based configuration parsing and provisioning for Unit-level settings
iamclient	IAM client interface — obtains TLS certificates, system identity, node information, and handles credential change notifications for cloud reconnection
database	Persistent storage — SQLite database with schema migration for CM operational state (network allocations, instance records, image metadata, update state)
config	Process configuration — loads and validates the CM configuration file (aos_cm.cfg)

Additionally, CM incorporates core library modules that run within its process:

Core Module	Responsibility
updatemanager	Update orchestration — processes desired-state deltas, coordinates SOTA and FOTA update workflows, manages update state machine
imagemanager	Image management — handles OCI image download coordination, storage, and layer tracking
launcher	Instance lifecycle — determines instance placement across Nodes, manages start/stop operations
monitoring	Resource monitoring — collects Node-level CPU, RAM, and disk metrics
alerts	Alert generation — watches systemd journal for configured alert patterns and aggregates alert events
storagestate	Storage state — manages persistent state and storage quotas for service instances
nodeinfoprovider	Node information — tracks registered Nodes, their capabilities, and connection status

Interfaces

Cloud Interface (Outbound WebSocket)

CM connects to AosCloud using a WebSocket-based JSON protocol:

1. Service Discovery: CM sends an HTTPS POST to the configured service discovery URL to obtain the cloud WebSocket endpoint
2. WebSocket Connection: A persistent WebSocket connection is established for bidirectional messaging
3. Protocol Version: The current protocol version is 7
4. Message Format: JSON-encoded messages with transaction IDs for request-response correlation
5. Acknowledgment: Messages requiring confirmation use an ACK/NACK mechanism with retry logic
6. Reconnection: Exponential backoff starting at 1 second, capped at 10 minutes

Through this interface, CM:

• Sends Unit status (component versions, service states, Node information)
• Receives desired-state updates (services to deploy, firmware to update, configuration changes)
• Forwards monitoring data, alerts, and logs
• Handles provisioning and certificate lifecycle messages

SM Interface (Inbound gRPC)

CM runs a gRPC server implementing the SMService (defined in servicemanager/v5/servicemanager.proto). SM instances on all Nodes connect to this server as clients.

Through this interface, CM:

• Receives SM registration (Node ID, capabilities, resource capacity)
• Pushes instance update commands (start/stop services)
• Receives instance status reports
• Collects monitoring data from each Node
• Receives alerts and log data
• Distributes network configuration to Nodes
• Manages Node configuration updates

IAM Interface (Outbound gRPC)

CM acts as a gRPC client to the local IAM instance, using both public and protected APIs:

• Public API: Certificate requests and renewals for the CM's own TLS credentials
• Protected API: Provisioning operations, Node management, and certificate lifecycle events
• Certificate Listener: CM subscribes to certificate change notifications and reconnects to the cloud when credentials are rotated

Update Scheduler Interface (Inbound gRPC)

CM exposes the UpdateSchedulerService (defined in communicationmanager/v3/updatescheduler.proto) for external update management integration:

• StartFOTAUpdate — triggers a firmware update
• StartSOTAUpdate — triggers a software update
• SubscribeNotifications — streams update status notifications (SOTA/FOTA progress and state changes)

Update states progress through: NO_UPDATE → DOWNLOADING → READY_TO_UPDATE → UPDATING.

Update Orchestration

One of CM's primary responsibilities is coordinating updates across the Unit. When a desired-state message arrives from the cloud:

1. The communication module receives and parses the message
2. The updatemanager compares the desired state against the current state
3. Required images are downloaded via the imagemanager
4. The launcher determines instance placement across Nodes
5. The smcontroller distributes deployment commands to the appropriate SM instances
6. Status is reported back to the cloud as instances transition through their states

CM handles both SOTA (Software Over-The-Air) updates for services and layers, and FOTA (Firmware Over-The-Air) updates for system components. The update scheduler interface allows external systems to trigger and monitor these updates.

Network Management

CM manages the network infrastructure for all service instances in the Unit:

• DNS Server: Operates a local DNS server for service name resolution
• IP Allocation: Manages IP subnet pools and allocates addresses to service instances
• VLAN Management: Generates and assigns VLAN IDs for network isolation
• Firewall Rules: Prepares firewall rules based on service connection policies
• Network Distribution: Pushes network configuration to SM instances on each Node via the smcontroller

Configuration

CM is configured through a JSON configuration file (default: aos_cm.cfg). Key configuration parameters include:

• Cloud service discovery URL
• IAM server URLs (protected and public)
• CM gRPC server address (for SM connections)
• File server URL (for inter-Node file distribution)
• Storage, state, and working directories
• DNS configuration (IP address, storage path)
• Certificate storage path
• Monitoring, alerting, and image management settings
• Timeouts (Unit status send interval, cloud response wait)

Related Pages

• Architecture Overview — high-level view of all four AosCore components
• Cloud Communication — detailed documentation of the cloud protocol and WebSocket connection

• Update Manager — SOTA/FOTA coordination and update state machine

• SM Controller — how CM manages SM instances across Nodes

• Network Manager — DNS, IP allocation, and network resource management

• Unit Configuration — Unit-level configuration handling

• Service Manager — the component CM coordinates for service execution

• Identity and Access Manager — the component providing CM's security credentials

• Key Concepts — terminology and foundational concepts
• Unit and Node Model — how Units and Nodes relate