OpenMower — Open Source RTK GPS Robotic Mower – Configuration

Docs: Configuring xESC

Mon, 01 Jan 0001 00:00:00 +0000

The xESC motor controllers can be configured to work with many BLDC and DC motors. The firmware for the controllers is based on the open source VESC project and therefore, the controllers can be configured using the VESC Configuration Tool.

Prerequisites

Windows or Linux computer to run the VESC Configuration Tool
VESC Tool (https://vesc-project.com/vesc_tool ) You can download the tool for free by adding the “free” version in your cart and proceeding to checkout.
OpenMower Firmware needs to be successfully installed in the xCore board. This is needed because the xCore bridges the connection between your computer and the xESC. If you haven’t done it, follow the Firmware Update guide.
Optional (but makes your life easier):
Configuration files for the mower you are using.
Look in the OpenMower repository for the files suited for your mower.
You will need three files:
- App configuration XML (sets the baud rate, etc. Same for all three xESC controllers)
- Mower Motor configuration XML (motor parameters for the mower motor)
- Drive Motor configuration XML (motor parameters for the wheel motors)

Configuration Process

Stop ROS from interfering with the controllers

openmower stop to stop ROS from interfering with the controllers during configuration.

Expose the ESC to the network

Run openmower expose-xesc [left|right|mower] to expose the xESC controller (choose left, mower or right).
The controller is then reachable in your local network on openmower:65102 until you hit Ctrl + C.

Connect to the xESC

Open the VESC Configuration Tool and connect to the xESC controllers by clicking:

Connection -> TCP [1]
Insert the IP address of your mower or openmower into the Address field [2].
Set the port to 65102 [3]
Click Connect [4]

Information

If you encounter this warning message:

you can safely ignore it. The VESC tool is backward compatible with the firmware version used on the xESC controller.

Configure xESC

Upload the configurations

With the VESC Configuration Tool connected, you can now upload the configuration to your xESC controllers:

[Image 1]: Click File -> Load Motor Configuration XML
[Image 2]: Select the motor configuration XML file for your motor (different for mowing motor and the drive motors)
[Image 3]: Ignore the version message, if it appears
[Image 4]: Click Write Motor configuration. The green banner will appear on success.
[Image 5]: Click File -> Load App Configuration XML. Ignore the version message, if it appears
[Image 6]: Click Write App configuration. The green banner will appear on success.
Hit Ctrl + C in the openmower terminal to stop exposing the xESC controller.

Repeat these steps for all three of the three xESC controllers.

Required preparations

Remove the mower blade.
Really, remove the blade! This is a huge mower with a strong motor and large blade! 💀
Lift the mower’s rear so wheels can spin freely (use a carton, block or stand).
Unmount the mower blade!
Use battery power for calibration (not dock power), and ensure the battery has sufficient charge.
Check if you disassembled the mower blade!

Drive motor calibration (left then right)

Perform calibration for left drive first, then repeat the procedure for the right drive.

Enable realtime data: Later on, we wanna validate our calibration with a known reference value, but also during calibration it’s interesting to see the displayed values in the marked 2 window. That’s why we enable real-time data first:
Start the FOC Calibration Wizard:
Now we need to provide some specs of our motor. These are the specs for the left and right drive motors, for the mow motor, we need to use other specs:
🡆 🡆

🡆 🡆
Once calibration has been done, do not change the direction (even though the left wheel turns forward during calibration, whereas the right one backwards):
Now that the calibration succeed, lets test the result:

Test with “D 0,4” (1) and press the “Duty cycle” play button (2). If it draw <= 0.15A (3) and sound healty, it is calibrated well.
Test with some higher duty settings. It will become more loud for sure, but should always spin smooth and sound healty. If not, press the STOP sign (4).
As a last important step, load the correct ESC-App config via: File → Load App Configuration XML, choose SABO_Drive-App.xml (see SABO ESCs configs ) and finally press the ↧A icon (Write app configuration) on the right side.

Done 😆
… but not finished ✌️ … you need to do the whole procedure again, but with the right drive side.

So, Ctrl+c your openmower expose-xesc left, and do it again but with openmower expose-xesc right.

Mow Motor Calibration

For the mow motor ESC calibration, you do the same workflow, but with adapted values:

openmower expose-xesc mower
During FOC Calibration Wizard use the following values:
- Tab “Motor” = Medium Inrunner ~750g
  - Advanced: Max Power Loss = 200, Motor Poles = 8
- Tab “Battery”
  - Battery Capacity = 3.9Ah (same as before)
- Tab “Setup”
  - Gear Ratio = Check Direct Drive
  - Motor Poles = 8
  - Motor Temp. Sensor = disabled
Test with “D 0,08” which should draw <= 0.52A (without assembled blade)
Check/Adjust blade rotation direction:
We need to ensure that the blade rotate CCW (when watching from downside onto the axis). Do this with a slow rotation speed like “D 0,02”.

If it rotates CW, change direction via: Motor Settings → General → Tab General → Invert Motor Direction. Do not forget to do: “Write motor configuration” via ↧M
Load the correct ESC-App config via: File → Load App Configuration XML, choose SABO_Mower-App.xml (see SABO ESCs configs ) and finally press the ↧A icon (Write app configuration) on the right side.
Limit blade RPM:
It’s important to limit the max. RPM to the one like OEM is running it! Otherwise you risk your motor bearings or more dangerous: Your blade might fly away 💀

Limit battery current:
Dependent on your Sabo-Carrier hardware version, you should limit the battery current:

Sabo-Carrier Version	VESC `Battery Current max.` Setting	Battery Fuse	Mow Fuse
v0.2.x	6A	Conservative 4A Medium	-
v0.4.x	4.5A	Conservative 4A Medium	-
v0.5.x	9A	4A Medium but irrelevant	8A medium

Note: The Battery Current max. settings listed above are theoretical design limits based on conservative track width calculations.

Warning: If you choose a value larger than the stock fuse, you’ve to expect that it may blow and need to be replaced with a higher-rated one.

Choose your adventure. Your build, your rules.

Docs: Configuring GPIO Inputs

Mon, 01 Jan 0001 00:00:00 +0000

Overview

OpenMower supports configuring GPIO pins as digital inputs that can trigger emergency stops or other events. Common use cases include:

Wheel lift sensors — detect when the mower is lifted
Stop buttons — physical emergency stop buttons on top of the mower

Step 1: Create the inputs configuration file

Create /home/openmower/params/inputs.yaml with your GPIO input definitions:

gpio:
 - name: Front left wheel lift
 line: GPIO10
 active: low
 emergency:
 reason: lift
 delay: 2500

 - name: Front right wheel lift
 line: GPIO11
 active: low
 emergency:
 reason: lift
 delay: 2500

 - name: Top stop button 1
 line: GPIO12
 active: low
 emergency:
 reason: stop
 delay: 10

 - name: Top stop button 2
 line: GPIO13
 active: low
 emergency:
 reason: stop
 delay: 10

Configuration fields

Field	Description
`name`	Human-readable label for the input
`line`	GPIO pin name (e.g. `GPIO10`)
`active`	Logic level that triggers the event — `low` or `high`
`emergency.reason`	Emergency type — `lift` for wheel lift, `stop` for stop button
`emergency.delay`	Debounce/delay in milliseconds before the emergency is triggered

GPIO Pin Mapping

The example config above uses GPIO10–GPIO13. Here is how those map to physical connectors on each board.

OpenMower Universal Board

Orientation: looking at the board with the ethernet ports facing you.

Position	GPIO
Top left	GPIO13
Top right	GPIO12
Bottom right	GPIO11
Bottom left	GPIO10

OpenMower Yardforce Board

Orientation: looking at the board with the ethernet ports at the bottom left, pins sorted top to bottom.

Position	GPIO
1st (topmost)	GPIO10
2nd	GPIO11
3rd	GPIO12
4th	GPIO13

Step 2: Enable the input service

Add the following to your mower_params.yaml (or custom_params.yaml for Universal board builds):

ll:
 services:
 input:
 config_file: /data/params/inputs.yaml

To open the file for editing:

openmower configure ros

Path mapping on OSv2

On OSv2, /home/openmower/params is mapped to /data/params inside the container. If you are on a different setup, adjust the config_file path accordingly.

Step 3: Restart OpenMower

After saving both files, restart the service to apply the changes:

openmower restart

Your GPIO inputs are now active and will trigger the configured emergency events when the specified logic level is detected.

Docs: Universal Board Configuration

Mon, 01 Jan 0001 00:00:00 +0000

This guide is for custom mower builds using the OpenMower Universal Board. Unlike supported mowers, custom builds require you to measure and set several hardware-specific parameters before the mower will operate correctly.

All custom parameters go into ~/params/custom_params.yaml on the mower.

Do not use openmower configure ros

openmower configure ros opens mower_params.yaml by default — this is the wrong file for custom builds. Always edit custom_params.yaml directly:

nano ~/params/custom_params.yaml

All other openmower commands (e.g. openmower configure env) work as expected.

Configuration Template

Download the template and place it at ~/params/custom_params.yaml on your mower as a starting point:

Download custom_params.yaml

The sections below explain every parameter marked # TODO.

Differential Drive

ll:
 services:
 diff_drive:
 wheel_distance_m: 0.325
 ticks_per_m: 1600.0

Parameter	What to set
`wheel_distance_m`	Distance in meters between the center of the left and right drive wheels. Measure with a tape measure.
`ticks_per_m`	Encoder ticks per meter of travel. Must be measured — see Calibrating Wheel Ticks below.

IMU Orientation

 imu:
 axis_config: "+X-Y-Z"

Parameter	What to set
`axis_config`	Orientation of the mainboard relative to the mower chassis. `+X-Y-Z` is correct for a flat, horizontal mounting with the board’s X axis pointing forward. Change this if your mainboard is mounted at an angle or rotated.

Battery Voltages

 power:
 battery_full_voltage: 20.0
 battery_empty_voltage: 18.5
 battery_critical_voltage: 16.5
 battery_critical_high_voltage: 21.0
 charge_critical_high_voltage: 30.0
 charge_critical_high_current: 1.5

Look up the voltage spec for your battery pack and set accordingly.

Parameter	What to set
`battery_full_voltage`	Voltage of a fully charged pack (from spec).
`battery_empty_voltage`	Voltage at which the mower returns to dock.
`battery_critical_voltage`	Emergency low-voltage cutoff. Set below empty but above damaging discharge.
`battery_critical_high_voltage`	Overvoltage protection threshold. Set slightly above full charge voltage.
`charge_critical_high_voltage`	Maximum acceptable charger output voltage.
`charge_critical_high_current`	Maximum acceptable charge current in amps.

GPS Antenna Offset

xbot_positioning:
 antenna_offset_x: 0.3
 antenna_offset_y: 0.0

The positioning system needs to know where the GPS antenna is relative to the mower’s center of rotation (the midpoint between the two drive wheels).

Parameter	What to set
`antenna_offset_x`	Forward/back offset in meters. Positive = antenna is in front of the rotation center. Measure from wheel midpoint to antenna.
`antenna_offset_y`	Left/right offset in meters. Positive = antenna is to the left. Usually 0 if the antenna is centered.

GPS Datum

 gps:
 datum_lat: 53.457452
 datum_long: 10.014737

These are not marked TODO in the template but must be changed. Set them to coordinates near your docking station — this becomes the origin of your mower’s map. Use a GPS or map tool to get the coordinates.

NTRIP Credentials

ntrip_client:
 host: "www.your-ntrip-caster.de"
 port: 2101
 username: "ntripuser"
 password: "ntrippass"
 mountpoint: "ntripmount"

Fill in the credentials from your RTK correction provider.

Emergency Sensors

Before enabling the mower motor, configure and verify all emergency sensors (lift detection, tilt detection, stop buttons). This is done via the GPIO input configuration — see Configuring GPIO Inputs for the full setup guide.

Enable Mower Motor

mower_logic:
 enable_mower: false

Set to true only after all emergency sensors are wired, configured, and verified to work correctly. Running without functioning emergency sensors is unsafe.

Calibrating Wheel Ticks

This procedure measures the ticks_per_m value for your specific mower’s wheel encoders.

Prerequisites

OpenMower is running
SSH or web terminal access
A flat surface with ~10 m of clear, straight space
Something to mark the start and end position (tape, chalk, etc.)

Step 1: Enter recording mode

Open the OpenMower app and activate area recording mode. This ensures the drive motors and wheel encoders are active and publishing odometry data.

Step 2: Record start tacho values

Open the ROS shell:

openmower shell

Subscribe to the left ESC status topic and note the tacho field:

rostopic echo /ll/diff_drive/left_esc_status

Write down the value, then press Ctrl+C. Repeat for the right wheel:

rostopic echo /ll/diff_drive/right_esc_status

Step 3: Drive a 10 m straight line

Mark the mower’s current position, then drive it in a straight line for exactly 10 meters. Drive slowly and steadily — the straighter the line, the more accurate the result.

Step 4: Record end tacho values

Subscribe to each topic again and note the new tacho values:

rostopic echo /ll/diff_drive/left_esc_status

rostopic echo /ll/diff_drive/right_esc_status

Step 5: Calculate ticks_per_m

Compute the difference for each wheel. If negative, flip the sign:

left_diff = |tacho_end_left - tacho_start_left|
right_diff = |tacho_end_right - tacho_start_right|

The two values should be approximately equal. Average them and divide by 10:

ticks_per_m = (left_diff + right_diff) / (2 * 10)

Step 6: Apply the value

Edit custom_params.yaml directly:

nano ~/params/custom_params.yaml

Set the value you calculated:

ll:
 services:
 diff_drive:
 ticks_per_m: <your_value>

Save the file and restart OpenMower to apply.

Tip

Run the measurement two or three times and average the results for better accuracy. Small variations in how straight you drive will affect individual readings.

Docs: Managing ROS Parameters

Mon, 01 Jan 0001 00:00:00 +0000

Viewing and Configuring ROS Parameters

OpenMower is built on ROS, which means much of its behavior is controlled through parameters. Understanding how to inspect and modify these parameters gives you fine-grained control over your mower’s operation.

Listing All Parameters

To see all currently active ROS parameters, open the OpenMower shell:

openmower shell

Then run:

rosparam list

This will display a full list of parameters currently loaded in the system. It’s a useful first step when debugging or trying to understand how your mower is configured.

Overwriting Parameters

All parameters can be customized using the mower_params.yaml configuration file. This file acts as the central place to override default values.

The easiest way to edit it is with:

openmower configure ros

Example

In this example we will be overwriting the speed parameter.

1. Fetch the Parameter’s current value

After discovering a parameter you want to edit using rosparam list, you can get the value using rosparam get <parameter>:

🚜 openmower@openmower-v2:~$ rosparam get /move_base_flex/FTCPlanner/speed_fast
0.4

In this case, our speed is currently at 0.4 m/sec for mowing

2. Change the value for your config

On the host system call openmower configure ros and translate the parameter name to YAML. This is done by replacing each / into indentations (2x space).

For our example it looks like this:

move_base_flex:
 FTCPlanner:
 speed_fast: 0.5

3. Save the file and check the updated value

After saving the file, ROS is automatically restarted and you can check, if the value is now updated:

🚜 openmower@openmower-v2:~$ rosparam get /move_base_flex/FTCPlanner/speed_fast
0.5

🎉 Done!

If you have issues

If some parameter isn’t overriding correctly, make sure you are on the latest version of OpenMower. If it still doesn’t work ask on Discord.