DC
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 ADC.B
- control port BDC.C
- control port CDC.D
- control port DDC[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
// 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 to0
.
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 overstepmax
. 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.