esc_dshot.h File Reference

DSHOT driver based on ChibiOS. More...

#include <ch.h>
#include <hal.h>
#include "mcu_periph/hal_stm32_dma.h"
#include "modules/actuators/esc_dshot_config.h"

Include dependency graph for esc_dshot.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	DshotTelemetryFrame
	telemetry packed as sent by some KISS ESC More...
struct	DshotTelemetry
	telemetry with timestamp More...
union	DshotDmaBuffer
struct	DSHOTConfig
	DSHOT Driver configuration structure. More...
union	DshotPacket
struct	DshotPackets
struct	DSHOTDriver
	DSHOT driver structure. More...
union	DshotTelemetryFrame.__unnamed7__
struct	DshotTelemetryFrame.__unnamed7__.__unnamed9__
struct	DshotPacket.__unnamed11__

Macros
#define	DSHOT_CHANNEL_FIRST_INDEX   0U
#define	DSHOT_BIT_WIDTHS   16U
	DMA buffer size and number of channels. More...
#define	DSHOT_PRE_FRAME_SILENT_SYNC_BITS   2U
#define	DSHOT_POST_FRAME_SILENT_SYNC_BITS   4U
#define	DSHOT_DMA_BUFFER_SIZE
#define	DSHOT_BIDIR_ERR_CRC   UINT32_MAX
	special values returned by dshotGetRpm function More...
#define	DSHOT_BIDIR_TLM_EDT   (UINT32_MAX-1U)
#define	DSHOT_ALL_MOTORS   255U
	special value for index : send order to all channels More...

Typedefs
typedef struct DSHOTDriver	DSHOTDriver
	Type of a structure representing an DSHOT driver. More...

Enumerations
enum	dshot_special_commands_t {   DSHOT_CMD_MOTOR_STOP = 0U , DSHOT_CMD_BEACON1 , DSHOT_CMD_BEACON2 , DSHOT_CMD_BEACON3 ,   DSHOT_CMD_BEACON4 , DSHOT_CMD_BEACON5 , DSHOT_CMD_ESC_INFO , DSHOT_CMD_SPIN_DIRECTION_1 ,   DSHOT_CMD_SPIN_DIRECTION_2 , DSHOT_CMD_3D_MODE_OFF , DSHOT_CMD_3D_MODE_ON , DSHOT_CMD_SETTINGS_REQUEST ,   DSHOT_CMD_SAVE_SETTINGS , DSHOT_CMD_BIDIR_EDT_MODE_ON , DSHOT_CMD_BIDIR_EDT_MODE_OFF , DSHOT_CMD_SPIN_DIRECTION_NORMAL = 20U ,   DSHOT_CMD_SPIN_DIRECTION_REVERSED = 21U , DSHOT_CMD_LED0_ON , DSHOT_CMD_LED1_ON , DSHOT_CMD_LED2_ON ,   DSHOT_CMD_LED3_ON , DSHOT_CMD_LED0_OFF , DSHOT_CMD_LED1_OFF , DSHOT_CMD_LED2_OFF ,   DSHOT_CMD_LED3_OFF , DSHOT_CMD_AUDIO_STREAM_MODE_ON_OFF = 30U , DSHOT_CMD_SILENT_MODE_ON_OFF = 31U , DSHOT_CMD_MAX = 47U ,   DSHOT_MIN_THROTTLE }
	DSHOT special commands (0-47) for KISS and BLHELI ESC. More...

Functions
void	dshotStart (DSHOTDriver *driver, const DSHOTConfig *config)
	Configures and activates the DSHOT peripheral. More...
void	dshotStop (DSHOTDriver *driver)
	stop the DSHOT driver and free the related resources : pwm driver and dma driver. More...
void	dshotSetThrottle (DSHOTDriver *driver, const uint8_t index, const uint16_t throttle)
	prepare throttle order for specified ESC More...
void	dshotSendFrame (DSHOTDriver *driver)
	send throttle order More...
void	dshotSendThrottles (DSHOTDriver *driver, const uint16_t throttles[DSHOT_CHANNELS])
	send throttle packed order to all of the ESCs More...
void	dshotSendSpecialCommand (DSHOTDriver *driver, const uint8_t index, const dshot_special_commands_t specmd)
	send special order to one of the ESC (BHELIX, KISS, ...) More...
uint32_t	dshotGetCrcErrorCount (const DSHOTDriver *driver)
	return number of telemetry crc error since dshotStart More...
uint32_t	dshotGetTelemetryFrameCount (const DSHOTDriver *driver)
	return number of telemetry succesfull frame since dshotStart More...
DshotTelemetry	dshotGetTelemetry (DSHOTDriver *driver, const uint32_t index)
	return last received telemetry data More...

Detailed Description

DSHOT driver based on ChibiOS.

Author

Alexandre Bustico @maintainer Gautier Hattenberger gauti.nosp@m.er.h.nosp@m.atten.nosp@m.berg.nosp@m.er@en.nosp@m.ac.f.nosp@m.r

Definition in file esc_dshot.h.

---

Data Structure Documentation

DshotTelemetryFrame

struct DshotTelemetryFrame

telemetry packed as sent by some KISS ESC

Note

if other ESC use different binary representation in the future we'll have to add a little bit abstraction here

Definition at line 139 of file esc_dshot.h.

Data Fields
union DshotTelemetryFrame	__unnamed__
uint8_t	crc8

DshotTelemetry

struct DshotTelemetry

telemetry with timestamp

Definition at line 158 of file esc_dshot.h.

Collaboration diagram for DshotTelemetry:

Data Fields
DshotTelemetryFrame	frame
uint8_t	status
uint8_t	stress
systime_t	ts

DshotDmaBuffer

union DshotDmaBuffer

Definition at line 166 of file esc_dshot.h.

Data Fields
uint16_t	widths16[DSHOT_DMA_BUFFER_SIZE][DSHOT_CHANNELS]

DSHOTConfig

struct DSHOTConfig

DSHOT Driver configuration structure.

Definition at line 182 of file esc_dshot.h.

Collaboration diagram for DSHOTConfig:

Data Fields
DshotDmaBuffer *	dma_buf	dshot dma buffer, should be defined in a non Dcached region
uint8_t	dma_channel	: dma channel associated with pwm timer used to generate dshot output
uint32_t	dma_stream	: dma stream associated with pwm timer used to generate dshot output
PWMDriver *	pwmp	PWM driver that feed up to 4 dshot lines.
uint16_t	speed_khz	dynamic dshot speed, when speed id not known at compilation Note incompatible with BIDIR
SerialDriver *	tlm_sd	if non null : dshot telemetry serial driver

DshotPacket

union DshotPacket

Definition at line 265 of file esc_dshot.h.

Collaboration diagram for DshotPacket:

Data Fields
struct DshotPacket	__unnamed__
uint16_t	rawFrame

DshotPackets

struct DshotPackets

Definition at line 275 of file esc_dshot.h.

Collaboration diagram for DshotPackets:

Data Fields
uint8_t	currentTlmQry
DshotPacket	dp[DSHOT_CHANNELS]
DshotTelemetry	dt[DSHOT_CHANNELS]
volatile bool	onGoingQry
mutex_t	tlmMtx[DSHOT_CHANNELS]

DshotTelemetryFrame.__unnamed7__

union DshotTelemetryFrame.__unnamed7__

Definition at line 140 of file esc_dshot.h.

Data Fields
__unnamed7__	__unnamed__
uint8_t	rawData[9]

DshotTelemetryFrame.__unnamed7__.__unnamed9__

struct DshotTelemetryFrame.__unnamed7__.__unnamed9__

Definition at line 141 of file esc_dshot.h.

Data Fields
uint16_t	consumption
uint16_t	current
uint16_t	rpm
uint8_t	temp
uint16_t	voltage

DshotPacket.__unnamed11__

struct DshotPacket.__unnamed11__

Definition at line 266 of file esc_dshot.h.

Data Fields
uint16_t	crc:4
uint16_t	telemetryRequest:1
uint16_t	throttle:11

Macro Definition Documentation

DSHOT_ALL_MOTORS

#define DSHOT_ALL_MOTORS   255U

special value for index : send order to all channels

Note

could be used as index in dshotSetThrottle and dshotSendSpecialCommand functions

Definition at line 74 of file esc_dshot.h.

DSHOT_BIDIR_ERR_CRC

#define DSHOT_BIDIR_ERR_CRC   UINT32_MAX

special values returned by dshotGetRpm function

Note

must be checked after each call to dshotGetRpm

Definition at line 65 of file esc_dshot.h.

DSHOT_BIDIR_TLM_EDT

#define DSHOT_BIDIR_TLM_EDT   (UINT32_MAX-1U)

Definition at line 66 of file esc_dshot.h.

DSHOT_BIT_WIDTHS

#define DSHOT_BIT_WIDTHS   16U

DMA buffer size and number of channels.

Definition at line 48 of file esc_dshot.h.

DSHOT_CHANNEL_FIRST_INDEX

#define DSHOT_CHANNEL_FIRST_INDEX   0U

Definition at line 43 of file esc_dshot.h.

DSHOT_DMA_BUFFER_SIZE

#define DSHOT_DMA_BUFFER_SIZE

Value:

               (DSHOT_BIT_WIDTHS + \
               DSHOT_PRE_FRAME_SILENT_SYNC_BITS + \
               DSHOT_POST_FRAME_SILENT_SYNC_BITS )

Definition at line 51 of file esc_dshot.h.

DSHOT_POST_FRAME_SILENT_SYNC_BITS

#define DSHOT_POST_FRAME_SILENT_SYNC_BITS   4U

Definition at line 50 of file esc_dshot.h.

DSHOT_PRE_FRAME_SILENT_SYNC_BITS

#define DSHOT_PRE_FRAME_SILENT_SYNC_BITS   2U

Definition at line 49 of file esc_dshot.h.

Typedef Documentation

DSHOTDriver

typedef struct DSHOTDriver DSHOTDriver

Type of a structure representing an DSHOT driver.

Definition at line 1 of file esc_dshot.h.

Enumeration Type Documentation

dshot_special_commands_t

enum dshot_special_commands_t

DSHOT special commands (0-47) for KISS and BLHELI ESC.

Note

commands 48-2047 are used to send motor power

Enumerator
DSHOT_CMD_MOTOR_STOP
DSHOT_CMD_BEACON1
DSHOT_CMD_BEACON2
DSHOT_CMD_BEACON3
DSHOT_CMD_BEACON4
DSHOT_CMD_BEACON5
DSHOT_CMD_ESC_INFO
DSHOT_CMD_SPIN_DIRECTION_1
DSHOT_CMD_SPIN_DIRECTION_2
DSHOT_CMD_3D_MODE_OFF
DSHOT_CMD_3D_MODE_ON
DSHOT_CMD_SETTINGS_REQUEST
DSHOT_CMD_SAVE_SETTINGS
DSHOT_CMD_BIDIR_EDT_MODE_ON
DSHOT_CMD_BIDIR_EDT_MODE_OFF
DSHOT_CMD_SPIN_DIRECTION_NORMAL
DSHOT_CMD_SPIN_DIRECTION_REVERSED
DSHOT_CMD_LED0_ON
DSHOT_CMD_LED1_ON
DSHOT_CMD_LED2_ON
DSHOT_CMD_LED3_ON
DSHOT_CMD_LED0_OFF
DSHOT_CMD_LED1_OFF
DSHOT_CMD_LED2_OFF
DSHOT_CMD_LED3_OFF
DSHOT_CMD_AUDIO_STREAM_MODE_ON_OFF
DSHOT_CMD_SILENT_MODE_ON_OFF
DSHOT_CMD_MAX
DSHOT_MIN_THROTTLE

Definition at line 102 of file esc_dshot.h.

Function Documentation

dshotGetCrcErrorCount()

uint32_t dshotGetCrcErrorCount

(

const DSHOTDriver *

driver

)

return number of telemetry crc error since dshotStart

Parameters

[in]

driver

pointer to the DSHOTDriver object

Returns

number of CRC errors @api

Definition at line 442 of file esc_dshot.c.

References DSHOTDriver::crc_errors.

dshotGetTelemetry()

DshotTelemetry dshotGetTelemetry	(	DSHOTDriver *	driver,
		uint32_t	index
	)

return last received telemetry data

Parameters

[in]	driver	pointer to the DSHOTDriver object
[in]	index	channel : [0..3] or [0..1] depending on driver used

Returns

telemetry structure by copy @api

Definition at line 468 of file esc_dshot.c.

References DSHOT_CHANNEL_FIRST_INDEX, DSHOT_CHANNELS, DSHOTDriver::dshotMotors, DshotPackets::dt, and DshotPackets::tlmMtx.

Referenced by actuators_dshot_arch_commit(), and esc_msg_send().

Here is the caller graph for this function:

dshotGetTelemetryFrameCount()

uint32_t dshotGetTelemetryFrameCount

(

const DSHOTDriver *

driver

)

return number of telemetry succesfull frame since dshotStart

Parameters

[in]

driver

pointer to the DSHOTDriver object

Returns

number of frames @api

Definition at line 454 of file esc_dshot.c.

References DSHOTDriver::tlm_frame_nb.

dshotSendFrame()

void dshotSendFrame

(

DSHOTDriver *

driver

)

send throttle order

Parameters

[in]

driver

pointer to the DSHOTDriver object

Note

dshotSetXXX api should be called prior to this function @api

Definition at line 404 of file esc_dshot.c.

References buildDshotDmaBuffer(), DSHOTDriver::config, DshotPackets::currentTlmQry, DSHOTConfig::dma_buf, DMA_READY, DSHOTDriver::dmap, dmaTransfert(), DshotPackets::dp, DSHOT_CHANNELS, DSHOT_DMA_BUFFER_SIZE, DSHOTDriver::dshotMotors, dshotRpmCatchErps(), dshotStop(), DSHOTDriver::mb, DshotPackets::onGoingQry, DSHOTConfig::pwmp, setDshotPacketTlm(), DMADriver::state, and DSHOTConfig::tlm_sd.

Referenced by actuators_dshot_arch_commit(), dshotSendSpecialCommand(), and dshotSendThrottles().

Here is the call graph for this function:

Here is the caller graph for this function:

dshotSendSpecialCommand()

void dshotSendSpecialCommand	(	DSHOTDriver *	driver,
		const uint8_t	index,
		const dshot_special_commands_t	specmd
	)

send special order to one of the ESC (BHELIX, KISS, ...)

Parameters

[in]	driver	pointer to the DSHOTDriver object
[in]	index	channel : [0..3] or [0..1] depending on driver used
[in]	specmd	special commands, see enum @api

Definition at line 330 of file esc_dshot.c.

References DSHOTDriver::config, DshotPackets::dp, DSHOT_ALL_MOTORS, DSHOT_CHANNELS, DSHOT_CMD_3D_MODE_OFF, DSHOT_CMD_3D_MODE_ON, DSHOT_CMD_AUDIO_STREAM_MODE_ON_OFF, DSHOT_CMD_BIDIR_EDT_MODE_OFF, DSHOT_CMD_BIDIR_EDT_MODE_ON, DSHOT_CMD_MAX, DSHOT_CMD_SAVE_SETTINGS, DSHOT_CMD_SETTINGS_REQUEST, DSHOT_CMD_SILENT_MODE_ON_OFF, DSHOT_CMD_SPIN_DIRECTION_1, DSHOT_CMD_SPIN_DIRECTION_2, DSHOTDriver::dshotMotors, dshotSendFrame(), setDshotPacketThrottle(), setDshotPacketTlm(), and DSHOTConfig::tlm_sd.

Here is the call graph for this function:

dshotSendThrottles()

void dshotSendThrottles	(	DSHOTDriver *	driver,
		const uint16_t	throttles[DSHOT_CHANNELS]
	)

send throttle packed order to all of the ESCs

Parameters

[in]	driver	pointer to the DSHOTDriver object
[in]	throttle[DSHOT_CHANNELS]	[48 .. 2047]

Note

dshotSendFrame is called by this function

telemetry bit is set in turn for each ESC of the ESCs @api

Definition at line 385 of file esc_dshot.c.

References DshotPackets::dp, DSHOT_CHANNELS, DSHOTDriver::dshotMotors, dshotSendFrame(), and setDshotPacketThrottle().

Here is the call graph for this function:

dshotSetThrottle()

void dshotSetThrottle	(	DSHOTDriver *	driver,
		const uint8_t	index,
		const uint16_t	throttle
	)

prepare throttle order for specified ESC

Parameters

[in]	driver	pointer to the DSHOTDriver object
[in]	index	channel : [0..3] or [0..1] depending on driver used
[in]	throttle	[48 .. 2047]

Note

dshotSendFrame has to be called after using this function

see also dshotSendThrottles @api

Definition at line 301 of file esc_dshot.c.

References DshotPackets::dp, DSHOT_ALL_MOTORS, DSHOT_CHANNEL_FIRST_INDEX, DSHOT_CHANNELS, DSHOT_CMD_MAX, DSHOT_MAX_VALUE, DSHOTDriver::dshotMotors, Min, and setDshotPacketThrottle().

Referenced by actuators_dshot_arch_commit().

Here is the call graph for this function:

Here is the caller graph for this function:

dshotStart()

void dshotStart	(	DSHOTDriver *	driver,
		const DSHOTConfig *	config
	)

Configures and activates the DSHOT peripheral.

Parameters

[in]	driver	pointer to the DSHOTDriver object
[in]	config	pointer to the DSHOTConfig object. @api

Definition at line 154 of file esc_dshot.c.

References DSHOTDriver::_mbBuf, ARRAY_LEN, DSHOTDriver::bit0Duty, DSHOTDriver::bit1Duty, DSHOTDriver::config, config, DSHOTDriver::crc_errors, DshotPackets::currentTlmQry, DCR_DBA, DCR_DBL, DSHOTDriver::dma_conf, DMA_DIR_M2P, DMA_ONESHOT, dmaObjectInit(), DSHOTDriver::dmap, dmaStart(), DshotPackets::dp, DSHOT_BIDIR, DSHOT_BIT0_DUTY_RATIO, DSHOT_CHANNELS, DSHOT_PWM_PERIOD, DSHOT_TELEMETRY_BAUD, DSHOTDriver::dshotMotors, dshotRpmCaptureStart(), dshotTlmRec(), getTimerWidth(), makeDshotPacket(), DSHOTDriver::mb, DshotPackets::onGoingQry, DSHOTDriver::pwm_conf, DSHOTConfig::pwmp, DMAConfig::stream, TICK_FREQ, TICKS_PER_PERIOD, DSHOTDriver::tlm_frame_nb, DSHOTConfig::tlm_sd, and DshotPackets::tlmMtx.

Referenced by actuators_dshot_arch_init().

Here is the call graph for this function:

Here is the caller graph for this function:

dshotStop()

void dshotStop

(

DSHOTDriver *

driver

)

stop the DSHOT driver and free the related resources : pwm driver and dma driver.

Parameters

[in]

driver

pointer to the DSHOTDriver object @api

Definition at line 260 of file esc_dshot.c.

References DSHOTDriver::config, DSHOTDriver::dmap, dmaStop(), dmaStopTransfert(), and DSHOTConfig::pwmp.

Referenced by dshotSendFrame().

Here is the call graph for this function:

Here is the caller graph for this function: