.. include:: ../text_colors.rst .. toctree:: .. _vspin_api_reference_tables: ################################# VSpin API Reference Tables ################################# This page provides API client reference tables for VSpin specific clients. **These are only applicable if you are using** :ref:`VSpin style firmware `. .. _motor_driver_api: ****************************************************** Type ID 96 | Motor Driver ****************************************************** Motor Driver provides access to the low level driver for VSpin, where current commands become voltage vectors and are applied to the stator. Message Table =============== Type ID 96 | Motor Driver .. table:: Motor Driver :widths: 8 18 15 10 5 50 :class: tight-table +--------+----------------------------------+-----------------------+-----------+----------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | Sub ID | Short Name | Access | Data Type | Unit | Note | +========+==================================+=======================+===========+======================+========================================================================================================================================================================================+ | 0 | rotor_magnitude | get | float | :math:`V` | The magnitude of the voltage space vector to apply to the drive in the rotor frame before adding the additional drive volts. | +--------+----------------------------------+-----------------------+-----------+----------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | 1 | rotor_angle | get | float | :math:`\text{rad}` | The angle of the voltage space vector to apply to the drive in the rotor frame before adding the additional drive volts. | +--------+----------------------------------+-----------------------+-----------+----------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | 2 | final_rotor_magnitude | get | float | :math:`V` | The magnitude of the voltage space vector to apply to the drive in the rotor frame after adding the additional drive volts. | +--------+----------------------------------+-----------------------+-----------+----------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | 3 | final_rotor_angle | get | float | :math:`\text{rad}` | The angle of the voltage space vector to apply to the drive in the rotor frame after adding the additional drive volts. | +--------+----------------------------------+-----------------------+-----------+----------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | 4 | direct_stator_magnitude | get, set | float | :math:`V` | Used when commanding the motor in direct stator mode, the magnitude of the voltage space vector to apply to the motor. Should not be used by customers, can cause excessive heating. | +--------+----------------------------------+-----------------------+-----------+----------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | 5 | direct_stator_angle | get, set | float | :math:`\text{rad}` | Used when commanding the motor in direct stator mode, the angle of the voltage space vector to apply to the motor in the stator frame. | +--------+----------------------------------+-----------------------+-----------+----------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | 6 | stator_magnitude | get | float | :math:`V` | The magnitude of the final voltage space vector to apply to the drive in the stator frame. | +--------+----------------------------------+-----------------------+-----------+----------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | 7 | stator_electrical_angle | get | float | :math:`\text{rad}` | The angle of the final voltage space vector to apply to the drive in the stator frame. | +--------+----------------------------------+-----------------------+-----------+----------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | 8 | pwm | get | float | :math:`\text{PU}` | The stator magnitude divided by the supply voltage, can be at most 1. | +--------+----------------------------------+-----------------------+-----------+----------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | 9 | coast | set | | | This disables all drive circuitry, which causes the motor to coast passively. | +--------+----------------------------------+-----------------------+-----------+----------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | 10 | brake | set | | | This shorts the motor phases, which slows the motor down by dissipating energy in the motor. | +--------+----------------------------------+-----------------------+-----------+----------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | 11 | set_apply_target_mode | set | | | Set the driver to apply commanded targets to spin the motor with efficient torque production. This mode is what is used when normally spinning the motor. | +--------+----------------------------------+-----------------------+-----------+----------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | 12 | set_apply_direct_stator_sv_mode | set | | | Set the driver to apply the direct stator space vector specified by the user. Not useful for normal spinning, should generally not be used by customers. | +--------+----------------------------------+-----------------------+-----------+----------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | 13 | driver_mode | get | uint8 | :math:`\text{enum}` | The current mode of the drive. 0 \= Apply Target, 1 \= Apply Direct Stator Space Vector, 2 \= Coast, 3 \= Brake, 4 \= Lockout | +--------+----------------------------------+-----------------------+-----------+----------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | 14 | additional_drive_volts | get, set | float | :math:`V` | Additional voltage added to the magnitude of the target space vector. Generally should not be set by customers. | +--------+----------------------------------+-----------------------+-----------+----------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | 15 | estimated_motor_amps | get, | float | :math:`A` | An estimation of the motor current. Note that motor current is not the same as the supply current. | +--------+----------------------------------+-----------------------+-----------+----------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | 16 | commutation_hz | get, set, save | uint32 | :math:`\text{Hz}` | This is the frequency of commutation. Higher frequencies run faster and more efficiently, but may not give the controller enough computation time. Should not be changed by customers. | +--------+----------------------------------+-----------------------+-----------+----------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ .. _drive_control_interface_api: ****************************************************** Type ID 97 | Drive Control Interface ****************************************************** Drive Control Interface provides a way to directly command the drive with voltage, PWM, torque, or current targets as well as coasting and braking. Message Table =============== Type ID 97 | Drive Control Interface .. table:: Drive Control Interface :widths: 8 18 15 10 5 50 :class: tight-table +--------+-------------------+-----------+-----------+---------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+ | Sub ID | Short Name | Access | Data Type | Unit | Note | +========+===================+===========+===========+=====================+=============================================================================================================================================================+ | 0 | voltage_target | get, set | float | :math:`V` | The motor’s target drive voltage. | +--------+-------------------+-----------+-----------+---------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+ | 1 | pwm_target | get, set | float | :math:`\text{PU}` | The percentage of the supply voltage to target applying to the motor. | +--------+-------------------+-----------+-----------+---------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+ | 2 | torque_target | get, set | float | :math:`N*m` | The torque target for the motor. | +--------+-------------------+-----------+-----------+---------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+ | 3 | q_current_target | get, set | float | :math:`A` | The q-current target for the motor. The q-current is proportional to the torque of the motor, as determined by the Kt of the motor. | +--------+-------------------+-----------+-----------+---------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+ | 4 | d_current_target | get, set | float | :math:`A` | The d-current target for the motor. D-current does not produce torque, generally this should not be used by customers. | +--------+-------------------+-----------+-----------+---------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+ | 5 | coast | set | | | This disables all drive circuitry, which causes the motor to coast passively. | +--------+-------------------+-----------+-----------+---------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+ | 6 | brake | set | | | This shorts the motor phases, which slows the motor down by dissipating energy in the motor. | +--------+-------------------+-----------+-----------+---------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+ | 7 | mode | get | uint8 | :math:`\text{enum}` | The mode the drive control interface is currently in. 0 \= Coast, 1 \= Brake, 2 \= Voltage Target, 3 \= Current Target, 4 \= Torque Target, 5 \= PWM Target | +--------+-------------------+-----------+-----------+---------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+ .. _motor_model_api: ****************************************************** Type ID 98 | Motor Model ****************************************************** Motor Model serves as a central location for information about the current state of the module and how its model is configured. Message Table =============== Type ID 98 | Motor Model .. table:: Motor Model :widths: 8 18 15 10 5 50 :class: tight-table +--------+-------------------------------+-----------------+-----------+-------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+ | Sub ID | Short Name | Access | Data Type | Unit | Note | +========+===============================+=================+===========+===========================================+=========================================================================================================================================+ | 0 | mechanical_inductance | get, set, save | float | :math:`H` | The cross-inductance of the motor. Set during tuning, should not be changed by customers. | +--------+-------------------------------+-----------------+-----------+-------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+ | 1 | mechanical_velocity | get | float | :math:`\frac{\text{rad}}{s}` | The current velocity of the motor. | +--------+-------------------------------+-----------------+-----------+-------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+ | 2 | mechanical_ke_at_20c | get, set, save | float | :math:`\frac{V}{(\frac{\text{rad}}{s})}` | The Ke of the motor at 20°C. Set during tuning, should not be changed by customers. | +--------+-------------------------------+-----------------+-----------+-------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+ | 3 | mechanical_ke | get | float | :math:`\frac{V}{(\frac{\text{rad}}{s})}` | The Ke of the motor at the current temperature. | +--------+-------------------------------+-----------------+-----------+-------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+ | 4 | coil_resistance_at_20c | get, set, save | float | :math:`\Omega` | The resistance of the motor’s coils at 20 °C. Set during tuning, should not be changed by customers. | +--------+-------------------------------+-----------------+-----------+-------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+ | 5 | coil_resistance | get | float | :math:`\Omega` | The resistance of the motor’s coils at the current temperature. | +--------+-------------------------------+-----------------+-----------+-------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+ | 6 | additional_resistance | get, set, save | float | :math:`\Omega` | Additional resistance due to the controller’s electronics. Set during tuning, should not be changed by customers. | +--------+-------------------------------+-----------------+-----------+-------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+ | 7 | effective_resistance | get | float | :math:`\Omega` | Total effective resistance at the current temperature. | +--------+-------------------------------+-----------------+-----------+-------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+ | 8 | pole_pairs | get, set, save | uint16 | | The number of magnet pole pairs in the motor. | +--------+-------------------------------+-----------------+-----------+-------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+ | 9 | lead_time | get, set, save | float | :math:`s` | Set during tuning, should not be changed by customers. | +--------+-------------------------------+-----------------+-----------+-------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+ | 10 | permute_wires | get, set, save | bool | | Set during tuning, should not be changed by customers. | +--------+-------------------------------+-----------------+-----------+-------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+ | 11 | calibration_angle | get, set, save | float | :math:`{\text{rad}}` | Defines the angle for converting between the stator and rotor reference frames. Set during tuning, should not be changed by customers. | +--------+-------------------------------+-----------------+-----------+-------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+ | 12 | lead_angle | get | float | :math:`{\text{rad}}` | Angle added for position lag compensation. | +--------+-------------------------------+-----------------+-----------+-------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+ | 13 | back_emf | get | float | :math:`V` | The current calculated back-EMF of the motor. | +--------+-------------------------------+-----------------+-----------+-------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+ | 14 | encoder_angle | get | float | :math:`{\text{rad}}` | The angle read by the encoder at the current position. | +--------+-------------------------------+-----------------+-----------+-------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+ | 15 | coil_temperature | get | float | :math:`^{\circ}C` | The current estimated temperature of the motor coils. | +--------+-------------------------------+-----------------+-----------+-------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+ | 16 | mechanical_acceleration | get | float | :math:`\frac{\text{rad}}{s^2}` | The current acceleration of the motor. | +--------+-------------------------------+-----------------+-----------+-------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+ | 17 | calibration_angle_adjustment | get | float | :math:`{\text{rad}}` | The mechanical angle from the q-axis to d-axis. | +--------+-------------------------------+-----------------+-----------+-------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+ | 18 | bd_calibration_angle | get | float | :math:`{\text{rad}}` | The calibration angle from a previous calibration with Brushless Drive. | +--------+-------------------------------+-----------------+-----------+-------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+ .. _current_safeties_api: ****************************************************** Type ID 102 | Current Safeties ****************************************************** Current Safeties serves as a central location for configuring the various safety features available with VSpin. Message Table =============== Type ID 102 | Current Safeties .. table:: Current Safeties :widths: 8 18 15 10 5 50 :class: tight-table +--------+----------------------------------------+-----------------+-----------+-------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ | Sub ID | Short Name | Access | Data Type | Unit | Note | +========+========================================+=================+===========+===============================+==================================================================================================================================================+ | 0 | final_max_current_derate | get | float | :math:`\text{PU}` | The final derate applied to the base maximum motor current. | +--------+----------------------------------------+-----------------+-----------+-------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ | 1 | base_max_current | get, set, save | float | :math:`A` | The base maximum motor current, this will be used when the derate is 1. | +--------+----------------------------------------+-----------------+-----------+-------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ | 2 | derated_max_current | get | float | :math:`A` | The maximum motor current after applying the derate. | +--------+----------------------------------------+-----------------+-----------+-------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ | 3 | speed_redline_start | get, set, save | float | :math:`\frac{\text{rad}}{s}` | The speed at which the speed limiter starts attempting to slow down the motor. | +--------+----------------------------------------+-----------------+-----------+-------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ | 4 | speed_redline_end | get, set, save | float | :math:`\frac{\text{rad}}{s}` | The speed at which the speed limiter will be applying its maximum speed limiting. | +--------+----------------------------------------+-----------------+-----------+-------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ | 5 | supply_voltage_max_start | get, set, save | float | :math:`V` | The supply voltage at which the supply voltage limiter will begin derating. | +--------+----------------------------------------+-----------------+-----------+-------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ | 6 | supply_voltage_max_end | get, set, save | float | :math:`V` | The supply voltage at which the supply voltage limiter will reach maximum derate. | +--------+----------------------------------------+-----------------+-----------+-------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ | 7 | motoring_supply_current_limit_enable | get, set, save | bool | | Enables or disables the motoring supply current limiter. | +--------+----------------------------------------+-----------------+-----------+-------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ | 10 | regen_supply_current_limit_enable | get, set, save | bool | | Enables or disables the regen supply current limiter. | +--------+----------------------------------------+-----------------+-----------+-------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ | 13 | final_q_current_target | get | float | :math:`A` | The final q-current after applying all safeties. | +--------+----------------------------------------+-----------------+-----------+-------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ | 14 | final_d_current_target | get | float | :math:`A` | The final d-current after applying all safeties. | +--------+----------------------------------------+-----------------+-----------+-------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ | 15 | supply_current_filter_fc | get, set, save | uint32 | :math:`\text{Hz}` | The cutoff frequency of the supply current low-pass filter. A filtered supply current is used with the safeties. | +--------+----------------------------------------+-----------------+-----------+-------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ | 16 | current_slew_rate_limit | get, set, save | float | :math:`A` | The motor current slew rate limit to apply. | +--------+----------------------------------------+-----------------+-----------+-------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ | 17 | current_slew_rate_enable | get, set, save | bool | | Enables or disables the motor current slew rate limit. | +--------+----------------------------------------+-----------------+-----------+-------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ | 18 | motoring_supply_current_limit | get, set, save | float | :math:`A` | The supply current limit when using the motoring supply current limiter. | +--------+----------------------------------------+-----------------+-----------+-------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ | 19 | motoring_supply_current_limit_p | get, set, save | float | | P for the PID controller that can be used with the motoring supply current limiter. | +--------+----------------------------------------+-----------------+-----------+-------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ | 20 | motoring_supply_current_limit_i | get, set, save | float | | I for the PID controller that can be used with the motoring supply current limiter. | +--------+----------------------------------------+-----------------+-----------+-------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ | 21 | motoring_supply_current_limit_d | get, set, save | float | | D for the PID controller that can be used with the motoring supply current limiter. | +--------+----------------------------------------+-----------------+-----------+-------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ | 22 | motoring_supply_limit_max_adjust | get, set, save | float | :math:`A` | Maximum amount of closed loop adjustment or the PID controller that can be used with the motoring supply current limiter. | +--------+----------------------------------------+-----------------+-----------+-------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ | 23 | regen_supply_current_limit | get, set, save | float | | The supply current limit when using the regeneration supply current limiter. | +--------+----------------------------------------+-----------------+-----------+-------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ | 24 | regen_supply_current_limit_p | get, set, save | float | | P for the PID controller that can be used with the regeneration supply current limiter. | +--------+----------------------------------------+-----------------+-----------+-------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ | 25 | regen_supply_current_limit_i | get, set, save | float | | I for the PID controller that can be used with the motoring supply current limiter. | +--------+----------------------------------------+-----------------+-----------+-------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ | 26 | regen_supply_current_limit_d | get, set, save | float | | D for the PID controller that can be used with the motoring supply current limiter. | +--------+----------------------------------------+-----------------+-----------+-------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ | 27 | regen_supply_current_limit_max_adjust | get, set, save | float | :math:`A` | Maximum amount of closed loop adjustment or the PID controller that can be used with the motoring supply current limiter. | +--------+----------------------------------------+-----------------+-----------+-------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ .. _field_weakening_controller_api: ****************************************************** Type ID 105 | Field Weakening Controller ****************************************************** Field Weakening Controller provides access to configure field weakening and query its current state. Message Table =============== Type ID 105 | Field Weakening Controller .. table:: Field Weakening Controller :widths: 8 18 15 10 5 50 :class: tight-table +--------+------------------------------------+-----------+-----------+----------------------+------------------------------------------------------------------------------------------------------------------------------------------+ | Sub ID | Short Name | Access | Data Type | Unit | Note | +========+====================================+===========+===========+======================+==========================================================================================================================================+ | 0 | regulation_mode | get, set | uint8 | :math:`\text{enum}` | Sets how the controller will regulate the current. 0 \= Field Weakening Disabled, Limit to Supply Voltage, 1 \= Field Weakening Enabled | +--------+------------------------------------+-----------+-----------+----------------------+------------------------------------------------------------------------------------------------------------------------------------------+ | 1 | field_weakened_q_current | get | float | :math:`A` | The target q-current after applying field weakening. | +--------+------------------------------------+-----------+-----------+----------------------+------------------------------------------------------------------------------------------------------------------------------------------+ | 2 | field_weakened_d_current | get | float | :math:`A` | The target d-current after applying field weakening. | +--------+------------------------------------+-----------+-----------+----------------------+------------------------------------------------------------------------------------------------------------------------------------------+ | 3 | current_limit_regulated_q_current | get | float | :math:`A` | The target q-current after applying additional safeties to the field weakened q-current. | +--------+------------------------------------+-----------+-----------+----------------------+------------------------------------------------------------------------------------------------------------------------------------------+ | 4 | current_limit_regulated_d_current | get | float | :math:`A` | The target d-current after applying additional safeties to the field weakened d-current. | +--------+------------------------------------+-----------+-----------+----------------------+------------------------------------------------------------------------------------------------------------------------------------------+