Raspberry Pi HX711 Python Bindings

Python bindings for Raspberry Pi HX711 C++ Library

Use with Raspberry Pi
Read from a HX711 using Python
Code tested inside virtual Raspberry Pi Zero/3/4 environments on GitHub and builds automatically uploaded to PyPI
This repo automatically rebuilds when the C++ library is updated

Sample Output

The .gif above illustrates the output of a simple Python script on a Raspberry Pi Zero W where the HX711 chip was operating at 80Hz. In this example, each time the .weight function is called the median of three samples was used to calculate the weight in grams.

Examples

from HX711 import *

# create a SimpleHX711 object using GPIO pin 2 as the data pin,
# GPIO pin 3 as the clock pin, -370 as the reference unit, and
# -367471 as the offset
with SimpleHX711(2, 3, -370, -367471) as hx:

  # set the scale to output weights in ounces
  hx.setUnit(Mass.Unit.OZ)

  # zero the scale
  hx.zero()

  # constantly output weights using the median of 35 samples
  while True:
    print(hx.weight(35)) #eg. 1.08 oz

Alternative Syntax (w/out `with`)

from HX711 import *

hx = SimpleHX711(2, 3, -370, -367471)
hx.setUnit(Mass.Unit.OZ)
hx.zero()
while True:
  print(hx.weight(35))

Keep in mind that calling .weight() will return a Mass object, but you can do the following:

# set the scale to output weights in ounces
hx.setUnit(Mass.Unit.OZ)

# obtain a median reading from 35 samples as a Mass object in ounces
m = hx.weight(35)

# number in ounces
num = float(m) # eg. 1.08

# string representation of the Mass
s = str(m) # eg. 1.08 oz

# print the Mass object
print(m) # eg. 1.08 oz

# change the unit to grams
m.setUnit(Mass.Unit.G)
grams_as_str = str(m) # eg. 30.62 g

# or obtain a new Mass object
m2 = m.convertTo(Mass.Unit.KG)
kgs_as_str = str(m2) # eg. 0.031 kg

The list of different Mass.Units can be viewed here.

Time-Based Sampling

You can use datetime.timedelta to obtain as many samples as possible within the time period.

from HX711 import *
from datetime import timedelta

with SimpleHX711(2, 3, -370, -367471) as hx:
  while True:
    # eg. obtain as many samples as possible within 1 second
    print(hx.weight(timedelta(seconds=1)))

Options

.weight(), .zero(), and .read() can all take an Options parameter. You can use this to fine tune how you want the scale to behave.

# zero the scale by using the average value of all samples obtained within 1 second
hx.zero(Options(
  timedelta(seconds=1),
  ReadType.Average))

# obtain a raw value from the scale using the median of 100 samples
num = hx.read(Options(
  100,
  ReadType.Median))

# obtain a Mass object using the median of three samples
# all four statements below are equivalent
m = hx.weight()
m = hx.weight(3)
m = hx.weight(Options())
m = hx.weight(Options(
  3,
  ReadType.Median))

# Options can also be created separately
opts = Options()
opts.timeout = timedelta(seconds=5)
opts.stratType = StrategyType.Time
m = hx.weight(opts)

Install

Install libhx711
pip3 install --upgrade hx711-rpi-py

Calibrate

There is a Python script in the src directory you can use to calibrate your load cell and obtain the reference unit and offset values referred to above. The simplest way to use it after installing hx711-rpi-py is as follows:

pi@raspberrypi:~ $ wget https://raw.githubusercontent.com/endail/hx711-rpi-py/master/src/calibrate.py
pi@raspberrypi:~ $ python3 calibrate.py [data pin] [clock pin]

Substitute [data pin] and [clock pin] with the GPIO pin numbers which are connected to the HX711's data pin and clock pin, respectively.

Documentation

As the Python code relies upon the underlying C++ library, the documentation is identical. However, not all of the code is exposed to Python. You can check precisely which functionality is accessible through Python in the bindings.cpp file.

Release files for hx711-rpi-py 1.65.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for hx711-rpi-py 1.65.0
File	Size	Uploaded
hx711-rpi-py-1.65.0.tar.gz	6.7 kB	Jan 21, 2024	Details

Built distributions (wheels)

Table of built distributions (wheels) for hx711-rpi-py 1.65.0
File	Interpreter	ABI	Platform	Reset
hx711_rpi_py-1.65.0-cp311-cp311-linux_armv7l.whl 154.6 kB Jan 21, 2024	CPython 3.11	CPython 3.11	linux armv7l	Details
hx711_rpi_py-1.65.0-cp311-cp311-linux_armv6l.whl 154.6 kB Jan 21, 2024	CPython 3.11	CPython 3.11	linux armv6l	Details

Total release size: 315.8 kB

Release files / hx711-rpi-py-1.65.0.tar.gz

Download URL	hx711-rpi-py-1.65.0.tar.gz
Size	6.7 kB
Tags	Source
SHA-256 checksum How to use checksums	`fafe804a6deda31f5a6476eba59a0f39ee75bafab5c6c158a475a9e8407ed2d6`
BLAKE2b-256 checksum How to use checksums	`dbcb7426f6621b9a2ef616e3eb7dbc68073504a9b81658d877158b81233cff3a`
Upload date	Jan 21, 2024
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/4.0.2 CPython/3.9.18`

Release files / hx711_rpi_py-1.65.0-cp311-cp311-linux_armv7l.whl

Download URL	hx711_rpi_py-1.65.0-cp311-cp311-linux_armv7l.whl
Size	154.6 kB
Tags	CPython 3.11 linux armv7l
SHA-256 checksum How to use checksums	`2dd3abe960cb04df5e5ea36d0789db91fbbf6ce4d31df8f0dcd49ce13922d9c6`
BLAKE2b-256 checksum How to use checksums	`2749f64b71716922ebcd0551dfb1c6a06da222faf2396150a00fecba28c7bff2`
Upload date	Jan 21, 2024
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/4.0.2 CPython/3.9.18`

Release files / hx711_rpi_py-1.65.0-cp311-cp311-linux_armv6l.whl

Download URL	hx711_rpi_py-1.65.0-cp311-cp311-linux_armv6l.whl
Size	154.6 kB
Tags	CPython 3.11 linux armv6l
SHA-256 checksum How to use checksums	`10d15b6f6e7b7480a12cf15cb793fc2e804142fa80ff29927987bd972b7e2ac1`
BLAKE2b-256 checksum How to use checksums	`deb5afe7e5ef662a9aaf07d85b8f04bf02b223a6d19114171661636c7d5cbd09`
Upload date	Jan 21, 2024
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/4.0.2 CPython/3.9.18`