Discovery Protocol

Technical reference for OctoMY™'s node discovery system, which enables nodes to find and connect to each other.

Did You Know?

OctoMY™'s adaptive discovery timing ("honeymoon scheduler") dramatically reduces network traffic - when idle, discovery broadcasts happen only once per minute, but when you open the pairing screen, the system shifts to 1-second intervals for rapid detection. This means battery-powered devices can stay discoverable without draining their batteries.

Overview

Discovery is the process by which OctoMY™ nodes detect other nodes and establish communication. The system supports multiple discovery channels that can operate independently or together.

Design principles

Discovery channels

OctoMY™ supports six discovery channels:

Channel selection

Channels are enabled via DiscoveryMandate:

DiscoveryMandate mandate{
    .connecting = true,     // Enable discovery
    .useZoo = true,         // Use Zoo server
    .useNetwork = true,     // Use LAN broadcast
    .useBluetooth = false,  // Bluetooth disabled
    .useAudio = false,      // Audio disabled
    .useNFC = false,        // NFC disabled
    .useCamera = false      // Camera disabled
};

LAN Discovery

The primary discovery mechanism for nodes on the same local network.

Constants

Packet format

Packet types

Discovery flow

Broadcast Phase:

1. Node binds to UDP port 8473
2. Broadcasts ANNOUNCE packet to 255.255.255.255
3. Repeats every 5 seconds while discovering

Response Phase:

1. Receiving node validates packet (magic, version)
2. Extracts sender's Node ID and port
3. Sends ANNOUNCE_ACK directly to sender's IP:port
4. Emits nodeDiscovered(nodeId) signal

Discovery timing

Discovery uses adaptive timing via HoneymoonScheduler to balance responsiveness with resource usage.

Timing parameters

State transitions

Trigger events

Discovery becomes "triggered" when:

• User opens pairing screen
• New peer is added to address book
• Connection lost to known peer
• Application starts

State management

Discovery separates desired state (mandate) from actual state (status).

DiscoveryMandate

Represents what the user wants to happen:

struct DiscoveryMandate {
    bool connecting;     // Should we be discovering?
    bool useZoo;         // Use Zoo server?
    bool useNetwork;     // Use LAN broadcast?
    bool useBluetooth;   // Use Bluetooth?
    bool useAudio;       // Use audio?
    bool useNFC;         // Use NFC?
    bool useCamera;      // Use camera?
};

DiscoveryStatus

Represents what is actually happening:

struct ChannelStatus {
    bool active;              // Currently running?
    bool attempting;          // Trying to start?
    qint64 lastActivityTime;  // Last successful operation
    qint64 lastAttemptTime;   // Last start attempt
    QString lastError;        // Error message if failed
};

Status queries

DiscoveryStatus status = discoveryClient->status();

// Per-channel status
ChannelStatus lan = status.networkStatus();
ChannelStatus zoo = status.zooStatus();
ChannelStatus bt  = status.bluetoothStatus();

// Check if any channel is active
bool anyActive = status.isAnyActive();

// Check if trying to connect
bool trying = status.isAttempting();

Discovery classes

DiscoveryClient

Main orchestrator for client-side discovery.

Source: src/libs/libpair/discovery/DiscoveryClient.hpp:81

Signals:

DiscoveryServer

Server-side handling of discovery requests.

Source: src/libs/libpair/discovery/DiscoveryServer.hpp

Receives discovery announcements and responds with node information.

LANDiscovery

UDP broadcast implementation.

Source: src/libs/libpair/discovery/LANDiscovery.hpp

Zoo discovery

For nodes behind NAT or on different networks, Zoo servers provide discovery.

Flow

1. Node registers with Zoo server (HTTPS)
2. Provides Node ID, node type, external address
3. Zoo stores registration
4. Other nodes query Zoo for registered nodes
5. Zoo provides peer's public address for NAT punch

Advantages

Discovery events

Event flow

Event types

Packet validation

Magic validation

static const char MAGIC[] = "OCTOMY";  // 6 bytes

bool validateMagic(const QByteArray &packet) {
    if (packet.size() < PACKET_SIZE) return false;
    return memcmp(packet.data(), MAGIC, 6) == 0;
}

Version check

const quint8 CURRENT_VERSION = 0x01;

bool validateVersion(quint8 version) {
    return version == CURRENT_VERSION;
}

Node type validation

enum NodeType : quint8 {
    TYPE_AGENT  = 0,
    TYPE_REMOTE = 1,
    TYPE_HUB    = 2
};

bool validateNodeType(quint8 type) {
    return type <= TYPE_HUB;
}

Security considerations

Threats

Best practices

• Only trust discovered nodes after key exchange
• Rate limit discovery processing
• Validate all packet fields before use
• Use Zoo for sensitive environments

Integration example

// Configure discovery
auto client = mNode->discoveryClient();
client->configure(mNode, 1000, 60000, 20000, 40000);

// Connect signals
connect(client, &DiscoveryClient::nodeDiscovered,
    this, &MyClass::onNodeDiscovered);

// Set mandate (enable LAN + Zoo)
DiscoveryMandate mandate{
    .connecting = true,
    .useZoo = true,
    .useNetwork = true
};
client->setMandate(mandate);

// Activate
client->activate(true);

// Trigger immediate discovery
client->discover(true);

Troubleshooting

Common issues

Debug logging

Enable discovery debug output:

qputenv("QT_LOGGING_RULES", "oc.discovery.debug=true");