Skip to content

DC

RoboBoard X3 DC motor ports

Note: motor wire colors (red, black) does not indicate polarity (+, -). Swapping wires only changes spin direction.

Control interface for RoboBoard DC H-bridge motor drivers.
May access specific port or all at once:

  • DC.A, DC.B, DC.C, DC.D - control single port
  • DC[0] - control port A [1-B, 2-C, 3-D] (invalid indexes will be ignored)
  • DC - control all ports (some "get" functions are not available in this case)

Code snippets

Function usage example
// Control all DC ports
DC.spin(-50); // Spin backward at 50% power
DC.spin(0); // Stop spin
DC.brake(); // Brake motor
DC.coast(); // Free spin (no breaking and power)
// Play tone on all motors
DC.tone(5000); // Play 5kHz tone trough motor coils
// Change ports PWM frequency
DC.setFrequency(50); // Set PWM frequency to 50Hz
// Brake DC port B
DC[1].brake();
// Configure DC A port
DC.A.setRange(10, 90); // Set power range to [10% : 90%]
DC.A.setAccelerationTime(300); // Set acceleration to 300ms
DC.A.setDecelerationTime(150); // Set acceleration to 150ms
DC.A.setInvert(true); // Invert spin direction

Output ports are directly connected to battery trough motor driver and controlled using PWM modulation. Peak voltage is dependent on SOC of battery. This can vary between 8.4V - 12.6V (X4) and 2.8V - 4.2V (X3). The higher the voltage, the faster motor will spin.

Functions

DC motor can be in 1 of 3 different states:

  • Spin - spinning forward / backward at 0-100% of power
  • Brake - braking (stopping) at 0-100% of power
  • Tone - vibrating coils to generate audible tone

🕹 Spin motors

DC.A.spin(power)

Spin motor at specified amount of power (%) and direction.
-(backward),+(forward), 0(no power).
Parameter:
power - output power [-100:100]%.

DC.A.brake()

DC.A.brake(power)

Brake motor at specified amount of power (%).
Electric brake only. Does not hold wheel in place.
Parameter:
power - set brake power [0:100]%. Default: 100.

DC.A.coast()

Free spin motor (no power, no brake). Same as brake(0).

power DC.A.getSpin()

Get motor current spin power (%) and direction.
-(backward),+(forward), 0(no power).
Returns:
power - output power [-100:100]%.

power DC.A.getBrake()

Get motor current braking power (%).
Returns:
power - brake power [0:100]%.

Tone output

Danger

Do not use tone function for a long period of time. This may overheat the motors.

Play tone (sound) by vibrating DC motor coil. Similar as Arduino tone() function, but with motors. Outputs audible range up to 20kHz. At low frequencies motor may shake a little.

DC.tone(frequency)

DC.tone(frequency,duration)

Start vibrating all DC motors at specified frequency.
Parameter:
frequency - tone frequency [0:20000]Hz. 0 - stop.
duration - output duration [0:65535]ms. 0 - indefinitely (default).

number DC.getTone()

Get currently applied tone.
Returns:
frequency - tone frequency [0:20000]Hz.

Acceleration

Configure motor acceleration and deceleration time. These gradual increase or decrease in speed is applied when changing motor output power with spin(). Any difference between old value and target one will transit gradually. Typically used for tall robots to prevent tip over or gradually spin up some high mass object.
Configuration takes parameter of maximum amount of time required to change speed between 0% and 100%.
Example: Setting setAccelerationTime(1000), motor will require 1 second to reach maximum speed from stand still to 100%.

state DC.A.isAccelerating()

Check if motor is currently in acceleration or deceleration state.
Returns:
state - yes / no [true,false].

state DC.A.wait()

state DC.A.wait(time)

Wait until motor finishes accelerating or decelerating (block code until).
Parameter: time - maximum time to wait (ms) for motor to finish. 0 - disabled.
Returns: state - true if motor finished, false if timeout.

DC.A.setAccelerationTime(time)

Configure amount of time required to accelerate motor from 0% to 100%.
Parameter:
time - acceleration time in milliseconds. 0 - disabled.

DC.A.setDecelerationTime(time)

Configure amount of time required to decelerate motor from 100% to 0%.
If disabled - motor will stop by free spinning (from inertia) or braking (if autobrake enabled).
Parameter:
time - deceleration time in milliseconds. 0 - disabled.

number DC.A.getAccelerationTime()

Get configured amount of time for motor acceleration from 0% to 100%.
Returns:
number - acceleration time in milliseconds. 0 - disabled.

number DC.A.getDecelerationTime()

Get configured amount of time for motor deceleration from 100% to 0%.
Returns:
number - deceleration time in milliseconds. 0 - disabled.

Configure

DC.A.setEnable(state)

Turn motor port on / off to disable any output.

DC.A.setInvert(state)

Invert DC motor spin direction (swaps polarity + -).
Parameter:
state - is inverted spin direction [true:false]

DC.A.setAutobrake(power)

Set automatic brake. Will apply brake when spin() is set to 0.
Used to prevent motor from free spinning.
Parameter:
power - automatic brake power [0:100]% or [false:true].

DC.A.setRange(min,max)

Set motor power range limits. Doing so - motor will start spin at min power and does not overstep max. Used to boost motor at low speed and limit max voltage.
Applied spin power 0-100% spin() will be mapped to configured range.
RoboBoard X4 default: [10:100].
Parameter:
min - minimum percentage required to start spinning a motor. Default: 0
max - maximum allowed percentage of power for the motor. Default: 100

DC.A.setFastDecay()

DC.A.setSlowDecay()

Set coil current dissipation speed (fast or slow). Changes motor behavior.
Fast decay mode: Motor free spins during speed change.
Slow decay mode: More linear speed control. Better torque at low speed.
Note: RoboBoard X4 requires driver version 1.60 or later.

Get settings:

state DC.A.getEnable()

Check if motor port is enabled.
Returns:
state - enabled / disabled [true:false].

state DC.A.getInvert()

Check if motor spin direction is inverted.
Returns:
state - yes / no [true:false].

state DC.A.getAutobrake()

Get configured automatic brake power (if enabled).
Returns:
state - braking power [0:100]%.

Range DC.A.getRange()

Get configured motor port power range.
Returns:
Range - Range structure.

void setup() {
    auto range = DC.A.getRange();
    range.min;
    range.max;
    // Alternative use
    DC.A.getRange().min;
    DC.A.getRange().max;
}

state DC.A.getFastDecay()

state DC.A.getSlowDecay()

Get selected decay mode (fast or slow).
Returns:
state - true if mode is selected.

Configure PWM frequency:

DC.setFrequency(frequency)

Set DC ports PWM frequency. Default: 20kHz.
Can be changed if certain application or motor requires so.
Parameter:
frequency - PWM frequency [1:65535]Hz.

number DC.getFrequency()

Get configured DC ports PWM frequency.
Returns:
number - PWM frequency [1:65535]Hz.