VSpin API Reference Tables

This page provides API client reference tables for VSpin specific clients. These are only applicable if you are using VSpin style firmware.

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

Motor Driver

Sub ID	Short Name	Access	Data Type	Unit	Note
0	rotor_magnitude	get	float	\(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	\(\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	\(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	\(\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	\(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	\(\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	\(V\)	The magnitude of the final voltage space vector to apply to the drive in the stator frame.
7	stator_electrical_angle	get	float	\(\text{rad}\)	The angle of the final voltage space vector to apply to the drive in the stator frame.
8	pwm	get	float	\(\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	\(\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	\(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	\(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	\(\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.

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

Drive Control Interface

Sub ID	Short Name	Access	Data Type	Unit	Note
0	voltage_target	get, set	float	\(V\)	The motor’s target drive voltage.
1	pwm_target	get, set	float	\(\text{PU}\)	The percentage of the supply voltage to target applying to the motor.
2	torque_target	get, set	float	\(N*m\)	The torque target for the motor.
3	q_current_target	get, set	float	\(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	\(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	\(\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

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

Motor Model

Sub ID	Short Name	Access	Data Type	Unit	Note
0	mechanical_inductance	get, set, save	float	\(H\)	The cross-inductance of the motor. Set during tuning, should not be changed by customers.
1	mechanical_velocity	get	float	\(\frac{\text{rad}}{s}\)	The current velocity of the motor.
2	mechanical_ke_at_20c	get, set, save	float	\(\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	\(\frac{V}{(\frac{\text{rad}}{s})}\)	The Ke of the motor at the current temperature.
4	coil_resistance_at_20c	get, set, save	float	\(\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	\(\Omega\)	The resistance of the motor’s coils at the current temperature.
6	additional_resistance	get, set, save	float	\(\Omega\)	Additional resistance due to the controller’s electronics. Set during tuning, should not be changed by customers.
7	effective_resistance	get	float	\(\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	\(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	\({\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	\({\text{rad}}\)	Angle added for position lag compensation.
13	back_emf	get	float	\(V\)	The current calculated back-EMF of the motor.
14	encoder_angle	get	float	\({\text{rad}}\)	The angle read by the encoder at the current position.
15	coil_temperature	get	float	\(^{\circ}C\)	The current estimated temperature of the motor coils.
16	mechanical_acceleration	get	float	\(\frac{\text{rad}}{s^2}\)	The current acceleration of the motor.
17	calibration_angle_adjustment	get	float	\({\text{rad}}\)	The mechanical angle from the q-axis to d-axis.
18	bd_calibration_angle	get	float	\({\text{rad}}\)	The calibration angle from a previous calibration with Brushless Drive.

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

Current Safeties

Sub ID	Short Name	Access	Data Type	Unit	Note
0	final_max_current_derate	get	float	\(\text{PU}\)	The final derate applied to the base maximum motor current.
1	base_max_current	get, set, save	float	\(A\)	The base maximum motor current, this will be used when the derate is 1.
2	derated_max_current	get	float	\(A\)	The maximum motor current after applying the derate.
3	speed_redline_start	get, set, save	float	\(\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	\(\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	\(V\)	The supply voltage at which the supply voltage limiter will begin derating.
6	supply_voltage_max_end	get, set, save	float	\(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	\(A\)	The final q-current after applying all safeties.
14	final_d_current_target	get	float	\(A\)	The final d-current after applying all safeties.
15	supply_current_filter_fc	get, set, save	uint32	\(\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	\(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	\(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	\(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	\(A\)	Maximum amount of closed loop adjustment or the PID controller that can be used with the motoring supply current limiter.

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

Field Weakening Controller

Sub ID	Short Name	Access	Data Type	Unit	Note
0	regulation_mode	get, set	uint8	\(\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	\(A\)	The target q-current after applying field weakening.
2	field_weakened_d_current	get	float	\(A\)	The target d-current after applying field weakening.
3	current_limit_regulated_q_current	get	float	\(A\)	The target q-current after applying additional safeties to the field weakened q-current.
4	current_limit_regulated_d_current	get	float	\(A\)	The target d-current after applying additional safeties to the field weakened d-current.