hil_is_valid End of trail navigation bar

Table of Contents

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