ArduMY

Reference for the ArduMY protocol - OctoMY™'s communication system between the Agent software and Arduino hardware controllers.

Did You Know?

ArduMY is designed to be "nimble" - it uses minimal data transfer and memory, making it suitable for resource-constrained Arduino boards. The protocol supports multiple value representations (bit, byte, word, float) so you can balance precision against bandwidth for each actuator type.

ArduMY overview

ArduMY is a protocol designed to communicate robot actuator configuration and state from OctoMY™ to Arduino over a serial link, either wired (D-SUB/USB) or wireless (Bluetooth).

While ArduMY is geared towards Arduino, it is designed to be easily adaptable to other MCU/SOC devices.

Design principles

Architecture

ArduMY provides bidirectional communication between OctoMY™ and Arduino:

Protocol basics

Serial configuration

Message structure

Message types

Command messages (Agent → Arduino)

Response messages (Arduino → Agent)

Configuration protocol

Configuration sequence

Actuator configuration message

struct ActuatorConfigMessage {
    quint8 count;            // Number of actuators
    ActuatorConfig configs[]; // Array of configs
};

struct ActuatorConfig {
    quint8 id;               // Actuator ID
    quint8 type;             // ActuatorType enum
    quint8 pin;              // Primary pin
    quint8 pin2;             // Secondary pin (optional)
    quint8 flags;            // Configuration flags
    quint16 minValue;        // Minimum value
    quint16 maxValue;        // Maximum value
    quint16 defaultValue;    // Default value
};

Sensor configuration message

struct SensorConfigMessage {
    quint8 count;            // Number of sensors
    SensorConfig configs[];  // Array of configs
};

struct SensorConfig {
    quint8 id;               // Sensor ID
    quint8 type;             // SensorType enum
    quint8 pin;              // Primary pin
    quint8 pin2;             // Secondary pin (optional)
    quint8 flags;            // Configuration flags
    quint16 sampleRate;      // Sample rate (ms)
};

Actuator commands

SET_ACTUATOR

Set a single actuator value:

struct SetActuatorCommand {
    quint8 id;               // Actuator ID
    qint16 value;            // Target value
};

SET_ALL_ACTUATORS

Set all actuators at once (lower latency):

struct SetAllActuatorsCommand {
    quint8 count;            // Number of values
    qint16 values[];         // Array of values
};

ENABLE_ACTUATOR

Enable or disable an actuator:

struct EnableActuatorCommand {
    quint8 id;               // Actuator ID
    quint8 enable;           // 1=enable, 0=disable
};

Sensor data

SENSOR_DATA message

struct SensorDataMessage {
    quint32 timestamp;       // Arduino millis()
    quint8 count;            // Number of readings
    SensorReading readings[]; // Sensor data
};

struct SensorReading {
    quint8 id;               // Sensor ID
    quint8 type;             // SensorType
    quint16 value;           // Sensor value
    quint8 quality;          // Signal quality (0-100)
};

Sensor polling

Sensors are polled at configured intervals. The Agent can also request immediate readings:

struct RequestSensorsCommand {
    quint8 flags;            // REQUEST_ALL or specific IDs
    quint8 sensorIds[];      // Optional: specific sensors
};

Status messages

STATUS message

Periodic status from Arduino:

struct StatusMessage {
    quint32 uptime;          // Milliseconds since boot
    quint8 actuatorStatus;   // Actuator status bitmask
    quint8 sensorStatus;     // Sensor status bitmask
    quint16 freeMemory;      // Free SRAM bytes
    quint8 errorCount;       // Errors since last status
    quint8 flags;            // Status flags
};

Status flags

Error handling

ERROR message

struct ErrorMessage {
    quint8 errorCode;        // Error code
    quint8 context;          // Error context (actuator/sensor ID)
    char message[32];        // Human-readable message
};

Error codes

Parsers and serializers

ArduMYCommandParser

Parses incoming messages from Arduino:

class ArduMYCommandParser {
public:
    void feed(quint8 byte);
    void feed(const QByteArray& data);

    bool hasMessage() const;
    ArduMYMessage takeMessage();

    void reset();

signals:
    void messageReceived(const ArduMYMessage& msg);
    void parseError(const QString& error);

private:
    enum State {
        WAITING_MAGIC_1,
        WAITING_MAGIC_2,
        READING_LENGTH_1,
        READING_LENGTH_2,
        READING_TYPE,
        READING_FLAGS,
        READING_PAYLOAD,
        READING_CRC_1,
        READING_CRC_2
    };
};

ArduMYCommandSerializer

Serializes outgoing messages:

class ArduMYCommandSerializer {
public:
    QByteArray serializeSync();
    QByteArray serializeConfig(const ArduMYActuatorSet& actuators);
    QByteArray serializeSetActuator(quint8 id, qint16 value);
    QByteArray serializeSetAllActuators(const QVector<qint16>& values);
    QByteArray serializeReset();

private:
    QByteArray buildMessage(quint8 type, const QByteArray& payload);
    quint16 calculateCRC(const QByteArray& data);
};

Magic detection

MagicDetector

Detects ArduMY protocol in serial stream:

class MagicDetector {
public:
    void feed(quint8 byte);
    bool detected() const;
    void reset();

signals:
    void magicDetected();

private:
    bool mSeenAD = false;
    bool mDetected = false;
};

Sync sequence

The Agent sends SYNC to establish communication:

Arduino firmware

ArduMYMain

Main firmware entry point:

class ArduMYMain {
public:
    void setup();
    void loop();

private:
    void processCommand(const ArduMYMessage& msg);
    void sendSensorData();
    void sendStatus();

    ArduMYCommandParser mParser;
    ArduMYActuatorSet mActuators;
    unsigned long mLastSensorUpdate;
    unsigned long mLastStatusUpdate;
};

// main.cpp
ArduMYMain ardumy;

void setup() {
    ardumy.setup();
}

void loop() {
    ardumy.loop();
}

BoardInfo

Hardware information:

struct BoardInfo {
    const char* boardName;
    quint8 digitalPins;
    quint8 analogPins;
    quint8 pwmPins;
    quint32 cpuFreq;
    quint32 sramSize;
};

// Board detection
#if defined(ARDUINO_AVR_UNO)
static const BoardInfo board = {"Uno", 14, 6, 6, 16000000, 2048};
#elif defined(ARDUINO_AVR_MEGA2560)
static const BoardInfo board = {"Mega", 54, 16, 15, 16000000, 8192};
#endif

Value encoding

Representation types

ArduMY supports multiple value representations for bandwidth efficiency:

ArduMYActuatorValue

Union type for actuator values:

union ArduMYActuatorValue {
    qint8 byteValue;
    quint8 ubyteValue;
    qint16 wordValue;
    quint16 uwordValue;
    qint32 dwordValue;
    quint32 udwordValue;
    float floatValue;

    QByteArray serialize(ValueType type) const;
    static ArduMYActuatorValue deserialize(const QByteArray& data,
                                           ValueType type);
};

Type conversions

class ArduMYTypeConversions {
public:
    // Convert between representations
    static qint16 floatToWord(float value, float min, float max);
    static float wordToFloat(qint16 value, float min, float max);

    // Servo angle conversion
    static quint16 angleToMicroseconds(float angle,
                                       float minAngle, float maxAngle,
                                       quint16 minUs, quint16 maxUs);
    static float microsecondsToAngle(quint16 us,
                                     quint16 minUs, quint16 maxUs,
                                     float minAngle, float maxAngle);
};

Using ArduMY

Qt integration

// Create serial connection
QSerialPort* serial = new QSerialPort(this);
serial->setPortName("/dev/ttyUSB0");
serial->setBaudRate(115200);
serial->open(QIODevice::ReadWrite);

// Create ArduMY interface
ArduMY* ardumy = new ArduMY(serial, this);

// Configure actuators
ArduMYActuatorSet actuators;
actuators.addActuator(/* ... */);
ardumy->configure(actuators);

// Set actuator values
ardumy->setActuator(0, 100);
ardumy->setAllActuators({100, 100, 90, 45});

// Receive sensor data
connect(ardumy, &ArduMY::sensorData,
        [](const SensorDataMessage& data) {
    for (int i = 0; i < data.count; i++) {
        qDebug() << "Sensor" << data.readings[i].id
                 << "=" << data.readings[i].value;
    }
});

Pin configuration widget

class ArduinoPinCombobox : public QComboBox {
public:
    void setBoardInfo(const BoardInfo& board);
    void setFilter(ArduinoPinFilter filter);

    int selectedPin() const;
    void setSelectedPin(int pin);
};

enum ArduinoPinFilter {
    FILTER_ALL,
    FILTER_DIGITAL,
    FILTER_ANALOG,
    FILTER_PWM,
    FILTER_INTERRUPT,
};

Troubleshooting

Common issues

Debugging

// Enable protocol debugging
QLoggingCategory::setFilterRules("octomy.ardumy.debug=true");

// Log raw bytes
ardumy->setRawLogging(true);

// Check connection status
qDebug() << "Connected:" << ardumy->isConnected()
         << "Configured:" << ardumy->isConfigured()
         << "Status:" << ardumy->lastStatus();

Serial monitor

Monitor ArduMY traffic:

# Linux
screen /dev/ttyUSB0 115200

# Or use hexdump for raw bytes
stty -F /dev/ttyUSB0 115200
hexdump -C /dev/ttyUSB0