hil_esc_output :: Quanser C Functions

navigation bar

hil_esc_output

Generates a PWM output value suitable for an ESC command.

Description

The hil_esc_output function generates an appropriate value to write to a PWM output to perform the given ESC command based on the given protocol and options. The PWM output value is written to the variable whose address is supplied in the pwm_output argument. This value is then written to the PWM output using a function such as hil_write_pwm.

For ESC protocols like standard PWM, OneShot and Multishot, the throttle value as a percentage (0% to 100%) is mapped to a pulse width in seconds. The PWM output mode should be configured as PWM_TIME_MODE (4) in the hil_set_pwm_mode function when using these protocols. The desired PWM period must also be configured using the hil_set_pwm_frequency functions.

The telemetry and command inputs are ignored unless the protocol is ESC_PROTOCOL_DSHOT.

For the DSHOT protocol, there are three inputs: throttle, telemetry and command. The throttle value is a percentage (0% to 100%) and the telemetry is a logical input indicating whether to include a telemetry request in the DSHOT output. The command input is used for special commands. A command value of 0 means "disarm", for instance. Command values from 0-47 are for special commands and the throttle value will be ignored in the output. A command value of 48 means "armed". In this case, the throttle value is included in the output value.

For DSHOT, the PWM output should be configured in PWM_RAW_MODE (6) in the hil_set_pwm_mode function and DSHOT should be enabled in the card-specific options e.g. pwm0_dshot=1 via the hil_set_card_specific_options function. The PWM frequency will determine the bit rate for the DSHOT. For example, a PWM frequency of 600e3 will result in DSHOT600 being output from the PWM output.

The table below enumerates the typical settings employed for various ESC protocols.

Protocol	Description	PWM Mode	PWM Frequency	ESC Constant
Standard PWM	1 to 2 ms pulse every 20 ms.	PWM_TIME_MODE (4)	50	ESC_PROTOCOL_STANDARD_PWM (0)
OneShot125	125 to 250 us pulse every 500us.	PWM_TIME_MODE (4)	2000	ESC_PROTOCOL_ONESHOT125 (1)
OneShot42	42 to 84 us pulse every 168us.	PWM_TIME_MODE (4)	1/168e-6	ESC_PROTOCOL_ONESHOT42 (2)
Multishot	5 to 25 us pulse every 50us.	PWM_TIME_MODE (4)	20000	ESC_PROTOCOL_MULTISHOT (3)
DShot150	16-bit packet at 150 kbaud.	PWM_RAW_MODE (6)	150e3	ESC_PROTOCOL_DSHOT (4)
DShot300	16-bit packet at 300 kbaud.	PWM_RAW_MODE (6)	300e3	ESC_PROTOCOL_DSHOT (4)
DShot600	16-bit packet at 600 kbaud.	PWM_RAW_MODE (6)	600e3	ESC_PROTOCOL_DSHOT (4)
DShot1200	16-bit packet at 1200 kbaud.	PWM_RAW_MODE (6)	1200e3	ESC_PROTOCOL_DSHOT (4)
DShot2400	16-bit packet at 2400 kbaud.	PWM_RAW_MODE (6)	2400e3	ESC_PROTOCOL_DSHOT (4)

The DSHOT commands are unique to the ESC, other than disarm (0) and armed (48). The table below shows the commands implemented by KISS. Not every ESC is guaranteed to implement all of these commands, and other manufacturers may implement a different set of commands.

Command	Value	Description
DSHOT_COMMAND_DISARM	0	Disarm. The motor will stop.
DSHOT_COMMAND_BEEP_LOW	1	Beep at low frequency.
DSHOT_COMMAND_BEEP_MEDIUM_LOW	2	Beep at medium-low frequency.
DSHOT_COMMAND_BEEP_MEDIUM	3	Beep at medium frequency.
DSHOT_COMMAND_BEEP_MEDIUM_HIGH	4	Beep at medium-high frequency.
DSHOT_COMMAND_BEEP_HIGH	5	Beep at high frequency.
DSHOT_COMMAND_ESC_INFORMATION	6	ESC information request (firmware version, serial number and settings sent over telemetry wire).
DSHOT_COMMAND_ROTATE	7	Rotate in one direction.
DSHOT_COMMAND_ROTATE_OTHER	8	Rotate in the other direction.
DSHOT_COMMAND_3D_MODE_OFF	9	3D mode off.
DSHOT_COMMAND_3D_MODE_ON	10	3D mode on.
DSHOT_COMMAND_ESC_SETTINGS	11	ESC settings request (settings will be saved over the telemetry wire). Not currently implemented.
DSHOT_COMMAND_SAVE_SETTINGS	12	Save settings.
	13-19	Reserved.
DSHOT_COMMAND_ROTATE_NORMAL	20	Rotate in the normal direction.
DSHOT_COMMAND_ROTATE_REVERSE	21	Rotate in the reverse direction.
DSHOT_COMMAND_LED0_ON	22	LED 0 on (BLHeli32 only).
DSHOT_COMMAND_LED1_ON	23	LED 1 on (BLHeli32 only).
DSHOT_COMMAND_LED2_ON	24	LED 2 on (BLHeli32 only).
DSHOT_COMMAND_LED3_ON	25	LED 3 on (BLHeli32 only).
DSHOT_COMMAND_LED0_OFF	26	LED 0 off (BLHeli32 offly).
DSHOT_COMMAND_LED1_OFF	27	LED 1 off (BLHeli32 offly).
DSHOT_COMMAND_LED2_OFF	28	LED 2 off (BLHeli32 offly).
DSHOT_COMMAND_LED3_OFF	29	LED 3 off (BLHeli32 offly).
DSHOT_COMMAND_AUDIO_ON_OFF	30	Audio stream mode on/off.
DSHOT_COMMAND_SILENT_MODE	31	Silent mode on/off.
	32-47	Reserved.
DSHOT_COMMAND_ARMED	48	Armed (normal operation).

Prototype

t_error
hil_esc_output(t_esc_protocol protocol, t_double throttle, t_boolean telemetry, t_dshot_command command, t_double* pwm_output);

Parameters

t_esc_protocol protocol

The ESC protocol for which the PWM output value will be generated.

t_double throttle

A fraction between 0.0 and 1.0 representing the throttle value from 0% to 100%.

t_boolean telemetry

When the ESC protocol is set to ESC_PROTOCOL_DSHOT, the telemetry parameter determines whether telemetry information is returned from the selected channel (true or false).

t_dshot_command command

When the ESC protocol is set to ESC_PROTOCOL_DSHOT, the commmand parameter represents the DSHOT command. Use DSHOT_COMMAND_ARMED when trying to control the motor throttle.

t_double * pwm_output

The address of a variable to receive the computed PWM output value.

Return value

The return value is 0 on success and a negative error code otehrewise. Error codes are defined in quanser_errors.h. A suitable error message may be retrieved using msg_get_error_message.

Error codes

QERR_INVALID_ARGUMENT

One of the arguments is invalid.

Requirements

Include Files	Libraries
hil.h	hil.lib;quanser_runtime.lib;quanser_common.lib

Examples

t_double value;
t_error result = hil_esc_output(ESC_PROTOCOL_DSHOT, 0.1, false, DSHOT_COMMAND_ARMED, &value);

navigation bar