RoboRun+

PC Utility

User Manual

V3.0, September 3, 2022

visit www.roboteq.com to download the latest revision of this manual

©Copyright 2016-2022 Roboteq, Inc

 1
 RoboRun+ PC Utility

Revision History

Date Version Changes

September 3, 2022 3.0 New layout, new features aligned to G4 products

December 3, 2020 2.1 Added Motor Characterization

June 27, 2019 2.0 Extracted from main User Manual

The information contained in this manual is believed to be accurate and reliable. How-
ever, it may contain errors that were not noticed at the time of publication. Users are
expected to perform their own product validation and not rely solely on data contained
in this manual.

2 RoboRun+ PC Utility Manual V3.0, September 3, 2022

Revision History.......................................................................................... 2

Introduction................................................................................................. 5
Refer to the Datasheet for Hardware-Specific Issues................................. 5
User Manual Structure and Use.................................................................. 5

Introduction................................................................................................. 7
Installation................................................................................................... 7
System Requirements........................................................................ 7
Installation Steps................................................................................ 8
Program Folder Structure.................................................................... 9
How to Use............................................................................................... 10
Header.............................................................................................. 10
Status Bar..........................................................................................11
Content Tabs......................................................................................11
Correcting Compilation Errors.......................................................... 31
Connecting to Controller........................................................................... 33
USB/Serial......................................................................................... 33
TCP................................................................................................... 33
Controller’s Pinout............................................................................ 34
Locking Controller’s Configuration............................................................ 35
Locking the Configuration................................................................. 35
Unlocking the Configuration............................................................. 35
Firmware Update...................................................................................... 36
Update Firmware via COM Port....................................................... 36
Update Firmware via USB................................................................ 37
Firmware Update via CANOpen................................................................ 39
Step-by-step.............................................................................................. 39
CANOpen configurations.......................................................................... 45
Recover Application via CANOpen............................................................ 46
Update Control Unit Logic (obsolete)............................................... 46
Update Power Unit Logic (obsolete)................................................. 46
Motor/Sensor Setup.................................................................................. 47
Sinusoidal Mode............................................................................... 48
Sensor Linearity Correction...................................................................... 48
Motor Characterization............................................................................. 50
Motor Sensor and Tuning Setup Manual................................................... 54
Part 1: Motor sensor setup .............................................................. 55
Part 2: Current Loop Auto Tuning...................................................... 57
Part 3: Closed loop Speed PI tuning................................................. 63

RoboRun+ PC Utility Manual 3

4 RoboRun+ PC Utility Manual V2.1, December 3, 2020
 User Manual Structure and Use

Introduction

Refer to the Datasheet for Hardware-Specific Issues

This manual is the companion to your controller’s datasheet. All information that is specific
to a particular controller model is found in the datasheet. These include:
• Number and types of I/O
• Connectors pin-out
• Wiring diagrams
• Maximum voltage and operating voltage
• Thermal and environmental specifications
• Mechanical drawings and characteristics
• Available storage for scripting
• Battery or/and Motor Amps sensing
• Storage size of user variables to Flash or Battery-backed RAM

User Manual Structure and Use

The user manual discusses issues that are common to all controllers inside a given prod-
uct family. Except for a few exceptions, the information contained in the manual does not
repeat the data that is provided in the datasheets.

Using the Roborun Configuration Utility

This section describes the features and capabilities of the Roborun PC utility. The utility
can be used for setting/changing configurations, operate/monitor the motors and I/O, edit,
simulate and run Microbasic scripts, and perform various maintenance functions such as
firmware updates.

RoboRun+ PC Utility Manual 5

 Introduction

6 RoboRun+ PC Utility Manual V3.0, September 3, 2022

 Installation

Using the Roborun

Configuration Utility

Introduction
Roborun+ is a PC utility that allows users configure their Roboteq’s motor controllers. Us-
ing the utility, you can alter the controller’s configuration parameters in addition to monitor
the operating state of the controller.

The utility provides means of diagnostics through rich charts and logs. Through the utility
you can monitor the commands/responses flow through USB, RS232, RS485, or TCP.

The utility provides means of updating the controller’s firmware through the UI with few
mouse clicks. In addition to that, the utility provides a way for writing, compiling, and up-
loading user defined script through a WYSWYG script editor integrated in the utility.

The utility is available on the website free of charge.

Installation
The utility can be obtained from the Support page on Roboteq’s website at www.roboteq.
com. Roborun+ has a setup wizard that guides you through the installation process with
few clicks. However, the setup will remove previous version of the utility on installation, it
is recommended to remove previous versions before attempting to install new versions.

The controller does not need to be connected to the PC to start the Utility. For installa-
tions on older versions of Windows, it may be necessary to install .NET Framework ver-
sion 3.5. On Windows 10 systems, you may need to enable .net framework version 3.5.

System Requirements
To run the utility, the following is needed:
• PC compatible computer running Microsoft Windows 7 or higher.
• Microsoft .NET Framework 2.0.
• Microsoft .NET Framework 4.0.

RoboRun+ PC Utility Manual 7

 Using the Roborun Configuration Utility

• A USB connector for controllers with USB connectivity.

• A USB connector and an RS232/RS485 to USB converter in order to communicate
via RS232/RS485.

Installation Steps
• Run setup.exe, on the welcome screen press Next button.

• In License Agreement screen check “I Agree” then press Next button.

8 RoboRun+ PC Utility Manual V3.0, September 3, 2022

 Installation

• Choose where you would like to install the application then press Next button.

• In the Confirm Installation screen, press Next button to proceed with the installa-
tion process.

• After installation completes, press Close button.

• You can run the program from your Start Menu > Programs > Roboteq or from the
shortcut placed on the desktop.

Program Folder Structure

• Compiler/doc: Contains the documentation for MicroBasic scripting.
• Trees: Contains configuration for the supported controller models.
• Utility: Contains internal utilities used by Roborun+.
• RoborunPlus.exe: The Roborun+ executable.
• changelog.txt: Contains the changes across all versions.
• eula.rtf: The end user license agreement file.

RoboRun+ PC Utility Manual 9

 Using the Roborun Configuration Utility

How to Use
The Roborun+ utility is provided as a tool for easily configuring the Roboteq controller and
running it for testing and troubleshooting purposes.

The Roborun+ main screen consists of 3 parts, header, status bar and content tabs. In the
following sections we will describe each in details.

Header

The header is always visible and contains the version number and date in addition to use-
ful information and actions to the currently connected controller.

Item Description

Help (?) Provide documentation (manuals and datasheets)

View Pinout… Display the pinout connection for the current controller.

Script Run Causes the controller to start run the Microbasic script previ-
ously loaded to the controller.

10 RoboRun+ PC Utility Manual V3.0, September 3, 2022

 How to Use

Item Description

Script Pause Causes the controller to pauses the currently running script.

Script Restart Causes the controller to stop the currently running script and
re-executes it for the beginning.

Work Offline When checked, this causes the utility to disconnect from any
connected controllers and allows user to choose the controller
model from the model combo box.
Working offline is useful for creating/editing configuration pro-
files without the need to have an actual controller attached to
the PC.

Controller Model Shows the currently connected controller model and allows
the user to choose from different models in case of working
offline.

COM Port Allows the user to choose the port at which is the controller
connected or make it Auto for the utility to search all ports for
controllers.
Choosing the port forces the utility to send/receive commands
to the controller even if the utility unable to receive the hand-
shake from the controller.
This option allows the utility to connect to controllers through
TCP for the controllers that supports ethernet connections
(see connecting to controller section for details).

Emergency Stop Caused the controller to enter the Emergency Stop state (for
more information, please refer to controller user’s manual).
Pressing it again causes to release Emergency Stop state.

Status Bar

The status bar is located at the bottom of the window and is split in 4 areas. From left to right:

Item Description

Ports List Lists the available ports that utility detected on the PC. These
ports are searched for the controllers when the COM Port option
is Auto.

Port Status Displays the status of the port being manipulated. “Port Open” in-
dicates that communication with the controller is established.

Firmware ID Displays the controller model and firmware version number and
date as reported by the controller.

Connected/Dis- When lit green, it indicates that the communication with the con-
connected LED troller is OK.

Content Tabs
The content tabs allow user to configure, monitor, and diagnose the controller through rich UI.

RoboRun+ PC Utility Manual 11

 Using the Roborun Configuration Utility

Configuration Tab
The configuration tab is used to read, modify and write the controller’s many possible
operating modes. It provides a user-friendly interface for viewing and editing the configu-
ration parameters.

The configuration tab contains two configuration trees: the one on the left deals mostly
with the I/O and control signals, while the tree on the right deals with the power output
and motor parameters. The exact content and layout of a tree depends on the controller
model that is detected.

The trees are, for the most part, self-explanatory and easy to follow.

Each node will expand when clicking on the small triangle next to it. When selecting a tree
item, the value of that item will show up as an underscored value. Clicking on it enables a
menu list or a free-form field that you can select to enter a new configuration value.

12 RoboRun+ PC Utility Manual V3.0, September 3, 2022

 How to Use

By selecting the desired configuration, you will be able to modify it accordingly by select-
ing the desired value for discrete, or type in the new configuration value for wide ranged
values configuration.

Selecting a new value, will cause the configuration node to display a red asterisk mark in-
dicating that this change is not applied to the controller yet.

Depending on the node type, values can be entered in one of many forms:
• Numerical
• Boolean (e.g. Enable/Disable)
• Selection List
• Text String

When entering a numerical value, that value is checked against the allowed minimum and
maximum range for that parameter. If the entered value is lower than the minimum, then
the minimum value will be used instead, if above the maximum, then the maximum value
will be used as the entered parameter.

Boolean parameters, such as Enabled/Disabled will appear as a two-state menu list.

RoboRun+ PC Utility Manual 13

 Using the Roborun Configuration Utility

Some parameters, like Commands or Actions have the option to apply to one or the other
of the motor channels. For this type of parameters, next to the menu list are checkboxes –
one for each of the channels. Checking one or the other tells the controller to which chan-
nel this input or action should apply.

Important Notice about Decimals

The use of Period vs Coma when entering a decimal configuration value depends
on the regional settings of Windows. On USA PC’s, use periods. On European PC’s
use comas. If unsure, load the configuration back from the controller after changing
and saving. Verify that the value that was stored in the controller is the one that was
entered.

You can use buttons to expand/collapse all nodes.

In the right side of this tab, there are actions that can be applied to the configuration:

Item Description

Load from Controller Fills out the configuration trees on the left by the ac-
tual values that is queried from the controller.

Save to Controller Save the configurations you altered to the controller.

Load Profile from Disk Allows the user to pick up a configuration XML file
that is previously saved to be applied to the configu-
ration trees.

Save Profile to Disk Allows user to save the current configuration to an

XML file.

Reset Defaults… Resets the controller’s configuration into defaults pro-

vided by the firmware.

Collect Diagnostics... The utiility gathers all the required data of the control-
ler in order to investigate reported issues.

Motor Sensor and Tuning A wizard that will help user setup the controller
Wizard... based on the sensor and motor connected. See the
respective chapter for more details

14 RoboRun+ PC Utility Manual V3.0, September 3, 2022

 How to Use

Item Description

Automatic PI Tuning... A wizard that will help user configure and tune PID
controllers with speed feedback. See chapter Motor
Sensor and Tuning Setup Manual

Add/Remove Lock Allows the user to enter a password to protect the

changes from being accidently altered or read.

Automatic Analog and Pulse input Calibration

Analog and Pulse inputs can be configured to have a user-defined minimum, maximum
and center range. These parameters can be viewed and edited manually by expanding the
Range sub node.

The minimum, maximum and center values can also be captured automatically by clicking
on the “Calibrate” link.

When clicking on the “Calibrate” link, a window pops up that displays a bar showing the
live value of that analog or pulse input in real time.

The window contains three cursors that move in relation to the input, capturing the mini-
mum and maximum detected values. It is possible to further manually adjust further these
settings by moving the sliders. The Center value will be either the value of the inputs (or
the joystick position) at the time when clicking on the “Done” button. The Center value
can also be automatically computed to be the middle between Min and Max when en-
abling the “Auto Center” checkbox. Clicking on “Reset” resets the Min, Max and Center
sliders and lets you restart the operation.

RoboRun+ PC Utility Manual 15

 Using the Roborun Configuration Utility

After clicking on the “Done” button, the capture values will appear in the Min, Max
and Center nodes in the tree with the orange * next to them, indicating that they have
changed but not yet be saved in the controller. At this point, they can be adjusted further
manually and saved in the controller.

Input/Output Labeling
Each analog, digital or pulse input/output, is given default label (e.g. DIN1, AIN2, ...). Al-
ternatively, it is possible to assign or a user defined label name (e.g. Limit1, eStop, ...) to
each of these signals. This label will then appear in the Run Tab next to the LED or Value
box. The label will also appear in the Pin View window. Custom labels make it much easier
to monitor the controller’s activity in the Run tab.

To label an Input or Output, simply select it in the tree. A text field will appear in which
you can enter the label name. Beware that while it is possible to enter a long label, names
with more than 8 letters will typically appear truncated in the Run tab.

Configuration Parameters Grouping & Organization

The total number of configuration parameters is quite large. While most system will oper-
ate well using the default values, when change is necessary, viewing and editing param-
eters is made easy thanks to a logical graphical organization of these parameters inside
collapsible tree lists.

The configuration tab contains two trees. The left tree includes all parameters that deal
with the Analog, Digital, Pulse I/O, encoder and communication. The right tree includes
all parameters related to the power drive section. The exact content of the trees changes
according to the controller that is attached to the PC.

Startup Parameters
These menus define the controller’s behavior immediately after startup.

The Script Autostart enables or disables script execution. Make sure that the script is bug
free before enabling.

Then a number of Command Safety parameters can also be configured. These are the Watch-
dog timeout when receiving Serial commands, and the safety ranges for analog commands.

The Telemetry parameter contains the string that is executed whenever controller is first
powered up. This parameter is typically composed of a series of real-time queries that the con-
troller automatically and periodically performs. Queries must be separated with the “:” colon
character. The string is normally terminated with the command to repeat (“#”) followed by the
repeated rate in milliseconds. See “TELS - Telemetry String” on Controller’s User Manual.

16 RoboRun+ PC Utility Manual V3.0, September 3, 2022

 How to Use

Commands Parameters
In the commands menu we can set the command priorities, the linearization or exponenti-
ation that must be performed on that input.

A number of Command Safety parameters can be configured. These are the Watchdog
timeout when receiving Serial commands, and the safety ranges for pulse and analog
commands.

CAN Communication Parameters

CAN bus node address, bit rate, choice of protocol and other parameter can be set from
this set of menus.

RoboRun+ PC Utility Manual 17

 Using the Roborun Configuration Utility

Encoder Parameters

Digital Input and Output Parameters

For Digital inputs, you can set the Active Level and select which action input should cause
when it is activated and on which motor channel that action should apply.

For Digital Output, you can set the Active Level and the trigger source that will activate
the Output.

18 RoboRun+ PC Utility Manual V3.0, September 3, 2022

 How to Use

Analog Input Parameters

For Analog inputs, all the parameters that can be selected include the enabling and con-
version type what this input should be used for and for which channel the input range
limits the deadband and which actions to perform when the minimum or maximum values
are reached.

Pulse Input Parameters

For Pulse inputs, the tree lets us enable that input and select what it is used for and what
type of capture it is to make. The range, deadband and actions to take on when Min and
Max are reached is also selectable.

Power Output Parameters

The on the right side of the configuration screen are the parameters that related to the
motor driver and power stage of the controller.

General Settings
There is one tree for setting parameters that apply to all channels of the controller. These
are: the low and high side Voltage Limits, the overtemperature limit, the Short Circuit Pro-
tection, the mixed mode, STO Enable, Molex Input and Automatic Fault Clearance.

RoboRun+ PC Utility Manual 19

 Using the Roborun Configuration Utility

Motor Parameters
The parameters for each motor are typically duplicated so that they can be set separately
for each motor.

The Motor Configuration group contains menus for configuring the motor’s characteristics,
and especially these of brushless motors.

The Motor Output group contains menus for setting Amps limits, Acceleration/Decelera-
tion, operating modes, and Control Loop gains and other operating parameters

Details on each of the possible configurations can be found in the Controller’s User Manual.

Run Tab
The Run tab lets you exercise the motors and visualize all the inputs and outputs of the
controller.

A powerful chart recorder is provided to plot real-time controller parameters on the PC,
and/or log to a file for later analysis.

This tab allows user to monitor the controller status and inputs/outputs in addition to oper-
ating parameters.

20 RoboRun+ PC Utility Manual V3.0, September 3, 2022

 How to Use

Each group of monitored parameters can be disabled with a checkbox at the upper left
corner of their frame. By default, all are enabled. Disabling one or more will increase the
capture resolution in the chart and log of the remaining ones.

Status and Fault Monitoring

Status LEDs show the real-time state of key operating flags. The meaning of each LED is
displayed next to it and can vary from one controller to another.

The Fault LEDs indicate all fault conditions. Any one LED that is lit will cause the controller
to disable the power to all motor output channels. The meaning of each LED is displayed
next to it and can vary from one controller to another.

The Def Config Fault LED indicates that an invalid configuration is read from the controller
and the controller has reverted to its factory default configuration. This would be an ex-
tremely unlikely occurrence, but if it happens, reload your custom configuration and verify
that the new configuration is not lost when restarting the controller a few times. If the
controller loses its configuration, this means it is faulty that it should not be used.

The DefConfig Fault LED will also turn on the first time the controller is restarted after a
new firmware release has be installed and default configuration first reloaded.

RoboRun+ PC Utility Manual 21

 Using the Roborun Configuration Utility

Digital, Analog and Pulse Input Monitoring

The status of Digital inputs and the value Analog and Pulse can be monitored in real-time.
Analog and Pulse inputs will update only if the selected channel is enabled. The labels for
the digital inputs, digital outputs, analog inputs and pulse inputs can be made to take the
value that has been entered in the configuration tree as described in Input/Output Label-
ing. Using a nickname for that signal makes it easier to monitor that information.

Digital Output Activation and Monitoring

The Digital output LEDs reflect the actual state of each of the controller’s Output. If an
output is not changed by the controller using one of the available automatic Output Trig-
gers, clicking on the LED will cause the selected output to toggle On and Off.

Applying Motor Commands

The command sliders will cause the command value to be applied to the controller.

Item Description

Mute Checkbox Prevents the utility from sending motor commands.

Join Checkbox In case of multi-channel controllers, the checkbox allows the user to send the same
motor command value for both motors.

Textbox Allows the user to enter the value manually. The motor commands value is ranged
from -1000 to 1000.

Decreases the motor command by 10.

Decreases the motor command by 1.

Increases the motor command by 1.

Increases the motor command by 10.

Stop Button 4 Set the motor command to 0.

22 RoboRun+ PC Utility Manual V3.0, September 3, 2022

 How to Use

Using the Chart Recorder

A powerful chart recorder is provided for real-time capture and plotting of operating param-
eters. This chart can display up to eight operating parameters at the same time. Each of
the chart’s channels has a pull-down menu that shows all of the operating parameters that
can be viewed and plotted. The colors can be changed by clicking on the color icon and
selecting another color.

When selecting a parameter to display, this parameter will appear in the chart and change
in real-time. The three boxes show a numerical representation of the actual value and the
Min and Max value reached by this input. Clicking on the “Clear” button for that channel
resets the Min and Max. The chart can be paused or it can be cleared and the recorded
values can be saved in an Excel format for later analysis.

“Handles” on the left vertical axis may be used to zoom in a particular vertical range. Simi-
lar handles on the horizontal axis can be used to change the scrolling speed of the chart.

Item Description
Channel Allows user to choose channels to be plotted on the chart area.
Value The current value of selected channel.
Min The minimum value captured so far.
Max The maximum value captures so far.
Clr Clear the minimum and maximum and re-evaluate.
Start/Pause chart capturing.

Save the captured values in one of the following formats:

Save
• Tab delimited.
• Comma Separated Values (CSV).
• Excel file.

Clear Chart Clear the chart and start over.

Clear Log Clear the values saved so far.

Log Configuration Clicking this button opens the following menu:

This menu allows user to Save/Load/Export/Delete configuration for later use.

RoboRun+ PC Utility Manual 23

 Using the Roborun Configuration Utility

Manual Commands
This allows the user to issue commands/queries to the controller in addition to view the
controller responses.

The user can enter the command/query in one of the five textboxes and press Enter key
or Send button to issue the command/query to the controller.

The user can also press View Log button at any time to display the controller’s log.

Console Tab
The console tab is useful for practicing low-level commands and viewing the raw data
exchanged by the controller and the PC. The Console tab also contains the buttons for per-
forming field updates of the controller.

24 RoboRun+ PC Utility Manual V3.0, September 3, 2022

 How to Use

Out Data
The console tab allows you to send low-level commands and view the raw controller re-
sponses. Ten text fields are provided in which you can type commands and send them in
any sequence by clicking on the respective “Send” button or pressing Enter key. All the
traffic that is exchanged by the controller and the PC is logged in the console box on the
right. It is then possible to copy that information and paste it into a word processor or an
Excel spreadsheet for further analysis.

The Stop button sends the “#” command to the controller and will stop the automatic
query updating if it is currently active.

The Clear button clears all the textboxes at once.

Time
In some controller models, there is onboard clock. Pressing the Get button, the utility
reads the time from the controller’s onboard clock while pressing the Set button stores
the current PC time into the controller.

RoboRun+ PC Utility Manual 25

 Using the Roborun Configuration Utility

Controller’s Log
Displays the response from the controller this includes the prints from the MicroBasic
script running.

Item Description

Display Control Characters Checking this option causes the utility to display control
characters (non-printable characters) in a readable form.

Saves the controller’s log to a text file.

Pressing the printer image, causes to print the controller’s

log to the default printer with the default configuration.
Pressing the dropdown allows user to choose the printer
and configure the page setup.

Copies the controller’s log into clipboard.

Clears the current log and start over.

Configure
This allows user to update the controller’s firmware and logic in addition to uploading a
compiled Microbasic script file.

Item Description

Update Firmware via COM This allows user to update the controller’s firmware
port while connected through serial communication port.
See Firmware Update section for details.

Update Firmware via USB. This allows user to update the controller’s firmware
while connected through USB.
See Firmware Update section for details.

Update Firmware via This allows user to update the controller’s firmware
CANOpen while connected through USB.
See Firmware Update section for details.

26 RoboRun+ PC Utility Manual V3.0, September 3, 2022

 How to Use

Item Description

Update Script This allows user to update a compiled MicroBasic

script file previously generated by the utility.
See Scripting Tab section for details.

Update Control Unit Logic This allows user to update the control unit logic.
See Firmware Update section for details.

Update Power Unit Logic This allows user to update the power unit logic.
See Firmware Update section for details.

Diagnostics Tab
In some controller versions with firmware v2.0+ the utility has additional diagnostics tab to
diagnose the controller with high speed data transfer rate up to 1 millisecond refresh rate.

Options
This allows user to choose which channel to diagnose also to configure how often the
controller feeds information to the utility.

RoboRun+ PC Utility Manual 27

 Using the Roborun Configuration Utility

It is better to diagnose the controller with a refresh rate of 1 millisecond, however using 2
and 5 milliseconds option helps in diagnose controllers on slower connections.

Plot/Chart
Allow user to choose the diagnose items to be captured and plotted to the chart.

Please refer to the Capture part under Run Tab for details.
Command
Allows user to issue commands to motor at the selected channel.

Please refer to the Motor Commands part under Run Tab for details.

Configuration
Allows user to manually configure the controller by giving the ability to issue commands/
queries using the available 3 textboxes.

User can also make motor characterisation, motor/sensor setup in addition to linearity cor-
rection. Please refer to the Motor/Sensor Setup and Motor Characterization sections
for details.

28 RoboRun+ PC Utility Manual V3.0, September 3, 2022

 How to Use

Diagnostics Log
Allows user to monitor the log issued by the controller without the need to go to Console
Tab.

Please refer to the Controller’s Log part under Console Tab for details.

Scripting Tab
One of the controller’s most powerful and innovative features is the ability for the user
to write programs that are permanently saved into, and run from the controller’s Flash
Memory. This capability is the equivalent of combining the motor controller functionality
and this of a PLC or Single Board Computer directly into the controller. The scripting tab is
used to write, simulate, and download custom scripts to the controller.

RoboRun+ PC Utility Manual 29

 Using the Roborun Configuration Utility

Item Description
Create a new script file.

Open an existing script file.

Save the current script to disk.

Save the current script to a different file.

Cut the current selection.

Copy the current selection.

Paste the contents of the clipboard.

Comment out the selected code.

Uncomment the selected code.

Undo the previous change.

Redo the previous undo.

This will cause the source code to be immediately interpreted in low level instruc-
tions that are understandable by the controller. A window then pops up showing
the result of the translation. The code is not downloaded into the controller. This
command is generally used to check whether the code you are typing is grammat-
ically correct or not needed. It may be also used to see how many bytes will be
taken by the script inside the controller’s flash.
This will cause the source code to be interpreted and run in simulation mode on
the PC. This function is useful for simplifying script development and debug. The
simulator will operate identically to the real controller except for all commands
that normally read or write controller configuration and operation data. For these
commands, the simulated program will prompt the programmer for values to be
entered manually, or output data to the console.
This will cause the source code to be immediately interpreted in low level instruc-
tions that are understandable by the controller. If no errors are found during the
translation, the code is automatically transferred in the controller’s flash memory
where it is then ready for execution.
Note: For safety, you need to make sure that the connected motors to the con-
troller are not running during downloading scripts to device.

30 RoboRun+ PC Utility Manual V3.0, September 3, 2022

 How to Use

Item Description
This will cause the source code to be interpreted and downloaded to a remote
controller on a RoboCAN network. After clicking a pop-up window will list in a pull-
down menu all controllers found alive on the CAN network. Select the node you
wish the script to be downloaded to.
For more details about RoboCAN network please refer to Roboteq Controllers
User’s Manual.
Note: For safety, you need to make sure that the connected motors to the con-
troller are not running during downloading scripts to device.
Used to save the compiled code of a given script. This way a script can be loaded
in a controller without giving away the source code.
The Hex file can then be loaded from the Console tab using the Update Script button.
It is a kind of debugging feature that enables the user to see real-time values of
variables while the script is running.
The steps for debugging are the following:
Write the code and download it to controller using Download To Device feature.
From the utility header, run the script by pressing the Run button.
While the script is running, press Inspect Variables button to start variables in-
spection.
While in variable inspection mode, you can hover on any variable to get its value.
This button is to show/hide compilation errors/warnings.

Shows a local version of the MicroBasic reference.

For latest documentation, please refer to MicroBasic reference at website.

Correcting Compilation Errors

When building or trying to download a script that contains errors, the compile errors will
be listed in the bottom half of the window. Double clicking on the error will move the cur-
sor to the place in the source code where the error was found.

RoboRun+ PC Utility Manual 31

 Using the Roborun Configuration Utility

Beware that not all programming errors are detected. Be especially careful with vari-
able names. Use the option explicit directive to enforce variable declarations. Beware
not to mix SetConfig() and SetCommand() when changing a configuration or a com-
mand. A faulty script can cause the controller to crash. Enable the scripting Auto Start
configuration only on known working scripts.

Executing Scripts
Scripts are not automatically executed after the transfer. To execute manually, you must
Run or Restart buttons that are in the Utility’s header. Alternatively, click on the Console
tab and send the !r command via the console. Unless a script includes print statements, it
will run silently with no visible signs in the console. Clicking on !r 0 will stop a script, !r or
!r 1 will resume a stopped script. !r 2 will clear all variables and restart a script. The Run-
script LED in the Run tab will be on when script is running.

Executing a script on a remote controller on a CANbus network using the RoboCAN proto-
col is done using the @nn!r command, where nn is the remote node address in hex format.

Debugging Scripts
A number of techniques can be used to debug a script that is not behaving as expected.
You can view the value of variable in real time during program execution by clicking on the
Inspect Variables button. Then hover the mouse over a variable in the program listing. The
variable value will be read and displayed at the mouse location. The variable value is read
only once when first hovering over the variable. To read the value again, move the mouse
away and return over that variable.

Embedding print statements is another common technique. Place print statements in

specific places of the script to verify that a given part of the code gets executed. Print the
value of variables you wish to see. To avoid large data dumps on the screen, add code to
print conditionally, for example when a variable changes or reaches a given value range.

32 RoboRun+ PC Utility Manual V3.0, September 3, 2022

 Connecting to Controller

Connecting to Controller
You can connect to the controller through serial communication (USB, RS232 or RS485) or
through TCP connection for models that supports TCP.

When the utility detects the controllers, it pops up asking for reading controller’s configuration.

Choosing Yes causes the utility to query for the controller’s configuration and updates the
utility’s configuration trees accordingly.

It is highly recommended to load the controller’s configurations first before attempting to make
any changes in order to make sure that the configurations are in sync with the controller.

Note: For safety, you need to make sure that the connected motors to the controller are
not running during loading/saving of the configuration from/to device.

USB/Serial
The utility checks for controllers on all available COM ports when the COM Port options is
set to Auto.

If the utility cannot find the controller, you can manually choose the port from the COM
Port list. Choosing the COM port causes the utility to not handshakes with the controller
and this is suitable when there are issues with the controller.

TCP
In controllers that supports Ethernet, you connect to the controller using TCP connection.
In order to do that, you should know the IP address and communication port of the con-
troller and make sure that TCP is enabled in the controller.

The TCP configuration could be set using the utility from the configuration tab:

In order to connect to the controller through TCP:

• Choose TCP from COM Port drop down list.
• Type in the IP address and port:

RoboRun+ PC Utility Manual 33

 Using the Roborun Configuration Utility

• Press Ok button.

Controller’s Pinout
In order to know the pinout of the controller, you can simply press View Pinout button
while the controller is connected or the model is selected in Work Offline mode.
The pinout form pops up with each connector configuration.

Note: Some connectors are upside down in the pinout form in order to retain pin ordering,
so rely only on the pin number in the connection.

For most recent configuration for each model, please refer to product’s datasheet on our
website.

34 RoboRun+ PC Utility Manual V3.0, September 3, 2022

 Locking Controller’s Configuration

Locking Controller’s Configuration

In order to make sure that the configuration is retained on the controller without accident-
ly changes, the controllers have a configuration locking/unlocking feature.

Locking the Configuration

• Make sure the controller is connected to the utility.
• From utility’s configuration tab, press Add/Remove Lock button.
• The Create Lock Key dialog appears.

• Type in an integer number representing your key and the same in the Confirm
Key box and press Ok button.
• Next time, when you try to load the configuration from the utility you will be asked
to enter the configuration key.

Unlocking the Configuration

• Make sure the controller is connected to the utility.
• From utility’s configuration tab, press Add/Remove Lock button.
• A configuration message appears, press Yes button.

RoboRun+ PC Utility Manual 35

 Using the Roborun Configuration Utility

• A dialog appears asking for the key. Type in the key and press Ok button.

Firmware Update
It is recommended to always have the latest firmware in order to be up to date with new
features and issue fixing.

You can visit our website for latest firmware release.

Update Firmware via COM Port

This method is used to update the controller’s firmware when it is connected through
RS232. You need to have the .bin or .zbin firmware file from our website.

In order to go with the update, make sure that the controller is connected through RS232
and all the connected motors is not running.

Go to the Console Tab and press Update Controller Firmware via COM Port button, the
following dialog appears.

36 RoboRun+ PC Utility Manual V3.0, September 3, 2022

 Firmware Update

Choose your firmware file and press Program button.

After the controller is updated, it will be restarted. Press the Close button to return back
to the utility.

Make sure that the new firmware version is reported in the Status Bar.

Update Firmware via USB

This method is used when the controller is connected through USB. This method uses
DFU (Device Firmware Update) method to do the update.

You need to have the .dfu or .zdfu firmware file in order to be able to update.

In order to do the update, go to the Console Tab and press Update Controller Firmware
via USB. The following confirmation message will popup, you need to press OK.

The device will be restarted in DFU mode and the DFU Loader utility will open.

RoboRun+ PC Utility Manual 37

 Using the Roborun Configuration Utility

Make sure that the device is selected in the combo box. Press Choose and point to the
firmware file.

After locating the firmware file, press Upgrade button.

You may have a confirmation message to ensure you are using the correct firmware file,
make sure you have the correct firmware file and press Yes button to continue.

After the firmware update, press Quit button in order to exit the DFU mode.

38 RoboRun+ PC Utility Manual V3.0, September 3, 2022

 Firmware Update

The device will be restarted, so you need to go back to the utility and make sure the con-
troller reports the new firmware in the Status Bar.

Firmware Update via CANOpen

Controllers equipped with a CAN interface can have their firmware updated via the
CANOpen protocol. The CANOpen firmware update process is performed with the Robo-
RunPlus PC utility.

This section/… provides a guide to the CANOpen firmware update. It describes the steps
to be performed in RoboRun+, the possible configurations of the CAN interface and how
to recover the application firmware in case of unexpected failure.

Step-by-step
Open the RoboRun+ PC utility and connect to the target Roboteq device.

In “Configuration” tab, the CAN interface tab shall be set to “CANOpen” mode and
“CANOpen Autostart” is shall be enabled. The configured Bit Rate and Node ID will be
used during the firmware update. See Figure 1-1.

RoboRun+ PC Utility Manual 39

 Using the Roborun Configuration Utility

FIGURE 1-1. CAN Interface in CANOpen mode

Next E-STOP shall be enabled by clicking on the “EMCY release” button in order firmware
update to be allowed. (Figure 1-2).

40 RoboRun+ PC Utility Manual V3.0, September 3, 2022

 Firmware Update

FIGURE 1-2. E-STOP enabled

In “Console” tab, the button “Update Firmware via CANOpen” shall be enabled. If it is
greyed out, then the controller family does not support CANOpen firmware update. By
clicking on the button, the firmware update process shall start. As shown in Figure 1-3,
the device was found at Node ID of 1 and Bit Rate of 1 Mbit/sec as shown in the “Con-
figuration” tab in Figure 1-1.

RoboRun+ PC Utility Manual 41

 Using the Roborun Configuration Utility

FIGURE 1-3. Starting CANOpen Firmware Update

In case the error in Figure 1-4 pops up instead, then the CAN interface is not in CANOpen
mode. It shall be set as shown in Figure 1-1.

FIGURE 1-4. Error: CAN interface not in CANOpen mode

42 RoboRun+ PC Utility Manual V3.0, September 3, 2022

 Firmware Update

After the CANOpen Firmware Loader connects to the Roboteq device, the firmware to
upload can be selected by clicking on the white button on the right the “firmware” label.
Once the firmware has been selected, the full path of the selected firmware is displayed
in the input box next to the “firmware” label. See Figure 1-5.

FIGURE 1-5. Selected firmware to upload

By clicking on “Update Firmware…”, the firmware update process shall start. The Firm-
ware Loader will request via SDO the Roboteq device to boot into its bootloader. Once
CANOpen communication between the Firmware Loader and the bootloader is estab-
lished, the upload of the firmware will begin. Figure 6 shows progress of a CANOpen
firmware upload.

Once the firmware upload is completed (Figure 1-7), the firmware application will be veri-
fied and booted if the procedure was successful.

After reconnecting to RoboRun+, the uploaded firmware version can be checked on the
bottom right corner of the utility. The Node ID and Bit Rate should be the same as the
one in Figure 1-1 and Figure 1-3.

RoboRun+ PC Utility Manual 43

 Using the Roborun Configuration Utility

FIGURE 1-6. CANOpen firmware update progress

44 RoboRun+ PC Utility Manual V3.0, September 3, 2022

 Firmware Update

FIGURE 1-7. CANOpen firmware update complete

CANOpen configurations
The parameters Node ID and Bit Rate of the application are passed to the bootloader in
case of a CANOpen firmware update request. These parameters are used to initialize the
CAN interface of the bootloader for CANOpen communication.

The available Node ID range is from 1 to 126 and the available bit rate 125Kb/s, 250Kb/s,
500Kb/s, 800Kb/s, 1000Kb/s (1Mb/s).

By communicating the Node ID and Bit Rate of the application to the bootloader, the only
input required by the user is the firmware to upload.

Alternatively, firmware update via CANOpen can be requested also with the DFU com-
mand. In that case no CAN parameters are passed to the bootloader. The default parame-
ters are used instead which are Node ID 126 and Bit Rate 125Kb/s. Once the CANOpen
firmware update is completed, the main application will be using the default Node ID and
Bit Rate. It is strongly advised to re-configure them right away to the desired, previously
used, values.

RoboRun+ PC Utility Manual 45

 Using the Roborun Configuration Utility

Recover Application via CANOpen

If the Roboteq device is not responding and not connecting via RoboRun+, then the firm-
ware application may have been corrupted. The Roboteq device is most likely running in its
bootloader and can be updated via CANOpen, if the device supports the CAN interface.

As a first step the Firmware Loader application inside the installation folder of the Robo-
Run+ utility shall be run. By trial and error, the Loader shall connect to the Roboteq device.
For the first try, the default Node ID 126 and Bit Rate 125Kb/s should be used. Select the
firmware to upload and start the update process. Once finished, by connecting to Robo-
Run+ the CAN interface can be configured with the desired parameters.

The default Node ID and Bit Rate values take into account application recovery. Default
Node ID 126 is the last available Node ID and it is expected that devices in a CANOpen
network are assigned Node IDs in an incremental fashion (1st device: 1, 2nd device: 2,
…). It is therefore strongly advised to avoid assigning value 126 to a device’s Node ID for
normal use. Default Bit Rate was set to the lowest rate of 125Kb/s to ensure the highest
success probability of the firmware update process.

Update Control Unit Logic (obsolete)

There are boards that have CPLD used for the controlling part of the motor controller. With
this button one can update the binary of the CPLD.

The update should be done only via RS232, an a testbench environment, and only power
control should be connected to the controller. Beware this action should be done only
with the support of a Roboteq technician, since any mal-function will end up with a unre-
sponsive board.

Update Power Unit Logic (obsolete)

There are boards that have CPLD used for the powering part of the motor controller. With
this button one can update the binary of the CPLD.

46 RoboRun+ PC Utility Manual V3.0, September 3, 2022

 Motor/Sensor Setup

The update should be done only via RS232, an a testbench environment, and only power
control should be connected to the controller. Beware this action should be done only
with the support of a Roboteq technician, since any mal-function will end up with a unre-
sponsive board.

Motor/Sensor Setup
Brushless motor controllers have the ability to automatically setup the motor and/or the
sensor (used for angle estimation) in order to perform optimally in sinusoidal mode. The
respective button “Motor/Sensor Setup” in diagnostics tab will initiate the abovemen-
tioned process.

This process supports the following commutation modes:

• Hall Sinusoidal Mode
• Hall+Encoder Sinusoidal Mode.
• Encoder Sinusoidal Mode.
• SPI/SSI Sinusoidal Mode.
• Sin/Cos Sinusoidal Mode.
• Resolver Sinusoidal Mode.
Before pressing this button, the following configuration fields need to be set:
• Number of Pole Pairs (according to motor manufacturer).
• Switching Mode (Sinusoidal or Sensorless).
• Reference Seek Power (usually half of the motor’s nominal current is enough).

RoboRun+ PC Utility Manual 47

 Using the Roborun Configuration Utility

• SinCos/SSI Sensor Poles (according to SSI or Sin/Cos or Resolver sensor manufac-

turer).
• Sensor Phase Shift Angle (according to Sin/Cos or Resolver sensor manufacturer).
• Sinusoidal Angle Sensor (according to the sensor used).
• Encoder Pulses/Rev (in case of Encoder or Hall+Encoder Sinusoidal mode).
• SPI/SSI Sensor Resolution (in case of SPI/SSI Sinusoidal mode).

Sinusoidal Mode
After pressing the button, the motor will move back and forth from 1 electrical revolution
up to 1 mechanical revolution, depending the sensor configured. If the motor is not mov-
ing smoothly try to increase the Reference Seek Power.
The main tasks of the process are:
• To determine the hall sensor alignment and adjust.
• To determine the Sin/Cos or Resolver sensor range and adjust.
• To determine where the zero angle is.
• To align motor and sensor directions.
During the process, the following configuration fields will be modified in order to achieve
optimal performance:
• Motor Pole Pairs (only the sign).
• Swap Windings.
• Angle Zero Adjust.
• Hall Sensor Angle Table.
• Sine/Cosine Calibration Values.
• Encoder Pulses/Rev (only the sign).
• SPI/SSI Sensor Resolution (only the sign).

Sensor Linearity Correction

Brushless motor controllers with firmware v2.0 and higher have the ability to automati-
cally determine whether a sensor has linearity issues and perform correction on it. The
respective button “ Sensor Linearity Correction” in diagnostics tab will initiate the above-
mentioned process, while the button “Reset Linearity Correction” will erase any kind of
correction that has been applied.

48 RoboRun+ PC Utility Manual V3.0, September 3, 2022

 Sensor Linearity Correction

This process is applicable only for the following sensors:

• SPI/SSI Sensor.
• Sin/Cos Sensor.
• Resolver Sensor.

RoboRun+ PC Utility Manual 49

 Using the Roborun Configuration Utility

After pressing the “Sensor “Linearity Correction” the motor will move for a couple of
revolutions until it determines the behavior of the sensor. Upon done a pop-up window
like the one above will be displayed. If the shape of the graph is sinusoidal-like then the
sensor can be considered as non-linear. Repeat the process a couple of times in order
to make sure that the behavior is recorded identically and until the graph has not spikes.
Then press the “Apply Correction” button in order to apply the correction to controller and
save to flash.

If the behavior of the motor after the correction is not better than before, then you can
remove the correction by pressing the “Reset Linearity Correction” button.

Motor Characterization

Brushless motor controllers with firmware v2.1 and higher have the ability in sinusoidal mode
commutation to automatically calculate the two axis (d-q) equivalent circuit characteristics (R,
Lq, Ld), in order to calculate effectively the torque mode FOC PI gains and operate as IPM
motor, if Lq > Ld. More specifically, the following characteristics are calculated:

1. Phase 1
a. Motor phase resistance Rs
b. D-axis inductance Ld

c. Q-axis inductance Lq

4. Phase 2
a. FOC Flux PI gains
b. FOC Torque PI gains

The respective button “Motor Characterization” in diagnostics tab will initiate the
abovementioned process as shown in below figure.

50 RoboRun+ PC Utility Manual V3.0, September 3, 2022

 Motor Characterization

Important Warning
The motor characterization process is supported only by USB communication.

For the motor equivalent circuit calculation, the motor is locked on d and q axes and
the resistance, inductance values at various electric frequencies are calculated from
motor equivalent circuit equations, utilizing motor phase voltage, current instantaneous
measurements and appropriate Clarke transformation.

The only parameter needed to be configured for the motor characterization is the
“Reference Seek Power”. This parameter can be configured either from the configuration
tab or from the motor characterization tool from the Phase 1 of the motor characterization
wizard tool as shown below. It is recommended to use motor nominal RMS current as
reference seek power.

RoboRun+ PC Utility Manual 51

 Using the Roborun Configuration Utility

Then, press “Start” and the process will start. It is noted that during the process the
motor will slightly move and will produce some noise due to the wide range of testing
frequencies utilized in order to calculate d, q axis motor inductances. No load should be
applied at the motor during characterization process (free shaft inertia operation).

After the successful finalization of the process, the R, Ld and Lq values will be shown in
the screen, as well as a “DONE” message will be printed in the log.

Next, the process continues to Phase 2, where the FOC gains will be calculated. The
user is able to select the current loop bandwidth from a wide range of 5 - 100 Hz. More
information regarding the FOC gains determination and tuning is included in chapter “Field
Oriented Control” at Section 8 of RoboteQ Controllers User Manual. After the bandwidth
selection, the calculated Torque and Flux FOC PI gains are illustrated in the screen.

52 RoboRun+ PC Utility Manual V3.0, September 3, 2022

 Motor Characterization

In order to set the calculated motor parameters and FOC gains, the user should press
“Save” at the finalization stage of the process as shown below. It is recommended to
evaluate the results before set them to the controller’s configuration.

The motor characterization process employs a wide variety of safety features, in order to
achieve good accuracy in the provided results. Therefore, one of the following errors could
appear at the Phase 1 logs, aborting the motor parameters and FOC gains calculation process:

1. “PROCESS ABORTED (RESTARTED TWICE)!”. This error appears in case of a

communication error between Roborun+ Utility and motor controller. In this case it is
recommended to check the communication cable (USB) and try the process again.
2. “CONNECTION ERROR!”. This error appears in case the motor is not connected
correctly with the controller.
3. “CAN NOT REACH REFERENCE CURRENT!”. This error appears in case the motor
inductance is very high and the controller cannot reach the desired current at the
configured maximum time slot. In this case, it is recommended to insert the FOC
gains manually.

RoboRun+ PC Utility Manual 53

 Using the Roborun Configuration Utility

4. “CALCULATION ERROR!”. This error appears in case of high asymmetries between

phase currents or high dc offset component at each phase current waveform. This
kind of errors may be attributed to motor local magnetic saturation or stator windings
asymmetries, leading to abort the calculated R, Ld, Lq values. In this case, it is
recommended to increase the reference seek power (up to maximum permitted
motor current if applicable) and repeat the test. If the calculation error remains, it is
recommended to insert the FOC gains manually.
5. “FAULT FLAG APPEARED!”. This error appears in case of a controller fault flag
trigger during motor characterization process. More information regarding fault
flags is included in RoboteQ Controllers User Manual (query ?FF). In this case, it
is recommended to check thoroughly the motor drive setup and clear all fault flags
before repeating the test.

Motor Sensor and Tuning Setup Manual

Motor sensor and tuning setup wizard provides a complete motor drive system tuning
toolbox. The motor sensor and tuning setup wizard is supported for firmware versions
v3.0 and later. The wizard comprises of the following parts:
1. Motor Sensor Setup
2. Current Loop Auto Tuning
3. Speed Loop Auto Tuning

The motor sensor setup and/or current loop auto tuning processes can be skipped, in or-
der to cover cases where the motor sensor and FOC gains have already tuned.

In all tuning process steps, the user can stop or cancel in case of undesired movement/
motor status. In case of “Cancel” command applied from the wizard, the motor can revert
to the previous configuration.

This wizard is applicable only for brushless dc motor (BL) controllers with sinusoidal com-
mutation. Motor Sensor and Tuning setup button is located below “Collect Diagnostics” in
configuration tab.

54 RoboRun+ PC Utility Manual V3.0, September 3, 2022

 Motor Sensor and Tuning Setup Manual

Part 1: Motor sensor setup

The Motor sensor setup process is similar with the Motor/Sensor Setup process existed
in Diagnostics tab. Brushless motor controllers with firmware v3.0 and higher are capable
to automatically setup the motor and/or the sensor (used for angle estimation) to perform
optimally in sinusoidal mode using the wizard.

RoboRun+ PC Utility Manual 55

 Using the Roborun Configuration Utility

Important Warning
For the motor sensor setup process, the motor should not be connected to the load
(free shaft test).

This process supports the following sensor types:

• Hall Sinusoidal Mode
• Hall+Encoder Sinusoidal Mode
• Encoder Sinusoidal Mode
• SPI/SSI Sinusoidal Mode
• Sin/Cos Sinusoidal Mode
• Resolver Sinusoidal Mode

Configure
Before the sensor setup procedure implemented, the user needs to configure the follow-
ing parameters:

• Channel configured
• Number of Pole Pairs (according to motor manufacturer).
• Reference Seek Power (motor’s nominal current is recommended for this process)
• Motor Direction
• Sinusoidal Angle sensor type, according to the sensor used

Additionally, for each sensor type the following parameters needed to be set:
• Pulses/Rev (in case of Encoder or Hall+Encoder)
• SPI/SSI Number of Bits (in case of SPI/SSI)
• Counter Start Bit Position (in case of SPI/SSI)
• Sin/Cos SSI Sensor Poles (in case of SPI/SSI)
• SinCos/SSI Sensor Poles (according to SSI or Sin/Cos or Resolver sensor manufac-
turer).

Also before starting the sensor setup process, the user should ensure that the sensor op-
erated well and connected properly to the controller. Otherwise, wrong automatic sensor
result will be returned.

Setup Procedure
After pressing the “Run Setup Procedure” button, the motor will move back and forth
from 1 electrical revolution up to 1 mechanical revolution, depending the sensor config-
ured. If the motor is not moving at all check the wiring and sensor connections. If the mo-
tor is not moving smoothly try to increase the Reference Seek Power (A).

56 RoboRun+ PC Utility Manual V3.0, September 3, 2022

 Motor Sensor and Tuning Setup Manual

The main tasks of the process are:

• To determine the hall sensor alignment and adjust
• To determine the Sin/Cos or Resolver sensor range and adjust
• To determine where the zero (d-axis) angle is
• To align motor and sensor directions

During the process, the following configuration fields will be modified to achieve optimal
performance:
• Motor Pole Pairs (only the sign)
• Swap Windings ( ~SWD )
• Angle Zero Adjust ( ~BADJ )
• Hall Sensor Angle Table ( ~HSAT )
• Sine/Cosine Calibration Values
• Encoder Pulses/Rev (only the sign)
• SPI/SSI Sensor Resolution (only the sign)

Example from successful Motor Sensor Setup procedure in Hall+Encoder sensor. Logs
can also be saved to respective .txt file. After successful completion of the first channel,
the process can directly start configuring the remaining unconfigured channel (applicable
for dual channel controllers).

RoboRun+ PC Utility Manual 57

 Using the Roborun Configuration Utility

Part 2: Current Loop Auto Tuning

After the motor sensor setup successful completion, the controller should proceed to the
Current Loop Auto Tuning (Part 2). This current loop tuning part includes the automatic
tuning procedure through appropriate motor characterization, as well as further manual
fine-tuning process through current square waveform command process.

Important Warning
For the current loop auto tuning process, the motor should not be connected to the
load (free shaft tests).

Motor Characterization
Brushless motor controllers have the ability in sinusoidal mode commutation to automat-
ically calculate the two axis (d-q) equivalent circuit characteristics (R, Lq, Ld), in order to
effectively calculate the torque mode FOC PI gains and operate as IPM motor, if Lq > Ld.
More specifically, the following characteristics are calculated:
1. Motor phase resistance Rs
2. D-axis inductance Ld
3. Q-axis inductance Lq

The only parameter needed to be configured for the motor characterization is the “Ref-
erence Seek Power”, as shown in below figure. It is recommended to use motor nominal
RMS current as reference seek power.

For the motor equivalent circuit calculation, the motor is locked on d and q axes and the
resistance, inductance values at various electric frequencies are calculated from motor
equivalent circuit equations, utilizing motor phase voltage, current instantaneous mea-
surements, and appropriate Clarke transformation.

Then, press “Start” and the process will start. It is noted that during the process the
motor will slightly move and will produce some noise due to the wide range of testing fre-
quencies utilized in order to calculate d, q axis motor inductances. No load should be ap-
plied at the motor during characterization process (free shaft inertia operation). During the
motor characterization process, a progress bar in bottom left will be shown up for informa-
tion purposes. Furthermore, additional information for the process can be observed in the
Characterization Log, as illustrated in below example. After the successful finalization of
the process, the R, Ld and Lq values will be shown in the screen, as well as a motor char-
acterization completion message will be printed in the log.

Alternatively, the user can skip the motor characterization process by introducing manually
the resistance and d-q inductance values as shown in below figure. This option facilitates
the user in cases the motor parameters are already known from datasheet or from pre-
vious motor characterization process execution, as the wizard reads the already stored
values.

Important Warning
The motor characterization process is supported only by USB communication.

58 RoboRun+ PC Utility Manual V3.0, September 3, 2022

 Motor Sensor and Tuning Setup Manual

The motor characterization process employs a wide variety of safety features, in order to
achieve good accuracy in the provided results. Therefore, one of the following errors could
appear at the Motor Characterization logs, aborting the motor parameters and FOC gains
calculation process:
1. “aa Timout --> bb “. This error appears in case of timeout error in reading various pa-
rameters needed for the R, Ld, Lq calculation stage, where:
aa: The parameter realized the timeout error:
?P : Motor Output Power Applied
?V : Battery volts
?RAW : instantaneous current
bb: The characterization script stage where the timeout error triggered:
Init() : Initialization function of the process
Main() -> Rs_Estimation : Resistance calculation stage
Main() -> Ldq_Estimation: D-q inductances calculation stage
If this error appears 5 times, the motor characterization script will restart.
2. “Failed 5 times to get query answer, restarting ... (Make sure USB communication is
used)”. This error appears in case of timeout errors (five times) for the considered quer-
ries described above. In that case the script will restart. It is recommended to check
the USB communication.
3. “Unexpected exception caught (Code: {ExceptionExitCode}) , restarting ...”. This error
appears in case of unexpected exception error returned from Utility. Then, the script
will restart.

RoboRun+ PC Utility Manual 59

 Using the Roborun Configuration Utility

4. “PROCESS ABORTED (RESTARTED TWICE)!”. This error appears in case of a com-

munication error between Roborun+ Utility and motor controller. More specifically,
the script has been restarted twice due to timeout errors on requested querries or
unexpected exception errors triggered. In this case it is recommended to check the
communication cable (USB) and try the process again.
5. “CONNECTION ERROR!”. This error appears in case the motor is not connected cor-
rectly with the controller.
6. “CAN NOT REACH REFERENCE CURRENT!”.This error appears in case the motor induc-
tance is very high and the controller cannot reach the desired current at the configured
maximum time slot. In this case, it is recommended to insert the FOC gains manually.
7. “CALCULATION ERROR!”. This error appears in case of high asymmetries between
phase currents, high dc offset component at each phase current waveform or the re-
sulted R, Ld, Lq values are higher than the predefined thresholds. This kind of errors
may be attributed to motor local magnetic saturation or stator windings asymmetries,
leading to abort the calculated R, Ld, Lq values. In this case, it is recommended to
increase the reference seek power (up to maximum permitted motor current if appli-
cable) and repeat the test. If the calculation error remains, it is recommended to insert
the FOC gains manually.
8. “FAULT FLAG APPEARED!”. This error appears in case of a controller fault flag trigger
during motor characterization process (overheat, overvotlage etc.). More information
regarding fault flags is included in RoboteQ Controllers User Manual (query ?FF). In
this case, it is recommended to check thoroughly the motor drive setup and clear all
fault flags before repeating the test.

Current Gains
Next, the current loop tuning process continues to Current Gains page, where the FOC
gains will be calculated. The user is able to select the current loop bandwidth from a wide
range of 50 -1600 Hz for G4 products, based on the calculated motor resistance and
inductance values. More information regarding the FOC gains determination and tuning
is included in chapter “Field Oriented Control” at Section 8 of RoboteQ Controllers User
Manual. After the bandwidth selection, the calculated Torque and Flux FOC PI gains are
illustrated in the screen.

The bandwidth selected (Hz) is responsible for the current loop PI control responsiveness
and stability. The lower bandwidth selected the more tolerant the control is at motor
current turbulences, the higher bandwidth selected the faster responsiveness achieved.
Therefore, the appropriate bandwidth is dependent on the application and motor electric
time constant. The default bandwidth is set at 300 Hz.

Furthermore, there is also the opportunity the user to introduce manually the desired
gains in order to manually tune the current loop, by selecting the “Manual Entry”.

60 RoboRun+ PC Utility Manual V3.0, September 3, 2022

 Motor Sensor and Tuning Setup Manual

Step Command
In Step Command page, the controller will run some square waveform current commands
in Torque mode, in order to evaluate the current control performance and stability. The test
current waveform command should be as shown in following figure. The value needed to
be configured for the test waveform are the following:
• Positive Iq current command amplitude (A). Value range can be from 0-50% of the
Current limit set in the configuration. It is noted that the appropriate current limit
should be initially set at the configuration in order to apply the desirable amount of
positive current command amplitude.
• Negative Iq current command amplitude (A). Value range can be from 0-50% of the
Current limit set in the configuration. It is noted that the appropriate current limit
should be initially set at the configuration in order to apply the desirable amount of
negative current command amplitude.
• Test Wave Time period (ms), which is the respective time needed for the whole
waveform period. It is noted that the test is recommended to be done with motor
not moved due to the free shaft test, in order to be able to absorb the commanded
current. Therefore, a value from 20-100 msec is recommended, relative to motor
electric time constant.
• Repeat counts, which refers to the times the test waveform should run. Value
range is 1-100.

RoboRun+ PC Utility Manual 61

 Using the Roborun Configuration Utility

10
Positive command
5 amplitude (A)

10
1

5
-5
Negative command
amplitude (A)
-10
Period (msec)

When the user presses the “Run Waveform” button, the motor should operate according
to the reference test waveform. An example is shown in the following figure. The desired
parameters can be selected in the chart box. Additionally, a configuration toolbox is intro-
duced in order to multiply/offset appropriately the reported parameters.

From the graph, the motor current can be observed in order to evaluate the current loop
performance with the applied FOC gains. There is also opportunity to zoom in x-axis
through mouse wheel + shift button and in y-axis through mouse wheel + ctrl button. The
graph can return to the former scaling by double click.

The 1msec stream data shown in the graph can be exported in .xlsx file through the ap-
propriate toolbox marked below for further analysis. Furthermore, the process provides
the opportunity to re-tune the FOC gains in “Current Gains” collapse button.

62 RoboRun+ PC Utility Manual V3.0, September 3, 2022

 Motor Sensor and Tuning Setup Manual

Finalize
In order to set the calculated motor parameters and FOC gains, the user should press
“Save & Next” at the finalization stage of the process as shown below. It is recommend-
ed to evaluate the results before setting them to the controller’s configuration.

Part 3: Closed loop Speed PI tuning

After the motor sensor setup and current loop tuning successful completion, the motor
drive shall proceed to the close loop speed auto tuning process. In this part, the following
capabilities are provided:
1. Automating PI tuning procedure through appropriate calculation of mechanical system
inertia J and rotating friction B.
2. Manual fine-tuning process through speed square waveform command process
3. Manual fine-tuning process through ramped waveform command process

Important Warning
For the speed loop auto tuning procedure, the motor should be connected to the
actual load of the application.

RoboRun+ PC Utility Manual 63

 Using the Roborun Configuration Utility

Feedback Sensor and Auto Tuning Configuration

In feedback sensor configuration page, the sensor utilized for close loop speed feedback
value is configured.

Next, in auto-tuning configuration the necessary values needed for automatic speed loop
PI tuning operation as well as for the safety mechanism should be set as shown in below
figure. It is noted that during the speed loop automatic PI tuning process, the motor will
accelerate up to half of the maximum configured speed and then decelerate quickly up to
zero speed in order to calculate application’s inertia (J) and rotating friction (B). Therefore,
it is necessary to monitor the distance (rotary or linear) of the motor in order to stop safely
the system before hitting any obstacle or the speed difference between motor channels in
case of concurrent operation, in order to prevent any undesirable movement.

64 RoboRun+ PC Utility Manual V3.0, September 3, 2022

 Motor Sensor and Tuning Setup Manual

The application categories supported by the automatic PI function are described in the
following figure.

Rotary Linear
movement movement

Single Ch Dual Ch Single Ch Dual Ch

Boards Boards Boards Boards

One One
Concurrent Concurrent
channel channel

Non AGV AGV -

traction traction

• Wheel radius
• Gear ratio • Gear ratio • Wheel radius
• Max rotation angle • Max angle diff • Max distance • Gear ratio
(mechanical deg) • Gear ratio • Wheelbase length
• Max speed diff
• Safety zone radius

Below is an auto tuning configuration parameters description:

Movement type:
Linear (linear movement of the mechanical system)

Rotary (rotary movement of the mechanical system)

Tuning target:
Channel 1 (Tune only channel 1)

Channel 2 (Tune only channel 2)

Concurrent (Tune both channels concurrently).

Important Warning
Motors need to operate on the same mechanical system and both channels sensor
setup and current loop tuning should have been successfully completed.

Traction application:
AGV traction (AGV traction application tuning)

Non-AGV traction (Non-AGV traction application tuning)

Wheel/shaft radius (m): (Rotor wheel or shaft radius in meters)

Gearbox ratio: (Motor’s gearbox ratio)

RoboRun+ PC Utility Manual 65

 Using the Roborun Configuration Utility

Max distance (m): (maximum allowed distance during the procedure)

Wheelbase length (m): (distance between wheels)

Radius of safety zone (m): (radius of the maximum space the AGV can cover during the
procedure)

Max speed difference(RPM): (maximum allowed speed difference between the two mo-
tors during the procedure)

Max angle difference (deg): (maximum allowed angle difference between the two motors
during the procedure)

Max rotation angle (deg): (maximum allowed angle for the motor movement during the
procedure)

Configuration parameters
Except from safety configuration options described above, it is very important to config-
ure properly the auto-tuning script parameters.
• The selected maximum speed should be the maximum motor speed according to
the datasheet, as the higher mechanical speed achieved the more accurate the ro-
tating friction coefficient estimation is.
• The current limit configured for the test should be relevant to the application, as
different current command applied based on the application’s power rating. There-
fore, if for example an FBLG controller is used but the mechanical system is under
no load (e.g. free shaft load test), then the amps limit should not be set at 60A,
which is the controller’s maximum current, but to a much lower value e.g 10 A.
• The torque constant of the motor is expressed in produced Nm per peak current
amplitude. It is noted that in cases of applications where a motor with gearbox is
utilized, only the motor torque constant should be set without the gearbox.

Auto PI Tuning
Brushless motor controllers and IPM motors are capable to automatically calculate the ap-
plication’s mechanical system inertia and friction, in order to tune the speed loop PI gains.
After the successful automatic PI tuning configuration described above, the process can
start by pressing the “Start PI tuning” button shown below. Next, the wizard will down-
load the autotune function script and the motor drive will start accelerating and then de-
celerating to zero speed. Finally, the mechanical system inertia J (in kg.cm2) and rotating
friction B (in mNm/rad/sec) will be illustrated in the Auto-PI tuning log. Alternatively, there
is a Skip Auto PI Tuning (Manual Gains) button, in order to tune manually the speed loop PI
gains.

Detailed logs can be saved from the process by pressing the “Save Log” or “Copy Log”
shown below, for further analysis and investigation. An example of autotune process main
parameters variation with time (ms), such as motor power, ramped command, torque
amps, flux amps and speed, is shown in below figure.

The speed loop automatic PI tuning process employs a wide variety of safety and accu-
racy features, in order to achieve good accuracy in the provided results, as well as safety
and reliable motor operation on the permitted space set by user. Therefore, one of the
following errors could appear at the Auto PI tuning logs, aborting the inertia/friction param-
eters and speed gains calculation process:
1. “Insert appropriate FOC Torq gains”. This error appears in case the current loop PI gains
have not configured. In this case, it is recommended to configure appropriately the
current control loop and repeat the test.

66 RoboRun+ PC Utility Manual V3.0, September 3, 2022

 Motor Sensor and Tuning Setup Manual

2. “Fault!! = nn”, where nn is the respective fault flag value. This error appears in case of
a controller fault flag trigger during auto PI tuning process. More information regarding
fault flags is included in RoboteQ Controllers User Manual (query ?FF). In this case,
it is recommended to check thoroughly the motor drive setup and clear all fault flags
before repeating the test.
3. “rpm1 vs rpm2 (accel) = nn vs mm”, where nn is motor 1 speed and mm is the motor
2 speed. This error appears in case of a non-traction linear movement dual channel
concurrent operation when the motor 1 speed differs much compared to motor 2
speed during acceleration, based on the configured permissible speed difference.
Then, for safety reasons the system should stop, by applying safety stop mechanism,
in order to prevent any potential damage. In such case the bit 0 of safety status pa-
rameter will be set to one. It is recommended to check thoroughly the mechanical sys-
tem and the load distribution of the application, before repeating the test.
4. “Ang1 vs Ang2 (accel) = nn vs mm”, where nn is motor 1 angle and mm is motor 2
angle. This error appears in case of a non-traction rotary movement dual channel con-
current operation when the motor 1 speed differs much compared to motor 2 speed
during acceleration, based on the configured permissible angle difference. Then, for
safety reasons the system should stop, by applying safety stop mechanism, in order
to prevent any potential damage. In such case the bit 3 of safety status parameter will
be set to one. It is recommended to check thoroughly the application’s mechanical
system and the load distribution, before repeating the test.
5. “AGV exceeds permissible area”. This error appears in case of AGV traction linear
movement dual channel concurrent operation when AGV trajectory exceeds during ac-
celeration the permissible area based on the configured maximum distance. Then, for
safety reasons the system should stop, by applying safety stop mechanism, in order
to prevent any potential damage. In such case the bit 1 of safety status parameter will
be set to one. It is recommended to increase the area arranged for the autotune test,
before repeating it.
6. “Tot dist/ang till saf stop (accel) = nn”, where nn is the total distance (for linear move-
ment) or the total angle (for rotary movement). This error appears in case of a single
channel operation when the motor exceeds the permissible length/angle during accel-
eration, based on the configured maximum distance/angle. Then, for safety reasons
the system should stop, by applying safety stop mechanism, in order to prevent any
potential damage. In such case the bit 2 of safety status parameter will be set to one.
It is recommended to increase the area arranged for the autotune test, before repeat-
ing it.
7. “ch1 decel to 0 & ch2 still accel”. This error appears in dual channel concurrent oper-
ation (same mechanical system for both channels) when the Ch1 motor decelerates
with the Ch2 motor continues to accelerate. This situation provide accuracy errors
in dual channel concurrent operation, due to the fact that the motor continuing to
accelerate should satisfy the load, as well as the braking force from the decelerating
motor. In such case the bit 0 of accuracy status parameter will be set to one. It is rec-
ommended to check thoroughly the mechanical system and the load distribution of the
application, before repeating the test.
8. “ch2 decel to 0 & ch1 still accel”. This error appears in dual channel concurrent oper-
ation (same mechanical system for both channels) when the Ch2 motor decelerates
with the Ch1 motor continues to accelerate. This situation provide accuracy errors
in dual channel concurrent operation, due to the fact that the motor continuing to
accelerate should satisfy the load, as well as the braking force from the decelerating
motor. In such case the bit 1 of accuracy status parameter will be set to one. It is rec-
ommended to check thoroughly the mechanical system and the load distribution of the
application, before repeating the test.
9. “Big J divergence”. This error appears in dual channel concurrent operation (same
mechanical system for both channels) when high divergence between the calculated

RoboRun+ PC Utility Manual 67

 Using the Roborun Configuration Utility

inertia of Ch1 and Ch2 exists. In such case the bit 2 of accuracy status parameter will
be set to one. It is recommended to check thoroughly the mechanical system and the
load distribution of the application, before repeating the test.
10. “Big B divergence”. This error appears in dual channel concurrent operation (same
mechanical system for both channels) when high divergence between the calculated
friction of Ch1 and Ch2 exists. In such case the bit 3 of accuracy status parameter will
be set to one. It is recommended to check thoroughly the mechanical system and the
load distribution of the application, before repeating the test.
11. “J/B out of range”. This error appears when the calculated inertia/friction is above the
upper or below the lower limit, resulted from a calculation/accuracy error during auto-
tune test. In such case the bit 4 of accuracy status parameter will be set to one. It is
recommended to check thoroughly the mechanical system and the load distribution of
the application, before repeating the test.
12. “Speed diff > nn”, where nn is in speed rpm. This error appears in dual channel concur-
rent operation when the measured speed difference between channels is higher than
1/6 of the configured max speed for considerable amount of time, resulting to accu-
racy error. In such case the bit 5 of accuracy status parameter will be set to one. It is
recommended to check thoroughly the mechanical system and the load distribution of
the application, before repeating the test.

The maximum length/rotating angle configured by the user is considered for both accel-
eration and deceleration part of the autotuning function. It is noted that generally equal
mechanical system load distribution, as well as same motor 1 and 2 torque constant are
needed in order to perform safely the test and calculate accurately the system’s inertia
and friction.

68 RoboRun+ PC Utility Manual V3.0, September 3, 2022

 Motor Sensor and Tuning Setup Manual

Important Warning
The speed Auto-PI tuning process is supported only by USB communication.

Speed Gains
Next, the speed loop tuning process continues to Speed Gains page, where the gains will
be calculated. The user is able to select the speed loop bandwidth from a wide range of
0.1 – 50.0 Hz, based on the calculated mechanical system inertia and rotating friction. Af-
ter the bandwidth selection, the calculated speed PI gains are illustrated in the screen.

The bandwidth selected (Hz) is responsible for the speed loop PI control responsiveness
and stability. The lower bandwidth selected the more tolerant the control is at speed
feedback oscillations and resonances provoked from the mechanical system, the higher
bandwidth selected the faster responsiveness achieved. Therefore, the appropriate band-
width is dependent on the application and mechanical system time constant. The default
bandwidth is set at 1 Hz.

Furthermore, there is also the opportunity the user to introduce manually the desired
gains in order to manually tune the speed loop, by selecting the “Manual PI Gains”.

RoboRun+ PC Utility Manual 69

 Using the Roborun Configuration Utility

Step Command
In Step Command page, the controller will run some square waveform speed commands
in Close Loop Speed mode, in order to evaluate the speed control performance and stabil-
ity. The test speed waveform command should be as shown in following figure. The value
needed to be configured for the test waveform are the following:
1. Positive speed command amplitude (rpm). Value range can be from 0-25% of the Max-
imum Speed set in the configuration.
2. Negative speed current command amplitude (rpm). Value range can be from 0-25% of
the Maximum Speed set in the configuration.
3. Test Wave Time period (ms), which is the respective time needed for the whole wave-
form period. It is worth mentioning that the time period selected should be appropriate
for the rotor speed to reach the commanded value. Therefore, a value of 100-3000
msec is recommended, relative to the mechanical system time constant.
4. Repeat counts, which refers to the times the test waveform should run. Value range is
1-20.

70 RoboRun+ PC Utility Manual V3.0, September 3, 2022

 Motor Sensor and Tuning Setup Manual

100
Positive command
amplitude (rpm)
50

93

1013
1

185
277
369
461
553
645
737
829
921
-50
Negative command
amplitude (rpm)
-100
Period (msec)
Speed CMD

When the user presses the “Run Waveform” button, the motor should operate according
to the reference test waveform. An example is shown in the following figure. The desired
parameters can be selected in the chart box. Additionally, a configuration toolbox is intro-
duced in order to multiply/offset appropriately the reported parameters.

From the graph, the speed current can be observed in order to evaluate the speed loop
performance with the applied speed PI gains. There is also opportunity to zoom in x-axis
through mouse wheel + shift button and in y-axis through mouse wheel + ctrl button. The
graph can return to the former scaling by double click.

The 1msec stream data shown in the graph can be exported in .xlsx file through the ap-
propriate toolbox marked below for further analysis. Furthermore, the process provides
the opportunity to re-tune the PI gains in “Speed Gains” collapse button.

RoboRun+ PC Utility Manual 71

 Using the Roborun Configuration Utility

Ramped Command
In Ramped Command page, the controller will run some ramp waveform speed com-
mands in Close Loop Speed mode, in order to evaluate the speed control performance
and stability. The test speed waveform command should be as shown in following figure.
The value needed to be configured for the test waveform are the following:
• Positive speed command amplitude (rpm). Value range can be from 0-100% of the
Maximum Speed set in the configuration.
• Negative speed command amplitude (rpm). Value range can be from 0-100% of the
Maximum Speed set in the configuration.
• Test Wave Time period (ms), which is the respective time needed for the whole
waveform period. It is worth mentioning that the time period selected should be
appropriate for the rotor speed to reach the commanded value, also considering
the acceleration and deceleration time. Therefore, a value of 1000-10000 msec is
recommended, relative to the mechanical system time constant. acceleration, de-
celeration, and final speed command values.
• Repeat counts, which refers to the times the test waveform should run. Value
range is 1-10.

800

Positive command
600
amplitude (rpm)

400

200

0
1
227
453
679
905
1131
1357
1583
1809
2035
2261
2487
2713
2939
3165
3391
3617
3843
4069
4295
4521
4747
4973
5199
5425
5651
5877
6103
6329
6555
6781
7007
7233
7459
7685
7911
8137
8363
8589
8815
9041
9267
-200 Period (msec)

-400

Negative command
-600
amplitude (rpm)

-800

When the user presses the “Run Waveform” button, the motor should operate according
to the reference test waveform. An example from concurrent operation is shown in the
following figure. The desired parameters can be selected in the chart box. Additionally, a
configuration toolbox is introduced in order to multiply/offset appropriately the reported
parameters.

From the graph, the motor speed can be observed in order to evaluate the speed loop
performance with the applied PI gains. There is also opportunity to zoom in x-axis through
mouse wheel + shift button and in y-axis through mouse wheel + ctrl button. The graph
can return to the former scaling by double click.

The 1msec stream data shown in the graph can be exported in .xlsx file through the ap-
propriate toolbox marked below for further analysis. Furthermore, the process provides
the opportunity to re-tune the PI gains in “Speed Gains” collapse button.

72 RoboRun+ PC Utility Manual V3.0, September 3, 2022

 Motor Sensor and Tuning Setup Manual

Finalize
In order to set the controller parameters and calculated speed PI gains, the user should
press “Save & Finish” at the finalization stage of the process as shown below. It is rec-
ommended to evaluate the results before setting them to the controller’s configuration.
The operating mode also finally applied from the tuning wizard also shown for monitoring
purposes.

Then, the tuning process is finished. You can validate that the calculated gains and con-
troller parameters have been correctly configured by pressing the “Load from Controller”
command in the configuration tab of Roborun+.

RoboRun+ PC Utility Manual 73

 Using the Roborun Configuration Utility

74 RoboRun+ PC Utility Manual V3.0, September 3, 2022