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.
Can be accessed for each port individually:

  • DC.A - control port A
  • DC.B - control port B
  • DC.C - control port C
  • DC.D - control port D
  • DC[0] - control port A [1-B, 2-C, 3-D] (invalid indexes will be ignored)
  • DC - control all ports ("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)
DC.tone(5000); // Play 5kHz tone trough motor coils
// Brake DC port B
DC[1].brake();
// Configure DC A port
DC.A.setFrequency(50); // Set PWM frequency to 50Hz
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.
PWM configuration:
RoboBoard X3: slow decay at 20kHz.
RoboBoard X4: fast decay at 50Hz (slow decay not available at the moment).

Functions

Single DC motor port 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 spin a little.

Note: RoboBoard X4 has ports AB and CD tied together. By setting tone to A, port B will start to output same tone also.

DC.A.tone(frequency) ¶

DC.A.tone(frequency,duration) X4 only ¶

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

number DC.A.getTone() ¶

Get current tone frequency applied to the motor.
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.setFrequency(frequency) ¶

Set motor PWM frequency. Default X3: 20kHz, X4: 50Hz.
Can be changed if certain application or motor requires so.
Note: RoboBoard X4 ports AB and CD are tied together (setting A will affect B also).
Parameter:
frequency - PWM frequency [1:65535]Hz.

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(state) X3 only ¶

Set motor 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 currently supports only fast decay mode.
Parameter:
state - false(slow decay), true(fast decay). Default: slow decay.

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]%.

number DC.A.getFrequency() ¶

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

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() X3 only ¶

Get selected decay mode (fast or slow).
Returns:
state - false(slow decay), true(fast decay). Default: slow decay.