Installation

This tutorial walks you through installing OctoMY™ on your computer or device.

What you'll need

• For development: A computer running Linux, Windows, or macOS
• For running an Agent: An Android device or Raspberry Pi
• For running a Remote: A phone, tablet, or desktop computer

Choose your platform

Pro Tip

For the fastest setup, use Linux with pre-built binaries. You can be up and running in under 5 minutes.

Linux installation

From pre-built binaries

1. Download the latest release:

# Download from GitHub releases
wget https://github.com/mrdeveloperdude/OctoMY/releases/latest/download/octomy-linux-x64.tar.gz

2. Extract the archive:

tar -xzf octomy-linux-x64.tar.gz
cd octomy

3. Run the applications:

# Run the Agent
./agent

# Run the Remote
./remote

# Run the Hub
./hub

Building from source

Building from source is recommended for development or to get the latest features.

Prerequisites

Install the required dependencies:

# Ubuntu/Debian
sudo apt update
sudo apt install -y \
    build-essential \
    git \
    qt6-base-dev \
    qt6-multimedia-dev \
    qt6-positioning-dev \
    qt6-serialport-dev \
    qt6-bluetooth-dev \
    qt6-svg-dev \
    qt6-sensors-dev \
    qt6-tools-dev \
    libmbedtls-dev

# Fedora
sudo dnf install -y \
    gcc-c++ \
    git \
    qt6-qtbase-devel \
    qt6-qtmultimedia-devel \
    qt6-qtpositioning-devel \
    qt6-qtserialport-devel \
    qt6-qtconnectivity-devel \
    qt6-qtsvg-devel \
    qt6-qtsensors-devel \
    mbedtls-devel

Clone and build

# Clone the repository
git clone https://github.com/mrdeveloperdude/OctoMY.git
cd OctoMY

# Build using Qbs
qbs build -f project.qbs

# The executables are in default/install-root/usr/local/bin/
./default/install-root/usr/local/bin/agent

Android installation

From APK

1. Download the APK from the releases page
2. Enable "Install from Unknown Sources" in your Android settings
3. Install the APK by opening the downloaded file
4. Launch OctoMY™ from your app drawer

Building for Android

For Android development, you'll need:

• Android SDK
• Android NDK
• Qt for Android

# Configure Qt for Android in your environment
export ANDROID_SDK_ROOT=/path/to/android-sdk
export ANDROID_NDK_ROOT=/path/to/android-ndk

# Build for Android
qbs build -f project.qbs profile:android

Raspberry Pi installation

Recommended image

Use Raspberry Pi OS (64-bit) for best compatibility.

Installation steps

1. Update your system:

sudo apt update && sudo apt upgrade -y

2. Install Qt dependencies:

sudo apt install -y \
    qt6-base-dev \
    qt6-serialport-dev \
    qt6-bluetooth-dev \
    libmbedtls-dev

3. Download or build OctoMY™ following the Linux instructions above.

4. Auto-start on boot (optional):

# Create a systemd service
sudo tee /etc/systemd/system/octomy-agent.service << 'EOF'
[Unit]
Description=OctoMY Agent
After=network.target

[Service]
Type=simple
User=pi
ExecStart=/home/pi/octomy/agent --personality MyRobot
Restart=always

[Install]
WantedBy=multi-user.target
EOF

# Enable and start
sudo systemctl enable octomy-agent
sudo systemctl start octomy-agent

Verify installation

After installation, verify everything is working:

Check version

./agent --version
# Output: OctoMY Agent 1.0.0

Run a quick test

# Start the Agent
./agent --personality TestAgent

# In another terminal, start the Remote
./remote --personality TestRemote

You should see both applications start and display their main windows.

Directory structure

After first run, OctoMY™ creates its data directory:

~/.local/share/OctoMY™/
├── OctoMY Agent/
│   └── <personality>/
│       ├── keystore.json
│       └── addressbook.json
├── OctoMY Remote/
│   └── <personality>/
│       ├── keystore.json
│       └── addressbook.json
└── OctoMY Hub/
    └── <personality>/
        ├── keystore.json
        └── addressbook.json

Did You Know?

Each personality gets its own isolated data directory. This means you can run multiple Agents on the same machine, each with different configurations and trust relationships.

Troubleshooting

"Qt platform plugin could not be loaded"

Install the missing Qt platform plugins:

# Ubuntu/Debian
sudo apt install qt6-base-plugins

# Or set the platform explicitly
export QT_QPA_PLATFORM=xcb
./agent

"Permission denied on /dev/ttyUSB0"

Add your user to the dialout group for serial port access:

sudo usermod -a -G dialout $USER
# Log out and back in for the change to take effect

"Cannot connect to X server"

For headless operation, use the offscreen platform:

export QT_QPA_PLATFORM=offscreen
./agent

Pro Tip

If you're running on a Raspberry Pi without a display, the offscreen platform is the way to go. You can still access OctoMY™ remotely via the Remote app.

Next steps

Now that OctoMY™ is installed, continue to:

Your first Agent - Set up your first robot node