Couriers and Sessions

How OctoMY™ nodes communicate through typed message handlers (Couriers) over secure connections (Sessions).

Did You Know?

The courier system is inspired by medieval postal services - each courier has a "mandate" specifying urgency and priority. CommsChannel acts as the postmaster, deciding which couriers get to send based on their mandates and available bandwidth. High-urgency couriers (like real-time control) get priority over low-urgency ones (like file transfers).

Overview

OctoMY™ communication uses two key concepts:

Sessions

A Session is an active, secure communication channel between two nodes.

Session lifecycle

Session properties

Multiple sessions

A node can have multiple active sessions simultaneously:

Couriers

Couriers are typed message handlers that manage specific kinds of data within a session.

What couriers do

• Maintain state - Keep latest data ready to send
• Handle priorities - Express urgency and importance
• Process incoming - React to received messages
• Generate outgoing - Produce messages when given opportunity

The courier interface

Each Courier exposes a CourierMandate describing its needs:

struct CourierMandate {
    int urgency;        // ms until next send desired
    int priority;       // 0-255, lower = lower priority
    bool acceptReads;   // accept incoming data?
    bool wantToSend;    // have outgoing data?
    int payloadSize;    // expected bytes to send
};

Common couriers

AgentStateCourier

The primary courier for robot state synchronization.

Responsibilities

• Expose current agent state (position, battery, status)
• Accept state updates from controllers
• Maintain "verified" flag for each parameter
• Answer freshness queries ("how old is this data?")

Idle packets

AgentStateCourier sends idle packets even when nothing changes:

• Confirms data is still current
• Maintains connection liveness
• Allows rapid detection of disconnection

BlobCourier

Handles large data transfers that don't fit in single packets.

Features

• Chunking - Splits large data into packets
• Reassembly - Reconstructs at destination
• Reliability - Retransmits lost chunks
• Progress - Reports transfer progress

Use cases

• Firmware updates
• Log file transfers
• Configuration files
• Captured images

How couriers are scheduled

CommsChannel manages all registered couriers:

Courier sets

Couriers are grouped into CourierSets for convenience:

AgentCourierSet

Default couriers for Agent nodes:

• AgentStateCourier
• SensorsCourier
• BlobCourier

RemoteCourierSet

Default couriers for Remote nodes:

• RemoteStateCourier
• CommandCourier
• BlobCourier

Dynamic registration

Couriers can be added/removed dynamically:

• When connecting to new nodes
• When enabling/disabling features
• When changing operational mode

Session vs courier multiplexing

Single session, multiple couriers

One session can carry many courier types:

Session A ──┬── AgentStateCourier
            ├── SensorsCourier
            ├── BlobCourier
            └── CommandCourier

Multiple sessions, Same Courier Types

A Remote controlling multiple Agents:

Remote
  ├── Session to Agent-A
  │     ├── AgentStateCourier (for A)
  │     └── SensorsCourier (for A)
  │
  └── Session to Agent-B
        ├── AgentStateCourier (for B)
        └── SensorsCourier (for B)

Connection modes

CommsChannel operates in different modes:

Normal mode

• Pings inactive nodes at exponentially decaying rate
• Maintains active sessions
• Balances bandwidth across couriers

Honeymoon mode

• Enabled after connection enabled
• Pings all known nodes frequently
• Quickly establishes sessions
• Automatically expires

Celibacy mode

• After explicit disconnection
• Node receives no pings for grace period
• Prevents unwanted reconnection