step.motion.set_speed_mode

Toggle the firmware’s SpeedMode (BEMF on/off) and synchronize the library flag.

SpeedMode disables the STM32’s BEMF closed-loop control. The firmware no longer measures wheel velocity and integrates encoder ticks, so the robot gains roughly 10% top speed at the cost of cm-accurate distance and angle termination. While SpeedMode is on every motion primitive must terminate via an explicit until-condition; using a distance- or angle-based goal raises std::logic_error from the C++ controller.

This step is the only sanctioned way to flip the flag — it owns the LCM handshake with stm32-data-reader:

  1. Publish raccoon::scalar_i32_t(value=1|0) on raccoon/cmd/feature/bemf_enabled (1 = BEMF on / normal mode, 0 = BEMF off / SpeedMode).

  2. Wait for the retained ACK on raccoon/feature/bemf_enabled.

  3. On ACK, update raccoon.foundation.set_speed_mode_enabled so the motion runtime sees the new state.

  4. On timeout, raise RuntimeError — the firmware did not confirm the change and the library state must not diverge from the hardware state.

Classes

SetSpeedMode

Enable or disable SpeedMode (BEMF off / on) via an LCM handshake.

Module Contents

class step.motion.set_speed_mode.SetSpeedMode(enabled: bool, timeout_s: float = _DEFAULT_ACK_TIMEOUT_S)

Bases: step.Step

Enable or disable SpeedMode (BEMF off / on) via an LCM handshake.

SpeedMode disables the firmware’s BEMF closed-loop measurements, granting ~10% additional top speed in exchange for cm precision. Once SpeedMode is active, every motion that has a distance- or angle-based goal will refuse to start — use until-conditions (sensors, timeouts, light gates, …) to terminate motions instead. Returning to normal mode restores BEMF and cm accuracy.

The step publishes the command, waits for the firmware’s ACK on the retained raccoon/feature/bemf_enabled channel, and only then updates the library’s SpeedModeContext flag. If no ACK arrives within the timeout it raises so the program does not proceed with library / firmware state out of sync.

Parameters:

  • enabled – True to engage SpeedMode (BEMF off, 10% faster, no cm precision); False to return to normal closed-loop BEMF control.

  • timeout_s – Maximum time in seconds to wait for the firmware ACK before raising RuntimeError. Defaults to 0.5 s.

Raises:

RuntimeError – If the firmware does not acknowledge the command within timeout_s.

Example:

from raccoon.step.motion import set_speed_mode, drive_forward
from raccoon.step.sensor import on_black

set_speed_mode(True)
drive_forward(speed=1.0).until(on_black(line_sensor))
set_speed_mode(False)