类: 步进电机驱动

约 6235 字大约 21 分钟

2026-05-21

构建固件和导入到JS

在 C++ 里加入以下代码, 然后重新编译构建固件：

// 为了控制固件的尺寸，BeShell 的 module 是按需引入的。
beshell.use<be::fas::FastAccelStepper>() ;

Stepper 类由 fas 模块提供：

import { Stepper } from 'fas'

类方法

方法 waitStop

原型: waitStop ()

等待电机停止运行。返回一个 Promise，当电机完全停止后 resolve。内部通过定时轮询 isRunning() 状态实现，不会阻塞 JS 主线程。

例子:

stepper.move(1000);
await stepper.waitStop();
console.log('电机已停止，当前位置:', stepper.getCurrentPosition());

// 配合限位使用
stepper.setLimitPin(17);
await stepper.waitStop();

返回值:

类型Promise<void>

说明电机停止后 resolve 的 Promise

方法 setLimitPin

原型: setLimitPin (pin:number, activeLow:boolean=true)

为步进电机设置限位引脚。可以多次调用此方法为一个电机添加多个限位引脚。当限位引脚触发时，电机将立即停止并触发 "limit" 事件。如需在限位触发后反向移出限位区域，可调用 {@link ignoreLimit} 临时屏蔽限位信号，移动完成后再恢复监听。

注意：此方法不会检查引脚是否已被注册。如果对同一个引脚重复调用，会导致 ISR 数据泄漏和不可预知的错误行为，请确保每个引脚只设置一次。

例子:

// 设置多个限位引脚
stepper.setLimitPin(17);        // GPIO17，默认低电平有效
stepper.setLimitPin(18, false); // GPIO18，高电平有效

stepper.on('limit', (pin) => {
    console.log('限位触发:', pin);
});

// 临时忽略限位
stepper.ignoreLimit(true);

参数:

pin
类型number
参数说明限位引脚 GPIO 编号
activeLow
类型boolean
默认值true
参数说明触发电平，true 为下降沿触发（低电平有效），false 为上升沿触发

返回值:

类型undefined

方法 ignoreLimit

原型: ignoreLimit (ignore:boolean=true)

临时忽略限位引脚的触发信号。通常用于撞到限位后需要反向移动电机离开限位位置的场景。

例子:

stepper.setLimitPin(17);
stepper.move(1000);
await stepper.waitStop();

// 撞到限位后，忽略限位并反向移出
stepper.ignoreLimit(true);
await stepper.move(-200);
stepper.ignoreLimit(false);

参数:

ignore
类型boolean
默认值true
参数说明是否忽略限位，true 忽略，false 恢复监听

返回值:

类型undefined

方法 setDirectionPin

原型: setDirectionPin (pin:number, polarity:boolean=true, delay_us:number=0)

设置步进电机的方向控制引脚、极性和切换方向时的延迟时间（以微秒为单位）。

例子:

stepper.setDirectionPin(5, true, 100);

参数:

pin
类型number
参数说明GPIO 引脚号，用于控制步进电机的方向。
polarity
类型boolean
默认值true
参数说明方向极性，true 表示正向，false 表示反向。
delay_us
类型number
默认值0
参数说明切换方向时的延迟时间，单位为微秒。这个参数用于确保在切换方向时有足够的时间让电机停下来，以避免损坏。

异常:

如果参数无效或设置失败，将抛出异常。

返回值:

类型undefined

方法 setEnablePin

原型: setEnablePin (pin:number, low_active:boolean=true)

设置步进电机的使能控制引脚和低电平激活模式。

例子:

stepper.setEnablePin(4, true);

参数:

pin
类型number
参数说明GPIO 引脚号，用于控制步进电机的使能。
low_active
类型boolean
默认值true
参数说明true 表示低电平激活使能，false 表示高电平激活。

异常:

如果参数无效或设置失败，将抛出异常。

返回值:

类型undefined

方法 getStepPin

原型: getStepPin ()

获取步进电机的步进引脚号。

例子:

const pin = stepper.getStepPin();
console.log("Step pin:", pin);

返回值:

类型number

说明步进引脚的 GPIO 编号。

方法 getDirectionPin

原型: getDirectionPin ()

获取步进电机的方向引脚号。

例子:

const pin = stepper.getDirectionPin();
console.log("Direction pin:", pin);

返回值:

类型number

说明方向引脚的 GPIO 编号。

方法 directionPinHighCountsUp

原型: directionPinHighCountsUp ()

检查方向引脚高电平是否表示正向计数。

例子:

const highCountsUp = stepper.directionPinHighCountsUp();
console.log("Direction pin high counts up:", highCountsUp);

返回值:

类型boolean

说明如果高电平表示正向计数返回 true，否则返回 false。

方法 getEnablePinHighActive

原型: getEnablePinHighActive ()

获取使能引脚高电平激活的引脚号。

例子:

const pin = stepper.getEnablePinHighActive();
console.log("Enable pin (high active):", pin);

返回值:

类型number

说明使能引脚高电平激活的 GPIO 编号。

方法 getEnablePinLowActive

原型: getEnablePinLowActive ()

获取使能引脚低电平激活的引脚号。

例子:

const pin = stepper.getEnablePinLowActive();
console.log("Enable pin (low active):", pin);

返回值:

类型number

说明使能引脚低电平激活的 GPIO 编号。

方法 setAutoEnable

原型: setAutoEnable (enable:boolean)

设置步进电机的自动使能模式。

例子:

stepper.setAutoEnable(true);

参数:

enable
类型boolean
参数说明true 启用自动使能，电机移动前自动使能，停止后自动禁用。

异常:

如果参数无效，将抛出异常。

返回值:

类型undefined

方法 setDelayToEnable

原型: setDelayToEnable (delay_us:number)

设置电机使能后的延迟时间。

例子:

stepper.setDelayToEnable(500);

参数:

delay_us
类型number
参数说明使能到第一个步进脉冲之间的延迟时间，单位为微秒。

异常:

如果参数无效，将抛出异常。

返回值:

类型undefined

方法 setDelayToDisable

原型: setDelayToDisable (delay_ms:number)

设置电机停止后的禁用延迟时间。

例子:

stepper.setDelayToDisable(100);

参数:

delay_ms
类型number
参数说明电机停止后到禁用输出之间的延迟时间，单位为毫秒。

异常:

如果参数无效，将抛出异常。

返回值:

类型undefined

方法 setSpeedInHz

原型: setSpeedInHz (hz:number)

设置步进电机的最大速度。

例子:

stepper.setSpeedInHz(1000);

参数:

hz
类型number
参数说明最大速度，单位为步/秒。

异常:

如果参数无效，将抛出异常。

返回值:

类型undefined

方法 setSpeedInUs

原型: setSpeedInUs (us:number)

设置步进电机的最大速度。

例子:

stepper.setSpeedInUs(1000);

参数:

us
类型number
参数说明最大速度，单位为微秒/步。

异常:

如果参数无效，将抛出异常。

返回值:

类型undefined

方法 setSpeedInTicks

原型: setSpeedInTicks (ticks:number)

设置步进电机的最大速度。

例子:

stepper.setSpeedInTicks(16000);

参数:

ticks
类型number
参数说明最大速度，单位为定时器时钟周期。

异常:

如果参数无效，将抛出异常。

返回值:

类型undefined

方法 getMaxSpeedInHz

原型: getMaxSpeedInHz ()

获取步进电机的最大速度（以赫兹为单位）。

例子:

const maxSpeed = stepper.getMaxSpeedInHz();
console.log("Max speed in Hz:", maxSpeed);

返回值:

类型number

说明最大速度，单位为赫兹。

方法 getMaxSpeedInUs

原型: getMaxSpeedInUs ()

获取步进电机的最大速度（以微秒为单位）。

例子:

const maxSpeed = stepper.getMaxSpeedInUs();
console.log("Max speed in us:", maxSpeed);

返回值:

类型number

说明最大速度，单位为微秒。

方法 getMaxSpeedInTicks

原型: getMaxSpeedInTicks ()

获取步进电机的最大速度（以时钟周期为单位）。

例子:

const maxSpeed = stepper.getMaxSpeedInTicks();
console.log("Max speed in ticks:", maxSpeed);

返回值:

类型number

说明最大速度，单位为时钟周期。

方法 getSpeedInUs

原型: getSpeedInUs ()

获取步进电机的当前速度（以微秒为单位）。

例子:

const speed = stepper.getSpeedInUs();
console.log("Current speed in us:", speed);

返回值:

类型number

说明当前速度，单位为微秒。

方法 getSpeedInTicks

原型: getSpeedInTicks ()

获取步进电机的当前速度（以时钟周期为单位）。

例子:

const speed = stepper.getSpeedInTicks();
console.log("Current speed in ticks:", speed);

返回值:

类型number

说明当前速度，单位为时钟周期。

方法 getSpeedInMilliHz

原型: getSpeedInMilliHz ()

获取步进电机的当前速度（以毫赫兹为单位）。

例子:

const speed = stepper.getSpeedInMilliHz();
console.log("Current speed in milliHz:", speed);

返回值:

类型number

说明当前速度，单位为毫赫兹。

方法 setAcceleration

原型: setAcceleration (accel:number)

设置步进电机的加速度。

例子:

stepper.setAcceleration(1000);

参数:

accel
类型number
参数说明加速度，单位为步/秒²。

异常:

如果参数无效，将抛出异常。

返回值:

类型undefined

方法 getAcceleration

原型: getAcceleration ()

获取步进电机的加速度。

例子:

const accel = stepper.getAcceleration();
console.log("Acceleration:", accel);

返回值:

类型number

说明加速度值。

方法 getCurrentAcceleration

原型: getCurrentAcceleration ()

获取步进电机的当前加速度。

例子:

const accel = stepper.getCurrentAcceleration();
console.log("Current acceleration:", accel);

返回值:

类型number

说明当前加速度值。

方法 setLinearAcceleration

原型: setLinearAcceleration (steps:number)

设置线性加速度的步数。

例子:

stepper.setLinearAcceleration(100);

参数:

steps
类型number
参数说明线性加速度的步数，用于平滑启动。

异常:

如果参数无效，将抛出异常。

返回值:

类型undefined

方法 setJumpStart

原型: setJumpStart (steps:number)

设置跳跃启动的步数。

例子:

stepper.setJumpStart(50);

参数:

steps
类型number
参数说明跳跃启动的步数，用于快速启动。

异常:

如果参数无效，将抛出异常。

返回值:

类型undefined

方法 move

原型: move (steps:number, blocking:boolean=false)

相对移动步进电机指定步数。

例子:

stepper.move(1000, true);

参数:

steps
类型number
参数说明移动的步数，正数为正向，负数为反向。
blocking
类型boolean
默认值false
参数说明是否阻塞等待移动完成。

异常:

如果参数无效，将抛出异常。

返回值:

类型undefined

方法 moveTo

原型: moveTo (position:number, blocking:boolean=false)

绝对移动步进电机到指定位置。

例子:

stepper.moveTo(5000, false);

参数:

position
类型number
参数说明目标位置。
blocking
类型boolean
默认值false
参数说明是否阻塞等待移动完成。

异常:

如果参数无效，将抛出异常。

返回值:

类型undefined

方法 runForward

原型: runForward ()

让步进电机持续向前运行。

例子:

stepper.runForward();

返回值:

类型undefined

方法 runBackward

原型: runBackward ()

让步进电机持续向后运行。

例子:

stepper.runBackward();

返回值:

类型undefined

方法 keepRunning

原型: keepRunning ()

保持步进电机当前方向持续运行。

例子:

stepper.keepRunning();

返回值:

类型undefined

方法 moveByAcceleration

原型: moveByAcceleration (accel:number, reverse:boolean=true)

通过加速度控制步进电机的移动。

例子:

stepper.moveByAcceleration(500, true);

参数:

accel
类型number
参数说明加速度值，正数加速，负数减速。
reverse
类型boolean
默认值true
参数说明是否允许反向。

异常:

如果参数无效，将抛出异常。

返回值:

类型undefined

方法 moveTimed

原型: moveTimed (steps:number, duration:number, start:boolean=true)

在指定时间内完成指定步数的定时移动。

例子:

let result = stepper.moveTimed(100, 16000, true);
console.log(result);

参数:

steps
类型number
参数说明移动的步数。
duration
类型number
参数说明持续时间，单位为定时器时钟周期。
start
类型boolean
默认值true
参数说明是否立即开始。

异常:

如果参数无效，将抛出异常。

返回值:

类型number

说明MoveTimedResultCode 结果代码。

方法 stopMove

原型: stopMove ()

减速停止步进电机。

例子:

stepper.stopMove();

返回值:

类型undefined

方法 forceStop

原型: forceStop ()

立即停止步进电机，无减速度。

例子:

stepper.forceStop();

返回值:

类型undefined

方法 forwardStep

原型: forwardStep (blocking:boolean=false)

执行单个向前步进。

例子:

stepper.forwardStep(true);

参数:

blocking
类型boolean
默认值false
参数说明是否阻塞等待完成。

返回值:

类型undefined

方法 backwardStep

原型: backwardStep (blocking:boolean=false)

执行单个向后步进。

例子:

stepper.backwardStep(false);

参数:

blocking
类型boolean
默认值false
参数说明是否阻塞等待完成。

返回值:

类型undefined

方法 getCurrentPosition

原型: getCurrentPosition ()

获取步进电机的当前位置。

例子:

let pos = stepper.getCurrentPosition();
console.log(pos);

返回值:

类型number

说明当前位置。

方法 setCurrentPosition

原型: setCurrentPosition (new_pos:number)

设置步进电机的当前位置。

例子:

stepper.setCurrentPosition(1000);

参数:

new_pos
类型number
参数说明新的当前位置值。

异常:

如果参数无效，将抛出异常。

返回值:

类型undefined

方法 isRunning

原型: isRunning ()

检查步进电机是否正在运行。

例子:

if (stepper.isRunning()) {
    console.log("Motor is running");
}

返回值:

类型boolean

说明是否正在运行。

方法 getCurrentSpeedInUs

原型: getCurrentSpeedInUs (realtime:boolean=true)

获取步进电机的当前速度。

例子:

let speed = stepper.getCurrentSpeedInUs(true);
console.log(speed);

参数:

realtime
类型boolean
默认值true
参数说明是否实时获取。

返回值:

类型number

说明当前速度，单位为微秒/步。

方法 targetPos

原型: targetPos ()

获取步进电机的目标位置。

例子:

let target = stepper.targetPos();
console.log(target);

返回值:

类型number

说明目标位置。

方法 rampState

例子:

stepper.setPositionAfterCommandsCompleted(5000);

参数:

new_pos
类型number
参数说明新的目标位置值。

异常:

如果参数无效，将抛出异常。

返回值:

类型undefined

方法 getPeriodInUsAfterCommandsCompleted

原型: getPeriodInUsAfterCommandsCompleted ()

获取命令执行完成后步进电机的周期（以微秒为单位）。

例子:

const period = stepper.getPeriodInUsAfterCommandsCompleted();
console.log("Period after commands (us):", period);

返回值:

类型number

说明命令执行完成后的周期，单位为微秒。

方法 getPeriodInTicksAfterCommandsCompleted

原型: getPeriodInTicksAfterCommandsCompleted ()

获取命令执行完成后步进电机的周期（以时钟周期为单位）。

例子:

const period = stepper.getPeriodInTicksAfterCommandsCompleted();
console.log("Period after commands (ticks):", period);

返回值:

类型number

说明命令执行完成后的周期，单位为时钟周期。

方法 isRunningContinuously

原型: isRunningContinuously ()

检查步进电机是否正在连续运行。

例子:

const continuous = stepper.isRunningContinuously();
console.log("Running continuously:", continuous);

返回值:

类型boolean

说明如果正在连续运行返回 true，否则返回 false。

方法 isStopping

原型: isStopping ()

检查步进电机是否正在停止。

例子:

const stopping = stepper.isStopping();
console.log("Is stopping:", stopping);

返回值:

类型boolean

说明如果正在停止返回 true，否则返回 false。

控件

类: 步进电机驱动