import hx711
The hx711 module reads HX711 24-bit bridge/load-cell ADC boards using a DOUT pin and a PD_SCK clock pin. It supports raw readings, averaging, tare, scale calibration, weight reads, gain/channel selection, and power control.
Quick example
import hx711 scale = hx711.HX711(dout=4, sck=5) scale.tare(samples=20) # Put a known 100 gram weight on the scale, then calibrate. scale.calibrate(known_weight=100.0, samples=20) print(scale.weight(samples=5)) reading = scale.read_average(samples=10) print(reading["raw"]) print(reading["weight"])
importhx711
HX711 load-cell amplifier module.
The hx711 module reads HX711 24-bit bridge/load-cell ADC boards using a DOUT pin and a PD_SCK clock pin. It supports raw readings, averaging, tare, scale calibration, weight reads, gain/channel selection, and power control.
hx711.HX711(dout: int, sck: int, gain: int = None) -> hx711_scale
hx711.HX711(dout: int, sck: int, gain: int = None) -> hx711_scaleCreate and initialize an independent HX711 load-cell amplifier.
Use one HX711 object for each physical amplifier. Each object owns its DOUT and PD_SCK pins, plus its own gain, tare offset, and scale calibration.
| Name | Type | Pass as | Required | Description |
|---|---|---|---|---|
dout |
int |
positional or keyword | Yes | GPIO pin connected to HX711 DOUT. |
sck |
int |
positional or keyword | Yes | GPIO pin connected to HX711 PD_SCK. |
gain |
int |
positional or keyword | No | Optional gain/channel selector. Use 128 for channel A, 64 for channel A, or 32 for channel B. Defaults to 128. |
hx711_scale hx711_scale object.
hx711.HX711().configure(gain=None) -> bool
hx711.HX711().configure(gain=None) -> boolSet the gain/channel used by future reads.
| Name | Type | Pass as | Required | Description |
|---|---|---|---|---|
gain |
int |
positional or keyword | No | Optional value. Defaults to None. |
hx711.HX711().ready() -> bool
hx711.HX711().ready() -> boolCheck whether this HX711 has a conversion ready.
hx711.HX711().raw(timeout_ms=None) -> int
hx711.HX711().raw(timeout_ms=None) -> intRead one raw signed 24-bit value.
| Name | Type | Pass as | Required | Description |
|---|---|---|---|---|
timeout_ms |
int |
positional or keyword | No | Optional value. Defaults to None. |
hx711.HX711().read(timeout_ms=None) -> dict
hx711.HX711().read(timeout_ms=None) -> dictRead one sample and return raw and calibrated fields.
| Name | Type | Pass as | Required | Description |
|---|---|---|---|---|
timeout_ms |
int |
positional or keyword | No | Optional value. Defaults to None. |
hx711.HX711().read_average(samples=None, timeout_ms=None) -> dict
hx711.HX711().read_average(samples=None, timeout_ms=None) -> dictAverage several samples and return raw and calibrated fields.
| Name | Type | Pass as | Required | Description |
|---|---|---|---|---|
samples |
int |
positional or keyword | No | Optional value. Defaults to None. |
timeout_ms |
int |
positional or keyword | No | Optional value. Defaults to None. |
hx711.HX711().tare(samples=None, timeout_ms=None) -> bool
hx711.HX711().tare(samples=None, timeout_ms=None) -> boolSet the current unloaded reading as this scale's zero offset.
| Name | Type | Pass as | Required | Description |
|---|---|---|---|---|
samples |
int |
positional or keyword | No | Optional value. Defaults to None. |
timeout_ms |
int |
positional or keyword | No | Optional value. Defaults to None. |
hx711.HX711().calibrate(known_weight, samples=None, timeout_ms=None) -> float
hx711.HX711().calibrate(known_weight, samples=None, timeout_ms=None) -> floatCalculate and store this scale's calibration factor from a known weight.
| Name | Type | Pass as | Required | Description |
|---|---|---|---|---|
known_weight |
float |
positional or keyword | Yes | Required value. |
samples |
int |
positional or keyword | No | Optional value. Defaults to None. |
timeout_ms |
int |
positional or keyword | No | Optional value. Defaults to None. |
hx711.HX711().set_scale(scale) -> bool
hx711.HX711().set_scale(scale) -> boolSet a previously measured scale factor.
| Name | Type | Pass as | Required | Description |
|---|---|---|---|---|
scale |
float |
positional or keyword | Yes | Required value. |
hx711.HX711().set_offset(offset) -> bool
hx711.HX711().set_offset(offset) -> boolSet a raw tare offset manually.
| Name | Type | Pass as | Required | Description |
|---|---|---|---|---|
offset |
float |
positional or keyword | Yes | Required value. |
hx711.HX711().weight(samples=None, timeout_ms=None) -> float
hx711.HX711().weight(samples=None, timeout_ms=None) -> floatRead calibrated weight from this scale.
| Name | Type | Pass as | Required | Description |
|---|---|---|---|---|
samples |
int |
positional or keyword | No | Optional value. Defaults to None. |
timeout_ms |
int |
positional or keyword | No | Optional value. Defaults to None. |
hx711.HX711().power_down() -> bool
hx711.HX711().power_down() -> boolPut this HX711 into power-down mode.
hx711.HX711().power_up() -> bool
hx711.HX711().power_up() -> boolWake this HX711 from power-down mode.
hx711.HX711().reset() -> bool
hx711.HX711().reset() -> boolRestore this scale's defaults.
hx711.HX711().info() -> dict
hx711.HX711().info() -> dictReturn pin, gain, offset, scale, ready, and power state for this scale.
hx711.HX711().close() -> bool
hx711.HX711().close() -> boolRelease this HX711 handle.
hx711.HX711().Example
hx711.HX711().Examplescale = hx711.HX711(dout=4, sck=5) scale.tare(samples=20) print(scale.weight(samples=5))
hx711.begin(dout: int, sck: int, gain: int = None) -> bool
hx711.begin(dout: int, sck: int, gain: int = None) -> boolLegacy: initialize the module-level default HX711 load-cell amplifier.
Prefer ``scale = hx711.HX711(...)`` for new projects. The legacy wrapper keeps older singleton-style scripts working.
| Name | Type | Pass as | Required | Description |
|---|---|---|---|---|
dout |
int |
positional or keyword | Yes | GPIO pin connected to HX711 DOUT. |
sck |
int |
positional or keyword | Yes | GPIO pin connected to HX711 PD_SCK. |
gain |
int |
positional or keyword | No | Optional gain/channel selector. Use 128 for channel A, 64 for channel A, or 32 for channel B. Defaults to 128. |
bool True when the GPIO pins are configured.
hx711.configure(gain: int = None) -> bool
hx711.configure(gain: int = None) -> boolSet the HX711 gain/channel used by future reads.
The HX711 applies gain/channel selection through the extra clock pulses at the end of a read. After changing gain, the native module discards one conversion before returning the next measurement so reads are consistent.
| Name | Type | Pass as | Required | Description |
|---|---|---|---|---|
gain |
int |
positional or keyword | No | Optional gain/channel selector. Use 128 for channel A, 64 for channel A, or 32 for channel B. Defaults to the current gain. |
bool True when the gain setting is accepted.
hx711.ready() -> bool
hx711.ready() -> boolCheck whether the HX711 has a conversion ready.
bool True when DOUT is low and the chip is not powered down.
hx711.raw(timeout_ms: int = None) -> int
hx711.raw(timeout_ms: int = None) -> intRead one raw signed 24-bit HX711 value.
| Name | Type | Pass as | Required | Description |
|---|---|---|---|---|
timeout_ms |
int |
positional or keyword | No | Optional timeout in milliseconds. Defaults to 1000. |
int Integer raw ADC count.
hx711.read(timeout_ms: int = None) -> dict
hx711.read(timeout_ms: int = None) -> dictRead one HX711 sample and return a dict.
| Name | Type | Pass as | Required | Description |
|---|---|---|---|---|
timeout_ms |
int |
positional or keyword | No | Optional timeout in milliseconds. Defaults to 1000. |
dict Dict with ``ok``, ``raw``, ``average_raw``, ``value``, ``weight``, ``samples``, ``offset``, ``scale``, ``gain``, ``channel``, ``dout``, ``sck``, and ``timeout_ms`` fields.
hx711.read_average(samples: int = None, timeout_ms: int = None) -> dict
hx711.read_average(samples: int = None, timeout_ms: int = None) -> dictRead several HX711 samples and average them.
| Name | Type | Pass as | Required | Description |
|---|---|---|---|---|
samples |
int |
positional or keyword | No | Optional number of samples to average. Defaults to 10. |
timeout_ms |
int |
positional or keyword | No | Optional timeout in milliseconds per sample. Defaults to 1000. |
dict Dict with the same fields as ``read()``, with ``average_raw`` and ``samples`` reflecting the averaged read.
hx711.tare(samples: int = None, timeout_ms: int = None) -> bool
hx711.tare(samples: int = None, timeout_ms: int = None) -> boolSet the current unloaded reading as the zero offset.
Run this with the scale empty.
| Name | Type | Pass as | Required | Description |
|---|---|---|---|---|
samples |
int |
positional or keyword | No | Optional number of samples to average. Defaults to 10. |
timeout_ms |
int |
positional or keyword | No | Optional timeout in milliseconds per sample. Defaults to 1000. |
bool True when the offset was measured and stored.
hx711.calibrate(known_weight: float, samples: int = None, timeout_ms: int = None) -> float
hx711.calibrate(known_weight: float, samples: int = None, timeout_ms: int = None) -> floatCalibrate scale using a known weight.
Run ``tare()`` first with the scale empty, place a known weight on the load cell, then call ``calibrate(known_weight=...)``. The returned scale is raw counts per weight unit, so the unit is whatever unit you pass as ``known_weight``.
| Name | Type | Pass as | Required | Description |
|---|---|---|---|---|
known_weight |
float |
positional or keyword | Yes | Known weight currently on the scale. |
samples |
int |
positional or keyword | No | Optional number of samples to average. Defaults to 10. |
timeout_ms |
int |
positional or keyword | No | Optional timeout in milliseconds per sample. Defaults to 1000. |
float Float scale factor in raw counts per weight unit.
hx711.set_scale(scale: float) -> bool
hx711.set_scale(scale: float) -> boolSet a previously measured scale factor.
| Name | Type | Pass as | Required | Description |
|---|---|---|---|---|
scale |
float |
positional or keyword | Yes | Scale factor in raw counts per weight unit. Must not be zero. |
bool True when the scale factor is stored.
hx711.set_offset(offset: float) -> bool
hx711.set_offset(offset: float) -> boolSet a raw tare offset manually.
| Name | Type | Pass as | Required | Description |
|---|---|---|---|---|
offset |
float |
positional or keyword | Yes | Raw ADC offset. This may be fractional when copied from an averaged tare. |
bool True when the offset is stored.
hx711.weight(samples: int = None, timeout_ms: int = None) -> float
hx711.weight(samples: int = None, timeout_ms: int = None) -> floatRead calibrated weight.
The value is calculated as ``(raw - offset) / scale``. The unit matches the unit used when calibrating.
| Name | Type | Pass as | Required | Description |
|---|---|---|---|---|
samples |
int |
positional or keyword | No | Optional number of samples to average. Defaults to 1. |
timeout_ms |
int |
positional or keyword | No | Optional timeout in milliseconds per sample. Defaults to 1000. |
float Float calibrated weight.
hx711.power_down() -> bool
hx711.power_down() -> boolPut the HX711 into power-down mode.
bool True after PD_SCK is held high long enough to power down the chip.
hx711.power_up() -> bool
hx711.power_up() -> boolWake the HX711 from power-down mode.
bool True after PD_SCK is returned low.
hx711.reset() -> bool
hx711.reset() -> boolRestore module defaults.
This sets gain back to 128, clears tare offset, sets scale to 1, and wakes the chip if it was powered down.
bool True when the native state is reset.
hx711.info() -> dict
hx711.info() -> dictReturn HX711 module state.
dict Dict with initialization state, ready state, power state, DOUT/SCK pins, gain, channel, offset, scale, and gain-sync state.