From 35d1ccbf385c62c6d3f3a31e383985db7a4459ea Mon Sep 17 00:00:00 2001 From: Shawn Tan Date: Mon, 16 Feb 2026 15:28:01 -0800 Subject: [PATCH 01/27] Add getting started article --- tutorials/stepperdriver-setup.md | 17 +++++++++++++++++ tutorials/toc.yml | 4 +++- 2 files changed, 20 insertions(+), 1 deletion(-) create mode 100644 tutorials/stepperdriver-setup.md diff --git a/tutorials/stepperdriver-setup.md b/tutorials/stepperdriver-setup.md new file mode 100644 index 00000000..912d6da9 --- /dev/null +++ b/tutorials/stepperdriver-setup.md @@ -0,0 +1,17 @@ +# Getting Started + +The [Harp StepperDriver](https://github.com/harp-tech/device.stepperdriver) is a stepper motor controller device for four motors with support for quadrature encoder feedback. + +## Installation + +- Install the [FTDI D2XX driver](https://ftdichip.com/drivers/d2xx-drivers/) +- Install [Bonsai](https://bonsai-rx.org/docs/articles/installation.html). +- Install the `Harp.StepperDriver` package by searching for it in the [Bonsai package manager](https://bonsai-rx.org/docs/articles/packages.html). If the package does not appear in the search results, enable the "Show advanced" option. + +## Connections + +**Stepper Motor** - The `StepperDriver` supports 4-lead bipolar stepper motors that draw up to 2 A per phase. Ensure that the 4 leads (`A+`, `A-`, `B+`, and `B-`) are correctly connected to the labeled terminals on the device. + +**Power Supply** - The `StepperDriver` requires an external power supply that matches your motor configuration: +- **Voltage** - Select a supply matching the recommended driving voltage listed in the motor datasheet (15-35 V). For high-speed and high-torque applications, supply at least 10 V above the minimum driving voltage, and mount the `StepperDriver` on a metal surface to dissipate heat. +- **Current** - Provide at least double the motor's rated phase current, multiplied by the number of motors (e.g. 8 A for two 2 A motors). \ No newline at end of file diff --git a/tutorials/toc.yml b/tutorials/toc.yml index 3d2fb9aa..b40296e0 100644 --- a/tutorials/toc.yml +++ b/tutorials/toc.yml @@ -1,4 +1,6 @@ - name: Harp Hobgoblin - href: hobgoblin-setup.md - href: hobgoblin-acquisition.md -- href: hobgoblin-reaction.md \ No newline at end of file +- href: hobgoblin-reaction.md +- name: Harp StepperDriver +- href: stepperdriver-setup.md \ No newline at end of file From fd20cd96b9da95fefc666a29fed7e9c90c474279 Mon Sep 17 00:00:00 2001 From: Shawn Tan Date: Tue, 17 Feb 2026 15:17:45 -0800 Subject: [PATCH 02/27] Add configuration article --- tutorials/stepperdriver-configuration.md | 132 +++++++++++++++++ tutorials/toc.yml | 3 +- ...rdriver-configuration-devicepattern.bonsai | 33 +++++ ...pperdriver-configuration-devicepattern.svg | 57 ++++++++ ...epperdriver-configuration-interlock.bonsai | 34 +++++ .../stepperdriver-configuration-interlock.svg | 76 ++++++++++ ...r-configuration-microstepresolution.bonsai | 34 +++++ ...iver-configuration-microstepresolution.svg | 76 ++++++++++ ...r-configuration-operationparameters.bonsai | 54 +++++++ ...iver-configuration-operationparameters.svg | 133 ++++++++++++++++++ ...perdriver-configuration-togglemotor.bonsai | 48 +++++++ ...tepperdriver-configuration-togglemotor.svg | 110 +++++++++++++++ 12 files changed, 789 insertions(+), 1 deletion(-) create mode 100644 tutorials/stepperdriver-configuration.md create mode 100644 workflows/stepperdriver-configuration-devicepattern.bonsai create mode 100644 workflows/stepperdriver-configuration-devicepattern.svg create mode 100644 workflows/stepperdriver-configuration-interlock.bonsai create mode 100644 workflows/stepperdriver-configuration-interlock.svg create mode 100644 workflows/stepperdriver-configuration-microstepresolution.bonsai create mode 100644 workflows/stepperdriver-configuration-microstepresolution.svg create mode 100644 workflows/stepperdriver-configuration-operationparameters.bonsai create mode 100644 workflows/stepperdriver-configuration-operationparameters.svg create mode 100644 workflows/stepperdriver-configuration-togglemotor.bonsai create mode 100644 workflows/stepperdriver-configuration-togglemotor.svg diff --git a/tutorials/stepperdriver-configuration.md b/tutorials/stepperdriver-configuration.md new file mode 100644 index 00000000..06803d0c --- /dev/null +++ b/tutorials/stepperdriver-configuration.md @@ -0,0 +1,132 @@ +# Configuration + +Configuration parameters must be set for the [Harp StepperDriver](https://github.com/harp-tech/device.stepperdriver) before it can be used to drive stepper motors. + +> [!WARNING] +> When adding these operators to the workflow, make sure to use the device-specific versions, e.g. `Device (Harp.StepperDriver)` instead of `Device (Harp)`. If correctly selected, the names of these operators in the workflow panel will change to reflect either the name of the device or the selected register/payload. + +## Prerequisites + +- Install the `Bonsai.Windows.Input` package from the Bonsai [package manager](https://bonsai-rx.org/docs/articles/packages.html). +- The steps listed below demonstrate configuration of a single stepper motor connected to the `Motor1` output on the `StepperDriver`. Adjust the relevant properties for your specific configuration. + +## Device pattern + +Set up the standard Harp [device pattern](../articles/operators.md#device-pattern) to initialize the device, broadcast events, and send commands to the `StepperDriver`. + +:::workflow +![StepperDriver Device Pattern](../workflows/stepperdriver-configuration-devicepattern.bonsai) +::: + +- Insert a [`Device`] operator, set the `PortName` property to the communications port for the device. +- Insert a [`PublishSubject`] operator and name it `StepperDriver Events`. +- Right-click the [`Device`] operator, select "Create Source (Bonsai.Harp.HarpMessage)" > "BehaviorSubject". + - Name the generated [``BehaviourSubject`1``] [source subject](https://bonsai-rx.org/docs/articles/subjects.html#source-subjects) `StepperDriver Commands`. + - Connect it as input to the [`Device`] operator. + +## Configure interlock state + +The `StepperDriver` includes an external interlock terminal (labelled `Enable` on the device) designed for use with a safety switch. The interlock setting must be configured to enable the device. + +:::workflow +![StepperDriver Interlock](../workflows/stepperdriver-configuration-interlock.bonsai) +::: + +- Insert a [`SubscribeSubject`] operator and configure the `Name` property to `StepperDriver Events`. +- Insert a [`Take`] combinator and set the `Count` property to 1. +- Insert a [`CreateMessage`] operator to construct a [`HarpMessage`] command to send to the device and configure these properties: + - `Payload` - Select [`InterlockEnabledPayload`] from the property drop down menu. + - `InterlockEnabled` - Select either of these values: + - `Open` - to enable the device if the interlock is not in use. + - `Closed` - to enable the device with a connected interlock switch. +- Insert a [`MulticastSubject`] operator to send [`HarpMessage`] commands to named subjects, and configure the `Name` property to `StepperDriver Commands`. + +> [!TIP] +> The `StepperDriver Events` > `Take(1)` ensures that configuration commands are sent only after the `StepperDriver` has initialized. It requires the `DumpRegisters` property to be set to `True` in the [`Device`] operator. + +## Configure microstep resolution + +The microstep resolution determines the size of each step, and directly affects the speed and distance travelled by the movement commands. It must be set individually for each motor. Values range from `Microstep8` (coarsest) to `Microstep64` (finest). + +:::workflow +![StepperDriver Microstep Resolution](../workflows/stepperdriver-configuration-microstepresolution.bonsai) +::: + +- Insert a [`SubscribeSubject`] operator named `StepperDriver Events`. +- Insert a [`Take`] combinator and set the `Count` property to 1. +- Insert a [`CreateMessage`] operator and configure these properties: + - `Payload` - Set it to [`Motor1MicrostepResolution`]. + - `Motor1MicrostepResolution` - Select the desired microstep resolution (e.g. `Microstep8`). +- Insert a [`MulticastSubject`] operator named `StepperDriver Commands`. + +## Configure operation parameters + +Other operation parameters to be set include the operation mode of the motor, maximum run current, as well as the hold current. + +:::workflow +![StepperDriver Operation Parameters](../workflows/stepperdriver-configuration-operationparameters.bonsai) +::: + +- Insert a [`SubscribeSubject`] operator named `StepperDriver Events`. +- Insert a [`Take`] combinator and set the `Count` property to 1. +- Insert a [`CreateMessage`] operator and configure these properties: + - `Payload` - Set it to [`Motor1OperationMode`]. + - `Motor1OperationMode` - Set it to `QuietMode` for regular operation and `DynamicMode` for quick movements. +- Insert a [`CreateMessage`] operator on another branch, and configure these properties: + - `Payload` - Set it to [`Motor1MaximumRunCurrent`]. + - `Motor1MaximumRunCurrent` - Set it to match the motor's rated phase current in amps (e.g. 1). +- Insert a [`CreateMessage`] operator on another branch, and configure these properties: + - `Payload` - Set it to [`Motor1HoldCurrentReduction`]. + - `Motor1HoldCurrentReduction` - Set it to minimise heat reduction and adjust the holding torque of the motor at rest (e.g. `ReductionTo25Percent` for low holding torque with light external loads). +- Insert a [`Merge`] operator to combine all three commands into one [`HarpMessage`] stream. +- Insert a [`MulticastSubject`] operator named `StepperDriver Commands`. + +> [!TIP] +> The previous configuration commands can also be combined using [`Merge`] and sent into a single `StepperDriver Commands` pipeline. + +## Enable and disable motors + +Lastly, motor drivers have to be enabled before use, but can be disabled at any time. + +:::workflow +![StepperDriver Toggle Motor](../workflows/stepperdriver-configuration-togglemotor.bonsai) +::: + +- Insert a [`KeyDown`] source and set the `Filter` property to `1`. +- Insert a [`CreateMessage`] operator and configure these properties: + - `Payload` - Set this to [`EnableDriverPayload`]. + - `EnableDriver` - Set this to the motor to enable (e.g. `Motor1`). +- Insert a [`MulticastSubject`] operator named `StepperDriver Commands`. + +To disable the motor, set up a separate pipeline: + +- Insert a [`KeyDown`] source and set the `Filter` property to `2`. +- Insert a [`CreateMessage`] operator and configure these properties: + - `Payload` - Set this to [`DisableDriverPayload`]. + - `DisableDriver` - Set this to the motor to disable (e.g. `Motor1`). +- Insert a [`MulticastSubject`] operator named `StepperDriver Commands`. + +Run the workflow and press the 1 key to enable the motor and 2 key to disable the motor. When the motor is enabled, the LED above the motor port on the device will blink red. + +> [!TIP] +> To target multiple motors, enter their names, separated by a comma, for the `EnableDriver` and `DisableDriver` properties (e.g. `Motor0`, `Motor1`). + + +[``BehaviourSubject`1``]: xref:Bonsai.Reactive.BehaviorSubject +[`CreateMessage`]: xref:Harp.StepperDriver.CreateMessage +[`Device`]: xref:Harp.StepperDriver.Device +[`DisableDriverPayload`]: xref:Harp.StepperDriver.CreateDisableDriverPayload +[`EnableDriverPayload`]: xref:Harp.StepperDriver.CreateEnableDriverPayload +[`HarpMessage`]: xref:Bonsai.Harp.HarpMessage +[`InterlockEnabledPayload`]: xref:Harp.StepperDriver.CreateInterlockEnabledPayload +[`KeyDown`]: xref:Bonsai.Windows.Input.KeyDown +[`Merge`]: xref:Bonsai.Reactive.Merge +[`Motor1MaximumRunCurrent`]: xref:Harp.StepperDriver.CreateMotor1MaximumRunCurrentPayload +[`Motor1HoldCurrentReduction`]: xref:Harp.StepperDriver.CreateMotor1HoldCurrentReductionPayload +[`Motor1MicrostepResolution`]: xref:Harp.StepperDriver.CreateMotor1MicrostepResolutionPayload +[`Motor1OperationMode`]: xref:Harp.StepperDriver.CreateMotor1OperationModePayload +[`MulticastSubject`]: xref:Bonsai.Expressions.MulticastSubject +[`PublishSubject`]: xref:Bonsai.Reactive.PublishSubject +[`SubscribeSubject`]: xref:Bonsai.Expressions.SubscribeSubject +[`Take`]: xref:Bonsai.Reactive.Take +[`Timer`]: xref:Bonsai.Reactive.Timer \ No newline at end of file diff --git a/tutorials/toc.yml b/tutorials/toc.yml index b40296e0..f1c2e94a 100644 --- a/tutorials/toc.yml +++ b/tutorials/toc.yml @@ -3,4 +3,5 @@ - href: hobgoblin-acquisition.md - href: hobgoblin-reaction.md - name: Harp StepperDriver -- href: stepperdriver-setup.md \ No newline at end of file +- href: stepperdriver-setup.md +- href: stepperdriver-configuration.md \ No newline at end of file diff --git a/workflows/stepperdriver-configuration-devicepattern.bonsai b/workflows/stepperdriver-configuration-devicepattern.bonsai new file mode 100644 index 00000000..44d9a807 --- /dev/null +++ b/workflows/stepperdriver-configuration-devicepattern.bonsai @@ -0,0 +1,33 @@ + + + + + + StepperDriver Commands + + + + Active + On + true + On + Disabled + false + COM9 + + + + StepperDriver Events + + + + + + + + \ No newline at end of file diff --git a/workflows/stepperdriver-configuration-devicepattern.svg b/workflows/stepperdriver-configuration-devicepattern.svg new file mode 100644 index 00000000..1b862c11 --- /dev/null +++ b/workflows/stepperdriver-configuration-devicepattern.svg @@ -0,0 +1,57 @@ + + +]> + + + + + + + + + + + + + + StepperDriver + + + Events + + + + + + StepperDriver + + + + + + + StepperDriver + + + Commands + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/workflows/stepperdriver-configuration-interlock.bonsai b/workflows/stepperdriver-configuration-interlock.bonsai new file mode 100644 index 00000000..b8dd48e5 --- /dev/null +++ b/workflows/stepperdriver-configuration-interlock.bonsai @@ -0,0 +1,34 @@ + + + + + + StepperDriver Events + + + + 1 + + + + Write + + Open + + + + StepperDriver Commands + + + + + + + + + \ No newline at end of file diff --git a/workflows/stepperdriver-configuration-interlock.svg b/workflows/stepperdriver-configuration-interlock.svg new file mode 100644 index 00000000..fc22e1d2 --- /dev/null +++ b/workflows/stepperdriver-configuration-interlock.svg @@ -0,0 +1,76 @@ + + +]> + + + + + + + + + + + + + StepperDriver + + + Commands + + + + + + Stepper + + + Driver. + + + InterlockEnabl + + + + + Take + + + + + + + StepperDriver + + + Events + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/workflows/stepperdriver-configuration-microstepresolution.bonsai b/workflows/stepperdriver-configuration-microstepresolution.bonsai new file mode 100644 index 00000000..fe10868d --- /dev/null +++ b/workflows/stepperdriver-configuration-microstepresolution.bonsai @@ -0,0 +1,34 @@ + + + + + + StepperDriver Events + + + + 1 + + + + Write + + Microstep8 + + + + StepperDriver Commands + + + + + + + + + \ No newline at end of file diff --git a/workflows/stepperdriver-configuration-microstepresolution.svg b/workflows/stepperdriver-configuration-microstepresolution.svg new file mode 100644 index 00000000..ac7ca70d --- /dev/null +++ b/workflows/stepperdriver-configuration-microstepresolution.svg @@ -0,0 +1,76 @@ + + +]> + + + + + + + + + + + + + StepperDriver + + + Commands + + + + + + Stepper + + + Driver.Motor1 + + + MicrostepResol + + + + + Take + + + + + + + StepperDriver + + + Events + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/workflows/stepperdriver-configuration-operationparameters.bonsai b/workflows/stepperdriver-configuration-operationparameters.bonsai new file mode 100644 index 00000000..f4c238a8 --- /dev/null +++ b/workflows/stepperdriver-configuration-operationparameters.bonsai @@ -0,0 +1,54 @@ + + + + + + StepperDriver Events + + + + 1 + + + + Write + + QuietMode + + + + Write + + 1 + + + + Write + + ReductionTo25Percent + + + + + + + StepperDriver Commands + + + + + + + + + + + + + + \ No newline at end of file diff --git a/workflows/stepperdriver-configuration-operationparameters.svg b/workflows/stepperdriver-configuration-operationparameters.svg new file mode 100644 index 00000000..2b059b6c --- /dev/null +++ b/workflows/stepperdriver-configuration-operationparameters.svg @@ -0,0 +1,133 @@ + + +]> + + + + + + + + + + + + + + + + + + StepperDriver + + + Commands + + + + + + + Merge + + + + + + Stepper + + + Driver.Motor1 + + + OperationMod + + + + + + Stepper + + + Driver.Motor1 + + + MaximumRun + + + + + + Stepper + + + Driver.Motor1 + + + HoldCurrentRe + + + + + Take + + + + + + + StepperDriver + + + Events + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/workflows/stepperdriver-configuration-togglemotor.bonsai b/workflows/stepperdriver-configuration-togglemotor.bonsai new file mode 100644 index 00000000..c1b02959 --- /dev/null +++ b/workflows/stepperdriver-configuration-togglemotor.bonsai @@ -0,0 +1,48 @@ + + + + + + + D1 + false + + + + Write + + Motor1 + + + + StepperDriver Commands + + + + D2 + false + + + + Write + + Motor1 + + + + StepperDriver Commands + + + + + + + + + + \ No newline at end of file diff --git a/workflows/stepperdriver-configuration-togglemotor.svg b/workflows/stepperdriver-configuration-togglemotor.svg new file mode 100644 index 00000000..96dcaa73 --- /dev/null +++ b/workflows/stepperdriver-configuration-togglemotor.svg @@ -0,0 +1,110 @@ + + +]> + + + + + + + + + + + + + + StepperDriver + + + Commands + + + + + + + StepperDriver + + + Commands + + + + + + Stepper + + + Driver.Enable + + + DriverPayload + + + + + + Stepper + + + Driver.Disable + + + DriverPayload + + + + + + + KeyDown + + + + + + + KeyDown + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file From f08721ba0daf71a87a73edf56fdb840a734798dd Mon Sep 17 00:00:00 2001 From: Shawn Tan Date: Tue, 17 Feb 2026 16:53:12 -0800 Subject: [PATCH 03/27] Align motor driver terminology for configuration article --- tutorials/stepperdriver-configuration.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/tutorials/stepperdriver-configuration.md b/tutorials/stepperdriver-configuration.md index 06803d0c..49a9348d 100644 --- a/tutorials/stepperdriver-configuration.md +++ b/tutorials/stepperdriver-configuration.md @@ -1,4 +1,4 @@ -# Configuration +# Configure Driver Configuration parameters must be set for the [Harp StepperDriver](https://github.com/harp-tech/device.stepperdriver) before it can be used to drive stepper motors. @@ -8,7 +8,7 @@ Configuration parameters must be set for the [Harp StepperDriver](https://github ## Prerequisites - Install the `Bonsai.Windows.Input` package from the Bonsai [package manager](https://bonsai-rx.org/docs/articles/packages.html). -- The steps listed below demonstrate configuration of a single stepper motor connected to the `Motor1` output on the `StepperDriver`. Adjust the relevant properties for your specific configuration. +- The steps listed below demonstrate driver configuration for a single stepper motor connected to the `Motor1` output on the `StepperDriver`. Adjust the relevant properties for your specific configuration. ## Device pattern @@ -46,7 +46,7 @@ The `StepperDriver` includes an external interlock terminal (labelled `Enable` o ## Configure microstep resolution -The microstep resolution determines the size of each step, and directly affects the speed and distance travelled by the movement commands. It must be set individually for each motor. Values range from `Microstep8` (coarsest) to `Microstep64` (finest). +The microstep resolution determines the size of each step, and directly affects the speed and distance travelled by the movement commands. It must be set individually for each motor driver. Values range from `Microstep8` (coarsest) to `Microstep64` (finest). :::workflow ![StepperDriver Microstep Resolution](../workflows/stepperdriver-configuration-microstepresolution.bonsai) @@ -61,7 +61,7 @@ The microstep resolution determines the size of each step, and directly affects ## Configure operation parameters -Other operation parameters to be set include the operation mode of the motor, maximum run current, as well as the hold current. +Other operation parameters to be set include the operation mode of the motor driver, maximum run current, as well as the hold current. :::workflow ![StepperDriver Operation Parameters](../workflows/stepperdriver-configuration-operationparameters.bonsai) From 3e6ca5f45c2b1e6390f71adba23ad1ac96d4da81 Mon Sep 17 00:00:00 2001 From: Shawn Tan Date: Wed, 18 Feb 2026 00:16:28 -0800 Subject: [PATCH 04/27] Add draft of control motor article --- tutorials/stepperdriver-controlmotor.md | 84 +++++++++++ tutorials/toc.yml | 3 +- ...perdriver-controlmotor-acceleration.bonsai | 52 +++++++ ...tepperdriver-controlmotor-acceleration.svg | 118 +++++++++++++++ ...epperdriver-controlmotor-visualizer.bonsai | 59 ++++++++ .../stepperdriver-controlmotor-visualizer.svg | 142 ++++++++++++++++++ 6 files changed, 457 insertions(+), 1 deletion(-) create mode 100644 tutorials/stepperdriver-controlmotor.md create mode 100644 workflows/stepperdriver-controlmotor-acceleration.bonsai create mode 100644 workflows/stepperdriver-controlmotor-acceleration.svg create mode 100644 workflows/stepperdriver-controlmotor-visualizer.bonsai create mode 100644 workflows/stepperdriver-controlmotor-visualizer.svg diff --git a/tutorials/stepperdriver-controlmotor.md b/tutorials/stepperdriver-controlmotor.md new file mode 100644 index 00000000..ed7895a0 --- /dev/null +++ b/tutorials/stepperdriver-controlmotor.md @@ -0,0 +1,84 @@ +# Control Motor + +The follow exercises will demonstrate how to control motor speed and rotational position with the [Harp StepperDriver](https://github.com/harp-tech/device.stepperdriver). + +> [!WARNING] +> Ensure that you are familiar with the operation of the `StepperDriver` and motors before connecting external loads. Consider using end-of-travel switches in conjunction with a [digital input](xref:Harp.StepperDriver.CreateEnableDigitalInputsPayload) [configuration](xref:Harp.StepperDriver.CreateInput0OpModePayload). Improper use of the `StepperDriver` and motors may result in damage to equipment. + +## Prerequisites + +- Install the `Bonsai.Windows.Input` package from the Bonsai [package manager](https://bonsai-rx.org/docs/articles/packages.html). +- Connect a stepper motor to the `Stepper 1` output on the `StepperDriver`, set up the [device pattern](./stepperdriver-configuration.md#device-pattern), [configure](./stepperdriver-configuration.md) the device, and [enable](./stepperdriver-configuration.md#enable-and-disable-motors) the `Motor1` stepper driver. + +## Position visualizer + +For these exercises, it helps to track the rotational position of the motor. The `StepperDriver` can broadcast a stream of [`AccumulatedSteps`] events, which can be displayed in a visualizer for this purpose. + +:::workflow +![StepperDriver Position Visualizer](../workflows/stepperdriver-controlmotor-visualizer.bonsai) +::: + +Enable the [`AccumulatedSteps`] event register and configure the dispatch rate: + +- Insert a [`SubscribeSubject`] operator named `StepperDriver Events`. +- Insert a [`Take`] combinator and set the `Count` property to 1. +- Insert a [`CreateMessage`] operator and configure these properties: + - `Payload` - Set it to [`AccumulatedStepsSamplingRatePayload`]. + - `AccumulatedStepsSamplingRate` - Set it to the desired sampling rate (e.g. `Rate10Hz` for coarse movements). +- Insert a [`MulticastSubject`] operator named `StepperDriver Commands`. + +Read the [`AccumulatedSteps`] and display it in a visualizer: + +- Insert a [`SubscribeSubject`] operator named `StepperDriver Events`. +- Insert a [`Parse`] operator and set the `Register` property to [`AccumulatedSteps`]. +- Right-click on the [`Parse`] operator, select "Output (Harp.StepperDriver.AccumulatedStepsPayload)" > "Motor1" from the context menu. +- Insert a [`VisualizerWindow`] node. + +## Exercise 1: Set acceleration profile + +Motor motion is driven by a series of step pulses. Speed can be controlled by specifying the interval between steps (in μs). For any given movement, the acceleration profile is defined by three parameters: + +- the initial/final step interval +- the target step interval at nominal speed +- the change in interval per step during the acceleration/deceleration phase + +:::workflow +![StepperDriver Acceleration Profile](../workflows/stepperdriver-controlmotor-acceleration.bonsai) +::: + +- Insert a [`KeyDown`] source and set the `Filter` property to `3`. +- Insert a [`CreateMessage`] operator and configure these properties: + - `Payload` - Set it to [`Motor1MaximumStepIntervalPayload`]. + - `Motor1MaximumStepInterval` - Set this to the initial/final step interval (e.g. 2000). +- Insert a [`CreateMessage`] operator on a new branch and configure these properties: + - `Payload` - Set it to [`Motor1StepIntervalPayload`]. + - `Motor1StepInterval` - Set this to the target step interval (e.g. 250). +- Insert a [`CreateMessage`] operator on a new branch and configure these properties: + - `Payload` - Set it to [`Motor1StepAccelerationIntervalPayload`]. + - `Motor1StepAcceleration` - Set this to the change in step interval (e.g. 10). +- Combine the three messages with a [`Merge`] combinator. +- Insert a [`MulticastSubject`] operator named `StepperDriver Commands`. + +Run the workflow and press the 3 key to set the acceleration profile. You can also adjust the properties, and press the 3 key to update the acceleration profile while the workflow is running. This allows you to test different speeds with the movement commands. + +## Exercise 2: Move by relative steps + + +[`AccumulatedSteps`]: xref:Harp.StepperDriver.AccumulatedSteps +[`AccumulatedStepsSamplingRatePayload`]: xref:Harp.StepperDriver.CreateAccumulatedStepsSamplingRatePayload +[``BehaviourSubject`1``]: xref:Bonsai.Reactive.BehaviorSubject +[`CreateMessage`]: xref:Harp.StepperDriver.CreateMessage +[`Device`]: xref:Harp.StepperDriver.Device +[`HarpMessage`]: xref:Bonsai.Harp.HarpMessage +[`KeyDown`]: xref:Bonsai.Windows.Input.KeyDown +[`Merge`]: xref:Bonsai.Reactive.Merge +[`Motor1StepAccelerationIntervalPayload`]: xref:Harp.StepperDriver.CreateMotor1StepAccelerationIntervalPayload +[`Motor1MaximumStepIntervalPayload`]: xref:Harp.StepperDriver.CreateMotor1MaximumStepIntervalPayload +[`Motor1Motor1StepInterval`]: xref:Harp.StepperDriver.CreateMotor1StepIntervalPayload +[`MulticastSubject`]: xref:Bonsai.Expressions.MulticastSubject +[`Parse`]: xref:Harp.StepperDriver.Parse +[`PublishSubject`]: xref:Bonsai.Reactive.PublishSubject +[`SubscribeSubject`]: xref:Bonsai.Expressions.SubscribeSubject +[`Take`]: xref:Bonsai.Reactive.Take +[`Timer`]: xref:Bonsai.Reactive.Timer +[`VisualizerWindow`]: xref:Bonsai.Design.VisualizerWindow \ No newline at end of file diff --git a/tutorials/toc.yml b/tutorials/toc.yml index f1c2e94a..872621c9 100644 --- a/tutorials/toc.yml +++ b/tutorials/toc.yml @@ -4,4 +4,5 @@ - href: hobgoblin-reaction.md - name: Harp StepperDriver - href: stepperdriver-setup.md -- href: stepperdriver-configuration.md \ No newline at end of file +- href: stepperdriver-configuration.md +- href: stepperdriver-controlmotor.md \ No newline at end of file diff --git a/workflows/stepperdriver-controlmotor-acceleration.bonsai b/workflows/stepperdriver-controlmotor-acceleration.bonsai new file mode 100644 index 00000000..ead2041a --- /dev/null +++ b/workflows/stepperdriver-controlmotor-acceleration.bonsai @@ -0,0 +1,52 @@ + + + + + + + D3 + false + + + + Write + + 2000 + + + + Write + + 250 + + + + Write + + 10 + + + + + + + StepperDriver Commands + + + + + + + + + + + + + \ No newline at end of file diff --git a/workflows/stepperdriver-controlmotor-acceleration.svg b/workflows/stepperdriver-controlmotor-acceleration.svg new file mode 100644 index 00000000..5dc2cbc9 --- /dev/null +++ b/workflows/stepperdriver-controlmotor-acceleration.svg @@ -0,0 +1,118 @@ + + +]> + + + + + + + + + + + + + + + + + StepperDriver + + + Commands + + + + + + + Merge + + + + + + Stepper + + + Driver.Motor1 + + + MaximumStepI + + + + + + Stepper + + + Driver.Motor1 + + + StepIntervalPay + + + + + + Stepper + + + Driver.Motor1 + + + StepAccelerati + + + + + + + KeyDown + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/workflows/stepperdriver-controlmotor-visualizer.bonsai b/workflows/stepperdriver-controlmotor-visualizer.bonsai new file mode 100644 index 00000000..24ede8ec --- /dev/null +++ b/workflows/stepperdriver-controlmotor-visualizer.bonsai @@ -0,0 +1,59 @@ + + + + + + StepperDriver Events + + + + 1 + + + + Write + + Rate10Hz + + + + StepperDriver Commands + + + StepperDriver Events + + + + + + Motor1 + + + true + + 600 + 300 + + + 500 + 300 + + + + + + + + + + + + + + \ No newline at end of file diff --git a/workflows/stepperdriver-controlmotor-visualizer.svg b/workflows/stepperdriver-controlmotor-visualizer.svg new file mode 100644 index 00000000..2c419aa1 --- /dev/null +++ b/workflows/stepperdriver-controlmotor-visualizer.svg @@ -0,0 +1,142 @@ + + +]> + + + + + + + + + + + + + + + + StepperDriver + + + Commands + + + + + + + + Visualizer + + + Window + + + + + + Stepper + + + Driver. + + + AccumulatedSt + + + + + + + Motor1 + + + + + Take + + + + + Stepper + + + Driver. + + + AccumulatedSt + + + + + + + StepperDriver + + + Events + + + + + + + StepperDriver + + + Events + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file From 2ac61f49b94832c2e680b688435d16333a288501 Mon Sep 17 00:00:00 2001 From: Shawn Tan Date: Wed, 18 Feb 2026 00:32:16 -0800 Subject: [PATCH 05/27] Add 2nd exercise move relative --- tutorials/stepperdriver-controlmotor.md | 29 ++++- ...perdriver-controlmotor-moverelative.bonsai | 48 ++++++++ ...tepperdriver-controlmotor-moverelative.svg | 110 ++++++++++++++++++ 3 files changed, 186 insertions(+), 1 deletion(-) create mode 100644 workflows/stepperdriver-controlmotor-moverelative.bonsai create mode 100644 workflows/stepperdriver-controlmotor-moverelative.svg diff --git a/tutorials/stepperdriver-controlmotor.md b/tutorials/stepperdriver-controlmotor.md index ed7895a0..b29f049d 100644 --- a/tutorials/stepperdriver-controlmotor.md +++ b/tutorials/stepperdriver-controlmotor.md @@ -61,7 +61,33 @@ Motor motion is driven by a series of step pulses. Speed can be controlled by sp Run the workflow and press the 3 key to set the acceleration profile. You can also adjust the properties, and press the 3 key to update the acceleration profile while the workflow is running. This allows you to test different speeds with the movement commands. -## Exercise 2: Move by relative steps +## Exercise 2: Move relative steps + +The move relative command moves the motor by a specified number of steps from its current position. Positive values move in one direction, negative values in the other. + +:::workflow +![StepperDriver Move Relative](../workflows/stepperdriver-controlmotor-moverelative.bonsai) +::: + +To move the motor in the positive direction: + +- Insert a [`KeyDown`] source and set the `Filter` property to `A`. +- Insert a [`CreateMessage`] operator and configure these properties: + - `Payload` - Set it to [`Motor1MoveRelativePayload`]. + - `Motor1MoveRelative` - Set this to the number of steps to move (e.g. 3000). +- Insert a [`MulticastSubject`] operator named `StepperDriver Commands`. + +To move the motor in the negative direction, set up a separate pipeline: + +- Insert a [`KeyDown`] source and set the `Filter` property to `S`. +- Insert a [`CreateMessage`] operator and configure these properties: + - `Payload` - Set it to [`Motor1MoveRelativePayload`]. + - `Motor1MoveRelative` - Set this to a negative value (e.g. -3000). +- Insert a [`MulticastSubject`] operator named `StepperDriver Commands`. + +Run the workflow and press A to move the motor forward and S to move it back. Observe the accumulated steps in the visualizer to track the motor's position. + +**Optional**: Change the acceleration profile in the previous exercise (e.g. increase the initial and target step intervals). Rerun the exercise. What do you observe? [`AccumulatedSteps`]: xref:Harp.StepperDriver.AccumulatedSteps @@ -72,6 +98,7 @@ Run the workflow and press the 3 key to set the acceleration profile. [`HarpMessage`]: xref:Bonsai.Harp.HarpMessage [`KeyDown`]: xref:Bonsai.Windows.Input.KeyDown [`Merge`]: xref:Bonsai.Reactive.Merge +[`Motor1MoveRelativePayload`]: xref:Harp.StepperDriver.CreateMotor1MoveRelativePayload [`Motor1StepAccelerationIntervalPayload`]: xref:Harp.StepperDriver.CreateMotor1StepAccelerationIntervalPayload [`Motor1MaximumStepIntervalPayload`]: xref:Harp.StepperDriver.CreateMotor1MaximumStepIntervalPayload [`Motor1Motor1StepInterval`]: xref:Harp.StepperDriver.CreateMotor1StepIntervalPayload diff --git a/workflows/stepperdriver-controlmotor-moverelative.bonsai b/workflows/stepperdriver-controlmotor-moverelative.bonsai new file mode 100644 index 00000000..6557cff6 --- /dev/null +++ b/workflows/stepperdriver-controlmotor-moverelative.bonsai @@ -0,0 +1,48 @@ + + + + + + + A + false + + + + Write + + 3000 + + + + StepperDriver Commands + + + + S + false + + + + Write + + -3000 + + + + StepperDriver Commands + + + + + + + + + + \ No newline at end of file diff --git a/workflows/stepperdriver-controlmotor-moverelative.svg b/workflows/stepperdriver-controlmotor-moverelative.svg new file mode 100644 index 00000000..b7b4d35f --- /dev/null +++ b/workflows/stepperdriver-controlmotor-moverelative.svg @@ -0,0 +1,110 @@ + + +]> + + + + + + + + + + + + + + StepperDriver + + + Commands + + + + + + + StepperDriver + + + Commands + + + + + + Stepper + + + Driver.Motor1 + + + MoveRelativeP + + + + + + Stepper + + + Driver.Motor1 + + + MoveRelativeP + + + + + + + KeyDown + + + + + + + KeyDown + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file From 9f8910d635ebaaabfc09f5e61aa3437f188fedf3 Mon Sep 17 00:00:00 2001 From: Shawn Tan Date: Wed, 18 Feb 2026 00:38:10 -0800 Subject: [PATCH 06/27] Edit for grammar and clarity --- tutorials/stepperdriver-controlmotor.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/tutorials/stepperdriver-controlmotor.md b/tutorials/stepperdriver-controlmotor.md index b29f049d..aee6372d 100644 --- a/tutorials/stepperdriver-controlmotor.md +++ b/tutorials/stepperdriver-controlmotor.md @@ -63,7 +63,7 @@ Run the workflow and press the 3 key to set the acceleration profile. ## Exercise 2: Move relative steps -The move relative command moves the motor by a specified number of steps from its current position. Positive values move in one direction, negative values in the other. +The [`MoveRelative`] register moves the motor by a specified number of steps from its current position. Positive values move in one direction, negative values in the other. :::workflow ![StepperDriver Move Relative](../workflows/stepperdriver-controlmotor-moverelative.bonsai) @@ -87,7 +87,10 @@ To move the motor in the negative direction, set up a separate pipeline: Run the workflow and press A to move the motor forward and S to move it back. Observe the accumulated steps in the visualizer to track the motor's position. -**Optional**: Change the acceleration profile in the previous exercise (e.g. increase the initial and target step intervals). Rerun the exercise. What do you observe? +**Optional**: Change the acceleration profile in the previous exercise (e.g. increase the initial and target step interval). Rerun the exercise. What do you observe? + +> [!TIP] +> To move multiple motors simultaneously, use the [`MoveRelativePayload`]. [`AccumulatedSteps`]: xref:Harp.StepperDriver.AccumulatedSteps @@ -98,6 +101,8 @@ Run the workflow and press A to move the motor forward and S Date: Wed, 18 Feb 2026 00:58:49 -0800 Subject: [PATCH 07/27] Add 3rd exercise move absolute --- tutorials/stepperdriver-controlmotor.md | 24 +++++++- ...perdriver-controlmotor-moveabsolute.bonsai | 31 ++++++++++ ...tepperdriver-controlmotor-moveabsolute.svg | 61 +++++++++++++++++++ 3 files changed, 115 insertions(+), 1 deletion(-) create mode 100644 workflows/stepperdriver-controlmotor-moveabsolute.bonsai create mode 100644 workflows/stepperdriver-controlmotor-moveabsolute.svg diff --git a/tutorials/stepperdriver-controlmotor.md b/tutorials/stepperdriver-controlmotor.md index aee6372d..e1c82cc3 100644 --- a/tutorials/stepperdriver-controlmotor.md +++ b/tutorials/stepperdriver-controlmotor.md @@ -36,7 +36,7 @@ Read the [`AccumulatedSteps`] and display it in a visualizer: ## Exercise 1: Set acceleration profile -Motor motion is driven by a series of step pulses. Speed can be controlled by specifying the interval between steps (in μs). For any given movement, the acceleration profile is defined by three parameters: +Motor motion is driven by a series of step pulses and speed can be controlled by specifying the interval between steps (in μs). For any given movement, the acceleration profile is defined by three parameters: - the initial/final step interval - the target step interval at nominal speed @@ -92,6 +92,25 @@ Run the workflow and press A to move the motor forward and S [!TIP] > To move multiple motors simultaneously, use the [`MoveRelativePayload`]. +## Exercise 3: Move to absolute step position + +The [`MoveAbsolute`] register moves the motor to an absolute step position based on the [`AccumulatedSteps`] counter. + +:::workflow +![StepperDriver Move Absolute](../workflows/stepperdriver-controlmotor-moveabsolute.bonsai) +::: + +- Insert a [`KeyDown`] source and set the `Filter` property to `D`. +- Insert a [`CreateMessage`] operator and configure these properties: + - `Payload` - Set it to [`Motor1MoveAbsolutePayload`]. + - `Motor1MoveAbsolute` - Set this to the target step position (e.g. 2000). +- Insert a [`MulticastSubject`] operator named `StepperDriver Commands`. + +Run the workflow and press D to move the motor to the target position. Observe the accumulated steps in the visualizer to confirm the motor reaches the specified position. + +> [!TIP] +> To move multiple motors simultaneously, use the [`MoveAbsolutePayload`]. + [`AccumulatedSteps`]: xref:Harp.StepperDriver.AccumulatedSteps [`AccumulatedStepsSamplingRatePayload`]: xref:Harp.StepperDriver.CreateAccumulatedStepsSamplingRatePayload @@ -103,6 +122,9 @@ Run the workflow and press A to move the motor forward and S + + + + + + D + false + + + + Write + + 2000 + + + + StepperDriver Commands + + + + + + + + \ No newline at end of file diff --git a/workflows/stepperdriver-controlmotor-moveabsolute.svg b/workflows/stepperdriver-controlmotor-moveabsolute.svg new file mode 100644 index 00000000..ace3a625 --- /dev/null +++ b/workflows/stepperdriver-controlmotor-moveabsolute.svg @@ -0,0 +1,61 @@ + + +]> + + + + + + + + + + + + StepperDriver + + + Commands + + + + + + Stepper + + + Driver.Motor1 + + + MoveAbsolute + + + + + + + KeyDown + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file From e808818f33434e8e82c10a0012f5d53e1827e9ca Mon Sep 17 00:00:00 2001 From: Shawn Tan Date: Wed, 18 Feb 2026 07:52:24 -0800 Subject: [PATCH 08/27] Minor edits for grammar and clarity --- tutorials/stepperdriver-controlmotor.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/tutorials/stepperdriver-controlmotor.md b/tutorials/stepperdriver-controlmotor.md index e1c82cc3..48f6e630 100644 --- a/tutorials/stepperdriver-controlmotor.md +++ b/tutorials/stepperdriver-controlmotor.md @@ -36,7 +36,7 @@ Read the [`AccumulatedSteps`] and display it in a visualizer: ## Exercise 1: Set acceleration profile -Motor motion is driven by a series of step pulses and speed can be controlled by specifying the interval between steps (in μs). For any given movement, the acceleration profile is defined by three parameters: +Motor motion is driven by a series of step pulses, and speed can be controlled by specifying the interval between steps (in μs). The acceleration profile is defined by three parameters: - the initial/final step interval - the target step interval at nominal speed @@ -59,11 +59,11 @@ Motor motion is driven by a series of step pulses and speed can be controlled by - Combine the three messages with a [`Merge`] combinator. - Insert a [`MulticastSubject`] operator named `StepperDriver Commands`. -Run the workflow and press the 3 key to set the acceleration profile. You can also adjust the properties, and press the 3 key to update the acceleration profile while the workflow is running. This allows you to test different speeds with the movement commands. +Run the workflow and press the 3 key to set the acceleration profile. You can also adjust the properties, and press the 3 key to update the acceleration profile while the workflow is running. This allows you to test different speeds with the move commands. ## Exercise 2: Move relative steps -The [`MoveRelative`] register moves the motor by a specified number of steps from its current position. Positive values move in one direction, negative values in the other. +The [`MoveRelative`] register moves the motor by a specified number of steps from its current position. :::workflow ![StepperDriver Move Relative](../workflows/stepperdriver-controlmotor-moverelative.bonsai) @@ -111,6 +111,8 @@ Run the workflow and press D to move the motor to the target position > [!TIP] > To move multiple motors simultaneously, use the [`MoveAbsolutePayload`]. + + [`AccumulatedSteps`]: xref:Harp.StepperDriver.AccumulatedSteps [`AccumulatedStepsSamplingRatePayload`]: xref:Harp.StepperDriver.CreateAccumulatedStepsSamplingRatePayload From 611d2e6b65bedde67e75841543e9a90f05898fea Mon Sep 17 00:00:00 2001 From: Shawn Tan Date: Wed, 18 Feb 2026 08:16:30 -0800 Subject: [PATCH 09/27] Align payload and property formatting --- tutorials/stepperdriver-controlmotor.md | 28 ++++++++++++------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/tutorials/stepperdriver-controlmotor.md b/tutorials/stepperdriver-controlmotor.md index 48f6e630..23e9a4ce 100644 --- a/tutorials/stepperdriver-controlmotor.md +++ b/tutorials/stepperdriver-controlmotor.md @@ -23,8 +23,8 @@ Enable the [`AccumulatedSteps`] event register and configure the dispatch rate: - Insert a [`SubscribeSubject`] operator named `StepperDriver Events`. - Insert a [`Take`] combinator and set the `Count` property to 1. - Insert a [`CreateMessage`] operator and configure these properties: - - `Payload` - Set it to [`AccumulatedStepsSamplingRatePayload`]. - - `AccumulatedStepsSamplingRate` - Set it to the desired sampling rate (e.g. `Rate10Hz` for coarse movements). + - `Payload` - Select [`AccumulatedStepsSamplingRatePayload`]. + - `AccumulatedStepsSamplingRate` - Set the desired sampling rate (e.g. `Rate10Hz` for coarse movements). - Insert a [`MulticastSubject`] operator named `StepperDriver Commands`. Read the [`AccumulatedSteps`] and display it in a visualizer: @@ -48,14 +48,14 @@ Motor motion is driven by a series of step pulses, and speed can be controlled b - Insert a [`KeyDown`] source and set the `Filter` property to `3`. - Insert a [`CreateMessage`] operator and configure these properties: - - `Payload` - Set it to [`Motor1MaximumStepIntervalPayload`]. - - `Motor1MaximumStepInterval` - Set this to the initial/final step interval (e.g. 2000). + - `Payload` - Select [`Motor1MaximumStepIntervalPayload`]. + - `Motor1MaximumStepInterval` - Set the initial/final step interval (e.g. 2000). - Insert a [`CreateMessage`] operator on a new branch and configure these properties: - - `Payload` - Set it to [`Motor1StepIntervalPayload`]. - - `Motor1StepInterval` - Set this to the target step interval (e.g. 250). + - `Payload` - Select [`Motor1StepIntervalPayload`]. + - `Motor1StepInterval` - Set the target step interval (e.g. 250). - Insert a [`CreateMessage`] operator on a new branch and configure these properties: - - `Payload` - Set it to [`Motor1StepAccelerationIntervalPayload`]. - - `Motor1StepAcceleration` - Set this to the change in step interval (e.g. 10). + - `Payload` - Select [`Motor1StepAccelerationIntervalPayload`]. + - `Motor1StepAcceleration` - Set the change in step interval (e.g. 10). - Combine the three messages with a [`Merge`] combinator. - Insert a [`MulticastSubject`] operator named `StepperDriver Commands`. @@ -73,16 +73,16 @@ To move the motor in the positive direction: - Insert a [`KeyDown`] source and set the `Filter` property to `A`. - Insert a [`CreateMessage`] operator and configure these properties: - - `Payload` - Set it to [`Motor1MoveRelativePayload`]. - - `Motor1MoveRelative` - Set this to the number of steps to move (e.g. 3000). + - `Payload` - Select [`Motor1MoveRelativePayload`]. + - `Motor1MoveRelative` - Set the number of steps to move (e.g. 3000). - Insert a [`MulticastSubject`] operator named `StepperDriver Commands`. To move the motor in the negative direction, set up a separate pipeline: - Insert a [`KeyDown`] source and set the `Filter` property to `S`. - Insert a [`CreateMessage`] operator and configure these properties: - - `Payload` - Set it to [`Motor1MoveRelativePayload`]. - - `Motor1MoveRelative` - Set this to a negative value (e.g. -3000). + - `Payload` - Select [`Motor1MoveRelativePayload`]. + - `Motor1MoveRelative` - Set to a negative value (e.g. -3000). - Insert a [`MulticastSubject`] operator named `StepperDriver Commands`. Run the workflow and press A to move the motor forward and S to move it back. Observe the accumulated steps in the visualizer to track the motor's position. @@ -102,8 +102,8 @@ The [`MoveAbsolute`] register moves the motor to an absolute step position based - Insert a [`KeyDown`] source and set the `Filter` property to `D`. - Insert a [`CreateMessage`] operator and configure these properties: - - `Payload` - Set it to [`Motor1MoveAbsolutePayload`]. - - `Motor1MoveAbsolute` - Set this to the target step position (e.g. 2000). + - `Payload` - Select [`Motor1MoveAbsolutePayload`]. + - `Motor1MoveAbsolute` - Set the target step position (e.g. 2000). - Insert a [`MulticastSubject`] operator named `StepperDriver Commands`. Run the workflow and press D to move the motor to the target position. Observe the accumulated steps in the visualizer to confirm the motor reaches the specified position. From cf707cea828180ce49547e8b02350a4b73c96a59 Mon Sep 17 00:00:00 2001 From: Shawn Tan Date: Wed, 18 Feb 2026 08:39:18 -0800 Subject: [PATCH 10/27] Add exercise 4 position limits --- tutorials/stepperdriver-controlmotor.md | 33 ++++++++++++++++++++++++- 1 file changed, 32 insertions(+), 1 deletion(-) diff --git a/tutorials/stepperdriver-controlmotor.md b/tutorials/stepperdriver-controlmotor.md index 23e9a4ce..67f7a026 100644 --- a/tutorials/stepperdriver-controlmotor.md +++ b/tutorials/stepperdriver-controlmotor.md @@ -111,7 +111,34 @@ Run the workflow and press D to move the motor to the target position > [!TIP] > To move multiple motors simultaneously, use the [`MoveAbsolutePayload`]. +## Exercise 4: Set position limits +Position limits restrict the range of motion by defining a minimum and maximum step position based on the [`AccumulatedSteps`] counter. The motor will stop automatically if it reaches either limit. + +:::workflow +![StepperDriver Position Limits](../workflows/stepperdriver-controlmotor-positionlimits.bonsai) +::: + +Set the minimum position limit: + +- Insert a [`KeyDown`] source and set the `Filter` property to `4`. +- Insert a [`CreateMessage`] operator and configure these properties: + - `Payload` - Select [`Motor1MinPositionPayload`]. + - `Motor1MinPosition` - Set the minimum step position (e.g. 1000). +- Insert a [`MulticastSubject`] operator named `StepperDriver Commands`. + +Set the maximum position limit in a separate pipeline: + +- Insert a [`KeyDown`] source and set the `Filter` property to `5`. +- Insert a [`CreateMessage`] operator and configure these properties: + - `Payload` - Select [`Motor1MaxPositionPayload`]. + - `Motor1MaxPosition` - Set the maximum step position (e.g. 4000). +- Insert a [`MulticastSubject`] operator named `StepperDriver Commands`. + +Run the workflow and press 4 to set the minimum limit and 5 to set the maximum limit. Use the move commands from the previous exercises to verify that the motor stops at each limit. + +> [!TIP] +> To set position limits for all motors simultaneously, use the [`MinPositionPayload`] and [`MaxPositionPayload`]. [`AccumulatedSteps`]: xref:Harp.StepperDriver.AccumulatedSteps @@ -126,11 +153,15 @@ Run the workflow and press D to move the motor to the target position [`MoveRelativePayload`]: xref:Harp.StepperDriver.CreateMoveRelativePayload [`MoveAbsolute`]: xref:Harp.StepperDriver.MoveAbsolute [`MoveAbsolutePayload`]: xref:Harp.StepperDriver.CreateMoveAbsolutePayload +[`MaxPositionPayload`]: xref:Harp.StepperDriver.CreateMaxPositionPayload +[`MinPositionPayload`]: xref:Harp.StepperDriver.CreateMinPositionPayload +[`Motor1MaxPositionPayload`]: xref:Harp.StepperDriver.CreateMotor1MaxPositionPayload +[`Motor1MinPositionPayload`]: xref:Harp.StepperDriver.CreateMotor1MinPositionPayload [`Motor1MoveAbsolutePayload`]: xref:Harp.StepperDriver.CreateMotor1MoveAbsolutePayload [`Motor1MoveRelativePayload`]: xref:Harp.StepperDriver.CreateMotor1MoveRelativePayload [`Motor1StepAccelerationIntervalPayload`]: xref:Harp.StepperDriver.CreateMotor1StepAccelerationIntervalPayload [`Motor1MaximumStepIntervalPayload`]: xref:Harp.StepperDriver.CreateMotor1MaximumStepIntervalPayload -[`Motor1Motor1StepInterval`]: xref:Harp.StepperDriver.CreateMotor1StepIntervalPayload +[`Motor1Motor1StepIntervalPayload`]: xref:Harp.StepperDriver.CreateMotor1StepIntervalPayload [`MulticastSubject`]: xref:Bonsai.Expressions.MulticastSubject [`Parse`]: xref:Harp.StepperDriver.Parse [`PublishSubject`]: xref:Bonsai.Reactive.PublishSubject From 5f54969d707889b546416703461914b737c94d1a Mon Sep 17 00:00:00 2001 From: Shawn Tan Date: Wed, 18 Feb 2026 09:07:28 -0800 Subject: [PATCH 11/27] Add position limit bonsai workflow --- tutorials/stepperdriver-controlmotor.md | 2 +- ...erdriver-controlmotor-positionlimit.bonsai | 48 ++++++++ ...epperdriver-controlmotor-positionlimit.svg | 110 ++++++++++++++++++ 3 files changed, 159 insertions(+), 1 deletion(-) create mode 100644 workflows/stepperdriver-controlmotor-positionlimit.bonsai create mode 100644 workflows/stepperdriver-controlmotor-positionlimit.svg diff --git a/tutorials/stepperdriver-controlmotor.md b/tutorials/stepperdriver-controlmotor.md index 67f7a026..d5446397 100644 --- a/tutorials/stepperdriver-controlmotor.md +++ b/tutorials/stepperdriver-controlmotor.md @@ -138,7 +138,7 @@ Set the maximum position limit in a separate pipeline: Run the workflow and press 4 to set the minimum limit and 5 to set the maximum limit. Use the move commands from the previous exercises to verify that the motor stops at each limit. > [!TIP] -> To set position limits for all motors simultaneously, use the [`MinPositionPayload`] and [`MaxPositionPayload`]. +> To set position limits for all motors, use the [`MinPositionPayload`] and [`MaxPositionPayload`]. [`AccumulatedSteps`]: xref:Harp.StepperDriver.AccumulatedSteps diff --git a/workflows/stepperdriver-controlmotor-positionlimit.bonsai b/workflows/stepperdriver-controlmotor-positionlimit.bonsai new file mode 100644 index 00000000..5918c508 --- /dev/null +++ b/workflows/stepperdriver-controlmotor-positionlimit.bonsai @@ -0,0 +1,48 @@ + + + + + + + D4 + false + + + + Write + + 1000 + + + + StepperDriver Commands + + + + D5 + false + + + + Write + + 4000 + + + + StepperDriver Commands + + + + + + + + + + \ No newline at end of file diff --git a/workflows/stepperdriver-controlmotor-positionlimit.svg b/workflows/stepperdriver-controlmotor-positionlimit.svg new file mode 100644 index 00000000..a059e2d0 --- /dev/null +++ b/workflows/stepperdriver-controlmotor-positionlimit.svg @@ -0,0 +1,110 @@ + + +]> + + + + + + + + + + + + + + StepperDriver + + + Commands + + + + + + + StepperDriver + + + Commands + + + + + + Stepper + + + Driver.Motor1 + + + MinPositionPay + + + + + + Stepper + + + Driver.Motor1 + + + MaxPositionPay + + + + + + + KeyDown + + + + + + + KeyDown + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file From 68b8e9a0ab99d5e448ba3df5f0070c58227b0359 Mon Sep 17 00:00:00 2001 From: Shawn Tan Date: Wed, 18 Feb 2026 09:15:57 -0800 Subject: [PATCH 12/27] Minor edits for broken links --- tutorials/stepperdriver-controlmotor.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/tutorials/stepperdriver-controlmotor.md b/tutorials/stepperdriver-controlmotor.md index d5446397..19c58d2f 100644 --- a/tutorials/stepperdriver-controlmotor.md +++ b/tutorials/stepperdriver-controlmotor.md @@ -59,7 +59,9 @@ Motor motion is driven by a series of step pulses, and speed can be controlled b - Combine the three messages with a [`Merge`] combinator. - Insert a [`MulticastSubject`] operator named `StepperDriver Commands`. -Run the workflow and press the 3 key to set the acceleration profile. You can also adjust the properties, and press the 3 key to update the acceleration profile while the workflow is running. This allows you to test different speeds with the move commands. +Run the workflow and press the 3 key to set the acceleration profile. + +You can also adjust the properties, and press the 3 key to update the acceleration profile while the workflow is running. This allows you to test different speeds with the move commands. ## Exercise 2: Move relative steps @@ -116,7 +118,7 @@ Run the workflow and press D to move the motor to the target position Position limits restrict the range of motion by defining a minimum and maximum step position based on the [`AccumulatedSteps`] counter. The motor will stop automatically if it reaches either limit. :::workflow -![StepperDriver Position Limits](../workflows/stepperdriver-controlmotor-positionlimits.bonsai) +![StepperDriver Position Limit](../workflows/stepperdriver-controlmotor-positionlimit.bonsai) ::: Set the minimum position limit: @@ -137,6 +139,8 @@ Set the maximum position limit in a separate pipeline: Run the workflow and press 4 to set the minimum limit and 5 to set the maximum limit. Use the move commands from the previous exercises to verify that the motor stops at each limit. +You can also adjust the properties, and press the 4 and 5 key to update the position limits while the workflow is running. + > [!TIP] > To set position limits for all motors, use the [`MinPositionPayload`] and [`MaxPositionPayload`]. @@ -161,7 +165,7 @@ Run the workflow and press 4 to set the minimum limit and 5 Date: Wed, 18 Feb 2026 10:22:38 -0800 Subject: [PATCH 13/27] Add exercise 5 stop motor --- tutorials/stepperdriver-controlmotor.md | 27 +++++++- ...epperdriver-controlmotor-stopmotors.bonsai | 31 ++++++++++ .../stepperdriver-controlmotor-stopmotors.svg | 61 +++++++++++++++++++ 3 files changed, 116 insertions(+), 3 deletions(-) create mode 100644 workflows/stepperdriver-controlmotor-stopmotors.bonsai create mode 100644 workflows/stepperdriver-controlmotor-stopmotors.svg diff --git a/tutorials/stepperdriver-controlmotor.md b/tutorials/stepperdriver-controlmotor.md index 19c58d2f..dd954cb0 100644 --- a/tutorials/stepperdriver-controlmotor.md +++ b/tutorials/stepperdriver-controlmotor.md @@ -59,9 +59,9 @@ Motor motion is driven by a series of step pulses, and speed can be controlled b - Combine the three messages with a [`Merge`] combinator. - Insert a [`MulticastSubject`] operator named `StepperDriver Commands`. -Run the workflow and press the 3 key to set the acceleration profile. +Run the workflow and press 3 to set the acceleration profile. -You can also adjust the properties, and press the 3 key to update the acceleration profile while the workflow is running. This allows you to test different speeds with the move commands. +You can also adjust the properties, and press 3 to update the acceleration profile while the workflow is running. This allows you to test different speeds with the move commands. ## Exercise 2: Move relative steps @@ -139,11 +139,30 @@ Set the maximum position limit in a separate pipeline: Run the workflow and press 4 to set the minimum limit and 5 to set the maximum limit. Use the move commands from the previous exercises to verify that the motor stops at each limit. -You can also adjust the properties, and press the 4 and 5 key to update the position limits while the workflow is running. +You can also adjust the properties, and press the 4 and 5 keys to update the position limits while the workflow is running. > [!TIP] > To set position limits for all motors, use the [`MinPositionPayload`] and [`MaxPositionPayload`]. +## Exercise 5: Stop motors + +The [`StopMotors`] register immediately halts motors regardless of their current move command and can be used as an emergency stop. + +:::workflow +![StepperDriver Stop Motors](../workflows/stepperdriver-controlmotor-stopmotors.bonsai) +::: + +- Insert a [`KeyDown`] source and set the `Filter` property to `F`. +- Insert a [`CreateMessage`] operator and configure these properties: + - `Payload` - Select [`StopMotorsPayload`]. + - `StopMotors` - Select the motor to stop (e.g. `Motor1`). +- Insert a [`MulticastSubject`] operator named `StepperDriver Commands`. + +Run the workflow and use the move commands from the previous exercises to set the motor in motion. Press F to immediately stop the motor. + +> [!TIP] +> To target multiple motors, enter their names, separated by a comma, for the `StopMotors` property (e.g. `Motor0`, `Motor1`). + [`AccumulatedSteps`]: xref:Harp.StepperDriver.AccumulatedSteps [`AccumulatedStepsSamplingRatePayload`]: xref:Harp.StepperDriver.CreateAccumulatedStepsSamplingRatePayload @@ -158,6 +177,8 @@ You can also adjust the properties, and press the 4 and 5 [`MoveAbsolute`]: xref:Harp.StepperDriver.MoveAbsolute [`MoveAbsolutePayload`]: xref:Harp.StepperDriver.CreateMoveAbsolutePayload [`MaxPositionPayload`]: xref:Harp.StepperDriver.CreateMaxPositionPayload +[`StopMotors`]: xref:Harp.StepperDriver.StopMotors +[`StopMotorsPayload`]: xref:Harp.StepperDriver.CreateStopMotorsPayload [`MinPositionPayload`]: xref:Harp.StepperDriver.CreateMinPositionPayload [`Motor1MaxPositionPayload`]: xref:Harp.StepperDriver.CreateMotor1MaxPositionPayload [`Motor1MinPositionPayload`]: xref:Harp.StepperDriver.CreateMotor1MinPositionPayload diff --git a/workflows/stepperdriver-controlmotor-stopmotors.bonsai b/workflows/stepperdriver-controlmotor-stopmotors.bonsai new file mode 100644 index 00000000..14b68038 --- /dev/null +++ b/workflows/stepperdriver-controlmotor-stopmotors.bonsai @@ -0,0 +1,31 @@ + + + + + + + F + false + + + + Write + + Motor1 + + + + StepperDriver Commands + + + + + + + + \ No newline at end of file diff --git a/workflows/stepperdriver-controlmotor-stopmotors.svg b/workflows/stepperdriver-controlmotor-stopmotors.svg new file mode 100644 index 00000000..cf38eb93 --- /dev/null +++ b/workflows/stepperdriver-controlmotor-stopmotors.svg @@ -0,0 +1,61 @@ + + +]> + + + + + + + + + + + + StepperDriver + + + Commands + + + + + + Stepper + + + Driver.Stop + + + MotorsPayload + + + + + + + KeyDown + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file From 5d993ae09525613b31ad65623e63aa18d10f7c46 Mon Sep 17 00:00:00 2001 From: Shawn Tan Date: Wed, 18 Feb 2026 11:06:51 -0800 Subject: [PATCH 14/27] Add exercise 6 move continuous --- tutorials/stepperdriver-controlmotor.md | 25 ++++++++ ...rdriver-controlmotor-movecontinuous.bonsai | 31 ++++++++++ ...pperdriver-controlmotor-movecontinuous.svg | 61 +++++++++++++++++++ 3 files changed, 117 insertions(+) create mode 100644 workflows/stepperdriver-controlmotor-movecontinuous.bonsai create mode 100644 workflows/stepperdriver-controlmotor-movecontinuous.svg diff --git a/tutorials/stepperdriver-controlmotor.md b/tutorials/stepperdriver-controlmotor.md index dd954cb0..28f35ef5 100644 --- a/tutorials/stepperdriver-controlmotor.md +++ b/tutorials/stepperdriver-controlmotor.md @@ -163,6 +163,28 @@ Run the workflow and use the move commands from the previous exercises to set th > [!TIP] > To target multiple motors, enter their names, separated by a comma, for the `StopMotors` property (e.g. `Motor0`, `Motor1`). +## Exercise 6: Move continuously + +The [`StepRelative`] register ignores the acceleration profile and moves the motor continuously at a fixed speed determined by the step interval and a direction determined by the sign of the value. + +> [!WARNING] +> Ensure that position limits or the stop command are in place before trying this exercise. + +:::workflow +![StepperDriver Move Continuously](../workflows/stepperdriver-controlmotor-movecontinuous.bonsai) +::: + +- Insert a [`KeyDown`] source and set the `Filter` property to `G`. +- Insert a [`CreateMessage`] operator and configure these properties: + - `Payload` - Select [`Motor1StepRelativePayload`]. + - `Motor1` - Set the step interval and direction (e.g. 1000 for forward). +- Insert a [`MulticastSubject`] operator named `StepperDriver Commands`. + +Run the workflow and press G to start continuous motor motion. Press F from the previous exercise to stop the motor. + +> [!TIP] +> To move multiple motors simultaneously, use the [`StepRelativePayload`]. + [`AccumulatedSteps`]: xref:Harp.StepperDriver.AccumulatedSteps [`AccumulatedStepsSamplingRatePayload`]: xref:Harp.StepperDriver.CreateAccumulatedStepsSamplingRatePayload @@ -185,11 +207,14 @@ Run the workflow and use the move commands from the previous exercises to set th [`Motor1MoveAbsolutePayload`]: xref:Harp.StepperDriver.CreateMotor1MoveAbsolutePayload [`Motor1MoveRelativePayload`]: xref:Harp.StepperDriver.CreateMotor1MoveRelativePayload [`Motor1StepAccelerationIntervalPayload`]: xref:Harp.StepperDriver.CreateMotor1StepAccelerationIntervalPayload +[`Motor1StepRelativePayload`]: xref:Harp.StepperDriver.CreateMotor1StepRelativePayload [`Motor1MaximumStepIntervalPayload`]: xref:Harp.StepperDriver.CreateMotor1MaximumStepIntervalPayload [`Motor1StepIntervalPayload`]: xref:Harp.StepperDriver.CreateMotor1StepIntervalPayload [`MulticastSubject`]: xref:Bonsai.Expressions.MulticastSubject [`Parse`]: xref:Harp.StepperDriver.Parse [`PublishSubject`]: xref:Bonsai.Reactive.PublishSubject +[`StepRelative`]: xref:Harp.StepperDriver.StepRelative +[`StepRelativePayload`]: xref:Harp.StepperDriver.StepRelativePayload [`SubscribeSubject`]: xref:Bonsai.Expressions.SubscribeSubject [`Take`]: xref:Bonsai.Reactive.Take [`Timer`]: xref:Bonsai.Reactive.Timer diff --git a/workflows/stepperdriver-controlmotor-movecontinuous.bonsai b/workflows/stepperdriver-controlmotor-movecontinuous.bonsai new file mode 100644 index 00000000..5cfcbbb1 --- /dev/null +++ b/workflows/stepperdriver-controlmotor-movecontinuous.bonsai @@ -0,0 +1,31 @@ + + + + + + + G + false + + + + Write + + 1000 + + + + StepperDriver Commands + + + + + + + + \ No newline at end of file diff --git a/workflows/stepperdriver-controlmotor-movecontinuous.svg b/workflows/stepperdriver-controlmotor-movecontinuous.svg new file mode 100644 index 00000000..6cb16ba4 --- /dev/null +++ b/workflows/stepperdriver-controlmotor-movecontinuous.svg @@ -0,0 +1,61 @@ + + +]> + + + + + + + + + + + + StepperDriver + + + Commands + + + + + + Stepper + + + Driver.Motor1 + + + StepRelativeP + + + + + + + KeyDown + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file From cdac70a56ea21966e3c8772bcfcbe5d2030bce0d Mon Sep 17 00:00:00 2001 From: Shawn Tan Date: Wed, 18 Feb 2026 12:27:10 -0800 Subject: [PATCH 15/27] Add exercise 7 to reset position --- tutorials/stepperdriver-controlmotor.md | 28 +++++++-- ...erdriver-controlmotor-resetposition.bonsai | 34 +++++++++++ ...epperdriver-controlmotor-resetposition.svg | 61 +++++++++++++++++++ 3 files changed, 119 insertions(+), 4 deletions(-) create mode 100644 workflows/stepperdriver-controlmotor-resetposition.bonsai create mode 100644 workflows/stepperdriver-controlmotor-resetposition.svg diff --git a/tutorials/stepperdriver-controlmotor.md b/tutorials/stepperdriver-controlmotor.md index 28f35ef5..9e36ddeb 100644 --- a/tutorials/stepperdriver-controlmotor.md +++ b/tutorials/stepperdriver-controlmotor.md @@ -10,7 +10,7 @@ The follow exercises will demonstrate how to control motor speed and rotational - Install the `Bonsai.Windows.Input` package from the Bonsai [package manager](https://bonsai-rx.org/docs/articles/packages.html). - Connect a stepper motor to the `Stepper 1` output on the `StepperDriver`, set up the [device pattern](./stepperdriver-configuration.md#device-pattern), [configure](./stepperdriver-configuration.md) the device, and [enable](./stepperdriver-configuration.md#enable-and-disable-motors) the `Motor1` stepper driver. -## Position visualizer +## Visualize position For these exercises, it helps to track the rotational position of the motor. The `StepperDriver` can broadcast a stream of [`AccumulatedSteps`] events, which can be displayed in a visualizer for this purpose. @@ -27,7 +27,7 @@ Enable the [`AccumulatedSteps`] event register and configure the dispatch rate: - `AccumulatedStepsSamplingRate` - Set the desired sampling rate (e.g. `Rate10Hz` for coarse movements). - Insert a [`MulticastSubject`] operator named `StepperDriver Commands`. -Read the [`AccumulatedSteps`] and display it in a visualizer: +Extract the [`AccumulatedSteps`] events and format it for visualizer display: - Insert a [`SubscribeSubject`] operator named `StepperDriver Events`. - Insert a [`Parse`] operator and set the `Register` property to [`AccumulatedSteps`]. @@ -144,7 +144,7 @@ You can also adjust the properties, and press the 4 and 5 > [!TIP] > To set position limits for all motors, use the [`MinPositionPayload`] and [`MaxPositionPayload`]. -## Exercise 5: Stop motors +## Exercise 6: Stop motors The [`StopMotors`] register immediately halts motors regardless of their current move command and can be used as an emergency stop. @@ -163,7 +163,7 @@ Run the workflow and use the move commands from the previous exercises to set th > [!TIP] > To target multiple motors, enter their names, separated by a comma, for the `StopMotors` property (e.g. `Motor0`, `Motor1`). -## Exercise 6: Move continuously +## Exercise 7: Move continuously The [`StepRelative`] register ignores the acceleration profile and moves the motor continuously at a fixed speed determined by the step interval and a direction determined by the sign of the value. @@ -185,8 +185,28 @@ Run the workflow and press G to start continuous motor motion. Press > [!TIP] > To move multiple motors simultaneously, use the [`StepRelativePayload`]. +## Exercise 7: Reset position + +Writing new values to the [`AccumulatedSteps`] register resets the position tracking to a new origin. + +:::workflow +![StepperDriver Reset Position](../workflows/stepperdriver-controlmotor-resetposition.bonsai) +::: + +- Insert a [`KeyDown`] source and set the `Filter` property to `6`. +- Insert a [`CreateMessage`] operator and configure these properties: + - `Payload` - Select [`AccumulatedStepsPayload`]. + - `Motor1` - Set to 0. +- Insert a [`MulticastSubject`] operator named `StepperDriver Commands`. + +Run the workflow and press 6 to reset the accumulated steps. Observe the accumulated steps in the visualizer to verify that the position has been reset. + +> [!WARNING] +> Note that any absolute position moves and position limits set in the previous exercises will now refer to a different physical location. + [`AccumulatedSteps`]: xref:Harp.StepperDriver.AccumulatedSteps +[`AccumulatedStepsPayload`]: xref:Harp.StepperDriver.CreateAccumulatedStepsPayload [`AccumulatedStepsSamplingRatePayload`]: xref:Harp.StepperDriver.CreateAccumulatedStepsSamplingRatePayload [``BehaviourSubject`1``]: xref:Bonsai.Reactive.BehaviorSubject [`CreateMessage`]: xref:Harp.StepperDriver.CreateMessage diff --git a/workflows/stepperdriver-controlmotor-resetposition.bonsai b/workflows/stepperdriver-controlmotor-resetposition.bonsai new file mode 100644 index 00000000..846c440e --- /dev/null +++ b/workflows/stepperdriver-controlmotor-resetposition.bonsai @@ -0,0 +1,34 @@ + + + + + + + D6 + false + + + + Write + + 0 + 0 + 0 + 0 + + + + StepperDriver Commands + + + + + + + + \ No newline at end of file diff --git a/workflows/stepperdriver-controlmotor-resetposition.svg b/workflows/stepperdriver-controlmotor-resetposition.svg new file mode 100644 index 00000000..57827eec --- /dev/null +++ b/workflows/stepperdriver-controlmotor-resetposition.svg @@ -0,0 +1,61 @@ + + +]> + + + + + + + + + + + + StepperDriver + + + Commands + + + + + + Stepper + + + Driver. + + + AccumulatedSt + + + + + + + KeyDown + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file From 8b2a6a4f17d3381a5ba6d2cf405348a7a2ed9342 Mon Sep 17 00:00:00 2001 From: Shawn Tan Date: Wed, 18 Feb 2026 18:25:21 -0800 Subject: [PATCH 16/27] Minor grammar and clarity edits --- tutorials/stepperdriver-configuration.md | 17 ++++++++--------- tutorials/stepperdriver-controlmotor.md | 1 - 2 files changed, 8 insertions(+), 10 deletions(-) diff --git a/tutorials/stepperdriver-configuration.md b/tutorials/stepperdriver-configuration.md index 49a9348d..148ee2c4 100644 --- a/tutorials/stepperdriver-configuration.md +++ b/tutorials/stepperdriver-configuration.md @@ -8,7 +8,7 @@ Configuration parameters must be set for the [Harp StepperDriver](https://github ## Prerequisites - Install the `Bonsai.Windows.Input` package from the Bonsai [package manager](https://bonsai-rx.org/docs/articles/packages.html). -- The steps listed below demonstrate driver configuration for a single stepper motor connected to the `Motor1` output on the `StepperDriver`. Adjust the relevant properties for your specific configuration. +- The steps listed below demonstrate driver configuration for a single stepper motor (`Motor1`) connected to the `Stepper 1` output on the `StepperDriver`. Adjust the relevant properties for your specific configuration. ## Device pattern @@ -84,7 +84,7 @@ Other operation parameters to be set include the operation mode of the motor dri > [!TIP] > The previous configuration commands can also be combined using [`Merge`] and sent into a single `StepperDriver Commands` pipeline. -## Enable and disable motors +## Enable and disable motor drivers Lastly, motor drivers have to be enabled before use, but can be disabled at any time. @@ -95,21 +95,21 @@ Lastly, motor drivers have to be enabled before use, but can be disabled at any - Insert a [`KeyDown`] source and set the `Filter` property to `1`. - Insert a [`CreateMessage`] operator and configure these properties: - `Payload` - Set this to [`EnableDriverPayload`]. - - `EnableDriver` - Set this to the motor to enable (e.g. `Motor1`). + - `EnableDriver` - Set this to the motor driver to enable (e.g. `Motor1`). - Insert a [`MulticastSubject`] operator named `StepperDriver Commands`. -To disable the motor, set up a separate pipeline: +To disable the driver, set up a separate pipeline: - Insert a [`KeyDown`] source and set the `Filter` property to `2`. - Insert a [`CreateMessage`] operator and configure these properties: - `Payload` - Set this to [`DisableDriverPayload`]. - - `DisableDriver` - Set this to the motor to disable (e.g. `Motor1`). + - `DisableDriver` - Set this to the motor driver to disable (e.g. `Motor1`). - Insert a [`MulticastSubject`] operator named `StepperDriver Commands`. -Run the workflow and press the 1 key to enable the motor and 2 key to disable the motor. When the motor is enabled, the LED above the motor port on the device will blink red. +Run the workflow and press the 1 key to enable the driver and 2 key to disable the driver. When the driver is enabled, the LED above the driver connection on the device will blink red. > [!TIP] -> To target multiple motors, enter their names, separated by a comma, for the `EnableDriver` and `DisableDriver` properties (e.g. `Motor0`, `Motor1`). +> To target multiple drivers, enter their names, separated by a comma, for the `EnableDriver` and `DisableDriver` properties (e.g. `Motor0`, `Motor1`). [``BehaviourSubject`1``]: xref:Bonsai.Reactive.BehaviorSubject @@ -128,5 +128,4 @@ Run the workflow and press the 1 key to enable the motor and 26 to reset the accumulated steps. Observe [`StepRelativePayload`]: xref:Harp.StepperDriver.StepRelativePayload [`SubscribeSubject`]: xref:Bonsai.Expressions.SubscribeSubject [`Take`]: xref:Bonsai.Reactive.Take -[`Timer`]: xref:Bonsai.Reactive.Timer [`VisualizerWindow`]: xref:Bonsai.Design.VisualizerWindow \ No newline at end of file From b7a057b18dc1f704c15bf997fa987afaebb00bba Mon Sep 17 00:00:00 2001 From: Shawn Tan Date: Wed, 18 Feb 2026 21:00:30 -0800 Subject: [PATCH 17/27] Add draft of quickmovement article --- tutorials/stepperdriver-configuration.md | 22 ++-- tutorials/stepperdriver-controlmotor.md | 2 +- tutorials/stepperdriver-quickmovement.md | 49 ++++++++ tutorials/toc.yml | 3 +- ...r-quickmovement-driverconfiguration.bonsai | 46 ++++++++ ...iver-quickmovement-driverconfiguration.svg | 110 ++++++++++++++++++ 6 files changed, 218 insertions(+), 14 deletions(-) create mode 100644 tutorials/stepperdriver-quickmovement.md create mode 100644 workflows/stepperdriver-quickmovement-driverconfiguration.bonsai create mode 100644 workflows/stepperdriver-quickmovement-driverconfiguration.svg diff --git a/tutorials/stepperdriver-configuration.md b/tutorials/stepperdriver-configuration.md index 148ee2c4..2021f1aa 100644 --- a/tutorials/stepperdriver-configuration.md +++ b/tutorials/stepperdriver-configuration.md @@ -36,9 +36,7 @@ The `StepperDriver` includes an external interlock terminal (labelled `Enable` o - Insert a [`Take`] combinator and set the `Count` property to 1. - Insert a [`CreateMessage`] operator to construct a [`HarpMessage`] command to send to the device and configure these properties: - `Payload` - Select [`InterlockEnabledPayload`] from the property drop down menu. - - `InterlockEnabled` - Select either of these values: - - `Open` - to enable the device if the interlock is not in use. - - `Closed` - to enable the device with a connected interlock switch. + - `InterlockEnabled` - Select `Open` to enable the device if the interlock is not in use, or `Closed` to enable the device with a connected interlock switch. - Insert a [`MulticastSubject`] operator to send [`HarpMessage`] commands to named subjects, and configure the `Name` property to `StepperDriver Commands`. > [!TIP] @@ -55,7 +53,7 @@ The microstep resolution determines the size of each step, and directly affects - Insert a [`SubscribeSubject`] operator named `StepperDriver Events`. - Insert a [`Take`] combinator and set the `Count` property to 1. - Insert a [`CreateMessage`] operator and configure these properties: - - `Payload` - Set it to [`Motor1MicrostepResolution`]. + - `Payload` - Set it to [`Motor1MicrostepResolutionPayload`]. - `Motor1MicrostepResolution` - Select the desired microstep resolution (e.g. `Microstep8`). - Insert a [`MulticastSubject`] operator named `StepperDriver Commands`. @@ -70,13 +68,13 @@ Other operation parameters to be set include the operation mode of the motor dri - Insert a [`SubscribeSubject`] operator named `StepperDriver Events`. - Insert a [`Take`] combinator and set the `Count` property to 1. - Insert a [`CreateMessage`] operator and configure these properties: - - `Payload` - Set it to [`Motor1OperationMode`]. - - `Motor1OperationMode` - Set it to `QuietMode` for regular operation and `DynamicMode` for quick movements. + - `Payload` - Set it to [`Motor1OperationModePayload`]. + - `Motor1OperationMode` - Set it to `QuietMode` for regular operation and `DynamicMovements` for quick movements. - Insert a [`CreateMessage`] operator on another branch, and configure these properties: - - `Payload` - Set it to [`Motor1MaximumRunCurrent`]. + - `Payload` - Set it to [`Motor1MaximumRunCurrentPayload`]. - `Motor1MaximumRunCurrent` - Set it to match the motor's rated phase current in amps (e.g. 1). - Insert a [`CreateMessage`] operator on another branch, and configure these properties: - - `Payload` - Set it to [`Motor1HoldCurrentReduction`]. + - `Payload` - Set it to [`Motor1HoldCurrentReductionPayload`]. - `Motor1HoldCurrentReduction` - Set it to minimise heat reduction and adjust the holding torque of the motor at rest (e.g. `ReductionTo25Percent` for low holding torque with light external loads). - Insert a [`Merge`] operator to combine all three commands into one [`HarpMessage`] stream. - Insert a [`MulticastSubject`] operator named `StepperDriver Commands`. @@ -121,10 +119,10 @@ Run the workflow and press the 1 key to enable the driver and 2< [`InterlockEnabledPayload`]: xref:Harp.StepperDriver.CreateInterlockEnabledPayload [`KeyDown`]: xref:Bonsai.Windows.Input.KeyDown [`Merge`]: xref:Bonsai.Reactive.Merge -[`Motor1MaximumRunCurrent`]: xref:Harp.StepperDriver.CreateMotor1MaximumRunCurrentPayload -[`Motor1HoldCurrentReduction`]: xref:Harp.StepperDriver.CreateMotor1HoldCurrentReductionPayload -[`Motor1MicrostepResolution`]: xref:Harp.StepperDriver.CreateMotor1MicrostepResolutionPayload -[`Motor1OperationMode`]: xref:Harp.StepperDriver.CreateMotor1OperationModePayload +[`Motor1MaximumRunCurrentPayload`]: xref:Harp.StepperDriver.CreateMotor1MaximumRunCurrentPayload +[`Motor1HoldCurrentReductionPayload`]: xref:Harp.StepperDriver.CreateMotor1HoldCurrentReductionPayload +[`Motor1MicrostepResolutionPayload`]: xref:Harp.StepperDriver.CreateMotor1MicrostepResolutionPayload +[`Motor1OperationModePayload`]: xref:Harp.StepperDriver.CreateMotor1OperationModePayload [`MulticastSubject`]: xref:Bonsai.Expressions.MulticastSubject [`PublishSubject`]: xref:Bonsai.Reactive.PublishSubject [`SubscribeSubject`]: xref:Bonsai.Expressions.SubscribeSubject diff --git a/tutorials/stepperdriver-controlmotor.md b/tutorials/stepperdriver-controlmotor.md index e171f30e..f2578524 100644 --- a/tutorials/stepperdriver-controlmotor.md +++ b/tutorials/stepperdriver-controlmotor.md @@ -8,7 +8,7 @@ The follow exercises will demonstrate how to control motor speed and rotational ## Prerequisites - Install the `Bonsai.Windows.Input` package from the Bonsai [package manager](https://bonsai-rx.org/docs/articles/packages.html). -- Connect a stepper motor to the `Stepper 1` output on the `StepperDriver`, set up the [device pattern](./stepperdriver-configuration.md#device-pattern), [configure](./stepperdriver-configuration.md) the device, and [enable](./stepperdriver-configuration.md#enable-and-disable-motors) the `Motor1` stepper driver. +- Connect a stepper motor to the `Stepper 1` output on the `StepperDriver`, set up the [device pattern](./stepperdriver-configuration.md#device-pattern), [configure](./stepperdriver-configuration.md) the device, and [enable](./stepperdriver-configuration.md#enable-and-disable-motor-drivers) the `Motor1` stepper driver. ## Visualize position diff --git a/tutorials/stepperdriver-quickmovement.md b/tutorials/stepperdriver-quickmovement.md new file mode 100644 index 00000000..7791813c --- /dev/null +++ b/tutorials/stepperdriver-quickmovement.md @@ -0,0 +1,49 @@ +# QuickMovement + +The [Harp StepperDriver](https://github.com/harp-tech/device.stepperdriver) features a `QuickMovement` mode that can be used for extremely fast movements with low trigger latency. + +> [!TIP] +> [`StepRelative`](./stepperdriver-controlmotor.md#exercise-7-move-continuously) with position limits may be sufficient for some applications requiring fast movements. + +## Prerequisites + +- Install the `Bonsai.Windows.Input` package from the Bonsai [package manager](https://bonsai-rx.org/docs/articles/packages.html). +- `QuickMovement` requires firmware `fw0.7-harp1.14` and later. Download the firmware from the [release](https://github.com/harp-tech/device.stepperdriver/releases) page and update it with the [Harp Toolkit](https://github.com/harp-tech/toolkit). +- Connect a stepper motor (`Motor1`) to `Stepper 1` output for these exercises. `QuickMovement` is only supported on `Stepper 1` and `Stepper 2` drivers. +- Set up the [device pattern](./stepperdriver-configuration.md#device-pattern), [configure](./stepperdriver-configuration.md) the device, and [enable](./stepperdriver-configuration.md#enable-and-disable-motor-drivers) the `Motor1` stepper driver. +- Use the [position visualizer](./stepperdriver-controlmotor.md#visualize-position) to visualize the movement. + +## Driver Configuration for QuickMovement + +`QuickMovement` requires the motor driver to be configured for `DynamicMovements`. It also helps to set a higher sampling rate for the [`AccumulatedSteps`] event for visualization. + +:::workflow +![StepperDriver QuickMovement Driver Configuration](../workflows/stepperdriver-quickmovements-driverconfiguration.bonsai) +::: + +- Insert a [`SubscribeSubject`] operator named `StepperDriver Events`. +- Insert a [`Take`] combinator and set the `Count` property to 1. +- Insert a [`CreateMessage`] operator and configure these properties: + - `Payload` - Select [`Motor1OperationModePayload`]. + - `Motor1OperationMode` - Set to `DynamicMovements`. +- Insert a [`CreateMessage`] operator on another branch and configure these properties: + - `Payload` - Select [`AccumulatedStepsSamplingRatePayload`]. + - `AccumulatedStepsSamplingRate` - Set to `Rate100Hz`. +- Combine the two messages with a [`Merge`] combinator. +- Insert a [`MulticastSubject`] operator named `StepperDriver Commands`. + +## Exercise 1: Arm QuickMovement + +## Exercise 2: Trigger QuickMovement + + + +[`AccumulatedSteps`]: xref:Harp.StepperDriver.AccumulatedSteps +[`AccumulatedStepsSamplingRatePayload`]: xref:Harp.StepperDriver.CreateAccumulatedStepsSamplingRatePayload +[`CreateMessage`]: xref:Harp.StepperDriver.CreateMessage +[`Merge`]: xref:Bonsai.Reactive.Merge +[`Motor1OperationModePayload`]: xref:Harp.StepperDriver.CreateMotor1OperationModePayload +[`MulticastSubject`]: xref:Bonsai.Expressions.MulticastSubject +[`StepRelative`]: xref:Harp.StepperDriver.StepRelative +[`SubscribeSubject`]: xref:Bonsai.Expressions.SubscribeSubject +[`Take`]: xref:Bonsai.Reactive.Take \ No newline at end of file diff --git a/tutorials/toc.yml b/tutorials/toc.yml index 872621c9..751dddc7 100644 --- a/tutorials/toc.yml +++ b/tutorials/toc.yml @@ -5,4 +5,5 @@ - name: Harp StepperDriver - href: stepperdriver-setup.md - href: stepperdriver-configuration.md -- href: stepperdriver-controlmotor.md \ No newline at end of file +- href: stepperdriver-controlmotor.md +- href: stepperdriver-quickmovement.md \ No newline at end of file diff --git a/workflows/stepperdriver-quickmovement-driverconfiguration.bonsai b/workflows/stepperdriver-quickmovement-driverconfiguration.bonsai new file mode 100644 index 00000000..c2fc90e2 --- /dev/null +++ b/workflows/stepperdriver-quickmovement-driverconfiguration.bonsai @@ -0,0 +1,46 @@ + + + + + + StepperDriver Events + + + + 1 + + + + Write + + DynamicMovements + + + + Write + + Rate100Hz + + + + + + + StepperDriver Commands + + + + + + + + + + + + \ No newline at end of file diff --git a/workflows/stepperdriver-quickmovement-driverconfiguration.svg b/workflows/stepperdriver-quickmovement-driverconfiguration.svg new file mode 100644 index 00000000..02918a8b --- /dev/null +++ b/workflows/stepperdriver-quickmovement-driverconfiguration.svg @@ -0,0 +1,110 @@ + + +]> + + + + + + + + + + + + + + + + StepperDriver + + + Commands + + + + + + + Merge + + + + + + Stepper + + + Driver.Motor1 + + + OperationMod + + + + + + Stepper + + + Driver. + + + AccumulatedSt + + + + + Take + + + + + + + StepperDriver + + + Events + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file From 2d4120ea76b2fbc8ab3089cdac7e4b4e683429cc Mon Sep 17 00:00:00 2001 From: Shawn Tan Date: Thu, 19 Feb 2026 00:21:22 -0800 Subject: [PATCH 18/27] Finish draft of quick movement article --- tutorials/stepperdriver-quickmovement.md | 65 ++++- .../stepperdriver-quickmovement-arming.bonsai | 125 +++++++++ .../stepperdriver-quickmovement-arming.svg | 238 ++++++++++++++++++ ...stepperdriver-quickmovement-trigger.bonsai | 32 +++ .../stepperdriver-quickmovement-trigger.svg | 55 ++++ 5 files changed, 511 insertions(+), 4 deletions(-) create mode 100644 workflows/stepperdriver-quickmovement-arming.bonsai create mode 100644 workflows/stepperdriver-quickmovement-arming.svg create mode 100644 workflows/stepperdriver-quickmovement-trigger.bonsai create mode 100644 workflows/stepperdriver-quickmovement-trigger.svg diff --git a/tutorials/stepperdriver-quickmovement.md b/tutorials/stepperdriver-quickmovement.md index 7791813c..b17f1b88 100644 --- a/tutorials/stepperdriver-quickmovement.md +++ b/tutorials/stepperdriver-quickmovement.md @@ -1,6 +1,6 @@ # QuickMovement -The [Harp StepperDriver](https://github.com/harp-tech/device.stepperdriver) features a `QuickMovement` mode that can be used for extremely fast movements with low trigger latency. +The [Harp StepperDriver](https://github.com/harp-tech/device.stepperdriver) features a special `QuickMovement` mode that can be used for extremely fast movements with low trigger latency. > [!TIP] > [`StepRelative`](./stepperdriver-controlmotor.md#exercise-7-move-continuously) with position limits may be sufficient for some applications requiring fast movements. @@ -13,12 +13,12 @@ The [Harp StepperDriver](https://github.com/harp-tech/device.stepperdriver) feat - Set up the [device pattern](./stepperdriver-configuration.md#device-pattern), [configure](./stepperdriver-configuration.md) the device, and [enable](./stepperdriver-configuration.md#enable-and-disable-motor-drivers) the `Motor1` stepper driver. - Use the [position visualizer](./stepperdriver-controlmotor.md#visualize-position) to visualize the movement. -## Driver Configuration for QuickMovement +## Driver Configuration -`QuickMovement` requires the motor driver to be configured for `DynamicMovements`. It also helps to set a higher sampling rate for the [`AccumulatedSteps`] event for visualization. +`QuickMovement` requires the motor driver to be configured for `DynamicMovements`. Set a higher sampling rate for the [`AccumulatedSteps`] event for visualization. :::workflow -![StepperDriver QuickMovement Driver Configuration](../workflows/stepperdriver-quickmovements-driverconfiguration.bonsai) +![StepperDriver QuickMovement Driver Configuration](../workflows/stepperdriver-quickmovement-driverconfiguration.bonsai) ::: - Insert a [`SubscribeSubject`] operator named `StepperDriver Events`. @@ -34,13 +34,70 @@ The [Harp StepperDriver](https://github.com/harp-tech/device.stepperdriver) feat ## Exercise 1: Arm QuickMovement +`QuickMovement` is not yet supported by the `Harp.StepperDriver` Bonsai interface package. Instead, it can be accessed through the generic [`Bonsai.Harp`](../articles/operators.md) interface. With this interface, values for configuration are converted into [`HarpMessage`] commands by using the [`Format (Harp)`] operator. Values have been precalibrated and are defined in millimeters rather than steps. The `QuickMovement` configuration is preloaded into the `StepperDriver` and armed for quick execution. + +:::workflow +![StepperDriver QuickMovement Arming](../workflows/stepperdriver-quickmovement-arming.bonsai) +::: + +- Insert a [`KeyDown`] source and set the `Filter` property to `7`. + +For each of the following registers: +- Insert a [`Float`] expression on a new branch and set the `Value` property to the specific default value. +- Insert a [`Format (Harp)`] operator and configure the following properties: + - `Format` - Select `Write`. + - `Register` - Select [`FormatMessagePayload`]. + - `Address` - Set the register address. + - `PayloadType` - Set to `Float`. + +| Register Name | Address | Default Values | Description | +| --------------------------------- | ------- | -------------- | ------------- | +| `Motor1QuickMovementPulseDistance` | 131 | 1.25 / 2.5 | Sets the single pulse distance for a quick movement, in millimeters, for the Motor 1. | +| `Motor1QuickMovementNominalSpeed` | 133 | 60 | Sets the target speed for a quick movement, in millimeters per second, for the Motor 1. | +| `Motor1QuickMovementInitialSpeed` | 135 | 2 | Sets the initial speed for a quick movement, in millimeters per second, for the Motor 1. | +| `Motor1QuickMovementAcceleration` | 137 | 2.5 | Sets the acceleration for a quick movement, in millimeters per second^2, for the Motor 1. | +| `Motor1QuickMovementDistance` | 139 | 5 / -5 | Sets the travel distance of a quick movement, in millimeters, for the Motor 1. The sign of the value will determine the direction of movement. | + +> [!TIP] +> The equivalent register addresses for `Motor2` are each offset by +1 (e.g. `Motor2QuickMovementPulseDistance` uses register 132). + +- Insert a [`Merge`] operator to combine all the commands. +- Insert a [`MulticastSubject`] operator named `StepperDriver Commands`. + +Run the workflow and press 7 to arm the `QuickMovement`. + +You can also adjust the properties, and press 7 to change the `QuickMovement` configuration while the workflow is running, which will allow you to test different `QuickMovement` settings. + ## Exercise 2: Trigger QuickMovement +To trigger the `QuickMovement`, use a [`CreateMessage (Harp)`] to access the `TriggerQuickMovement` register. + +:::workflow +![StepperDriver QuickMovement Trigger](../workflows/stepperdriver-quickmovement-trigger.bonsai) +::: + +- Insert a [`KeyDown`] source and set the `Filter` property to `H`. +- Insert a [`CreateMessage (Harp)`] operator and configure the following properties: + - `Format` - Select `Write`. + - `Register` - Select [`CreateMessagePayload`]. + - `Address` - Set the register address to 130. + - `PayloadType` - Set to `U8`. + - `Value` - Set to 2 for `Motor1`, or 4 for `Motor2`. +- Insert a [`MulticastSubject`] operator named `StepperDriver Commands`. + +Run the workflow and press H to trigger the `QuickMovement`. [`AccumulatedSteps`]: xref:Harp.StepperDriver.AccumulatedSteps [`AccumulatedStepsSamplingRatePayload`]: xref:Harp.StepperDriver.CreateAccumulatedStepsSamplingRatePayload [`CreateMessage`]: xref:Harp.StepperDriver.CreateMessage +[`CreateMessage (Harp)`]: xref:Bonsai.Harp.CreateMessage +[`CreateMessagePayload`]: xref:Bonsai.Harp.CreateMessagePayload +[`Float`]: xref:Bonsai.Expressions.FloatProperty +[`Format (Harp)`]: xref:Bonsai.Harp.Format +[`FormatMessagePayload`]: xref:Bonsai.Harp.FormatMessagePayload +[`HarpMessage`]: xref:Bonsai.Harp.HarpMessage +[`KeyDown`]: xref:Bonsai.Windows.Input.KeyDown [`Merge`]: xref:Bonsai.Reactive.Merge [`Motor1OperationModePayload`]: xref:Harp.StepperDriver.CreateMotor1OperationModePayload [`MulticastSubject`]: xref:Bonsai.Expressions.MulticastSubject diff --git a/workflows/stepperdriver-quickmovement-arming.bonsai b/workflows/stepperdriver-quickmovement-arming.bonsai new file mode 100644 index 00000000..cba817c0 --- /dev/null +++ b/workflows/stepperdriver-quickmovement-arming.bonsai @@ -0,0 +1,125 @@ + + + + + + StepperDriver Events + + + + 1 + + + + Motor1QuickPulseDistance + + + + + 1.25 + + + + Write + + 131 + Float + + + + Motor1QuickNominalSpeed + + + + + 60 + + + + Write + + 133 + Float + + + + Motor1QuickInitialSpeed + + + + + 2 + + + + Write + + 135 + Float + + + + Motor1QuickAcceleration + + + + + 2.5 + + + + Write + + 137 + Float + + + + Motor1QuickDistance + + + + + 5 + + + + Write + + 139 + Float + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/workflows/stepperdriver-quickmovement-arming.svg b/workflows/stepperdriver-quickmovement-arming.svg new file mode 100644 index 00000000..afe9b9fc --- /dev/null +++ b/workflows/stepperdriver-quickmovement-arming.svg @@ -0,0 +1,238 @@ + + +]> + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Merge + + + + + Format + + + + + Format + + + + + Format + + + + + Format + + + + + Format + + + + + + + + Float + + + + + + + + Float + + + + + + + + Float + + + + + + + + Float + + + + + + + + Float + + + + + Take + + + + + Motor1Quick + + + PulseDistance + + + + + Motor1Quick + + + Nominal + + + Speed + + + + + Motor1Quick + + + InitialSpeed + + + + + Motor1Quick + + + Acceleration + + + + + Motor1Quick + + + Distance + + + + + + + StepperDriver + + + Events + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/workflows/stepperdriver-quickmovement-trigger.bonsai b/workflows/stepperdriver-quickmovement-trigger.bonsai new file mode 100644 index 00000000..3644d23d --- /dev/null +++ b/workflows/stepperdriver-quickmovement-trigger.bonsai @@ -0,0 +1,32 @@ + + + + + + + H + false + + + + Write + + 130 + U8 + 2 + + + + StepperDriver Commands + + + + + + + + \ No newline at end of file diff --git a/workflows/stepperdriver-quickmovement-trigger.svg b/workflows/stepperdriver-quickmovement-trigger.svg new file mode 100644 index 00000000..bce87a80 --- /dev/null +++ b/workflows/stepperdriver-quickmovement-trigger.svg @@ -0,0 +1,55 @@ + + +]> + + + + + + + + + + + + StepperDriver + + + Commands + + + + + + Create + + + Message + + + + + + + KeyDown + + + + + + + + + + + + + + + + + + + + \ No newline at end of file From 73f22e51461a7c688367e27ec1e88c1261286736 Mon Sep 17 00:00:00 2001 From: Shawn Tan Date: Thu, 19 Feb 2026 01:56:36 -0800 Subject: [PATCH 19/27] Fix quickmovement config bonsai workflow --- tutorials/stepperdriver-configuration.md | 30 +- tutorials/stepperdriver-controlmotor.md | 26 +- tutorials/stepperdriver-quickmovement.md | 20 +- .../stepperdriver-quickmovement-arming.bonsai | 4 + .../stepperdriver-quickmovement-arming.svg | 421 +++++++++--------- 5 files changed, 259 insertions(+), 242 deletions(-) diff --git a/tutorials/stepperdriver-configuration.md b/tutorials/stepperdriver-configuration.md index 2021f1aa..4d020356 100644 --- a/tutorials/stepperdriver-configuration.md +++ b/tutorials/stepperdriver-configuration.md @@ -1,6 +1,6 @@ # Configure Driver -Configuration parameters must be set for the [Harp StepperDriver](https://github.com/harp-tech/device.stepperdriver) before it can be used to drive stepper motors. +Configuration parameters must be set for the [Harp StepperDriver](https://github.com/harp-tech/device.stepperdriver) before it can be used to drive stepper motors. > [!WARNING] > When adding these operators to the workflow, make sure to use the device-specific versions, e.g. `Device (Harp.StepperDriver)` instead of `Device (Harp)`. If correctly selected, the names of these operators in the workflow panel will change to reflect either the name of the device or the selected register/payload. @@ -53,7 +53,7 @@ The microstep resolution determines the size of each step, and directly affects - Insert a [`SubscribeSubject`] operator named `StepperDriver Events`. - Insert a [`Take`] combinator and set the `Count` property to 1. - Insert a [`CreateMessage`] operator and configure these properties: - - `Payload` - Set it to [`Motor1MicrostepResolutionPayload`]. + - `Payload` - Select [`Motor1MicrostepResolutionPayload`]. - `Motor1MicrostepResolution` - Select the desired microstep resolution (e.g. `Microstep8`). - Insert a [`MulticastSubject`] operator named `StepperDriver Commands`. @@ -68,23 +68,23 @@ Other operation parameters to be set include the operation mode of the motor dri - Insert a [`SubscribeSubject`] operator named `StepperDriver Events`. - Insert a [`Take`] combinator and set the `Count` property to 1. - Insert a [`CreateMessage`] operator and configure these properties: - - `Payload` - Set it to [`Motor1OperationModePayload`]. - - `Motor1OperationMode` - Set it to `QuietMode` for regular operation and `DynamicMovements` for quick movements. + - `Payload` - Select [`Motor1OperationModePayload`]. + - `Motor1OperationMode` - Set `QuietMode` for regular operation and `DynamicMovements` for quick movements. - Insert a [`CreateMessage`] operator on another branch, and configure these properties: - - `Payload` - Set it to [`Motor1MaximumRunCurrentPayload`]. - - `Motor1MaximumRunCurrent` - Set it to match the motor's rated phase current in amps (e.g. 1). + - `Payload` - Select [`Motor1MaximumRunCurrentPayload`]. + - `Motor1MaximumRunCurrent` - Set the motor's rated phase current in amps (e.g. 1). - Insert a [`CreateMessage`] operator on another branch, and configure these properties: - - `Payload` - Set it to [`Motor1HoldCurrentReductionPayload`]. - - `Motor1HoldCurrentReduction` - Set it to minimise heat reduction and adjust the holding torque of the motor at rest (e.g. `ReductionTo25Percent` for low holding torque with light external loads). + - `Payload` - Select [`Motor1HoldCurrentReductionPayload`]. + - `Motor1HoldCurrentReduction` - Set to minimise heat generation and adjust the holding torque of the motor at rest (e.g. `ReductionTo25Percent` for low holding torque with light external loads). - Insert a [`Merge`] operator to combine all three commands into one [`HarpMessage`] stream. - Insert a [`MulticastSubject`] operator named `StepperDriver Commands`. > [!TIP] -> The previous configuration commands can also be combined using [`Merge`] and sent into a single `StepperDriver Commands` pipeline. +> All configuration commands can be combined using [`Merge`] and sent into a single `StepperDriver Commands` pipeline. ## Enable and disable motor drivers -Lastly, motor drivers have to be enabled before use, but can be disabled at any time. +Motor drivers have to be enabled before use and can be disabled at any time. :::workflow ![StepperDriver Toggle Motor](../workflows/stepperdriver-configuration-togglemotor.bonsai) @@ -92,19 +92,19 @@ Lastly, motor drivers have to be enabled before use, but can be disabled at any - Insert a [`KeyDown`] source and set the `Filter` property to `1`. - Insert a [`CreateMessage`] operator and configure these properties: - - `Payload` - Set this to [`EnableDriverPayload`]. - - `EnableDriver` - Set this to the motor driver to enable (e.g. `Motor1`). + - `Payload` - Select [`EnableDriverPayload`]. + - `EnableDriver` - Select motor driver to enable (e.g. `Motor1`). - Insert a [`MulticastSubject`] operator named `StepperDriver Commands`. To disable the driver, set up a separate pipeline: - Insert a [`KeyDown`] source and set the `Filter` property to `2`. - Insert a [`CreateMessage`] operator and configure these properties: - - `Payload` - Set this to [`DisableDriverPayload`]. - - `DisableDriver` - Set this to the motor driver to disable (e.g. `Motor1`). + - `Payload` - Select [`DisableDriverPayload`]. + - `DisableDriver` - Select the motor driver to disable (e.g. `Motor1`). - Insert a [`MulticastSubject`] operator named `StepperDriver Commands`. -Run the workflow and press the 1 key to enable the driver and 2 key to disable the driver. When the driver is enabled, the LED above the driver connection on the device will blink red. +Run the workflow and press 1 to enable the driver and 2 to disable the driver. When the driver is enabled, the LED above the driver connection on the device will blink red. > [!TIP] > To target multiple drivers, enter their names, separated by a comma, for the `EnableDriver` and `DisableDriver` properties (e.g. `Motor0`, `Motor1`). diff --git a/tutorials/stepperdriver-controlmotor.md b/tutorials/stepperdriver-controlmotor.md index f2578524..e201ccd7 100644 --- a/tutorials/stepperdriver-controlmotor.md +++ b/tutorials/stepperdriver-controlmotor.md @@ -1,6 +1,6 @@ # Control Motor -The follow exercises will demonstrate how to control motor speed and rotational position with the [Harp StepperDriver](https://github.com/harp-tech/device.stepperdriver). +The follow exercises demonstrate how to control motor speed and rotational position with the [Harp StepperDriver](https://github.com/harp-tech/device.stepperdriver). > [!WARNING] > Ensure that you are familiar with the operation of the `StepperDriver` and motors before connecting external loads. Consider using end-of-travel switches in conjunction with a [digital input](xref:Harp.StepperDriver.CreateEnableDigitalInputsPayload) [configuration](xref:Harp.StepperDriver.CreateInput0OpModePayload). Improper use of the `StepperDriver` and motors may result in damage to equipment. @@ -27,7 +27,7 @@ Enable the [`AccumulatedSteps`] event register and configure the dispatch rate: - `AccumulatedStepsSamplingRate` - Set the desired sampling rate (e.g. `Rate10Hz` for coarse movements). - Insert a [`MulticastSubject`] operator named `StepperDriver Commands`. -Extract the [`AccumulatedSteps`] events and format it for visualizer display: +Extract the [`AccumulatedSteps`] events and format them for display in the visualizer: - Insert a [`SubscribeSubject`] operator named `StepperDriver Events`. - Insert a [`Parse`] operator and set the `Register` property to [`AccumulatedSteps`]. @@ -61,7 +61,7 @@ Motor motion is driven by a series of step pulses, and speed can be controlled b Run the workflow and press 3 to set the acceleration profile. -You can also adjust the properties, and press 3 to update the acceleration profile while the workflow is running. This allows you to test different speeds with the move commands. +While the workflow is running, you can also adjust the properties, and press 3 to update the acceleration profile and test different settings. ## Exercise 2: Move relative steps @@ -87,9 +87,7 @@ To move the motor in the negative direction, set up a separate pipeline: - `Motor1MoveRelative` - Set to a negative value (e.g. -3000). - Insert a [`MulticastSubject`] operator named `StepperDriver Commands`. -Run the workflow and press A to move the motor forward and S to move it back. Observe the accumulated steps in the visualizer to track the motor's position. - -**Optional**: Change the acceleration profile in the previous exercise (e.g. increase the initial and target step interval). Rerun the exercise. What do you observe? +Run the workflow and press A to move the motor forward and S to move it back. Observe the accumulated steps in the visualizer to track the motor's position. > [!TIP] > To move multiple motors simultaneously, use the [`MoveRelativePayload`]. @@ -139,14 +137,14 @@ Set the maximum position limit in a separate pipeline: Run the workflow and press 4 to set the minimum limit and 5 to set the maximum limit. Use the move commands from the previous exercises to verify that the motor stops at each limit. -You can also adjust the properties, and press the 4 and 5 keys to update the position limits while the workflow is running. +While the workflow is running, you can also adjust the properties and press 4 or 5 to update the position limits. > [!TIP] > To set position limits for all motors, use the [`MinPositionPayload`] and [`MaxPositionPayload`]. -## Exercise 6: Stop motors +## Exercise 5: Stop motors -The [`StopMotors`] register immediately halts motors regardless of their current move command and can be used as an emergency stop. +The [`StopMotors`] register immediately halts motors regardless of any current move command and can be used as an emergency stop. :::workflow ![StepperDriver Stop Motors](../workflows/stepperdriver-controlmotor-stopmotors.bonsai) @@ -163,9 +161,9 @@ Run the workflow and use the move commands from the previous exercises to set th > [!TIP] > To target multiple motors, enter their names, separated by a comma, for the `StopMotors` property (e.g. `Motor0`, `Motor1`). -## Exercise 7: Move continuously +## Exercise 6: Move continuously -The [`StepRelative`] register ignores the acceleration profile and moves the motor continuously at a fixed speed determined by the step interval and a direction determined by the sign of the value. +The [`StepRelative`] register ignores the acceleration profile and moves the motor continuously at a fixed speed determined by the step interval and a direction indicated by the sign of the value. > [!WARNING] > Ensure that position limits or the stop command are in place before trying this exercise. @@ -208,10 +206,7 @@ Run the workflow and press 6 to reset the accumulated steps. Observe [`AccumulatedSteps`]: xref:Harp.StepperDriver.AccumulatedSteps [`AccumulatedStepsPayload`]: xref:Harp.StepperDriver.CreateAccumulatedStepsPayload [`AccumulatedStepsSamplingRatePayload`]: xref:Harp.StepperDriver.CreateAccumulatedStepsSamplingRatePayload -[``BehaviourSubject`1``]: xref:Bonsai.Reactive.BehaviorSubject [`CreateMessage`]: xref:Harp.StepperDriver.CreateMessage -[`Device`]: xref:Harp.StepperDriver.Device -[`HarpMessage`]: xref:Bonsai.Harp.HarpMessage [`KeyDown`]: xref:Bonsai.Windows.Input.KeyDown [`Merge`]: xref:Bonsai.Reactive.Merge [`MoveRelative`]: xref:Harp.StepperDriver.MoveRelative @@ -232,9 +227,8 @@ Run the workflow and press 6 to reset the accumulated steps. Observe [`Motor1StepIntervalPayload`]: xref:Harp.StepperDriver.CreateMotor1StepIntervalPayload [`MulticastSubject`]: xref:Bonsai.Expressions.MulticastSubject [`Parse`]: xref:Harp.StepperDriver.Parse -[`PublishSubject`]: xref:Bonsai.Reactive.PublishSubject [`StepRelative`]: xref:Harp.StepperDriver.StepRelative -[`StepRelativePayload`]: xref:Harp.StepperDriver.StepRelativePayload +[`StepRelativePayload`]: xref:Harp.StepperDriver.CreateStepRelativePayload [`SubscribeSubject`]: xref:Bonsai.Expressions.SubscribeSubject [`Take`]: xref:Bonsai.Reactive.Take [`VisualizerWindow`]: xref:Bonsai.Design.VisualizerWindow \ No newline at end of file diff --git a/tutorials/stepperdriver-quickmovement.md b/tutorials/stepperdriver-quickmovement.md index b17f1b88..237be11e 100644 --- a/tutorials/stepperdriver-quickmovement.md +++ b/tutorials/stepperdriver-quickmovement.md @@ -3,7 +3,7 @@ The [Harp StepperDriver](https://github.com/harp-tech/device.stepperdriver) features a special `QuickMovement` mode that can be used for extremely fast movements with low trigger latency. > [!TIP] -> [`StepRelative`](./stepperdriver-controlmotor.md#exercise-7-move-continuously) with position limits may be sufficient for some applications requiring fast movements. +> For some applications, [`StepRelative`](./stepperdriver-controlmotor.md#exercise-7-move-continuously) with position limits configured may be sufficient requiring fast movements. ## Prerequisites @@ -34,7 +34,9 @@ The [Harp StepperDriver](https://github.com/harp-tech/device.stepperdriver) feat ## Exercise 1: Arm QuickMovement -`QuickMovement` is not yet supported by the `Harp.StepperDriver` Bonsai interface package. Instead, it can be accessed through the generic [`Bonsai.Harp`](../articles/operators.md) interface. With this interface, values for configuration are converted into [`HarpMessage`] commands by using the [`Format (Harp)`] operator. Values have been precalibrated and are defined in millimeters rather than steps. The `QuickMovement` configuration is preloaded into the `StepperDriver` and armed for quick execution. +`QuickMovement` is not yet supported by the `Harp.StepperDriver` Bonsai interface package. Instead, it can be accessed through the generic [`Bonsai.Harp`](../articles/operators.md) interface. + +With this interface, values for configuration are converted into [`HarpMessage`] commands using the [`Format (Harp)`] operator. Values have been precalibrated and are set in millimeters rather than steps. The configuration is subsequently preloaded into the `StepperDriver` to arm the `QuickMovement` for rapid execution. :::workflow ![StepperDriver QuickMovement Arming](../workflows/stepperdriver-quickmovement-arming.bonsai) @@ -43,7 +45,7 @@ The [Harp StepperDriver](https://github.com/harp-tech/device.stepperdriver) feat - Insert a [`KeyDown`] source and set the `Filter` property to `7`. For each of the following registers: -- Insert a [`Float`] expression on a new branch and set the `Value` property to the specific default value. +- Insert a [`Float`] expression on a new branch and set the `Value` property to the default value from the table below. - Insert a [`Format (Harp)`] operator and configure the following properties: - `Format` - Select `Write`. - `Register` - Select [`FormatMessagePayload`]. @@ -52,11 +54,11 @@ For each of the following registers: | Register Name | Address | Default Values | Description | | --------------------------------- | ------- | -------------- | ------------- | -| `Motor1QuickMovementPulseDistance` | 131 | 1.25 / 2.5 | Sets the single pulse distance for a quick movement, in millimeters, for the Motor 1. | -| `Motor1QuickMovementNominalSpeed` | 133 | 60 | Sets the target speed for a quick movement, in millimeters per second, for the Motor 1. | -| `Motor1QuickMovementInitialSpeed` | 135 | 2 | Sets the initial speed for a quick movement, in millimeters per second, for the Motor 1. | -| `Motor1QuickMovementAcceleration` | 137 | 2.5 | Sets the acceleration for a quick movement, in millimeters per second^2, for the Motor 1. | -| `Motor1QuickMovementDistance` | 139 | 5 / -5 | Sets the travel distance of a quick movement, in millimeters, for the Motor 1. The sign of the value will determine the direction of movement. | +| `Motor1QuickMovementPulseDistance` | 131 | 1.25 / 2.5 | Sets the single pulse distance for a quick movement, in millimeters, for Motor 1. | +| `Motor1QuickMovementNominalSpeed` | 133 | 60 | Sets the target speed for a quick movement, in millimeters per second, for Motor 1. | +| `Motor1QuickMovementInitialSpeed` | 135 | 2 | Sets the initial speed for a quick movement, in millimeters per second, for Motor 1. | +| `Motor1QuickMovementAcceleration` | 137 | 2.5 | Sets the acceleration for a quick movement, in millimeters per second^2, for Motor 1. | +| `Motor1QuickMovementDistance` | 139 | 5 / -5 | Sets the travel distance of a quick movement, in millimeters, for Motor 1. The sign determines the direction of movement. | > [!TIP] > The equivalent register addresses for `Motor2` are each offset by +1 (e.g. `Motor2QuickMovementPulseDistance` uses register 132). @@ -66,7 +68,7 @@ For each of the following registers: Run the workflow and press 7 to arm the `QuickMovement`. -You can also adjust the properties, and press 7 to change the `QuickMovement` configuration while the workflow is running, which will allow you to test different `QuickMovement` settings. +While the workflow is running, you can adjust the properties, and press 7 to update the `QuickMovement` configuration and test different settings. ## Exercise 2: Trigger QuickMovement diff --git a/workflows/stepperdriver-quickmovement-arming.bonsai b/workflows/stepperdriver-quickmovement-arming.bonsai index cba817c0..066693a8 100644 --- a/workflows/stepperdriver-quickmovement-arming.bonsai +++ b/workflows/stepperdriver-quickmovement-arming.bonsai @@ -97,6 +97,9 @@ + + StepperDriver Commands + @@ -120,6 +123,7 @@ + \ No newline at end of file diff --git a/workflows/stepperdriver-quickmovement-arming.svg b/workflows/stepperdriver-quickmovement-arming.svg index afe9b9fc..b2a75f9b 100644 --- a/workflows/stepperdriver-quickmovement-arming.svg +++ b/workflows/stepperdriver-quickmovement-arming.svg @@ -1,238 +1,255 @@ + ]> - + - - - - - - - - - - - - - - - - - - - - - - - - - - - Merge - - - - - Format - - - - - Format - - - - - Format - - - - - Format - - - - - Format - - - - - - - - Float - - - - - - - - Float - - - - - - - - Float - - - - - - - - Float - - - - - - - - Float - - - - - Take - - - - - Motor1Quick - - - PulseDistance - - - - - Motor1Quick - - - Nominal - - - Speed - - - - - Motor1Quick - - - InitialSpeed - - - - - Motor1Quick - - - Acceleration - - - - - Motor1Quick - - - Distance - - - - - - - StepperDriver - - - Events + + + + + + + + + + + + + + + + + + + + + + + + + + + + StepperDriver + + + Commands + + + + + + + Merge + + + + + Format + + + + + Format + + + + + Format + + + + + Format + + + + + Format + + + + + + + + Float + + + + + + + + Float + + + + + + + + Float + + + + + + + + Float + + + + + + + + Float + + + + + Take + + + + + Motor1Quick + + + PulseDistance + + + + + Motor1Quick + + + Nominal + + + Speed + + + + + Motor1Quick + + + InitialSpeed + + + + + Motor1Quick + + + Acceleration + + + + + Motor1Quick + + + Distance + + + + + + + StepperDriver + + + Events - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + + + + + + + \ No newline at end of file From a4866a1f363268a03ccf26996f104c0e66427762 Mon Sep 17 00:00:00 2001 From: Shawn Tan Date: Thu, 19 Feb 2026 08:28:12 -0800 Subject: [PATCH 20/27] Minor grammar edit --- tutorials/stepperdriver-quickmovement.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tutorials/stepperdriver-quickmovement.md b/tutorials/stepperdriver-quickmovement.md index 237be11e..9fee8f6d 100644 --- a/tutorials/stepperdriver-quickmovement.md +++ b/tutorials/stepperdriver-quickmovement.md @@ -3,7 +3,7 @@ The [Harp StepperDriver](https://github.com/harp-tech/device.stepperdriver) features a special `QuickMovement` mode that can be used for extremely fast movements with low trigger latency. > [!TIP] -> For some applications, [`StepRelative`](./stepperdriver-controlmotor.md#exercise-7-move-continuously) with position limits configured may be sufficient requiring fast movements. +> For some applications requiring fast movements, [`StepRelative`](./stepperdriver-controlmotor.md#exercise-7-move-continuously) with position limits configured may be sufficient. ## Prerequisites From 80a792002142b025bca2ac16c58e78467dc5043b Mon Sep 17 00:00:00 2001 From: Shawn Tan Date: Mon, 23 Feb 2026 16:43:27 -0800 Subject: [PATCH 21/27] Remove FTDI, add version info, fix broken link --- tutorials/stepperdriver-quickmovement.md | 2 +- tutorials/stepperdriver-setup.md | 12 ++++++++++-- 2 files changed, 11 insertions(+), 3 deletions(-) diff --git a/tutorials/stepperdriver-quickmovement.md b/tutorials/stepperdriver-quickmovement.md index 9fee8f6d..8cbb04db 100644 --- a/tutorials/stepperdriver-quickmovement.md +++ b/tutorials/stepperdriver-quickmovement.md @@ -3,7 +3,7 @@ The [Harp StepperDriver](https://github.com/harp-tech/device.stepperdriver) features a special `QuickMovement` mode that can be used for extremely fast movements with low trigger latency. > [!TIP] -> For some applications requiring fast movements, [`StepRelative`](./stepperdriver-controlmotor.md#exercise-7-move-continuously) with position limits configured may be sufficient. +> For some applications requiring fast movements, [`StepRelative`](./stepperdriver-controlmotor.md#exercise-6-move-continuously) with position limits configured may be sufficient. ## Prerequisites diff --git a/tutorials/stepperdriver-setup.md b/tutorials/stepperdriver-setup.md index 912d6da9..b9776db6 100644 --- a/tutorials/stepperdriver-setup.md +++ b/tutorials/stepperdriver-setup.md @@ -4,7 +4,6 @@ The [Harp StepperDriver](https://github.com/harp-tech/device.stepperdriver) is a ## Installation -- Install the [FTDI D2XX driver](https://ftdichip.com/drivers/d2xx-drivers/) - Install [Bonsai](https://bonsai-rx.org/docs/articles/installation.html). - Install the `Harp.StepperDriver` package by searching for it in the [Bonsai package manager](https://bonsai-rx.org/docs/articles/packages.html). If the package does not appear in the search results, enable the "Show advanced" option. @@ -14,4 +13,13 @@ The [Harp StepperDriver](https://github.com/harp-tech/device.stepperdriver) is a **Power Supply** - The `StepperDriver` requires an external power supply that matches your motor configuration: - **Voltage** - Select a supply matching the recommended driving voltage listed in the motor datasheet (15-35 V). For high-speed and high-torque applications, supply at least 10 V above the minimum driving voltage, and mount the `StepperDriver` on a metal surface to dissipate heat. -- **Current** - Provide at least double the motor's rated phase current, multiplied by the number of motors (e.g. 8 A for two 2 A motors). \ No newline at end of file +- **Current** - Provide at least double the motor's rated phase current, multiplied by the number of motors (e.g. 8 A for two 2 A motors). + +
+ +--- + +These tutorials were written and tested with:
+**Hardware** v1.0
+**Firmware** v0.7
+**Harp.StepperDriver** v0.4 \ No newline at end of file From 14079f22622ed7da1f3e604e6befdfbb19e7f809 Mon Sep 17 00:00:00 2001 From: Shawn Tan Date: Mon, 23 Feb 2026 17:01:39 -0800 Subject: [PATCH 22/27] Update stepperdriver submodule for API docs --- src/device.stepperdriver | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/device.stepperdriver b/src/device.stepperdriver index 1b796cc5..4ac77dd2 160000 --- a/src/device.stepperdriver +++ b/src/device.stepperdriver @@ -1 +1 @@ -Subproject commit 1b796cc5004e6c2f8c7f39e14e22d9b51ce7400d +Subproject commit 4ac77dd27b6c1e2ef60f9ebf8d3fc71a6534f99d From 6ee64d38e545be4c33f78b27c5f06579bbce389b Mon Sep 17 00:00:00 2001 From: Shawn Tan Date: Tue, 24 Feb 2026 00:37:17 -0800 Subject: [PATCH 23/27] Update quickmovement article to use latest bonsai interface --- tutorials/stepperdriver-quickmovement.md | 99 ++--- .../stepperdriver-quickmovement-arming.bonsai | 129 ++----- .../stepperdriver-quickmovement-arming.svg | 342 ++++++------------ ...perdriver-quickmovement-calibration.bonsai | 34 ++ ...tepperdriver-quickmovement-calibration.svg | 76 ++++ ...perdriver-quickmovement-triggering.bonsai} | 9 +- ...tepperdriver-quickmovement-triggering.svg} | 34 +- 7 files changed, 330 insertions(+), 393 deletions(-) create mode 100644 workflows/stepperdriver-quickmovement-calibration.bonsai create mode 100644 workflows/stepperdriver-quickmovement-calibration.svg rename workflows/{stepperdriver-quickmovement-trigger.bonsai => stepperdriver-quickmovement-triggering.bonsai} (78%) rename workflows/{stepperdriver-quickmovement-trigger.svg => stepperdriver-quickmovement-triggering.svg} (81%) diff --git a/tutorials/stepperdriver-quickmovement.md b/tutorials/stepperdriver-quickmovement.md index 8cbb04db..3bae2597 100644 --- a/tutorials/stepperdriver-quickmovement.md +++ b/tutorials/stepperdriver-quickmovement.md @@ -1,21 +1,21 @@ # QuickMovement -The [Harp StepperDriver](https://github.com/harp-tech/device.stepperdriver) features a special `QuickMovement` mode that can be used for extremely fast movements with low trigger latency. +The [Harp StepperDriver](https://github.com/harp-tech/device.stepperdriver) features a special `QuickMovement` mode that can be used for extremely fast movements with low trigger latency. It requires calibration and preloading of speed and distance parameters. > [!TIP] > For some applications requiring fast movements, [`StepRelative`](./stepperdriver-controlmotor.md#exercise-6-move-continuously) with position limits configured may be sufficient. ## Prerequisites -- Install the `Bonsai.Windows.Input` package from the Bonsai [package manager](https://bonsai-rx.org/docs/articles/packages.html). - `QuickMovement` requires firmware `fw0.7-harp1.14` and later. Download the firmware from the [release](https://github.com/harp-tech/device.stepperdriver/releases) page and update it with the [Harp Toolkit](https://github.com/harp-tech/toolkit). -- Connect a stepper motor (`Motor1`) to `Stepper 1` output for these exercises. `QuickMovement` is only supported on `Stepper 1` and `Stepper 2` drivers. +- `QuickMovement` is only supported on `Stepper 1` and `Stepper 2` drivers. Connect a stepper motor (`Motor1`) to `Stepper 1` output for these exercises. +- Install the `Bonsai.Windows.Input` package from the Bonsai [package manager](https://bonsai-rx.org/docs/articles/packages.html). - Set up the [device pattern](./stepperdriver-configuration.md#device-pattern), [configure](./stepperdriver-configuration.md) the device, and [enable](./stepperdriver-configuration.md#enable-and-disable-motor-drivers) the `Motor1` stepper driver. -- Use the [position visualizer](./stepperdriver-controlmotor.md#visualize-position) to visualize the movement. +- Use the [position visualizer](./stepperdriver-controlmotor.md#visualize-position) to monitor the movement. -## Driver Configuration +## Configure Driver -`QuickMovement` requires the motor driver to be configured for `DynamicMovements`. Set a higher sampling rate for the [`AccumulatedSteps`] event for visualization. +Configure the motor driver operation mode for `QuickMovement` and set a higher sampling rate for the [`AccumulatedSteps`] event for visualization. :::workflow ![StepperDriver QuickMovement Driver Configuration](../workflows/stepperdriver-quickmovement-driverconfiguration.bonsai) @@ -32,59 +32,64 @@ The [Harp StepperDriver](https://github.com/harp-tech/device.stepperdriver) feat - Combine the two messages with a [`Merge`] combinator. - Insert a [`MulticastSubject`] operator named `StepperDriver Commands`. -## Exercise 1: Arm QuickMovement +## Exercise 1: Calibrate QuickMovement + +:::workflow +![StepperDriver QuickMovement Calibration](../workflows/stepperdriver-quickmovement-calibration.bonsai) +::: + +Calibrate `QuickMovement` before use. Subsequent commands will use millimeters (mm) or millimeters per second (mm/s) for values instead of steps or step intervals. + +- Insert a [`SubscribeSubject`] operator named `StepperDriver Events`. +- Insert a [`Take`] combinator and set the `Count` property to 1. +- Insert a [`CreateMessage`] operator and configure these properties: + - `Payload` - Select [`Motor1QuickMovementPulseDistancePayload`]. + - `Motor1QuickMovementPulseDistance` - Set the calibrated measurement for a single step pulse, in mm (e.g. 2.5). +- Insert a [`MulticastSubject`] operator named `StepperDriver Commands`. + +> [!WARNING] +> Recalibrate `QuickMovement` if you change [`Motor1MicrostepResolution`], as it determines the size of each step. -`QuickMovement` is not yet supported by the `Harp.StepperDriver` Bonsai interface package. Instead, it can be accessed through the generic [`Bonsai.Harp`](../articles/operators.md) interface. +## Exercise 2: Arm QuickMovement -With this interface, values for configuration are converted into [`HarpMessage`] commands using the [`Format (Harp)`] operator. Values have been precalibrated and are set in millimeters rather than steps. The configuration is subsequently preloaded into the `StepperDriver` to arm the `QuickMovement` for rapid execution. +Preload speed and distance parameters to arm the `QuickMovement` for rapid execution. :::workflow ![StepperDriver QuickMovement Arming](../workflows/stepperdriver-quickmovement-arming.bonsai) ::: - Insert a [`KeyDown`] source and set the `Filter` property to `7`. - -For each of the following registers: -- Insert a [`Float`] expression on a new branch and set the `Value` property to the default value from the table below. -- Insert a [`Format (Harp)`] operator and configure the following properties: - - `Format` - Select `Write`. - - `Register` - Select [`FormatMessagePayload`]. - - `Address` - Set the register address. - - `PayloadType` - Set to `Float`. - -| Register Name | Address | Default Values | Description | -| --------------------------------- | ------- | -------------- | ------------- | -| `Motor1QuickMovementPulseDistance` | 131 | 1.25 / 2.5 | Sets the single pulse distance for a quick movement, in millimeters, for Motor 1. | -| `Motor1QuickMovementNominalSpeed` | 133 | 60 | Sets the target speed for a quick movement, in millimeters per second, for Motor 1. | -| `Motor1QuickMovementInitialSpeed` | 135 | 2 | Sets the initial speed for a quick movement, in millimeters per second, for Motor 1. | -| `Motor1QuickMovementAcceleration` | 137 | 2.5 | Sets the acceleration for a quick movement, in millimeters per second^2, for Motor 1. | -| `Motor1QuickMovementDistance` | 139 | 5 / -5 | Sets the travel distance of a quick movement, in millimeters, for Motor 1. The sign determines the direction of movement. | - -> [!TIP] -> The equivalent register addresses for `Motor2` are each offset by +1 (e.g. `Motor2QuickMovementPulseDistance` uses register 132). - +- Insert a [`CreateMessage`] operator on a separate branch and configure these properties: + - `Payload` - Select [`Motor1QuickMovementInitialSpeedPayload`]. + - `Motor1QuickMovementInitialSpeed` - Set the initial speed in mm/s (e.g. 2). +- Insert a [`CreateMessage`] operator on a separate branch and configure these properties: + - `Payload` - Select [`Motor1QuickMovementNominalSpeedPayload`]. + - `Motor1QuickMovementNominalSpeed` - Set the target speed in mm/s (e.g. 60). +- Insert a [`CreateMessage`] operator on a separate branch and configure these properties: + - `Payload` - Select [`Motor1QuickMovementAccelerationPayload`]. + - `Motor1QuickMovementAcceleration` - Set the acceleration in mm/s² (e.g. 2.5). +- Insert a [`CreateMessage`] operator on a separate branch and configure these properties: + - `Payload` - Select [`Motor1QuickMovementDistancePayload`]. + - `Motor1QuickMovementDistance` - Set the travel distance in mm (e.g. 5 or -5, where the sign determines direction). - Insert a [`Merge`] operator to combine all the commands. - Insert a [`MulticastSubject`] operator named `StepperDriver Commands`. Run the workflow and press 7 to arm the `QuickMovement`. -While the workflow is running, you can adjust the properties, and press 7 to update the `QuickMovement` configuration and test different settings. +While the workflow is running, you can adjust the properties and press 7 to update the `QuickMovement` configuration to test different settings. -## Exercise 2: Trigger QuickMovement +## Exercise 3: Trigger QuickMovement -To trigger the `QuickMovement`, use a [`CreateMessage (Harp)`] to access the `TriggerQuickMovement` register. +Trigger `QuickMovement` with a single command. :::workflow -![StepperDriver QuickMovement Trigger](../workflows/stepperdriver-quickmovement-trigger.bonsai) +![StepperDriver QuickMovement Trigger](../workflows/stepperdriver-quickmovement-triggering.bonsai) ::: - Insert a [`KeyDown`] source and set the `Filter` property to `H`. -- Insert a [`CreateMessage (Harp)`] operator and configure the following properties: - - `Format` - Select `Write`. - - `Register` - Select [`CreateMessagePayload`]. - - `Address` - Set the register address to 130. - - `PayloadType` - Set to `U8`. - - `Value` - Set to 2 for `Motor1`, or 4 for `Motor2`. +- Insert a [`CreateMessage`] operator and configure the following properties: + - `Payload` - Select [`TriggerQuickMovementPayload`]. + - `TriggerQuickMovement` - Select `Motor1`. - Insert a [`MulticastSubject`] operator named `StepperDriver Commands`. Run the workflow and press H to trigger the `QuickMovement`. @@ -93,16 +98,16 @@ Run the workflow and press H to trigger the `QuickMovement`. [`AccumulatedSteps`]: xref:Harp.StepperDriver.AccumulatedSteps [`AccumulatedStepsSamplingRatePayload`]: xref:Harp.StepperDriver.CreateAccumulatedStepsSamplingRatePayload [`CreateMessage`]: xref:Harp.StepperDriver.CreateMessage -[`CreateMessage (Harp)`]: xref:Bonsai.Harp.CreateMessage -[`CreateMessagePayload`]: xref:Bonsai.Harp.CreateMessagePayload -[`Float`]: xref:Bonsai.Expressions.FloatProperty -[`Format (Harp)`]: xref:Bonsai.Harp.Format -[`FormatMessagePayload`]: xref:Bonsai.Harp.FormatMessagePayload -[`HarpMessage`]: xref:Bonsai.Harp.HarpMessage [`KeyDown`]: xref:Bonsai.Windows.Input.KeyDown [`Merge`]: xref:Bonsai.Reactive.Merge +[`Motor1QuickMovementAccelerationPayload`]: xref:Harp.StepperDriver.CreateMotor1QuickMovementAccelerationPayload +[`Motor1QuickMovementInitialSpeedPayload`]: xref:Harp.StepperDriver.CreateMotor1QuickMovementInitialSpeedPayload +[`Motor1QuickMovementDistancePayload`]: xref:Harp.StepperDriver.CreateMotor1QuickMovementDistancePayload +[`Motor1QuickMovementPulseDistancePayload`]: xref:Harp.StepperDriver.CreateMotor1QuickMovementPulseDistancePayload +[`Motor1QuickMovementNominalSpeedPayload`]: xref:Harp.StepperDriver.CreateMotor1QuickMovementNominalSpeedPayload [`Motor1OperationModePayload`]: xref:Harp.StepperDriver.CreateMotor1OperationModePayload +[`Motor1MicrostepResolution`]: xref:Harp.StepperDriver.Motor1MicrostepResolution [`MulticastSubject`]: xref:Bonsai.Expressions.MulticastSubject -[`StepRelative`]: xref:Harp.StepperDriver.StepRelative [`SubscribeSubject`]: xref:Bonsai.Expressions.SubscribeSubject -[`Take`]: xref:Bonsai.Reactive.Take \ No newline at end of file +[`Take`]: xref:Bonsai.Reactive.Take +[`TriggerQuickMovementPayload`]: xref:Harp.StepperDriver.CreateTriggerQuickMovementPayload \ No newline at end of file diff --git a/workflows/stepperdriver-quickmovement-arming.bonsai b/workflows/stepperdriver-quickmovement-arming.bonsai index 066693a8..df702881 100644 --- a/workflows/stepperdriver-quickmovement-arming.bonsai +++ b/workflows/stepperdriver-quickmovement-arming.bonsai @@ -1,98 +1,42 @@  - - StepperDriver Events - - - - 1 - - - - Motor1QuickPulseDistance - - - - 1.25 + + D7 + false - + Write - - 131 - Float - + + 2 + - - Motor1QuickNominalSpeed - - - - - 60 - - - + Write - - 133 - Float - - - - Motor1QuickInitialSpeed - + + 60 + - - - 2 - - - - Write - - 135 - Float - - - - Motor1QuickAcceleration - - - - - 2.5 - - - + Write - - 137 - Float - - - - Motor1QuickDistance - - - - - 5 - + + 2.5 + - + Write - - 139 - Float - + + 5 + @@ -103,27 +47,14 @@ - - - - - - - - - - - - - - - - - - - - - + + + + + + + + \ No newline at end of file diff --git a/workflows/stepperdriver-quickmovement-arming.svg b/workflows/stepperdriver-quickmovement-arming.svg index b2a75f9b..c9d9dce0 100644 --- a/workflows/stepperdriver-quickmovement-arming.svg +++ b/workflows/stepperdriver-quickmovement-arming.svg @@ -1,255 +1,141 @@ + ]> - + - - - - - - - - - - - - - - - - - - - - - - - - - - - - StepperDriver - - - Commands - - - - - - - Merge - - - - - Format - - - - - Format - - - - - Format - - - - - Format - - - - - Format - - - - - - - - Float - - - - - - - - Float - - - - - - - - Float - - - - - - - - Float - - - - - - - - Float - - - - - Take - - - - - Motor1Quick - - - PulseDistance - - - - - Motor1Quick - - - Nominal - - - Speed - - - - - Motor1Quick - - - InitialSpeed - - - - - Motor1Quick - - - Acceleration - - - - - Motor1Quick - - - Distance - - - - - - - StepperDriver - - - Events + + + + + + + + + + + + + + + StepperDriver + + + Commands + + + + + + + Merge + + + + + + Stepper + + + Driver.Motor1 + + + QuickMoveme + + + + + + Stepper + + + Driver.Motor1 + + + QuickMoveme + + + + + + Stepper + + + Driver.Motor1 + + + QuickMoveme + + + + + + Stepper + + + Driver.Motor1 + + + QuickMoveme + + + + + + + KeyDown - - + + - - + + - - + + - - + + - - + + - - - - - - - - - - - - - - - - - - - - + + - - + + - - - - - - - - - - - - - - - - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + \ No newline at end of file diff --git a/workflows/stepperdriver-quickmovement-calibration.bonsai b/workflows/stepperdriver-quickmovement-calibration.bonsai new file mode 100644 index 00000000..1c6cafa5 --- /dev/null +++ b/workflows/stepperdriver-quickmovement-calibration.bonsai @@ -0,0 +1,34 @@ + + + + + + StepperDriver Events + + + + 1 + + + + Write + + 2.5 + + + + StepperDriver Commands + + + + + + + + + \ No newline at end of file diff --git a/workflows/stepperdriver-quickmovement-calibration.svg b/workflows/stepperdriver-quickmovement-calibration.svg new file mode 100644 index 00000000..41443d1f --- /dev/null +++ b/workflows/stepperdriver-quickmovement-calibration.svg @@ -0,0 +1,76 @@ + + +]> + + + + + + + + + + + + + StepperDriver + + + Commands + + + + + + Stepper + + + Driver.Motor1 + + + QuickMoveme + + + + + Take + + + + + + + StepperDriver + + + Events + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/workflows/stepperdriver-quickmovement-trigger.bonsai b/workflows/stepperdriver-quickmovement-triggering.bonsai similarity index 78% rename from workflows/stepperdriver-quickmovement-trigger.bonsai rename to workflows/stepperdriver-quickmovement-triggering.bonsai index 3644d23d..ddf28175 100644 --- a/workflows/stepperdriver-quickmovement-trigger.bonsai +++ b/workflows/stepperdriver-quickmovement-triggering.bonsai @@ -2,6 +2,7 @@ @@ -12,12 +13,10 @@ false - + Write - - 130 - U8 - 2 + + Motor1 diff --git a/workflows/stepperdriver-quickmovement-trigger.svg b/workflows/stepperdriver-quickmovement-triggering.svg similarity index 81% rename from workflows/stepperdriver-quickmovement-trigger.svg rename to workflows/stepperdriver-quickmovement-triggering.svg index bce87a80..fb5f1457 100644 --- a/workflows/stepperdriver-quickmovement-trigger.svg +++ b/workflows/stepperdriver-quickmovement-triggering.svg @@ -1,8 +1,8 @@ + ]> - + @@ -22,17 +22,20 @@ - Create + Stepper - Message + Driver.Trigger - - - - - - KeyDown + + QuickMoveme + + + + + + + KeyDown @@ -43,13 +46,16 @@ - + - + + + + - - + + \ No newline at end of file From adaa439e4e0bb52e22bbe3c5125fafb8a095e0a7 Mon Sep 17 00:00:00 2001 From: Shawn Tan Date: Tue, 24 Feb 2026 23:28:09 -0800 Subject: [PATCH 24/27] Expand calibration section, use new values from testing --- tutorials/stepperdriver-quickmovement.md | 36 ++++- .../stepperdriver-quickmovement-arming.bonsai | 6 +- ...perdriver-quickmovement-calibration.bonsai | 24 ++- ...tepperdriver-quickmovement-calibration.svg | 145 ++++++++++++------ 4 files changed, 149 insertions(+), 62 deletions(-) diff --git a/tutorials/stepperdriver-quickmovement.md b/tutorials/stepperdriver-quickmovement.md index 3bae2597..b514b4a9 100644 --- a/tutorials/stepperdriver-quickmovement.md +++ b/tutorials/stepperdriver-quickmovement.md @@ -1,10 +1,13 @@ # QuickMovement -The [Harp StepperDriver](https://github.com/harp-tech/device.stepperdriver) features a special `QuickMovement` mode that can be used for extremely fast movements with low trigger latency. It requires calibration and preloading of speed and distance parameters. +The [Harp StepperDriver](https://github.com/harp-tech/device.stepperdriver) features a special `QuickMovement` mode that can be used for extremely fast movements with low trigger latency. It requires calibration and preloading of speed, acceleration and distance parameters. > [!TIP] > For some applications requiring fast movements, [`StepRelative`](./stepperdriver-controlmotor.md#exercise-6-move-continuously) with position limits configured may be sufficient. +> [!WARNING] +> Ensure that you are familiar with the operation of the `StepperDriver` and motors before connecting external loads. Consider using end-of-travel switches in conjunction with a [digital input](xref:Harp.StepperDriver.CreateEnableDigitalInputsPayload) [configuration](xref:Harp.StepperDriver.CreateInput0OpModePayload). Improper use of the `StepperDriver` and motors may result in damage to equipment, especially with `QuickMovement`. + ## Prerequisites - `QuickMovement` requires firmware `fw0.7-harp1.14` and later. Download the firmware from the [release](https://github.com/harp-tech/device.stepperdriver/releases) page and update it with the [Harp Toolkit](https://github.com/harp-tech/toolkit). @@ -34,17 +37,27 @@ Configure the motor driver operation mode for `QuickMovement` and set a higher s ## Exercise 1: Calibrate QuickMovement +Calibrate `QuickMovement` before use by measuring the distance an external load travels per step pulse in micrometers (μm). + :::workflow ![StepperDriver QuickMovement Calibration](../workflows/stepperdriver-quickmovement-calibration.bonsai) ::: -Calibrate `QuickMovement` before use. Subsequent commands will use millimeters (mm) or millimeters per second (mm/s) for values instead of steps or step intervals. +Connect the external load to the stepper motor, and move the motor a set number of steps. Make sure the path is clear or set [position limits](./stepperdriver-controlmotor.md#exercise-4-set-position-limits). + +- Insert a [`KeyDown`] source and set the `Filter` property to `A`. +- Insert a [`CreateMessage`] operator and configure these properties: + - `Payload` - Select [`Motor1MoveRelativePayload`]. + - `Motor1MoveRelative` - Set the number of steps to move (e.g. 100). +- Insert a [`MulticastSubject`] operator named `StepperDriver Commands`. + +Run the workflow and press A to move the external load. Measure the distance travelled and divide by the number of steps to get the distance per step pulse. - Insert a [`SubscribeSubject`] operator named `StepperDriver Events`. - Insert a [`Take`] combinator and set the `Count` property to 1. - Insert a [`CreateMessage`] operator and configure these properties: - `Payload` - Select [`Motor1QuickMovementPulseDistancePayload`]. - - `Motor1QuickMovementPulseDistance` - Set the calibrated measurement for a single step pulse, in mm (e.g. 2.5). + - `Motor1QuickMovementPulseDistance` - Set the calibrated step pulse distance, in μm (e.g. 100). - Insert a [`MulticastSubject`] operator named `StepperDriver Commands`. > [!WARNING] @@ -52,7 +65,10 @@ Calibrate `QuickMovement` before use. Subsequent commands will use millimeters ( ## Exercise 2: Arm QuickMovement -Preload speed and distance parameters to arm the `QuickMovement` for rapid execution. +Preload movement parameters to arm the `QuickMovement` for rapid execution. Instead of steps or step intervals, movement parameters will use SI units: +- millimeters (mm) for distance. +- millimeters per second (mm/s) for speed. +- meters per second squared (m/s²) for acceleration. :::workflow ![StepperDriver QuickMovement Arming](../workflows/stepperdriver-quickmovement-arming.bonsai) @@ -64,17 +80,20 @@ Preload speed and distance parameters to arm the `QuickMovement` for rapid execu - `Motor1QuickMovementInitialSpeed` - Set the initial speed in mm/s (e.g. 2). - Insert a [`CreateMessage`] operator on a separate branch and configure these properties: - `Payload` - Select [`Motor1QuickMovementNominalSpeedPayload`]. - - `Motor1QuickMovementNominalSpeed` - Set the target speed in mm/s (e.g. 60). + - `Motor1QuickMovementNominalSpeed` - Set the target speed in mm/s (e.g. 200). - Insert a [`CreateMessage`] operator on a separate branch and configure these properties: - `Payload` - Select [`Motor1QuickMovementAccelerationPayload`]. - - `Motor1QuickMovementAcceleration` - Set the acceleration in mm/s² (e.g. 2.5). + - `Motor1QuickMovementAcceleration` - Set the acceleration in m/s² (e.g. 5). - Insert a [`CreateMessage`] operator on a separate branch and configure these properties: - `Payload` - Select [`Motor1QuickMovementDistancePayload`]. - - `Motor1QuickMovementDistance` - Set the travel distance in mm (e.g. 5 or -5, where the sign determines direction). + - `Motor1QuickMovementDistance` - Set the travel distance in mm (e.g. 20 or -20, where the sign determines direction). - Insert a [`Merge`] operator to combine all the commands. - Insert a [`MulticastSubject`] operator named `StepperDriver Commands`. -Run the workflow and press 7 to arm the `QuickMovement`. +> [!TIP] +> The example values given above will move an external load 20 mm in ~ 100 ms (based on target speed). + +Run the workflow and press 7 to arm the `QuickMovement`. While the workflow is running, you can adjust the properties and press 7 to update the `QuickMovement` configuration to test different settings. @@ -100,6 +119,7 @@ Run the workflow and press H to trigger the `QuickMovement`. [`CreateMessage`]: xref:Harp.StepperDriver.CreateMessage [`KeyDown`]: xref:Bonsai.Windows.Input.KeyDown [`Merge`]: xref:Bonsai.Reactive.Merge +[`Motor1MoveRelativePayload`]: xref:Harp.StepperDriver.CreateMotor1MoveRelativePayload [`Motor1QuickMovementAccelerationPayload`]: xref:Harp.StepperDriver.CreateMotor1QuickMovementAccelerationPayload [`Motor1QuickMovementInitialSpeedPayload`]: xref:Harp.StepperDriver.CreateMotor1QuickMovementInitialSpeedPayload [`Motor1QuickMovementDistancePayload`]: xref:Harp.StepperDriver.CreateMotor1QuickMovementDistancePayload diff --git a/workflows/stepperdriver-quickmovement-arming.bonsai b/workflows/stepperdriver-quickmovement-arming.bonsai index df702881..5781f80e 100644 --- a/workflows/stepperdriver-quickmovement-arming.bonsai +++ b/workflows/stepperdriver-quickmovement-arming.bonsai @@ -23,19 +23,19 @@ Write - 60 + 200 Write - 2.5 + 5 Write - 5 + 20 diff --git a/workflows/stepperdriver-quickmovement-calibration.bonsai b/workflows/stepperdriver-quickmovement-calibration.bonsai index 1c6cafa5..1b24da8f 100644 --- a/workflows/stepperdriver-quickmovement-calibration.bonsai +++ b/workflows/stepperdriver-quickmovement-calibration.bonsai @@ -1,12 +1,28 @@  + + + A + false + + + + Write + + 100 + + + + StepperDriver Commands + StepperDriver Events @@ -18,7 +34,7 @@ Write - 2.5 + 100 @@ -28,7 +44,9 @@ - + + + \ No newline at end of file diff --git a/workflows/stepperdriver-quickmovement-calibration.svg b/workflows/stepperdriver-quickmovement-calibration.svg index 41443d1f..5b332605 100644 --- a/workflows/stepperdriver-quickmovement-calibration.svg +++ b/workflows/stepperdriver-quickmovement-calibration.svg @@ -1,76 +1,125 @@ + ]> - + - - - - - - - - StepperDriver + + + + + + + + + + StepperDriver - - Commands + + Commands - - - - - Stepper + + + + + + StepperDriver - - Driver.Motor1 + + Commands - - QuickMoveme + + + + + Stepper - - - - Take + + Driver.Motor1 - - - - - - StepperDriver + + MoveRelativeP - - Events + + + + + Stepper + + + Driver.Motor1 + + + QuickMoveme + + + + + + + KeyDown + + + + + Take + + + + + + + StepperDriver + + + Events - - + + - - + + - - + + - - + + - - + + - + + + + + + + + + + + + + + + + + + + - - + + - - + + \ No newline at end of file From 4cb4eeb6a1429eee4adcac96fdaf3f5e72f4e3f4 Mon Sep 17 00:00:00 2001 From: Shawn Tan Date: Thu, 26 Feb 2026 18:47:50 -0800 Subject: [PATCH 25/27] Add datadevicewriter to device pattern --- tutorials/stepperdriver-configuration.md | 11 ++- tutorials/stepperdriver-controlmotor.md | 2 +- tutorials/stepperdriver-quickmovement.md | 2 +- ...rdriver-configuration-devicepattern.bonsai | 10 +++ ...pperdriver-configuration-devicepattern.svg | 90 +++++++++++-------- 5 files changed, 72 insertions(+), 43 deletions(-) diff --git a/tutorials/stepperdriver-configuration.md b/tutorials/stepperdriver-configuration.md index 4d020356..a1a4aa3a 100644 --- a/tutorials/stepperdriver-configuration.md +++ b/tutorials/stepperdriver-configuration.md @@ -19,9 +19,11 @@ Set up the standard Harp [device pattern](../articles/operators.md#device-patter ::: - Insert a [`Device`] operator, set the `PortName` property to the communications port for the device. +- Insert a [`DeviceDataWriter`] sink and set the `Path` property (e.g. `StepperDriver.harp`). + - This will save the data in the standard Harp logging format, which can be loaded with [`harp-python`](../articles/python.md). - Insert a [`PublishSubject`] operator and name it `StepperDriver Events`. - Right-click the [`Device`] operator, select "Create Source (Bonsai.Harp.HarpMessage)" > "BehaviorSubject". - - Name the generated [``BehaviourSubject`1``] [source subject](https://bonsai-rx.org/docs/articles/subjects.html#source-subjects) `StepperDriver Commands`. + - Name the generated [``BehaviorSubject`1``] [source subject](https://bonsai-rx.org/docs/articles/subjects.html#source-subjects) `StepperDriver Commands`. - Connect it as input to the [`Device`] operator. ## Configure interlock state @@ -44,7 +46,7 @@ The `StepperDriver` includes an external interlock terminal (labelled `Enable` o ## Configure microstep resolution -The microstep resolution determines the size of each step, and directly affects the speed and distance travelled by the movement commands. It must be set individually for each motor driver. Values range from `Microstep8` (coarsest) to `Microstep64` (finest). +The microstep resolution determines the size of each step, and directly affects the speed and distance of movement commands. It must be set individually for each motor driver. Values range from `Microstep8` (coarsest) to `Microstep64` (finest). :::workflow ![StepperDriver Microstep Resolution](../workflows/stepperdriver-configuration-microstepresolution.bonsai) @@ -75,7 +77,7 @@ Other operation parameters to be set include the operation mode of the motor dri - `Motor1MaximumRunCurrent` - Set the motor's rated phase current in amps (e.g. 1). - Insert a [`CreateMessage`] operator on another branch, and configure these properties: - `Payload` - Select [`Motor1HoldCurrentReductionPayload`]. - - `Motor1HoldCurrentReduction` - Set to minimise heat generation and adjust the holding torque of the motor at rest (e.g. `ReductionTo25Percent` for low holding torque with light external loads). + - `Motor1HoldCurrentReduction` - Set to minimize heat generation and adjust the holding torque of the motor at rest (e.g. `ReductionTo25Percent` for low holding torque with light external loads). - Insert a [`Merge`] operator to combine all three commands into one [`HarpMessage`] stream. - Insert a [`MulticastSubject`] operator named `StepperDriver Commands`. @@ -110,9 +112,10 @@ Run the workflow and press 1 to enable the driver and 2 to > To target multiple drivers, enter their names, separated by a comma, for the `EnableDriver` and `DisableDriver` properties (e.g. `Motor0`, `Motor1`). -[``BehaviourSubject`1``]: xref:Bonsai.Reactive.BehaviorSubject +[``BehaviorSubject`1``]: xref:Bonsai.Reactive.BehaviorSubject [`CreateMessage`]: xref:Harp.StepperDriver.CreateMessage [`Device`]: xref:Harp.StepperDriver.Device +[`DeviceDataWriter`]: xref:Harp.StepperDriver.DeviceDataWriter [`DisableDriverPayload`]: xref:Harp.StepperDriver.CreateDisableDriverPayload [`EnableDriverPayload`]: xref:Harp.StepperDriver.CreateEnableDriverPayload [`HarpMessage`]: xref:Bonsai.Harp.HarpMessage diff --git a/tutorials/stepperdriver-controlmotor.md b/tutorials/stepperdriver-controlmotor.md index e201ccd7..4a06a0d5 100644 --- a/tutorials/stepperdriver-controlmotor.md +++ b/tutorials/stepperdriver-controlmotor.md @@ -1,6 +1,6 @@ # Control Motor -The follow exercises demonstrate how to control motor speed and rotational position with the [Harp StepperDriver](https://github.com/harp-tech/device.stepperdriver). +The following exercises demonstrate how to control motor speed and rotational position with the [Harp StepperDriver](https://github.com/harp-tech/device.stepperdriver). > [!WARNING] > Ensure that you are familiar with the operation of the `StepperDriver` and motors before connecting external loads. Consider using end-of-travel switches in conjunction with a [digital input](xref:Harp.StepperDriver.CreateEnableDigitalInputsPayload) [configuration](xref:Harp.StepperDriver.CreateInput0OpModePayload). Improper use of the `StepperDriver` and motors may result in damage to equipment. diff --git a/tutorials/stepperdriver-quickmovement.md b/tutorials/stepperdriver-quickmovement.md index b514b4a9..1405ca5a 100644 --- a/tutorials/stepperdriver-quickmovement.md +++ b/tutorials/stepperdriver-quickmovement.md @@ -51,7 +51,7 @@ Connect the external load to the stepper motor, and move the motor a set number - `Motor1MoveRelative` - Set the number of steps to move (e.g. 100). - Insert a [`MulticastSubject`] operator named `StepperDriver Commands`. -Run the workflow and press A to move the external load. Measure the distance travelled and divide by the number of steps to get the distance per step pulse. +Run the workflow and press A to move the external load. Measure the distance traveled and divide by the number of steps to get the distance per step pulse. - Insert a [`SubscribeSubject`] operator named `StepperDriver Events`. - Insert a [`Take`] combinator and set the `Count` property to 1. diff --git a/workflows/stepperdriver-configuration-devicepattern.bonsai b/workflows/stepperdriver-configuration-devicepattern.bonsai index 44d9a807..87755e2c 100644 --- a/workflows/stepperdriver-configuration-devicepattern.bonsai +++ b/workflows/stepperdriver-configuration-devicepattern.bonsai @@ -21,6 +21,15 @@ COM9 + + + StepperDriver.harp + true + false + Include + + + StepperDriver Events @@ -28,6 +37,7 @@ + \ No newline at end of file diff --git a/workflows/stepperdriver-configuration-devicepattern.svg b/workflows/stepperdriver-configuration-devicepattern.svg index 1b862c11..7045e7ff 100644 --- a/workflows/stepperdriver-configuration-devicepattern.svg +++ b/workflows/stepperdriver-configuration-devicepattern.svg @@ -1,57 +1,73 @@ + ]> - + - - - - - - - - - - StepperDriver + + + + + + + + + + + StepperDriver - - Events + + Events - - - - - StepperDriver + + + + + StepperDriver - - - - - - StepperDriver + + DataWriter - - Commands + + + + + StepperDriver + + + + + + + StepperDriver + + + Commands - - + + + + + + + + - - + + - - + + - - + + - - + + \ No newline at end of file From 02ad28921ee1e3d2123b69651566723d7b6225a9 Mon Sep 17 00:00:00 2001 From: Shawn Tan Date: Thu, 26 Feb 2026 21:48:41 -0800 Subject: [PATCH 26/27] Add microstep8 to quickmovement driver config --- tutorials/stepperdriver-quickmovement.md | 15 +- ...r-quickmovement-driverconfiguration.bonsai | 12 +- ...iver-quickmovement-driverconfiguration.svg | 169 ++++++++++-------- 3 files changed, 114 insertions(+), 82 deletions(-) diff --git a/tutorials/stepperdriver-quickmovement.md b/tutorials/stepperdriver-quickmovement.md index 1405ca5a..aef34fd0 100644 --- a/tutorials/stepperdriver-quickmovement.md +++ b/tutorials/stepperdriver-quickmovement.md @@ -13,12 +13,12 @@ The [Harp StepperDriver](https://github.com/harp-tech/device.stepperdriver) feat - `QuickMovement` requires firmware `fw0.7-harp1.14` and later. Download the firmware from the [release](https://github.com/harp-tech/device.stepperdriver/releases) page and update it with the [Harp Toolkit](https://github.com/harp-tech/toolkit). - `QuickMovement` is only supported on `Stepper 1` and `Stepper 2` drivers. Connect a stepper motor (`Motor1`) to `Stepper 1` output for these exercises. - Install the `Bonsai.Windows.Input` package from the Bonsai [package manager](https://bonsai-rx.org/docs/articles/packages.html). -- Set up the [device pattern](./stepperdriver-configuration.md#device-pattern), [configure](./stepperdriver-configuration.md) the device, and [enable](./stepperdriver-configuration.md#enable-and-disable-motor-drivers) the `Motor1` stepper driver. +- Set up the [device pattern](./stepperdriver-configuration.md#device-pattern), and [enable](./stepperdriver-configuration.md#enable-and-disable-motor-drivers) the `Motor1` stepper driver. - Use the [position visualizer](./stepperdriver-controlmotor.md#visualize-position) to monitor the movement. ## Configure Driver -Configure the motor driver operation mode for `QuickMovement` and set a higher sampling rate for the [`AccumulatedSteps`] event for visualization. +Configure the following registers for `QuickMovement`. For all other parameters, refer to the [configuration](./stepperdriver-configuration.md) guide. :::workflow ![StepperDriver QuickMovement Driver Configuration](../workflows/stepperdriver-quickmovement-driverconfiguration.bonsai) @@ -26,12 +26,15 @@ Configure the motor driver operation mode for `QuickMovement` and set a higher s - Insert a [`SubscribeSubject`] operator named `StepperDriver Events`. - Insert a [`Take`] combinator and set the `Count` property to 1. +- Insert a [`CreateMessage`] operator and configure these properties: + - `Payload` - Select [`Motor1MicrostepResolutionPayload`]. + - `Motor1MicrostepResolution` - Select `Microstep8` to achieve the highest speed. - Insert a [`CreateMessage`] operator and configure these properties: - `Payload` - Select [`Motor1OperationModePayload`]. - - `Motor1OperationMode` - Set to `DynamicMovements`. + - `Motor1OperationMode` - Select `DynamicMovements`. - Insert a [`CreateMessage`] operator on another branch and configure these properties: - `Payload` - Select [`AccumulatedStepsSamplingRatePayload`]. - - `AccumulatedStepsSamplingRate` - Set to `Rate100Hz`. + - `AccumulatedStepsSamplingRate` - Select `Rate100Hz` for a higher position visualizer refresh rate. - Combine the two messages with a [`Merge`] combinator. - Insert a [`MulticastSubject`] operator named `StepperDriver Commands`. @@ -60,9 +63,6 @@ Run the workflow and press A to move the external load. Measure the d - `Motor1QuickMovementPulseDistance` - Set the calibrated step pulse distance, in μm (e.g. 100). - Insert a [`MulticastSubject`] operator named `StepperDriver Commands`. -> [!WARNING] -> Recalibrate `QuickMovement` if you change [`Motor1MicrostepResolution`], as it determines the size of each step. - ## Exercise 2: Arm QuickMovement Preload movement parameters to arm the `QuickMovement` for rapid execution. Instead of steps or step intervals, movement parameters will use SI units: @@ -119,6 +119,7 @@ Run the workflow and press H to trigger the `QuickMovement`. [`CreateMessage`]: xref:Harp.StepperDriver.CreateMessage [`KeyDown`]: xref:Bonsai.Windows.Input.KeyDown [`Merge`]: xref:Bonsai.Reactive.Merge +[`Motor1MicrostepResolutionPayload`]: xref:Harp.StepperDriver.CreateMotor1MicrostepResolutionPayload [`Motor1MoveRelativePayload`]: xref:Harp.StepperDriver.CreateMotor1MoveRelativePayload [`Motor1QuickMovementAccelerationPayload`]: xref:Harp.StepperDriver.CreateMotor1QuickMovementAccelerationPayload [`Motor1QuickMovementInitialSpeedPayload`]: xref:Harp.StepperDriver.CreateMotor1QuickMovementInitialSpeedPayload diff --git a/workflows/stepperdriver-quickmovement-driverconfiguration.bonsai b/workflows/stepperdriver-quickmovement-driverconfiguration.bonsai index c2fc90e2..d253037d 100644 --- a/workflows/stepperdriver-quickmovement-driverconfiguration.bonsai +++ b/workflows/stepperdriver-quickmovement-driverconfiguration.bonsai @@ -15,6 +15,12 @@ 1 + + Write + + Microstep8 + + Write @@ -38,9 +44,11 @@ - - + + + + \ No newline at end of file diff --git a/workflows/stepperdriver-quickmovement-driverconfiguration.svg b/workflows/stepperdriver-quickmovement-driverconfiguration.svg index 02918a8b..9b2e26f2 100644 --- a/workflows/stepperdriver-quickmovement-driverconfiguration.svg +++ b/workflows/stepperdriver-quickmovement-driverconfiguration.svg @@ -1,110 +1,133 @@ + ]> - + - - - - - - - - - StepperDriver + + + + + + + + + + + StepperDriver - - Commands + + Commands - - - - - - Merge + + + + + + Merge - - - - - Stepper + + + + + Stepper - - Driver.Motor1 + + Driver.Motor1 - - OperationMod + + MicrostepResol - - - - - Stepper + + + + + Stepper - - Driver. + + Driver.Motor1 - - AccumulatedSt + + OperationMod - - - - Take + + + + + Stepper - - - - - - StepperDriver + + Driver. - - Events + + AccumulatedSt + + + + + Take + + + + + + + StepperDriver + + + Events - - + + + + + + + + + + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + \ No newline at end of file From bab8d65c513e9a65b0d008fbb18f839b34d42b36 Mon Sep 17 00:00:00 2001 From: Shawn Tan Date: Fri, 6 Mar 2026 08:08:38 -0800 Subject: [PATCH 27/27] Update instructions for new interface package release --- tutorials/stepperdriver-quickmovement.md | 1 + tutorials/stepperdriver-setup.md | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/tutorials/stepperdriver-quickmovement.md b/tutorials/stepperdriver-quickmovement.md index aef34fd0..c808469a 100644 --- a/tutorials/stepperdriver-quickmovement.md +++ b/tutorials/stepperdriver-quickmovement.md @@ -11,6 +11,7 @@ The [Harp StepperDriver](https://github.com/harp-tech/device.stepperdriver) feat ## Prerequisites - `QuickMovement` requires firmware `fw0.7-harp1.14` and later. Download the firmware from the [release](https://github.com/harp-tech/device.stepperdriver/releases) page and update it with the [Harp Toolkit](https://github.com/harp-tech/toolkit). +- `QuickMovement` requires `Harp.StepperDriver` package `0.4.0` and later, update it with the Bonsai [package manager](https://bonsai-rx.org/docs/articles/packages.html). - `QuickMovement` is only supported on `Stepper 1` and `Stepper 2` drivers. Connect a stepper motor (`Motor1`) to `Stepper 1` output for these exercises. - Install the `Bonsai.Windows.Input` package from the Bonsai [package manager](https://bonsai-rx.org/docs/articles/packages.html). - Set up the [device pattern](./stepperdriver-configuration.md#device-pattern), and [enable](./stepperdriver-configuration.md#enable-and-disable-motor-drivers) the `Motor1` stepper driver. diff --git a/tutorials/stepperdriver-setup.md b/tutorials/stepperdriver-setup.md index b9776db6..1ed8348e 100644 --- a/tutorials/stepperdriver-setup.md +++ b/tutorials/stepperdriver-setup.md @@ -5,7 +5,7 @@ The [Harp StepperDriver](https://github.com/harp-tech/device.stepperdriver) is a ## Installation - Install [Bonsai](https://bonsai-rx.org/docs/articles/installation.html). -- Install the `Harp.StepperDriver` package by searching for it in the [Bonsai package manager](https://bonsai-rx.org/docs/articles/packages.html). If the package does not appear in the search results, enable the "Show advanced" option. +- Install the `Harp.StepperDriver` package by searching for it in the [Bonsai package manager](https://bonsai-rx.org/docs/articles/packages.html). ## Connections