HX711

Driver superclass for the HX711 load cell amplifier/DAC.

  • Author(s): Erik Hess

Implementation Notes

Driver Subclasses

  • HX711_GPIO, works with all CircuitPython boards but may be subject to timing issues

  • HX711_PIO, uses RP2-series (ie, RP2040) PIO to provide consistent pulse timing

Hardware:

Software and Dependencies:

class hx711.HX711(gain: int = 1, offset: int = 0, scalar: float = 1, tare: bool = False)

Provide basic driver services for the HX711 load cell amplifier/ADC

This subclass includes a GPIO bit-bang implemenation of the HX711 two-wire serial protocol using two GPIO pins, one for data and one for clock.

Parameters:

  • int (offset) – Gain/channel setting for ADC readings. Defaults to 1

  • int – Zero-offset to apply to readings. Defaults to 0

  • scalar (float) – Scalar to use for conversion of ADC counts to units. Defaults to 1

  • tare (bool) – If true, perform tare() on instantiation. Defaults to False

Quickstart: Importing and using the HX711

Here is an example of using the HX711 class.

First you will need to import the specific library subclass you’d like to use to access the sensor

import board
from hx711.hx711_gpio import HX711_GPIO

Once this is done you can define your DigitalInOut objects for the pins attached to the HX711 sensor and define the sensor object.

from digitalio import DigitalInOut

gpio_data = DigitalInOut(board.D5)
gpio_clk = DigitalInOut(board.D6)
hx711 = HX711_GPIO(gpio_data, gpio_clk)

For defining the PIO subclass, you only need to use the board Pin rather than DigitalInOut objects.

pin_data = board.D5
pin_clk = board.D6
hx711 = HX711_PIO(pin_data, pin_clk)

After instantiation, you’ll have access to raw ADC counts.

hx711.read_raw()

These readings are a bit more useful with an offset applied, known as a “tare” operation. With this complete, future read() operations will return the difference between the offset and the reading.

hx711.tare()
print(hx711.read())

This tare() operation can be performed on instantation via kwarg as well.

hx711 = HX711_GPIO(gpio_data, gpio_clk, tare=True)

To return a weight in more useful units, you can determine and set a scalar value. The appropriate scalar for your particular load cell and unit of choice can be determined by adding a known weight and running determine_scalar(weight).

hx711.determine_scalar(weight)
print(hx711.scalar)

This scalar value can be applied in the future by directly setting it, like this.

hx711.scalar = new_scalar

A scalar value can be assigned at instantiation as well.

hx711 = HX711_GPIO(gpio_data, gpio_clk, scalar=new_scalar, tare=True)

Now you can read in weight values from the scale in the same units used to determine the scalar value.

hx711.read()
determine_scalar(added_weight: float) → float

Helper for determining scalar based on an object of known weight. This scalar is used for future read() operations to return a weight value scaled to any desired unit rather than raw ADC counts.

Parameters:

added_weight (float) – Known weight of added object, in any desired units of measure.

Caution

An offset is required for a scalar to be effectively determined.

property gain: int

Int value, 1, 2, or 3, representing the gain and channel to use for future ADC counts.

Channel

Gain

A

128

B

32

A

64

Hint

See the HX711 datasheet for more details.

read(average_count: int = 1) → float

Retrieves a raw ADC count (or an average of counts) and applies scalar before returning unit weight value

Parameters:

average_count (int) – Number of reads to perform for average. Defaults to 1.

read_average(count: int = 10) → int

Performs multiple raw ADC count reads and averages them

read_raw() → int

Retrieves and returns a raw ADC count

tare(pre_read: bool = True) → None

Helper to zero out future measurements by setting an offset

Parameters:

pre_read (bool) – If true, read in ADC values prior to tare to clear prior state or FIFOs. Defaults to True

HX711_GPIO

CircuitPython GPIO driver subclass for the HX711 load cell amplifer and ADC

  • Author(s): Erik Hess

Implementation Notes

Software and Dependencies:

class hx711.hx711_gpio.HX711_GPIO(pin_data: digitalio.DigitalInOut, pin_clk: digitalio.DigitalInOut, *, gain: int = 1, offset: int = 0, scalar: int = 1, tare: bool = False)

HX711 driver subclass for GPIO

read_raw() → int

Retrieves and returns a raw ADC count

HX711_PIO

CircuitPython PIO driver subclass for the HX711 load cell amplifer and ADC

  • Author(s): Erik Hess

Implementation Notes

Hardware:

  • Requires RP2-series or compatible PIO capability

Software and Dependencies:

class hx711.hx711_pio.HX711_PIO(pin_data: digitalio.DigitalInOut, pin_clk: digitalio.DigitalInOut, *, gain: int = 1, offset: int = 0, scalar: int = 1, tare: bool = False, pio_freq: int = 4000000)

HX711 driver subclass for RP2-series PIO

read_raw() → int

Read in raw ADC reading using PIO state machine

sm_deinit() → None

De-initialize the PIO StateMachine for this driver

sm_init(gain: int) → None

Initialize a PIO StateMachine for this driver