Agent node reference

Technical reference for the Agent node type. An Agent is the robot or autonomous device being controlled in the OctoMY™ network.

Overview

Architecture

Agent modes

Agents operate under different modes that control their behavior:

Authority mode

Determines who has control over the Agent:

Design Decision: Authority modes

The authority mode system separates "who can control" (trust/skeptron) from "is being controlled" (control mode). This allows an Agent to grant skeptron authority to a Remote without immediately surrendering control.

Alternatives considered: Always active skeptron, permission-based control Tradeoff: Requires understanding two related concepts Benefit: Flexible control handoff, maintains operator oversight

Skeptron mode

When a node gains skeptron authority over the Agent, they may choose to control it:

Note: Requires Agent to be in "Available" authority mode.

Did You Know?

"Skeptron" (σκῆπτρον) is the Greek word for scepter - a symbol of royal authority. In OctoMY™, holding the skeptron means having the authority to control the Agent. Like a real scepter, it can be passed between trusted parties.

Control mode

How the Agent is currently being controlled:

Core components

Agent class

The main Agent class extends Node with hardware-specific functionality:

class Agent : public Node {
    QSharedPointer<AgentWindow> mWindow;
    QSharedPointer<AgentConfigStore> mAgentConfigStore;
    QSharedPointer<AgentConfigService> mAgentConfigService;
    QSharedPointer<ControllerHandler> mControllerHandler;
    // ...
};

Key methods

Configuration

Agent config

Agent-specific configuration stored in AgentConfigStore:

Storage location

~/.local/share/OctoMY™/OctoMY Agent/<personality>/
├── keystore.json       # Cryptographic keys
├── addressbook.json    # Known peers
├── agentconfig.json    # Hardware configuration
└── planbook/           # Behavior plans

Pro Tip

Each Agent personality gets its own completely isolated data directory. This means you can run multiple Agents on the same machine, each with different hardware configurations and trust relationships. Useful for testing and development!

Services

The Agent activates these services in order:

Hardware integration

Controller types

Actuator support

• Servo motors (PWM)
• DC motors (H-bridge)
• Stepper motors
• LED indicators
• Custom GPIO

Sensor support

• Distance sensors (ultrasonic, IR)
• Cameras (via Qt Multimedia)
• GPS (via Qt Positioning)
• IMU (accelerometer, gyroscope, compass)
• Custom analog inputs

Communication

As Agent role

In communication, the Agent role means:

• Receives commands from Controls (Remote, Hub)
• Sends sensor data to Controls
• Receives Plan updates
• Executes local Plans

Couriers registered

UI components

Agent window

The main window for Agent UI:

Activities

First-time setup

The Agent "birth" process:

1. Key Generation - Create cryptographic identity
2. Personality Generation - Derive name, colors, identicon
3. Hardware Detection - Scan for connected controllers
4. Controller Configuration - Set up actuators/sensors
5. Discovery - Announce presence to network

Did You Know?

The Agent birth process is called "delivery" in OctoMY terminology. The AgentDeliveryActivity guides users through this one-time setup wizard. Once delivered, the Agent remembers its identity permanently.

Command line

# Start Agent with default personality
./agent

# Start with specific personality
./agent --personality "MyRobot"

# Start with specific base directory
./agent --base-dir /path/to/data

# Enable debug output
./agent --debug

API reference

Inherited from Node

The Node base class provides these inherited methods:

• keyStore() - Access cryptographic keys
• addressBook() - Access known peers
• comms() - Access communication system
• discoveryClient() - Access peer discovery
• nodeIdentity() - Get this node's identity

Agent-specific

Component reference