API Reference

The Arduino library API is implemented via 3 different classes:

  • HalfBridge. This class provides the primary API to operate and configure the half-bridge devices. → Use with arbitary board or custom hardware design with BTN99x0 half-bridge.

  • DCShield. This class is a convenience class resolving the hardware configuration of the DC Motor Control Shield with BTN9970LV and BTN9990LV half-bridge switches. → Use with the DC Motor control Shield when driving arbitary loads.

  • MotorControl. This class provides motor controlling functionality using the DC Motor Control Shield and abstracting the half-bridge API. → Use with the DC Motor control Shield when driving DC motors.

_images/btn99x0_class_overview.png

HalfBridge API

class btn99x0::HalfBridge

Public Functions

HalfBridge(ic_variant_t ic_variant, io_pins_t io_pins, hw_conf_t hw_conf)

BTN99x0 Half Bridge Constructor.

Parameters

  • ic_variant – [in] IC product variant

  • io_pins – [in] IC controller connected pins (inhibit, input and current sense)

  • hw_conf – [in] Hardware configuration and experimental parameters

Pre

None

~HalfBridge()

BTN99x0 Half Bridge Destructor.

Pre

None

void begin()

Initializes the device.

Calculates the offset current on the current sense ADC input port

Pre

None

void disable()

Disables the device output setting it to high impedance.

Set the inhibit pin low

Pre

None

void enable()

Enables the device output.

Sets the inhibit pin high

Pre

None

void set_pwm(uint8_t duty)

Sets a PWM signal in the output for the given duty cycle.

The PWM signal is provided at the half-bridge input pin

Parameters

duty – [in] Duty cycle in range from 0 to 255

Pre

None

void set_pwm_in_percentage(uint8_t duty_in_pct)

Sets a PWM signal in the output for the given duty cycle.

The PWM signal is provided at the half-bridge input pin

Parameters

duty_in_pct – [in] Duty cycle in percentage from 0 % to 100 %

Pre

None

error_t set_slew_rate(slew_rate_level_t sr_level)

Sets slew rate level.

The slew level is configured by making a pulse sequence at the input pin while the inhibit pin is set to low. The number of pulses determine the level of the slew rate. Find more information in the section “4.4.2 Adjustable

slew rate” in page 23 of the BTN99x0 datasheet (Rev. 1.0)

Warning

The current operation requires the device to be in slew rate selection mode, meaning the INH pin to be set to low. The function operates the INPUT pin, any PWM value previously configured will be overwritten

Parameters

re_level – [in] Slew rate level

Pre

begin() and disable() if the half bridge has been previously enabled

Returns

Error code

Returns

  • INVALID_OPERATION_ERROR – if the half bridge inhibit pin is not LOW

  • NO_ERROR – if the half-bridge is operating properly

void set_ktis(float ktis_amps_per_kelvin)

Sets the k_TIS constant.

The k_TIS constant is used to calculate the chip temperature. Find out more in the datasheet about how to experimentally measure the constant value for your system setup

Parameters

ktis_amps_per_kelvin – [in] K_TIS experimental constant

Pre

None

void set_dk(uint16_t dk)

Sets the dk constant.

The dk constant is used to calculate the load current. Find out more in the datasheet about how to experimentally measure the constant value for your system setup

Parameters

dk – [in] Differential current sense ratio

Pre

None

double get_load_current_in_amps()

Gets load current in amperes.

Returns

Load current in amperes

Pre

begin()

double get_temperature_in_kelvin()

Gets the device temperature in kelvin.

Warning

The current operation requires the device to be in slew rate selection mode, meaning the INH pin to be set to low. The function operates the INPUT pin, any PWM value previously configured will be overwritten

Pre

begin() and disable() if the half bridge has been previously enabled

Returns

Temperature in kelvin

Returns

Negative – value. INVALID_OPERATION_ERROR if the half bridge inhibit pin is not LOW

error_t get_diagnosis()

Checks if there is any failure in the half-bridge.

Check if the current at the sense resistor is above the fault current threshold. Find more information about extended diagnosis functionalities in the datasheet

Returns

Error code

Pre

begin()

Returns

  • FAULT_CURRENT_ERROR – if error

  • NO_ERROR – if the half-bridge is operating properly

DCShield API

class btn99x0::DCShield

Public Types

enum half_bridge_id_t

Values:

enumerator HALF_BRIDGE_1

Half-bridge identifier 1

enumerator HALF_BRIDGE_2

Half-bridge identifier 2

Public Functions

DCShield(io_pins_t hb1_io_pins = hb1_io_pins_default, io_pins_t hb2_io_pins = hb2_io_pins_default, hw_conf_t shield_platf_conf = hw_conf_default)

BTN99x0 DC Shield Constructor.

Constructs the half-bridge shield instances for the given arguments and the parameters set by the shield

Parameters

  • ic_variant – [in] IC product variant

  • hb1_io_pins – [in] Half-bridge 1 IO pins (inhibit, input and current sense)

  • hb2_io_pins – [in] Half-bridge 2 IO pins (inhibit, input and current sense)

  • shield_platf_conf – [in] Hardware configuration and experimental parameters

Pre

None

~DCShield()

BTN99x0 DC Shield Destructor.

Destructs the half-bridge shield instances

Pre

None

HalfBridge &get_half_bridge(half_bridge_id_t half_bridge_id)

Gets the reference of the half-bridge instance given its identifier.

Parameters

half_bridge_id – [in] Half-bridge identifier

Returns

half-bridge shield instance

Pre

None

void disable_all(void)

Disables all the half-bridges on the shield.

Pre

None

void enable_all(void)

Enables all the half-bridges on the shield.

Pre

None

MotorControl API

class btn99x0::MotorControl

Public Functions

MotorControl(DCShield &shield)

BTN99x0 Motor Control Constructor.

Parameters

shield – [in] DC shield reference to be used for motor controlling

Pre

None

~MotorControl()

BTN99x0 Motor Control Destructor.

Pre

None

void begin()

Initializes the motor controller.

Initializes both half-bridges

Pre

None

void brake(void)

Stops the motor.

Sets the input pin of both half-bridges to low

Pre

None

void freewheel(void)

Sets the motor in freewheeling mode.

Sets the inhibit pin of both half-bridges to low

Pre

None

void set_speed(int16_t speed)

Sets the motor speed.

Enables the half-bridges outputs and provides a PWM with the given duty cycle to half-bridge 1 if the speed is positive, or to half-bridge 2 if the speed is negative

Note

If speed values out of range are provided these will be set the maximum or minimum allowed

Parameters

speed – [in] Motor speed. Valid range is between -255 and 255. Use positive duty values for forward rotation and negative for backward rotation

Pre

None

void set_slew_rate(slew_rate_level_t sr_level)

Sets slew rate level.

Sets the slew rate level of both half-bridges

Warning

The current operation requires the device to be in slew rate selection mode, meaning the INH pins to be set to low. The function operates the INPUT pins, any PWM values previously configured will be overwritten

Parameters

sr_level – [in] Slew rate level

Pre

begin() and freewheel() if the motor has been previously enabled

BTN99x0 Types

struct btn99x0::io_pins_t

Half-bridge device pins.

Public Members

uint16_t analog

Current sense device analog output pin

uint16_t input

Input pin. Controls the output signal value

uint16_t inhibit

Inhibit pin- Controls the output enablement/disablement

struct btn99x0::ic_experimental_const_t

Half-bridge experimental constants.

Public Members

float ktis_amps_per_kelvin

Temperature coefficient for temperature sense uA/K

uint16_t dk

Differential current sense ratio

double sense_current_offset_amps

Current sense offset in amperes

struct btn99x0::hw_conf_t

Half-bridge hardware configuration.

Public Members

uint16_t sense_current_resistor_ohms

Sense current resistor in ohms

float adc_voltage_range_volts

Platform current sense ADC voltage range in volts

uint16_t adc_resolution_steps

Platform ADC resolution in steps (2^(bits) - 1)

enum btn99x0::ic_variant_t

Values:

enumerator IC_VARIANT_BTN9970LV

BTN9970LV variant

enumerator IC_VARIANT_BTN9990LV

BTN9990LV variant

enum btn99x0::slew_rate_level_t

Values:

enumerator SLEW_RATE_LEVEL_0

Slew level 0

enumerator SLEW_RATE_LEVEL_1

Slew level 1

enumerator SLEW_RATE_LEVEL_2

Slew level 2

enumerator SLEW_RATE_LEVEL_3

Slew level 3

enumerator SLEW_RATE_LEVEL_4

Slew level 4

enumerator SLEW_RATE_LEVEL_5

Slew level 5

enumerator SLEW_RATE_LEVEL_6

Slew level 6

enumerator SLEW_RATE_LEVEL_7

Slew level 7

enum btn99x0::error_t

Values:

enumerator NO_ERROR

No error

enumerator FAULT_CURRENT_ERROR

Fault current error

enumerator INVALID_OPERATION_ERROR

Invalid operation error