Communications Architecture

Real-time bidirectional communication for robot control. The comms system provides secure, low-latency communication between OctoMY nodes using multiple transport mechanisms.

Node Roles

Architecture Layers

Layer 1: Transport (CommsCarrier)

The lowest layer handles raw packet transmission over different physical media.

• UDP sockets for LAN communication
• Bluetooth for direct pairing
• Future: Audio channel for ultrasonic communication

Each carrier provides:

• Packet sending/receiving
• Address abstraction (NetworkAddress, BluetoothAddress)
• Connection state detection

Layer 2: Channel (CommsChannel)

Manages logical connections over the transport layer.

• Packet routing and multiplexing
• Session management
• SYN/SYNACK/ACK handshake protocol with hybrid asymmetric encryption
• Session key derivation (ECDH for Ed25519 pairs, key-transport for RSA/cross-algorithm)
• Flow control via heartbeat-derived RTT

Layer 3: Session (CommsSession)

Per-associate connection state management.

• One session per active connection
• Key-based authentication
• Session key for AEAD courier encryption
• 64-bit nonce counter with sliding-window replay detection
• Activity tracking (last seen time)
• Bandwidth and latency monitoring

Encryption

Encryption is applied at two levels, controlled at runtime via Comms::encryptionEnabled():

• Handshake packets (SYN/SYNACK/ACK): hybrid asymmetric encryption using the recipient's public key. Both RSA and Ed25519 are supported via the ISigningKey interface; cross-algorithm sessions (RSA ↔ Ed25519) work via key-transport.
• Courier data: XChaCha20-Poly1305 AEAD with a per-session symmetric key derived during the handshake. Each packet carries a monotonic 64-bit nonce counter; a sliding window detects replays.

Layer 4: Courier

Application-level message transporters. Each courier handles a specific data type:

Layer 5: Client

Runtime representation of an Associate connection.

• One Client per Associate in the AddressBook
• Manages CourierSet for the connection
• Tracks connection need state
• Handles courier registration lifecycle

Key Concepts

Associate vs Client

An Associate represents a known node (stored identity, keys, permissions). A Client is created when the node needs to communicate with that Associate.

Controls

From an Agent's perspective, "controls" are Remote nodes with permission to send commands.

• Designated by ROLE_CONTROL in Associate
• Filtered via ClientList::withActiveSessions()
• Multiple controls possible (primary operator + supervisor)

CourierSet

Groups related couriers for a single connection.

• One CourierSet per Client
• Enables/disables as a unit
• Registered with CommsChannel when connection needed
• Unregistered when connection no longer needed

Signal Flow

Connection State Discovery

DiscoveryMandate (what should be discovered)
    |
    v
DiscoveryClient (performs discovery)
    |
    v
ReachableState (tracks reachability)
    |
    v
UI Components (display status)

Courier Registration

Client::setNeedsConnection(bool)
    |
    v
Client::updateCourierRegistration()
    |
    v
CourierSet::enable(bool)
    |
    v
Individual Couriers register with CommsChannel

Control Filtering

ClientList::all()
    |
    v
Filter by ROLE_CONTROL
    |
    v
ClientList::withActiveSessions()
    |
    v
Active controller Clients

See Also

• Discovery - Node discovery protocol
• Sessions - Session management
• Protocols - Protocol specifications
• Couriers - Courier implementations