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

Public Member Functions | List of all members
DRV8704 Class Reference

Arduino-facing DRV8704 device driver class. More...

`#include <drv8704.h>`

## Public Member Functions
bool | applyConfig (const DRV8704Config &config)
| Apply a high-level configuration snapshot to the device. More...
bool | begin ()
| Initialize GPIO and SPI state for the device. More...
bool | beginPwmMode (const DRV8704PwmConfig &config=DRV8704PwmConfig())
| Enable board-specific PWM generation for the DRV8704 input pins. More...
void | brake (BridgeId bridge)
| Drive one bridge to brake. More...
DRV8704BridgeState | bridgeState (BridgeId bridge) const
| Return the stored direction/runtime-state report for one bridge. More...
uint16_t | cachedRegister (uint8_t address) const
| Return the cached contents of a register. More...
bool | clearFault (FaultBit bit)
| Clear one fault bit in the STATUS register. More...
bool | clearFaults ()
| Clear all clearable fault bits in the STATUS register. More...
void | coast (BridgeId bridge)
| Drive one bridge to coast. More...
DRV8704CurrentLimitResult | currentLimitResult () const
| Return the most recent derived chip-global current-limit settings. More...
DRV8704CurrentPresetConfig | currentModePresetConfig () const
| Return the preset configuration currently selected for current-limit operation. More...
Direction | direction (BridgeId bridge) const
| Return the configured high-level direction for one bridge. More...
bool | disableCurrentLimit ()
| Disable the high-level current-limit configuration without forcing a bridge-state change. More...
| DRV8704 (const DRV8704Pins &pins, SPIClass &spi=SPI)
| Construct a DRV8704 device instance. More...
bool | enableBridgeDriver (bool enabled)
| Enable or disable the bridge driver through the CTRL register. More...
void | end ()
| End driver operation. More...
void | endPwmMode ()
| Disable platform PWM generation and return bridge inputs to coast. More...
bool | hasFault ()
| Check whether any reported fault bit is active. More...
bool | hasFaultPin () const
| Report whether a dedicated `FAULTn` pin was provided. More...
DRV8704HealthCheck | healthCheck ()
| Perform a minimal transport/status health check. More...
bool | isCurrentLimitEnabled () const
| Return whether a high-level current limit is currently configured. More...
bool | isFaultPinActive () const
| Read the state of the optional `FAULTn` pin. More...
bool | isInitialized () const
| Report whether the driver completed initialization. More...
bool | isPwmModeEnabled () const
| Return whether PWM mode is currently active. More...
DRV8704PwmCapability | pwmCapability () const
| Return the resolved capability of the active PWM backend. More...
uint16_t | readRegister (RegisterAddress address)
| Read a register by symbolic address. More...
uint16_t | readRegister (uint8_t address)
| Read a 12-bit register payload from the device. More...
DRV8704Status | readStatus ()
| Read and decode the STATUS register. More...
void | reset ()
| Pulse the reset pin when available. More...
bool | setBlankTime (uint8_t blankTime)
| Set the current blanking time. More...
void | setBridgeMode (BridgeId bridge, BridgeMode mode)
| Low-level static bridge helper retained for compatibility. More...
bool | setCurrent (BridgeId bridge, Direction direction, float amps)
| Compatibility overload retained during the control-model refactor. More...
bool | setCurrent (BridgeId bridge, float amps)
| Program the chip for current drive on one bridge using the stored direction. More...
bool | setCurrentLimit (float amps)
| Program the chip-global current limit in amperes without changing bridge state. More...
bool | setCurrentModePreset (CurrentModePreset preset)
| Select the predefined timing and decay preset used by current mode. More...
bool | setDeadTime (DeadTime deadTime)
| Set the bridge dead time. More...
bool | setDecayMode (DecayMode mode)
| Set the decay mode. More...
bool | setDecayTime (uint8_t decayTime)
| Set the mixed-decay transition time. More...
bool | setDirection (BridgeId bridge, Direction direction)
| Set the direction used by high-level current-drive and PWM-drive commands. More...
bool | setGateDrive (const GateDriveConfig &gateDrive)
| Apply the complete DRIVE register configuration. More...
bool | setGateDriveCurrents (GateDriveSinkCurrent iDriveN, GateDriveSourceCurrent iDriveP)
| Set the gate-drive current fields. More...
bool | setGateDriveTimes (GateDriveTime tDriveN, GateDriveTime tDriveP)
| Set the gate-drive timing fields. More...
bool | setOcpDeglitch (OcpDeglitch deglitch)
| Set the overcurrent deglitch interval. More...
bool | setOcpThreshold (OcpThreshold threshold)
| Set the overcurrent threshold. More...
bool | setOffTime (uint8_t offTime)
| Set the fixed PWM off time. More...
bool | setPwmFrequency (uint32_t frequencyHz)
| Update the requested PWM frequency. More...
bool | setSenseGain (SenseGain gain)
| Set the current-sense amplifier gain. More...
bool | setShuntResistance (BridgeId bridge, float ohms)
| Set the shunt resistance for one bridge in current mode. More...
bool | setShuntResistance (float ohms)
| Set one shunt resistance value for both bridges in current mode. More...
bool | setSpeed (BridgeId bridge, Direction direction, float speedPercent)
| Compatibility overload retained during the control-model refactor. More...
bool | setSpeed (BridgeId bridge, float speedPercent)
| Apply an open-loop speed command to one bridge using hardware PWM. More...
bool | setTorque (uint8_t torque)
| Set the torque DAC value. More...
void | sleep ()
| Put the DRV8704 into sleep mode when the sleep pin is available. More...
float | smallestDutyIncrementPercent () const
| Return the smallest duty-percent step of the active PWM backend. More...
bool | syncRegisterCache ()
| Refresh the local register cache from device reads. More...
bool | updateRegister (RegisterAddress address, uint16_t mask, uint16_t value)
| Update selected register bits using a symbolic address. More...
bool | updateRegister (uint8_t address, uint16_t mask, uint16_t value)
| Update selected register bits while preserving other bits. More...
void | wake ()
| Bring the DRV8704 out of sleep mode when the sleep pin is available. More...
bool | writeRegister (RegisterAddress address, uint16_t value)
| Write a register by symbolic address. More...
bool | writeRegister (uint8_t address, uint16_t value)
| Write a 12-bit register payload to the device. More...

## Detailed Description

Arduino-facing DRV8704 device driver class.

## Constructor & Destructor Documentation

## ◆ DRV8704()

DRV8704::DRV8704 | ( | const DRV8704Pins & | pins,
|  | SPIClass & | spi = `SPI`
| ) |  |
| explicit

Construct a DRV8704 device instance.

Parameters

  pins | Pin assignment bundle for this device.
  spi | SPI bus instance to use for transfers.

## Member Function Documentation

## ◆ applyConfig()

bool DRV8704::applyConfig | ( | const DRV8704Config & | config | ) |

Apply a high-level configuration snapshot to the device.

Parameters

  config | Desired driver configuration.

Returns
  True if the configuration sequence completed.

## ◆ begin()

bool DRV8704::begin | ( |  | ) |

Initialize GPIO and SPI state for the device.

Returns
  True if startup completed without transport failure.

## ◆ beginPwmMode()

bool DRV8704::beginPwmMode | ( | const DRV8704PwmConfig & | config = `DRV8704PwmConfig()` | ) |

Enable board-specific PWM generation for the DRV8704 input pins.

Parameters

  config | Requested PWM frequency and duty resolution.

Returns
  True when a supported PWM backend was initialized.

## ◆ brake()

void DRV8704::brake | ( | BridgeId | bridge | ) |

Drive one bridge to brake.

Parameters

  bridge | Bridge selector.

## ◆ bridgeState()

DRV8704BridgeState DRV8704::bridgeState | ( | BridgeId | bridge | ) | const

Return the stored direction/runtime-state report for one bridge.

Parameters

  bridge | Bridge selector.

Returns
  Bridge runtime state report.

## ◆ cachedRegister()

uint16_t DRV8704::cachedRegister | ( | uint8_t | address | ) | const

Return the cached contents of a register.

Parameters

  address | Register address.

Returns
  Cached register payload or 0 for an invalid address.

## ◆ clearFault()

bool DRV8704::clearFault | ( | FaultBit | bit | ) |

Clear one fault bit in the STATUS register.

Parameters

  bit | Fault bit selector.

Returns
  True if the clear write completed.

## ◆ clearFaults()

bool DRV8704::clearFaults | ( |  | ) |

Clear all clearable fault bits in the STATUS register.

Returns
  True if the clear write completed.

## ◆ coast()

void DRV8704::coast | ( | BridgeId | bridge | ) |

Drive one bridge to coast.

Parameters

  bridge | Bridge selector.

## ◆ currentLimitResult()

DRV8704CurrentLimitResult DRV8704::currentLimitResult | ( |  | ) | const
| inline

Return the most recent derived chip-global current-limit settings.

Returns
  Current-limit result structure.

## ◆ currentModePresetConfig()

DRV8704CurrentPresetConfig DRV8704::currentModePresetConfig | ( |  | ) | const
| inline

Return the preset configuration currently selected for current-limit operation.

Returns
  Current-limit preset settings.

## ◆ direction()

Direction DRV8704::direction | ( | BridgeId | bridge | ) | const

Return the configured high-level direction for one bridge.

Parameters

  bridge | Bridge selector.

Returns
  Stored bridge direction.

## ◆ disableCurrentLimit()

bool DRV8704::disableCurrentLimit | ( |  | ) |

Disable the high-level current-limit configuration without forcing a bridge-state change.

Returns
  True when the high-level current-limit state was cleared.

The implementation programs the maximum representable current limit and clears the high-level bookkeeping so future PWM-current-limit commands require a deliberate limit request.

## ◆ enableBridgeDriver()

bool DRV8704::enableBridgeDriver | ( | bool | enabled | ) |

Enable or disable the bridge driver through the CTRL register.

Parameters

  enabled | True to enable bridge drive.

Returns
  True if the operation completed.

## ◆ end()

void DRV8704::end | ( |  | ) |

End driver operation.

## ◆ endPwmMode()

void DRV8704::endPwmMode | ( |  | ) |

Disable platform PWM generation and return bridge inputs to coast.

## ◆ hasFault()

bool DRV8704::hasFault | ( |  | ) |

Check whether any reported fault bit is active.

Returns
  True if a fault is reported.

## ◆ hasFaultPin()

bool DRV8704::hasFaultPin | ( |  | ) | const
| inline

Report whether a dedicated `FAULTn` pin was provided.

Returns
  True if the device instance can monitor the hardware fault pin.

## ◆ healthCheck()

DRV8704HealthCheck DRV8704::healthCheck | ( |  | ) |

Perform a minimal transport/status health check.

Returns
  Health-check result.

## ◆ isCurrentLimitEnabled()

bool DRV8704::isCurrentLimitEnabled | ( |  | ) | const
| inline

Return whether a high-level current limit is currently configured.

Returns
  True when current-limit settings are armed for current-drive or PWM-current-limit use.

## ◆ isFaultPinActive()

bool DRV8704::isFaultPinActive | ( |  | ) | const

Read the state of the optional `FAULTn` pin.

Returns
  True when the open-drain fault pin is asserted low.

## ◆ isInitialized()

bool DRV8704::isInitialized | ( |  | ) | const
| inline

Report whether the driver completed initialization.

Returns
  True if begin() completed successfully.

## ◆ isPwmModeEnabled()

bool DRV8704::isPwmModeEnabled | ( |  | ) | const
| inline

Return whether PWM mode is currently active.

Returns
  True when a supported PWM backend is enabled.

## ◆ pwmCapability()

DRV8704PwmCapability DRV8704::pwmCapability | ( |  | ) | const
| inline

Return the resolved capability of the active PWM backend.

Returns
  Active PWM capability report.

## ◆ readRegister() [1/2]

uint16_t DRV8704::readRegister | ( | RegisterAddress | address | ) |
| inline

Read a register by symbolic address.

Parameters

  address | Register address enum.

Returns
  Register payload masked to 12 bits.

## ◆ readRegister() [2/2]

uint16_t DRV8704::readRegister | ( | uint8_t | address | ) |

Read a 12-bit register payload from the device.

Parameters

  address | Register address.

Returns
  Register payload masked to 12 bits.

## ◆ readStatus()

DRV8704Status DRV8704::readStatus | ( |  | ) |

Read and decode the STATUS register.

Returns
  Decoded status structure.

## ◆ reset()

void DRV8704::reset | ( |  | ) |

Pulse the reset pin when available.

## ◆ setBlankTime()

bool DRV8704::setBlankTime | ( | uint8_t | blankTime | ) |

Set the current blanking time.

Parameters

  blankTime | BLANK register TBLANK value.

Returns
  True if the register update and readback verification completed.

## ◆ setBridgeMode()

void DRV8704::setBridgeMode | ( | BridgeId | bridge,
|  | BridgeMode | mode
| ) |  |

Low-level static bridge helper retained for compatibility.

Parameters

  bridge | Bridge selector.
  mode | Static bridge mode.

## ◆ setCurrent() [1/2]

bool DRV8704::setCurrent | ( | BridgeId | bridge,
|  | Direction | direction,
|  | float | amps
| ) |  |
| inline

Compatibility overload retained during the control-model refactor.

Parameters

  bridge | Bridge selector.
  direction | Desired bridge direction.
  amps | Requested current in amperes.

Returns
  True when the request was applied.

## ◆ setCurrent() [2/2]

bool DRV8704::setCurrent | ( | BridgeId | bridge,
|  | float | amps
| ) |  |

Program the chip for current drive on one bridge using the stored direction.

Parameters

  bridge | Bridge selector.
  amps | Requested current limit in amperes.

Returns
  True when the current-limit request was valid and the bridge entered current drive.

## ◆ setCurrentLimit()

bool DRV8704::setCurrentLimit | ( | float | amps | ) |

Program the chip-global current limit in amperes without changing bridge state.

Parameters

  amps | Requested current limit in amperes.

Returns
  True when the requested limit was derived and programmed successfully.

## ◆ setCurrentModePreset()

bool DRV8704::setCurrentModePreset | ( | CurrentModePreset | preset | ) |

Select the predefined timing and decay preset used by current mode.

Parameters

  preset | Preset family to apply.

Returns
  True when the preset configuration was written successfully.

## ◆ setDeadTime()

bool DRV8704::setDeadTime | ( | DeadTime | deadTime | ) |

Set the bridge dead time.

Parameters

  deadTime | Desired dead-time setting.

Returns
  True if the register update and readback verification completed.

## ◆ setDecayMode()

bool DRV8704::setDecayMode | ( | DecayMode | mode | ) |

Set the decay mode.

Parameters

  mode | Desired decay mode.

Returns
  True if the register update and readback verification completed.

## ◆ setDecayTime()

bool DRV8704::setDecayTime | ( | uint8_t | decayTime | ) |

Set the mixed-decay transition time.

Parameters

  decayTime | DECAY register TDECAY value.

Returns
  True if the register update and readback verification completed.

## ◆ setDirection()

bool DRV8704::setDirection | ( | BridgeId | bridge,
|  | Direction | direction
| ) |  |

Set the direction used by high-level current-drive and PWM-drive commands.

Parameters

  bridge | Bridge selector.
  direction | Desired bridge direction.

Returns
  True when the bridge direction was accepted.

## ◆ setGateDrive()

bool DRV8704::setGateDrive | ( | const GateDriveConfig & | gateDrive | ) |

Apply the complete DRIVE register configuration.

Parameters

  gateDrive | Desired gate-drive configuration.

Returns
  True if the register write and readback verification completed.

## ◆ setGateDriveCurrents()

bool DRV8704::setGateDriveCurrents | ( | GateDriveSinkCurrent | iDriveN,
|  | GateDriveSourceCurrent | iDriveP
| ) |  |

Set the gate-drive current fields.

Parameters

  iDriveN | Sink current selection.
  iDriveP | Source current selection.

Returns
  True if the register update and readback verification completed.

## ◆ setGateDriveTimes()

bool DRV8704::setGateDriveTimes | ( | GateDriveTime | tDriveN,
|  | GateDriveTime | tDriveP
| ) |  |

Set the gate-drive timing fields.

Parameters

  tDriveN | Sink timing selection.
  tDriveP | Source timing selection.

Returns
  True if the register update and readback verification completed.

## ◆ setOcpDeglitch()

bool DRV8704::setOcpDeglitch | ( | OcpDeglitch | deglitch | ) |

Set the overcurrent deglitch interval.

Parameters

  deglitch | Desired OCP deglitch setting.

Returns
  True if the register update and readback verification completed.

## ◆ setOcpThreshold()

bool DRV8704::setOcpThreshold | ( | OcpThreshold | threshold | ) |

Set the overcurrent threshold.

Parameters

  threshold | Desired OCP threshold.

Returns
  True if the register update and readback verification completed.

## ◆ setOffTime()

bool DRV8704::setOffTime | ( | uint8_t | offTime | ) |

Set the fixed PWM off time.

Parameters

  offTime | OFF register TOFF value.

Returns
  True if the register update and readback verification completed.

## ◆ setPwmFrequency()

bool DRV8704::setPwmFrequency | ( | uint32_t | frequencyHz | ) |

Update the requested PWM frequency.

Parameters

  frequencyHz | Requested PWM frequency in hertz.

Returns
  True when the active backend accepted the new frequency.

## ◆ setSenseGain()

bool DRV8704::setSenseGain | ( | SenseGain | gain | ) |

Set the current-sense amplifier gain.

Parameters

  gain | Desired sense amplifier gain.

Returns
  True if the register update and readback verification completed.

## ◆ setShuntResistance() [1/2]

bool DRV8704::setShuntResistance | ( | BridgeId | bridge,
|  | float | ohms
| ) |  |

Set the shunt resistance for one bridge in current mode.

Parameters

  bridge | Bridge selector.
  ohms | Sense resistor value in ohms.

Returns
  True when the provided value is valid.

## ◆ setShuntResistance() [2/2]

bool DRV8704::setShuntResistance | ( | float | ohms | ) |

Set one shunt resistance value for both bridges in current mode.

Parameters

  ohms | Sense resistor value in ohms.

Returns
  True when the provided value is valid.

## ◆ setSpeed() [1/2]

bool DRV8704::setSpeed | ( | BridgeId | bridge,
|  | Direction | direction,
|  | float | speedPercent
| ) |  |
| inline

Compatibility overload retained during the control-model refactor.

Parameters

  bridge | Bridge selector.
  direction | Desired bridge direction.
  speedPercent | Open-loop duty request from 0 to 100 percent.

Returns
  True when the requested speed was applied.

## ◆ setSpeed() [2/2]

bool DRV8704::setSpeed | ( | BridgeId | bridge,
|  | float | speedPercent
| ) |  |

Apply an open-loop speed command to one bridge using hardware PWM.

Parameters

  bridge | Bridge selector.
  speedPercent | Open-loop duty request from 0 to 100 percent.

Returns
  True when the requested speed was applied.

This is PWM with current limit. A speed of 0 behaves like coast. A speed of 100 forces a constant-on directional input without PWM toggling. Intermediate values apply hardware PWM using the stored bridge direction.

## ◆ setTorque()

bool DRV8704::setTorque | ( | uint8_t | torque | ) |

Set the torque DAC value.

Parameters

  torque | Torque DAC code.

Returns
  True if the register update and readback verification completed.

## ◆ sleep()

void DRV8704::sleep | ( |  | ) |

Put the DRV8704 into sleep mode when the sleep pin is available.

## ◆ smallestDutyIncrementPercent()

float DRV8704::smallestDutyIncrementPercent | ( |  | ) | const
| inline

Return the smallest duty-percent step of the active PWM backend.

Returns
  Smallest achievable duty increment in percent.

## ◆ syncRegisterCache()

bool DRV8704::syncRegisterCache | ( |  | ) |

Refresh the local register cache from device reads.

Returns
  True if all register reads completed.

## ◆ updateRegister() [1/2]

bool DRV8704::updateRegister | ( | RegisterAddress | address,
|  | uint16_t | mask,
|  | uint16_t | value
| ) |  |
| inline

Update selected register bits using a symbolic address.

Parameters

  address | Register address enum.
  mask | Bit mask for fields to update.
  value | New masked field value.

Returns
  True if the write transfer completed.

## ◆ updateRegister() [2/2]

bool DRV8704::updateRegister | ( | uint8_t | address,
|  | uint16_t | mask,
|  | uint16_t | value
| ) |  |

Update selected register bits while preserving other bits.

Parameters

  address | Register address.
  mask | Bit mask for fields to update.
  value | New masked field value.

Returns
  True if the write transfer completed.

## ◆ wake()

void DRV8704::wake | ( |  | ) |

Bring the DRV8704 out of sleep mode when the sleep pin is available.

## ◆ writeRegister() [1/2]

bool DRV8704::writeRegister | ( | RegisterAddress | address,
|  | uint16_t | value
| ) |  |
| inline

Write a register by symbolic address.

Parameters

  address | Register address enum.
  value | Register payload.

Returns
  True if the write transfer completed.

## ◆ writeRegister() [2/2]

bool DRV8704::writeRegister | ( | uint8_t | address,
|  | uint16_t | value
| ) |  |

Write a 12-bit register payload to the device.

Parameters

  address | Register address.
  value | Register payload.

Returns
  True if the write transfer completed.

The documentation for this class was generated from the following files:

- src/drv8704.h
- src/drv8704.cpp
- src/drv8704_bridge.cpp
- src/drv8704_comm.cpp
- src/drv8704_config.cpp
- src/drv8704_current.cpp
- src/drv8704_status.cpp