UUtzinger_DRV8704 0.1.0 Arduino library for the DRV8704 dual H-bridge gate driver

drv8704.h
Go to the documentation of this file.
1
6 #ifndef DRV8704_H
7 #define DRV8704_H
8
9 #include <Arduino.h>
10 #include <SPI.h>
11
12 #include "drv8704_defs.h"
13 #include "drv8704_types.h"
14 #include "drv8704_regs_typedefs.h"
15
16 class DRV8704PwmBackend;
17
21 class DRV8704 {
22 public:
28 explicit DRV8704(const DRV8704Pins& pins, SPIClass& spi = SPI);
29
34 bool begin();
35
39 void end();
40
44 void sleep();
45
49 void wake();
50
54 void reset();
55
61 uint16_t readRegister(uint8_t address);
62
68 uint16_t readRegister(RegisterAddress address) {
69 return readRegister(static_cast<uint8_t>(address));
70 }
71
78 bool writeRegister(uint8_t address, uint16_t value);
79
86 bool writeRegister(RegisterAddress address, uint16_t value) {
87 return writeRegister(static_cast<uint8_t>(address), value);
88 }
89
97 bool updateRegister(uint8_t address, uint16_t mask, uint16_t value);
98
106 bool updateRegister(RegisterAddress address, uint16_t mask, uint16_t value) {
107 return updateRegister(static_cast<uint8_t>(address), mask, value);
108 }
109
115 bool enableBridgeDriver(bool enabled);
116
122 bool setSenseGain(SenseGain gain);
123
129 bool setDeadTime(DeadTime deadTime);
130
136 bool setTorque(uint8_t torque);
137
143 bool setOffTime(uint8_t offTime);
144
150 bool setBlankTime(uint8_t blankTime);
151
157 bool setDecayMode(DecayMode mode);
158
164 bool setDecayTime(uint8_t decayTime);
165
171 bool setOcpThreshold(OcpThreshold threshold);
172
178 bool setOcpDeglitch(OcpDeglitch deglitch);
179
186 bool setGateDriveTimes(GateDriveTime tDriveN, GateDriveTime tDriveP);
187
194 bool setGateDriveCurrents(GateDriveSinkCurrent iDriveN, GateDriveSourceCurrent iDriveP);
195
201 bool setGateDrive(const GateDriveConfig& gateDrive);
202
208 bool applyConfig(const DRV8704Config& config);
209
215 bool setShuntResistance(float ohms);
216
223 bool setShuntResistance(BridgeId bridge, float ohms);
224
230 bool setCurrentModePreset(CurrentModePreset preset);
231
238 bool setDirection(BridgeId bridge, Direction direction);
239
245 Direction direction(BridgeId bridge) const;
246
252 bool setCurrentLimit(float amps);
253
260 bool setCurrent(BridgeId bridge, float amps);
261
268 bool disableCurrentLimit();
269
274 bool isCurrentLimitEnabled() const { return currentLimitEnabled_; }
275
280 DRV8704CurrentPresetConfig currentModePresetConfig() const { return currentPresetConfig_; }
281
286 DRV8704CurrentLimitResult currentLimitResult() const { return currentLimitResult_; }
287
292 DRV8704Status readStatus();
293
298 bool hasFault();
299
304 bool hasFaultPin() const { return pins_.faultPin >= 0; }
305
310 bool isFaultPinActive() const;
311
316 bool clearFaults();
317
323 bool clearFault(FaultBit bit);
324
329 void coast(BridgeId bridge);
330
335 void brake(BridgeId bridge);
336
342 void setBridgeMode(BridgeId bridge, BridgeMode mode);
343
349 DRV8704BridgeState bridgeState(BridgeId bridge) const;
350
356 bool beginPwmMode(const DRV8704PwmConfig& config = DRV8704PwmConfig());
357
361 void endPwmMode();
362
368 bool setPwmFrequency(uint32_t frequencyHz);
369
379 bool setSpeed(BridgeId bridge, float speedPercent);
380
388 bool setSpeed(BridgeId bridge, Direction direction, float speedPercent) {
389 return setDirection(bridge, direction) && setSpeed(bridge, speedPercent);
390 }
391
399 bool setCurrent(BridgeId bridge, Direction direction, float amps) {
400 return setDirection(bridge, direction) && setCurrent(bridge, amps);
401 }
402
407 DRV8704PwmCapability pwmCapability() const { return pwmCapability_; }
408
413 float smallestDutyIncrementPercent() const {
414 return pwmCapability_.smallestDutyIncrementPercent;
415 }
416
421 bool isPwmModeEnabled() const { return pwmModeEnabled_; }
422
427 DRV8704HealthCheck healthCheck();
428
433 bool isInitialized() const { return initialized_; }
434
440 uint16_t cachedRegister(uint8_t address) const;
441
446 bool syncRegisterCache();
447
448 private:
454 bool isValidAddress(uint8_t address) const;
455
463 bool writeRegisterVerified(uint8_t address, uint16_t value, uint16_t verifyMask);
464
473 bool updateRegisterVerified(uint8_t address, uint16_t mask, uint16_t value, uint16_t verifyMask);
474
478 void seedDefaultRegisterCache();
479
485 bool checkDefaultRegisters(uint8_t& matchCount);
486
492 float senseGainValue(SenseGain gain) const;
493
499 float shuntResistance(BridgeId bridge) const;
500
505 float currentLimitReferenceShunt() const;
506
513 DRV8704CurrentPresetConfig presetConfig(CurrentModePreset preset, uint32_t pwmFrequencyHz) const;
514
521 bool deriveCurrentLimit(float amps, DRV8704CurrentLimitResult& result) const;
522
529 bool applyCurrentLimitResult(const DRV8704CurrentLimitResult& result, uint32_t pwmFrequencyHz);
530
536 bool applyBridgeState(BridgeId bridge);
537
542 bool performWriteReadbackProbe();
543
547 void beginTransaction();
548
552 void endTransaction();
553
559 uint16_t transferFrame(uint16_t frame);
560
567 void setBridgePins(int8_t in1Pin, int8_t in2Pin, BridgeMode mode);
568
574 void setBridgeStaticMode(BridgeId bridge, BridgeMode mode);
575
584 bool setBridgePwm(int8_t in1Pin, int8_t in2Pin, Direction direction, float speedPercent);
585
586 DRV8704Pins pins_;
587 SPIClass* spi_;
588 SPISettings spiSettings_;
589 uint16_t registerCache_[DRV8704_REGISTER_COUNT];
590 float shuntOhms_[2];
591 Direction bridgeDirections_[2];
592 DRV8704BridgeState bridgeStates_[2];
593 float bridgeSpeedPercents_[2];
594 CurrentModePreset currentPreset_;
595 DRV8704CurrentPresetConfig currentPresetConfig_;
596 DRV8704CurrentLimitResult currentLimitResult_;
597 bool currentLimitEnabled_;
598 DRV8704PwmBackend* pwmBackend_;
599 DRV8704PwmConfig pwmConfig_;
600 DRV8704PwmCapability pwmCapability_;
601 bool pwmModeEnabled_;
602 bool initialized_;
603 };
604
605 #endif // DRV8704_H
DRV8704PwmBackend
Abstract board-specific PWM backend used for DRV8704 bridge inputs.
Definition: drv8704_pwm.h:16
DRV8704
Arduino-facing DRV8704 device driver class.
Definition: drv8704.h:21
DRV8704::setCurrent
bool setCurrent(BridgeId bridge, Direction direction, float amps)
Compatibility overload retained during the control-model refactor.
Definition: drv8704.h:399
DRV8704::wake
void wake()
Bring the DRV8704 out of sleep mode when the sleep pin is available.
Definition: drv8704.cpp:109
DRV8704::setBridgeMode
void setBridgeMode(BridgeId bridge, BridgeMode mode)
Low-level static bridge helper retained for compatibility.
Definition: drv8704_bridge.cpp:159
DRV8704::begin
bool begin()
Initialize GPIO and SPI state for the device.
Definition: drv8704.cpp:34
DRV8704::pwmCapability
DRV8704PwmCapability pwmCapability() const
Return the resolved capability of the active PWM backend.
Definition: drv8704.h:407
DRV8704::updateRegister
bool updateRegister(uint8_t address, uint16_t mask, uint16_t value)
Update selected register bits while preserving other bits.
Definition: drv8704_comm.cpp:46
DRV8704::setCurrent
bool setCurrent(BridgeId bridge, float amps)
Program the chip for current drive on one bridge using the stored direction.
Definition: drv8704_current.cpp:250
DRV8704::writeRegister
bool writeRegister(uint8_t address, uint16_t value)
Write a 12-bit register payload to the device.
Definition: drv8704_comm.cpp:26
DRV8704::currentLimitResult
DRV8704CurrentLimitResult currentLimitResult() const
Return the most recent derived chip-global current-limit settings.
Definition: drv8704.h:286
DRV8704::setOffTime
bool setOffTime(uint8_t offTime)
Set the fixed PWM off time.
Definition: drv8704_config.cpp:55
DRV8704::setBlankTime
bool setBlankTime(uint8_t blankTime)
Set the current blanking time.
Definition: drv8704_config.cpp:64
DRV8704::setGateDriveCurrents
bool setGateDriveCurrents(GateDriveSinkCurrent iDriveN, GateDriveSourceCurrent iDriveP)
Set the gate-drive current fields.
Definition: drv8704_config.cpp:113
DRV8704::setTorque
bool setTorque(uint8_t torque)
Set the torque DAC value.
Definition: drv8704_config.cpp:47
DRV8704::writeRegister
bool writeRegister(RegisterAddress address, uint16_t value)
Write a register by symbolic address.
Definition: drv8704.h:86
DRV8704::setGateDriveTimes
bool setGateDriveTimes(GateDriveTime tDriveN, GateDriveTime tDriveP)
Set the gate-drive timing fields.
Definition: drv8704_config.cpp:104
DRV8704::beginPwmMode
bool beginPwmMode(const DRV8704PwmConfig &config=DRV8704PwmConfig())
Enable board-specific PWM generation for the DRV8704 input pins.
Definition: drv8704_bridge.cpp:184
DRV8704::hasFault
bool hasFault()
Check whether any reported fault bit is active.
Definition: drv8704_status.cpp:30
DRV8704::enableBridgeDriver
bool enableBridgeDriver(bool enabled)
Enable or disable the bridge driver through the CTRL register.
Definition: drv8704_config.cpp:23
DRV8704::setOcpThreshold
bool setOcpThreshold(OcpThreshold threshold)
Set the overcurrent threshold.
Definition: drv8704_config.cpp:88
DRV8704::sleep
void sleep()
Put the DRV8704 into sleep mode when the sleep pin is available.
Definition: drv8704.cpp:103
DRV8704::updateRegister
bool updateRegister(RegisterAddress address, uint16_t mask, uint16_t value)
Update selected register bits using a symbolic address.
Definition: drv8704.h:106
DRV8704::setShuntResistance
bool setShuntResistance(float ohms)
Set one shunt resistance value for both bridges in current mode.
Definition: drv8704_current.cpp:107
DRV8704::reset
void reset()
Pulse the reset pin when available.
Definition: drv8704.cpp:116
DRV8704::currentModePresetConfig
DRV8704CurrentPresetConfig currentModePresetConfig() const
Return the preset configuration currently selected for current-limit operation.
Definition: drv8704.h:280
DRV8704::setSenseGain
bool setSenseGain(SenseGain gain)
Set the current-sense amplifier gain.
Definition: drv8704_config.cpp:31
DRV8704::setCurrentModePreset
bool setCurrentModePreset(CurrentModePreset preset)
Select the predefined timing and decay preset used by current mode.
Definition: drv8704_current.cpp:120
DRV8704::brake
void brake(BridgeId bridge)
Drive one bridge to brake.
Definition: drv8704_bridge.cpp:149
DRV8704::cachedRegister
uint16_t cachedRegister(uint8_t address) const
Return the cached contents of a register.
Definition: drv8704.cpp:144
DRV8704::setOcpDeglitch
bool setOcpDeglitch(OcpDeglitch deglitch)
Set the overcurrent deglitch interval.
Definition: drv8704_config.cpp:96
DRV8704::readRegister
uint16_t readRegister(uint8_t address)
Read a 12-bit register payload from the device.
Definition: drv8704_comm.cpp:8
DRV8704::setDecayMode
bool setDecayMode(DecayMode mode)
Set the decay mode.
Definition: drv8704_config.cpp:72
DRV8704::endPwmMode
void endPwmMode()
Disable platform PWM generation and return bridge inputs to coast.
Definition: drv8704_bridge.cpp:224
DRV8704::isFaultPinActive
bool isFaultPinActive() const
Read the state of the optional FAULTn pin.
Definition: drv8704_status.cpp:22
DRV8704::disableCurrentLimit
bool disableCurrentLimit()
Disable the high-level current-limit configuration without forcing a bridge-state change.
Definition: drv8704_current.cpp:263
DRV8704::bridgeState
DRV8704BridgeState bridgeState(BridgeId bridge) const
Return the stored direction/runtime-state report for one bridge.
Definition: drv8704_bridge.cpp:180
DRV8704::direction
Direction direction(BridgeId bridge) const
Return the configured high-level direction for one bridge.
Definition: drv8704_current.cpp:154
DRV8704::setDecayTime
bool setDecayTime(uint8_t decayTime)
Set the mixed-decay transition time.
Definition: drv8704_config.cpp:80
DRV8704::DRV8704
DRV8704(const DRV8704Pins &pins, SPIClass &spi=SPI)
Construct a DRV8704 device instance.
Definition: drv8704.cpp:8
DRV8704::isCurrentLimitEnabled
bool isCurrentLimitEnabled() const
Return whether a high-level current limit is currently configured.
Definition: drv8704.h:274
DRV8704::applyConfig
bool applyConfig(const DRV8704Config &config)
Apply a high-level configuration snapshot to the device.
Definition: drv8704_config.cpp:143
DRV8704::clearFault
bool clearFault(FaultBit bit)
Clear one fault bit in the STATUS register.
Definition: drv8704_status.cpp:45
DRV8704::setSpeed
bool setSpeed(BridgeId bridge, Direction direction, float speedPercent)
Compatibility overload retained during the control-model refactor.
Definition: drv8704.h:388
DRV8704::isPwmModeEnabled
bool isPwmModeEnabled() const
Return whether PWM mode is currently active.
Definition: drv8704.h:421
DRV8704::end
void end()
End driver operation.
Definition: drv8704.cpp:98
DRV8704::setPwmFrequency
bool setPwmFrequency(uint32_t frequencyHz)
Update the requested PWM frequency.
Definition: drv8704_bridge.cpp:257
DRV8704::smallestDutyIncrementPercent
float smallestDutyIncrementPercent() const
Return the smallest duty-percent step of the active PWM backend.
Definition: drv8704.h:413
DRV8704::setDeadTime
bool setDeadTime(DeadTime deadTime)
Set the bridge dead time.
Definition: drv8704_config.cpp:39
DRV8704::isInitialized
bool isInitialized() const
Report whether the driver completed initialization.
Definition: drv8704.h:433
DRV8704::syncRegisterCache
bool syncRegisterCache()
Refresh the local register cache from device reads.
Definition: drv8704.cpp:152
DRV8704::hasFaultPin
bool hasFaultPin() const
Report whether a dedicated FAULTn pin was provided.
Definition: drv8704.h:304
DRV8704::coast
void coast(BridgeId bridge)
Drive one bridge to coast.
Definition: drv8704_bridge.cpp:139
DRV8704::setCurrentLimit
bool setCurrentLimit(float amps)
Program the chip-global current limit in amperes without changing bridge state.
Definition: drv8704_current.cpp:237
DRV8704::readRegister
uint16_t readRegister(RegisterAddress address)
Read a register by symbolic address.
Definition: drv8704.h:68
DRV8704::readStatus
DRV8704Status readStatus()
Read and decode the STATUS register.
Definition: drv8704_status.cpp:8
DRV8704::setDirection
bool setDirection(BridgeId bridge, Direction direction)
Set the direction used by high-level current-drive and PWM-drive commands.
Definition: drv8704_current.cpp:142
DRV8704::setGateDrive
bool setGateDrive(const GateDriveConfig &gateDrive)
Apply the complete DRIVE register configuration.
Definition: drv8704_config.cpp:122
DRV8704::clearFaults
bool clearFaults()
Clear all clearable fault bits in the STATUS register.
Definition: drv8704_status.cpp:41
DRV8704::healthCheck
DRV8704HealthCheck healthCheck()
Perform a minimal transport/status health check.
Definition: drv8704.cpp:127
DRV8704::setSpeed
bool setSpeed(BridgeId bridge, float speedPercent)
Apply an open-loop speed command to one bridge using hardware PWM.
Definition: drv8704_bridge.cpp:274
drv8704_defs.h
Constants, register addresses, masks, and defaults for the DRV8704 driver.
DRV8704_REGISTER_COUNT
#define DRV8704_REGISTER_COUNT
Definition: drv8704_defs.h:35
drv8704_regs_typedefs.h
Typed register views for the DRV8704 register set.
drv8704_types.h
Public enums and data structures for the DRV8704 driver.
GateDriveSourceCurrent
GateDriveSourceCurrent
Supported source current values for the predriver.
Definition: drv8704_types.h:74
FaultBit
FaultBit
Selectable fault bits in the STATUS register.
Definition: drv8704_types.h:153
OcpDeglitch
OcpDeglitch
Supported OCP deglitch durations.
Definition: drv8704_types.h:54
Direction
Direction
High-level direction selector for current mode and PWM mode.
Definition: drv8704_types.h:122
CurrentModePreset
CurrentModePreset
Predefined load presets for current-mode timing and decay behavior.
Definition: drv8704_types.h:142
RegisterAddress
RegisterAddress
Supported register addresses.
Definition: drv8704_types.h:165
GateDriveTime
GateDriveTime
Supported gate-drive timing values.
Definition: drv8704_types.h:64
GateDriveSinkCurrent
GateDriveSinkCurrent
Supported sink current values for the predriver.
Definition: drv8704_types.h:84
DecayMode
DecayMode
Supported current-decay modes.
Definition: drv8704_types.h:34
OcpThreshold
OcpThreshold
Supported overcurrent thresholds.
Definition: drv8704_types.h:44
BridgeId
BridgeId
Bridge selector.
Definition: drv8704_types.h:94
DeadTime
DeadTime
Supported dead-time settings.
Definition: drv8704_types.h:24
SenseGain
SenseGain
Supported sense amplifier gain settings.
Definition: drv8704_types.h:14
BridgeMode
BridgeMode
Runtime bridge command.
Definition: drv8704_types.h:102
DRV8704BridgeState
Reported direction and runtime mode of one bridge.
Definition: drv8704_types.h:268
DRV8704Config
High-level DRV8704 configuration snapshot.
Definition: drv8704_types.h:223
DRV8704CurrentLimitResult
Derived chip-global current-limit settings and per-bridge consequences.
Definition: drv8704_types.h:284
DRV8704CurrentPresetConfig
Timing and decay recommendation associated with a current-mode preset.
Definition: drv8704_types.h:248
DRV8704HealthCheck
Minimal transport/bring-up health result.
Definition: drv8704_types.h:376
DRV8704Pins
Pin assignment bundle for a DRV8704 instance.
Definition: drv8704_types.h:179
DRV8704Pins::faultPin
int8_t faultPin
Definition: drv8704_types.h:183
DRV8704PwmCapability
Resolved platform PWM capabilities for the active backend.
Definition: drv8704_types.h:332
DRV8704PwmCapability::smallestDutyIncrementPercent
float smallestDutyIncrementPercent
Definition: drv8704_types.h:339
DRV8704PwmConfig
Requested PWM generator settings.
Definition: drv8704_types.h:320
DRV8704Status
Decoded device status and fault state.
Definition: drv8704_types.h:354
GateDriveConfig
Gate-drive configuration group.
Definition: drv8704_types.h:203