Settings

Reference for OctoMY™ application settings and configuration options.

Pro Tip

Environment variables override settings files, and command-line options override environment variables. This three-tier system lets you configure defaults in the settings file, environment-specific overrides via variables, and per-run overrides via CLI - perfect for deployment and testing.

Settings overview

OctoMY™ uses Qt's QSettings system for persistent configuration:

Settings categories

General settings

Network settings

Connection settings

Security settings

UI settings

Node-specific settings

Agent settings

Settings specific to Agent (robot) nodes:

Remote settings

Settings specific to Remote (controller) nodes:

Hub settings

Settings specific to Hub (fleet) nodes:

Settings API

Reading settings

#include "app/Settings.hpp"

// Get Settings instance
Settings* settings = mContext->settings();

// Read values with defaults
QString name = settings->value("personality/name", "Unknown").toString();
int port = settings->value("network/localPort", 8124).toInt();
bool discovery = settings->value("network/enableDiscovery", true).toBool();

Writing settings

// Write values
settings->setValue("personality/name", "MyRobot");
settings->setValue("network/localPort", 8124);
settings->setValue("network/enableDiscovery", true);

// Force immediate write
settings->sync();

Settings groups

// Use groups for organization
settings->beginGroup("network");
int port = settings->value("localPort", 8124).toInt();
bool discovery = settings->value("enableDiscovery", true).toBool();
settings->endGroup();

Watching settings changes

// Connect to settings changes
connect(settings, &Settings::valueChanged,
        [](const QString& key, const QVariant& value) {
    qDebug() << "Setting changed:" << key << "=" << value;
});

Settings file format

Settings are stored in INI format:

[General]
firstRun=false
lastVersion=1.0.0

[personality]
name=MyRobot
id=abc123def456...

[network]
localPort=8124
enableDiscovery=true
discoveryInterval=5000

[connection]
keepaliveInterval=5000
timeout=15000
autoReconnect=true

[security]
keySize=2048
requirePairing=true

[ui]
theme=dark
language=en

Environment variables

Environment variables override settings:

Using environment variables

# Override port
export OCTOMY_PORT=9000

# Override personality
export OCTOMY_PERSONALITY=TestBot

# Set log level
export OCTOMY_LOG_LEVEL=debug

# Run application
./octomy-agent

Constants

Application constants defined in Constants.hpp:

Application constants

Network constants

Protocol constants

Timing constants

Settings migration

Version migration

When updating OctoMY™, settings may need migration:

void migrateSettings(Settings* settings) {
    QString lastVersion = settings->value("general/lastVersion").toString();
    QString currentVersion = APP_VERSION;

    if (lastVersion < "1.1.0") {
        // Migrate old key format
        if (settings->contains("port")) {
            settings->setValue("network/localPort",
                             settings->value("port"));
            settings->remove("port");
        }
    }

    settings->setValue("general/lastVersion", currentVersion);
}

Backup and restore

// Export settings to file
void exportSettings(Settings* settings, const QString& path) {
    QFile file(path);
    if (file.open(QIODevice::WriteOnly)) {
        QTextStream out(&file);
        for (const QString& key : settings->allKeys()) {
            out << key << "=" << settings->value(key).toString() << "\n";
        }
    }
}

// Import settings from file
void importSettings(Settings* settings, const QString& path) {
    QFile file(path);
    if (file.open(QIODevice::ReadOnly)) {
        QTextStream in(&file);
        while (!in.atEnd()) {
            QString line = in.readLine();
            QStringList parts = line.split("=");
            if (parts.size() == 2) {
                settings->setValue(parts[0], parts[1]);
            }
        }
    }
}

Default settings

Reset to defaults

void resetToDefaults(Settings* settings) {
    // Network defaults
    settings->setValue("network/localPort", AGENT_DEFAULT_PORT);
    settings->setValue("network/enableDiscovery", true);
    settings->setValue("network/discoveryInterval", 5000);

    // Connection defaults
    settings->setValue("connection/keepaliveInterval", 5000);
    settings->setValue("connection/timeout", 15000);
    settings->setValue("connection/autoReconnect", true);

    // Security defaults
    settings->setValue("security/keySize", 2048);
    settings->setValue("security/requirePairing", true);

    // UI defaults
    settings->setValue("ui/theme", "auto");
    settings->setValue("ui/language", "en");

    settings->sync();
}

Settings locations

Platform-specific paths

Data directory

Cache directory

Troubleshooting

Common issues

Debugging settings

# View current settings file (Linux)
cat ~/.config/OctoMY™/OctoMY\ Agent.conf

# Watch settings changes
watch -n 1 cat ~/.config/OctoMY™/OctoMY\ Agent.conf

# Clear all settings
rm -f ~/.config/OctoMY™/OctoMY\ Agent.conf