Configuration & Operation

Firmware Version:

The driver can be controlled through a CAN Bus interface. By using our NLink Adapter, it can also be connected via USB, allowing for configuration and control through the NMotion CLI Tool and NMotion Transport Library.

The API functions that can be used with the driver can be found here: NDrive Z1 API documentation

Hardware Configuration

CAN Bus Configuration

The board utilizes a daisy chainable CAN bus for control. If multiple devices are present on the CAN bus, ensure that a unique CAN Node ID is assigned to the driver. The allowable values of CAN Node ID is in the range of 0 to 127. The default CAN Node ID is 0 and must be modified to avoid communication conflicts.

info

On setting the CAN Node ID, the driver will automatically save the CAN node ID and reboot.

The API functions involved in this configuration are as follows:

• Driver.setNodeId(id: int)
• Driver.getNodeId()

Power Configuration

Voltage Trigger Levels

The board features undervoltage and overvoltage protection mechanisms to ensure the safe operation of the driver and other components. If the bus voltage drops below the undervoltage threshold or exceeds the overvoltage threshold, the driver will enter idle mode and generate a DC_BUS_UNDER_VOLTAGE or DC_BUS_OVER_VOLTAGE error, respectively.

By default the under voltage level is set to 10 V and the over voltage level is set to 56 V.

The API functions involved in this configuration are as follows:

• Driver.setDCBusTripLevels(undervoltage_level: float, overvoltage_level: float)
• Driver.getDCBusTripLevels()

Brake Resistor and Maximum Regeneration Current Trigger Level

The board integrates a chopper circuit for braking, enabling the connection of an external brake resistor. If a brake resistor is used, its resistance value must be configured. Additionally, the amount of current to be dumped into the power bus can be specified, with the remaining current being dissipated through the brake resistor. This ensures that the power supply remains protected from excessive current dumping.

It is recommended to use a brake resistor when powering the driver with a power supply that does not support power dumping. In the case of battery power, regenerative braking allows the battery to recharge itself by utilizing the reverse current.

danger

Ensure a properly rated power resistor is used for dumping regenerative currents, as an incorrectly rated resistor may fail during operation.

If the regeneration current exceeds the configured maximum limit, the driver will enter idle mode and generate a DC_BUS_OVER_REGEN_CURRENT error. This condition can arise from either a saturated brake resistor or excessive current dumping into the power bus when the brake resistor is disabled.

info

Saving the configuration is necessary for the brake configuration to take effect in the driver.

The API functions involved in this configuration are as follows:

• Driver.enableBrakeResistor(brake_resistance_value: float)
• Driver.disableBrakeResistor()
• Driver.getBrakeResistorState()
• Driver.setRegenCurrentTripLevel(regen_current_trip_level: float)
• Driver.getRegenCurrentTripLevel()

Motor Configuration

The driver requires specific motor parameters to ensure proper operation:

• Pole Pair: This value is crucial for accurate phase energization. Incorrect configuration may result in a CPR_POLEPAIRS_MISMATCH error during calibration.
• kV Rating: This value is used to calculate the torque constant, which in turn determines the torque output of the motor.

Additionally, the motor's current limit (in Amperes) must be appropriately set to prevent excessive current draw and potential damage. A CURRENT_LIMIT_VIOLATION error will be triggered if the motor current exceeds the configured limit. To maintain optimal motor performance and minimize noise in the current sensing circuit, it is recommended to avoid setting the current limit above 60A.

The API functions involved in this configuration are as follows:

• Driver.setMotorParameters(pole_pairs: int, kV_rating: int, current_limit: float)
• Driver.getMotorParameters()

Encoder Configuration

The controller supports dual encoder mode. One encoder must be used as a motor encoder to control the rotor precisely, and one encoder can be configured as an output encoder (optional). You can configure the onboard absolute encoder or an external incremental encoder, or external SPI-based absolute encoder as either motor or ouput encoder.

• For the absolute encoder, the resolution (in number of possible values : 2^bits) value must be configured.
• For the incremental encoder, the CPR value and index usage must be configured.

If the configuration is not set properly then the driver could throw a CPR_POLEPAIRS_MISMATCH error when undergoing calibration.

info

The resolution of the onboard encoder is fixed to 14 bits and cannot be changed.

The configuration for different encoders are as follows:

Encoder Type Value	Encoder Type	Description
0	TYPE_NONE	Using no encoder
1	TYPE_ONBOARD_ENCODER	Using onboard absolute encoder (Tested)
2	TYPE_INCREMENTAL	Using External incremental Encoder (Tested)
3	TYPE_SPI_ABS_AMS	Using AS5047P absolute encoder from AMS (Tested)
4	TYPE_SPI_ABS_MAXXX	Using MAXXX series absolute encoders from Monolith Power Systems (Tested with MA732, MA702)
5	TYPE_SPI_ABS_MUXXX	Using MU series absolute encoders from iC-Haus (Tested with MU150, MU200)
6	TYPE_SPI_ABS_CUI	Using AMT 203 absolute encoder from CUI (Tested)
7	TYPE_SPI_ABS_AEAT	Using AEAT absolute encoders from Broadcomm (To be tested)
8	TYPE_SPI_ABS_RLS	Using RLS absolute encoders from Renishaw (To be tested)

In case you have a gearbox connected to the motor and the output encoder is connected to the gearbox output, then we can configure the gear ratio in the driver itself. This will relate the output encoder and the motor encoder values with that gear ratio. The default value of gear ratio is set to 1.

info

Saving the configuration is necessary for the encoder configuration to take effect in the driver.

The API functions involved with this configuration are as follows:

• Driver.configureMotorEncoder(encoder_type: int, resolution_param: int, use_index: bool)
• Driver.getMotorEncoderConfiguration()
• Driver.configureOutputEncoder(encoder_type: int, resolution_param: int, use_index: bool)
• Driver.getOutputEncoderConfiguration()
• Driver.disableOutputEncoder()
• Driver.setGearBoxParameters(gear_ratio: float)
• Driver.getGearBoxParameters()

Calibration Configuration

Before running the motor, the driver needs to do a calibration step. In this step the driver estimates the phase parameters of the motor and finds the motor encoder offset parameters.

It is crucial that the encoder and motor configuration is done properly before running calibration or it will throw errors such as CPR_POLEPAIRS_MISMATCH. The motor and encoder parameters are crucial for properly controlling the motion of the motor.

For calculating the phase parameters, calibration_voltage and calibration_current values are used. The default value for calibration_voltage is 5V and calibration_current is 5A. The maximum resistance of the motor which the driver can measure is given by the value of calibration_voltage/calibration_current (so for the default case, the driver will be able to measure motor phase resistances upto 1Ω). In case the resistance of the motor falls outside the measurable range of the driver, the driver will throw a PHASE_RESISTANCE_OUT_OF_RANGE error during calibration. To overcome this, one needs to change the value of calibration_voltage or calibration_current to increase the range of resistance the driver can measure (increasing calibration_voltage or decreasing calibration_current will increase the range). Considering the inductance, make sure that the phase inductance value of the motor is between 2 µH and 4000 µH, or else the driver will throw a PHASE_INDUCTANCE_OUT_OF_RANGE error during calibration.

info

The motor will rotate in clockwise and counterclockwise direction during the calibration process.

The API functions involved in this configuration are as follows:

• Driver.setMotorCalibrationParameters(motor_calib_voltage: float, motor_calib_current: float)
• Driver.getMotorCalibrationParameters()

Thermal Limit Configuration

The board uses an onboard NTC thermistor to measure the driver's temperature during the operation. The configuration for thermal limiting using this on-board thermistor cannot be changed, the driver will start limiting the current once the board temperature reaches 110°C. When the board temperature reaches 120°C, it will turn off the power to the motor and will set the error to FET_THERMISTOR_OVER_TEMP. If this limit is being reached, then it is suggested to add an active cooling mechanism to the MOSFETs on the board which will help to keep the temperature in safe levels during the operation.

Additionally, the board also supports an external motor NTC thermistor that can be used to limit the motor currents when the motor temperature goes beyond a safe limit. If the external motor thermistor is connected then one needs to configure the r_ref value (resistance at 25°C), beta value (Temperature coefficient of resistance) and the upper_limit value (in °C). The current limiting will start when the temperature reaches a value of upper_limit - 10 (in °C). When the motor temperature reaches the upper_limit value, the driver will turn off the power to the motor and will set the error to MOTOR_THERMISTOR_OVER_TEMP . If this limit is being reached, additional cooling is recommended to help maintain the motor's temperature within safe limits during operation.

The API functions involved in this configuration are as follows:

• Driver.setMotorThermistorParameters(r_ref: int, beta: int)
• Driver.getMotorThermistorConfiguration()
• Driver.enableMotorThermalLimit(upper_limit: int)
• Driver.disableMotorThermalLimit()

Startup Configuration

warning

This can only be configured after running the full calibration sequence at least once and saving the configuration. Setting startup configuration without setting all other motor and encoder parameters would cause the driver to throw errors.

The driver supports configuring startup events that should automatically happen once the driver starts. It supports these events

• Start motor encoder index search on startup. This is only applicable when an incremental encoder is being used as a motor encoder.
• Start encoder matching on startup to make sure that the output encoder and motor encoder is matched after the driver turns on. This is only applicable when an output encoder is properly configured.
• Go into a particular control mode when the driver starts up. The control mode will depend on the mode in which the configuration to the driver was last saved. However, the commanded values within the selected control mode are not retained. For example, if the driver was saved in position control mode with the motor set to a specific position, it will start in position control mode but remain at the current position without moving to the previously set position. Similarly, if saved in velocity control mode, the driver will start with velocity control enabled and a commanded velocity of zero, rather than resuming any prior velocity. This behavior also applies to current control mode, where the driver will start with a commanded current of zero.

The API functions involved in this configuration are as follows:

• Driver.setStartupConfigs(index_search: bool, encoder_matching: bool, closed_loop: bool)
• Driver.getStartupConfigs()

Controller Configuration

The controller in the driver is a cascading style controller with cascaded position, velocity and current control loops. When the control mode is set to position control or trajectory control, all of the cascaded controller runs. When running in velocity control mode, the position control part is removed and the velocity command is directly given to the velocity controller. Similarly, in torque control mode, only the current controller loop runs.

The controllers used in each of the loops is a variation of PID Controllers

Position Control Loop

Its a proportional controller with a single gain value (pos_gain). The output of the controller, velocity_command is calculated as follows:

velocity_command = pos_gain * (position_command - position_feedback)

Velocity Control Loop

Its a proportional-integral controller with a single gain value (vel_gain) and a single integrator gain (vel_integrator_gain). The output of the controller, current_command is calculated as follows:

vel_integral += vel_integrator_gain * (velocity_command - velocity_feedback)
current_command = vel_gain * (velocity_command - velocity_feedback) + vel_integrator_gain * (vel_integral)

Current Control Loop

Its a proportional-integral controller with a single gain value (current_gain) and a single integrator gain value (current_integral), the gain values of this loop is calculated based on the motor's phase parameters (phase resistance and phase inductance) and a current controller bandwidth parameter.

current_gain = current_control_bandwidth * motor_phase_inductance
current_integrator_gain = current_gain * (motor_phase_resistance / motor_phase_inductance)
current_integral += current_integrator_gain * (current_command - current_feedback)
motor_command = current_gain * (current_command - current_feedback) + current_integral

The gain values of the loop can be changed according to the needs of the application. If the gains cause an instability in the system, then the driver will throw a UNSTABLE_CONTROLLER_GAIN error.

The API functions involved in this configuration are as follows:

• Driver.setPositionControllerGain(position_gain: float)
• Driver.getPositionControllerGain()
• Driver.setVelocityControllerGains(vel_gain: float,vel_integrator_gain: float)
• Driver.getVelocityControllerGains()
• Driver.getCurrentControllerGains()
• Driver.setCurrentControllerBandwidth(bandwidth: float)
• Driver.getCurrentControllerBandwidth()

Saving Configuration

Upon completing the configuration process, the settings can be saved to the driver's non-volatile memory. This ensures that the configurations are retained even after a power cycle or device restart. Saving the configuration will trigger an automatic device reboot.

The following configurations in the driver are saved:

• CAN Bus Configuration : CAN Node ID of the device.
• Power Configuration : Voltage trigger levels (under voltage and over voltage trigger levels), Brake resistor enable/disable status, Brake resistor value, Maximum regeneration current trip level.
• Motor Configuration: Motor Pole pair, KV rating and current limit values.
• Encoder Configuration: Motor Encoder parameters (type, resolution parameter & use_index flag), Output Encoder parameters (type, resolution parameter & use_index flag) and Gearbox ratio.
• Calibration Configuration: Motor calibration voltage, Motor calibration current and Post-Calibration Parameters (motor encoder offset value, phase resistance and phase inductance).
• Thermal Limit Configuration: Motor Thermistor Parameters (r_ref and beta) and Thermal upper limit.
• Startup Configuration: All the flags to set the events on startup: index_search, encoder_matching and closed_loop.
• Controller Configuration: Control Loop parameters (position gain, velocity gain, velocity integrator gain, current controller bandwidth) & Control Mode without the commanded value.

warning

The configuration data is stored in the microcontroller's onboard EEPROM memory. To prolong the memory's lifespan, it is recommended to limit the frequency of configuration updates, as EEPROMs have a finite number of write cycles.

The API functions involved in this configuration are as follows:

• Driver.saveConfigurations()
• Driver.eraseConfigurations()
• Driver.rebootDriver()

Operation

Connection

The board uses a CAN bus to retrieve data and send commands to the driver. The driver can be controlled either through a native CAN interface or connected to a PC via USB using an NLink Adapter. Regardless of the interface used, the NMotion Transport Library can be used to control the driver.

Calibration

Before operation it is necessary to do the calibration step in which the driver finds out the motor phase and motor encoder offset parameters required for the motion of the motor. In case the motor encoder is an incremental one, then the driver will perform an index search and then do an offset calibration. In case the motor encoder is an absolute one, then the driver will only perform an offset calibration.

If an incremental encoder is configured as a motor encoder and the configuration is saved after calibration, an index search is necessary upon each device reboot. If the configuration is not saved, then the entire calibration sequence must be repeated after every reboot. However, if an absolute encoder is configured as the output encoder and the configuration is saved after calibration, no further calibration procedures are required upon device reboot.

When both input and output encoders are configured, an encoder matching cycle is recommended. This step synchronizes the motor encoder and output encoder, ensuring accurate position tracking and preventing unintended motion. The control loops utilize the motor encoder and gearbox ratio to compute the final output position, making encoder synchronization crucial.

The API functions involved with calibration step are as follows:

• Driver.runEncoderIndexSearch()
• Driver.runEncoderMatching()
• Driver.runCalibrationSequence()

Control Modes

The driver supports various control modes. The reference frame for these control modes is the actuator's output, which is calculated by using the motor encoder value and the configured gearbox ratio.

The different control modes in which the driver can run are as follows:

• Idle Mode: In this mode the motor will not be in any control loop, and it will be free to turn.
• Position Control Mode: The motor moves at a specified velocity to a particular position as commanded.
  • Parameters:
    • Position (in degrees) to which the motor should move
    • Velocity (in degrees per second) at which the motor should move.
• Velocity Control Mode: The motor moves at a particular velocity as commanded.
  • Parameters:
    • Velocity (in degrees per second) at which the motor should move.
• Torque Control Mode: The motor current is controlled so that a particular amount of torque remains applied as commanded. The motor velocity is also limited during this motion. Once the motor reaches the maximum motor velocity then it will start limiting the motor currents to make sure the velocity remains in the specified range.
  • Parameters:
    • Torque value (in Newton-meter) which the motor should supply.
    • Maximum velocity limit (in degrees per second) at which the motor should move.
• Trajectory Control Mode: The motor moves to a particular position in a trapezoidal trajectory pattern as commanded.
  • Parameters:
    • Position (in degrees) to which the motor should move.
    • Max velocity (in degrees per second) of the motor that it should reach during the motion.
    • Acceleration rate (in degrees per second²) of the motor which decides how fast the motor should reach the max velocity.
    • Decceleration rate (in degrees per second²) of the motor which decides how fast the motor should reach the zero velocity.
• Velocity Ramp Control Mode: The motor moves at a specified velocity as commanded. But the specified velocity is reached with a slow ramp as specified by the ramp rate.
  • Parameters:
    • Max velocity (in degrees per second) at which the motor should move.
    • Ramp rate (in degrees per second²) of the motor which decides how fast the motor should accelerate/deccelerate to reach that commanded max velocity value.

The API functions involved for this control modes are as follows:

• Driver.setDeviceToIdle()
• Driver.setDeviceToActive()
• Driver.setPositionControl(angle: float, degrees_per_seconds: float)
• Driver.setVelocityControl(degrees_per_seconds: float)
• Driver.setTorqueControl(torque: float, degrees_per_second: float)
• Driver.setTrajectoryControl(angle: float, degrees_per_seconds: float, accel_rate: float, decel_rate: float)
• Driver.setVelocityRampControl(degrees_per_seconds: float, ramp_rate_degrees_per_second: float)

Zero Position

The driver enables zero position setting for the motor using an absolute encoder. The driver can set the motor's current position as zero, relying on an available absolute encoder for precise position calculation. If an absolute encoder is configured as the output encoder, it will be used for this purpose. Alternatively, if no output encoder is available, the system will use an absolute encoder configured as the motor encoder. It’s important to note that this zero-position functionality requires at least one absolute encoder to be connected to the driver, as it cannot be used with incremental encoders.

info

To ensure the zero position remains the same after a driver reboot, saving the configuration after setting the zero position is required.

The API functions involved with setting the zero position are as follows:

• Driver.setCurrentPostionToZero()
• Driver.getZeroPosition()

Getting Other Datapoints

The driver includes a multitude of onboard sensors and it offers support for other external sensors. It also has various software states that determine the operation of the motor. There are specific API functions that can be used to get sensor data and different software states from the driver.

The API functions involved with getting various data points are as follows:

Versioning

• Driver.getHardwareVersion()
• Driver.getFirmwareVersion()

Encoder Data

• Driver.getOutputPosition()
• Driver.getOutputVelocity()
• Driver.getOutputAcceleration()
• Driver.getOutputTorque()
• Driver.getMotorPosition()
• Driver.getMotorVelocity()
• Driver.getMotorAcceleration()
• Driver.getMotorTorque()
• Driver.getMotorEncoderRawData()
• Driver.getOutputEncoderRawData()

Temperature

• Driver.getDriverTemperature()
• Driver.getMotorTemperature()

Electrical

• Driver.getBusVoltage()
• Driver.getBusCurrent()
• Driver.getIdqCurrents()
• Driver.getMotorPhaseCurrents()
• Driver.getMotorPhaseParameters()
• Driver.getBrakeCurrent()

Miscellaneous

• Driver.isConnected()
• Driver.getCANCommunicationStatus()
• Driver.getTrajectoryDoneStatus()
• Driver.getControllerMode()
• Driver.getMotorState()
• Driver.getControllerState()
• Driver.getMotorEncoderState()
• Driver.getOutputEncoderState()

Error Handling

During operation there are cases in which the driver will throw an error in case of wrong configuration or other operational scenarios. When the driver throws an error, the Error LED will turn ON and then the motor will be set to an idle state. During this time, driver is able to return an error code value for the errors. The value of which can be looked up in the below table to find out what the error means and how to solve it.

When the driver throws an error, the error needs to be manually cleared before the motor can normally run, if the errors are still not cleared then driver reboot would be necessary.

Error Code	Error	Reason	Troubleshooting
1	DC_BUS_UNDER_VOLTAGE	Bus voltage drops lower than the under voltage trip level. Could be caused when the motor is trying to draw more current than what the power supply can give.	Check the cause of the drop in bus voltage, then adjust the under-voltage trip level if needed.
2	DC_BUS_OVER_VOLTAGE	Bus voltage goes higher than the over voltage trip level. Could be caused when the dumped regeneration current to the supply is too high, and the supply is not able to handle it.	Check for the cause of the spike in bus voltage, and then adjust the over-voltage trip level if needed. If the cause of spikes is attributed to regeneration current, use an appropriate brake resistor to divert more current through the resistor.
3	DC_BUS_OVER_REGEN_CURRENT	Regenerative current goes higher than the maximum regen current trip level	Change the trip level value if more current can be dumped via brake resistor, if not find an appropriate brake resistor with the required specifications.
5	INVALID_STATE	Driver state is invalid, Possibly caused when motor is set to closed loop control without running calibration	Make sure to run the calibration step before putting the motor in closed loop control
6	ESTOP_REQUESTED	Received emergency stop signal from user	Clear errors and continue.
7	PHASE_RESISTANCE_OUT_OF_RANGE	Phase resistance is out of range	Set calibration current and calibration voltage such that the phase resistance is in the measurement range
8	PHASE_INDUCTANCE_OUT_OF_RANGE	Phase inductance is out of range	Check if the phase inductance value of the motor is between 2 µH and 4000 µH
9	DRV_FAULT	Low level driver fault	-
10	FOC_ERROR	Low level control loop fault	-
12	CURRENT_LIMIT_VIOLATION	Motor current goes higher than the current limit	Check why the motor is drawing too much current, and if necessary, increase the current limit while ensuring it remains safe for the motor.
13	MOTOR_THERMISTOR_OVER_TEMP	Motor temperature is higher than the upper limit	Actively cool the motor during operation, and if needed, increase the temperature upper limit while ensuring it remains safe for the motor.
14	FET_THERMISTOR_OVER_TEMP	Driver temperature reaches 120 °C	Actively cool the driver during operation.
16	UNKNOWN_PHASE_ESTIMATE	Phase estimate errors, Possibly caused when motor is set to closed loop control without running calibration	Make sure to run the calibration step before putting the motor in closed loop control
17	UNBALANCED_PHASES	Considerable amount of difference between phase inductance and phase resistance values between each phases	Check if the phase A, B and C connections from the motor is proper, Check if the phase coils of the motor is damaged.
19	UNSTABLE_CONTROLLER_GAIN	Gain values of the control loop is causing instabilities	Tune the gain values properly.
20	SPINOUT_DETECTED	Mechanical slip between motor and motor encoder	Make sure that the mechanical coupling between the motor and motor encoder is proper.
21	CPR_POLEPAIRS_MISMATCH	Mismatch between resolution or CPR value of Motor Encoder and Motor pole pairs	Set the CPR / resolution parameter of the motor encoder and the pole pair values of the motor properly
22	NO_RESPONSE	There is no response from Motor Encoder	Check if the connections are fine and the motor encoder is operational.
23	UNSUPPORTED_ENCODER_MODE	Configured motor and output encoder is not supported	Set a properly supported encoder type.
24	INDEX_NOT_FOUND_YET	Unable to find index of incremental motor encoder	Check if the incremental encoder is operational and if the index pin of the encoder is properly connected to the driver
25	ABS_SPI_TIMEOUT	Encoder SPI communication error	Check if a compatible absolute encoder is being used and check SPI connection
26	ABS_SPI_COM_FAIL	Encoder SPI communication error	Check if a compatible absolute encoder is being used and check SPI connection
27	ABS_SPI_NOT_READY	Encoder SPI communication error	Check if a compatible absolute encoder is being used and check SPI connection
255	UNKNOWN_ERROR	Unknown Error	-

If you continue to face any other errors or errors even after following the troubleshooting step, make sure to reach out to us.

The API functions involved with error handling are as follows:

• Driver.getErrorCode()
• Driver.clearDriverErrors()