# Raspberry Pi HX711 Python Bindings
[](https://github.com/endail/hx711-rpi-py/actions/workflows/build_and_upload.yml) [](https://pepy.tech/project/hx711-rpi-py)
Python bindings for [Raspberry Pi HX711 C++ Library](https://github.com/endail/hx711)
- Use with Raspberry Pi
- Read from a HX711 using Python
- Code tested inside [virtual Raspberry Pi Zero/3/4 environments](.github/workflows/build_and_upload.yml) 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](src/test.py) 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
```python
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`)
```python
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:
```python
# 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.Unit`s can be viewed [here](https://github.com/endail/hx711#mass).
### Time-Based Sampling
You can use [`datetime.timedelta`](https://docs.python.org/3/library/datetime.html#timedelta-objects) to obtain as many samples as possible within the time period.
```python
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.
```python
# 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
1. Install [libhx711](https://github.com/endail/hx711)
2. `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:
```console
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](https://pinout.xyz/) which are connected to the HX711's data pin and clock pin, respectively.
## Documentation
As the Python code relies upon the [underlying C++ library](https://github.com/endail/hx711#documentation), 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](src/bindings.cpp).
Raw data
{
"_id": null,
"home_page": "https://github.com/endail/hx711-rpi-py",
"name": "hx711-rpi-py",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6, <4",
"maintainer_email": "",
"keywords": "hx711,raspberry-pi,sensor,weight,load-cell",
"author": "Daniel Robertson",
"author_email": "52652357+endail@users.noreply.github.com",
"download_url": "https://files.pythonhosted.org/packages/db/cb/7426f6621b9a2ef616e3eb7dbc68073504a9b81658d877158b81233cff3a/hx711-rpi-py-1.65.0.tar.gz",
"platform": null,
"description": "# Raspberry Pi HX711 Python Bindings\n\n[](https://github.com/endail/hx711-rpi-py/actions/workflows/build_and_upload.yml) [](https://pepy.tech/project/hx711-rpi-py)\n\nPython bindings for [Raspberry Pi HX711 C++ Library](https://github.com/endail/hx711)\n\n- Use with Raspberry Pi\n- Read from a HX711 using Python\n- Code tested inside [virtual Raspberry Pi Zero/3/4 environments](.github/workflows/build_and_upload.yml) on GitHub and builds automatically uploaded to PyPI\n- This repo automatically rebuilds when the C++ library is updated\n\n## Sample Output\n\n\n\nThe .gif above illustrates the output of a [simple Python script](src/test.py) 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.\n\n## Examples\n\n```python\nfrom HX711 import *\n\n# create a SimpleHX711 object using GPIO pin 2 as the data pin,\n# GPIO pin 3 as the clock pin, -370 as the reference unit, and\n# -367471 as the offset\nwith SimpleHX711(2, 3, -370, -367471) as hx:\n\n # set the scale to output weights in ounces\n hx.setUnit(Mass.Unit.OZ)\n\n # zero the scale\n hx.zero()\n\n # constantly output weights using the median of 35 samples\n while True:\n print(hx.weight(35)) #eg. 1.08 oz\n```\n\n### Alternative Syntax (w/out `with`)\n\n```python\nfrom HX711 import *\n\nhx = SimpleHX711(2, 3, -370, -367471)\nhx.setUnit(Mass.Unit.OZ)\nhx.zero()\nwhile True:\n print(hx.weight(35))\n```\n\nKeep in mind that calling `.weight()` will return a `Mass` object, but you can do the following:\n\n```python\n# set the scale to output weights in ounces\nhx.setUnit(Mass.Unit.OZ)\n\n# obtain a median reading from 35 samples as a Mass object in ounces\nm = hx.weight(35)\n\n# number in ounces\nnum = float(m) # eg. 1.08\n\n# string representation of the Mass\ns = str(m) # eg. 1.08 oz\n\n# print the Mass object\nprint(m) # eg. 1.08 oz\n\n# change the unit to grams\nm.setUnit(Mass.Unit.G)\ngrams_as_str = str(m) # eg. 30.62 g\n\n# or obtain a new Mass object\nm2 = m.convertTo(Mass.Unit.KG)\nkgs_as_str = str(m2) # eg. 0.031 kg\n```\n\nThe list of different `Mass.Unit`s can be viewed [here](https://github.com/endail/hx711#mass).\n\n### Time-Based Sampling\n\nYou can use [`datetime.timedelta`](https://docs.python.org/3/library/datetime.html#timedelta-objects) to obtain as many samples as possible within the time period.\n\n```python\nfrom HX711 import *\nfrom datetime import timedelta\n\nwith SimpleHX711(2, 3, -370, -367471) as hx:\n while True:\n # eg. obtain as many samples as possible within 1 second\n print(hx.weight(timedelta(seconds=1)))\n```\n\n### Options\n\n`.weight()`, `.zero()`, and `.read()` can all take an `Options` parameter. You can use this to fine tune how you want the scale to behave.\n\n```python\n\n# zero the scale by using the average value of all samples obtained within 1 second\nhx.zero(Options(\n timedelta(seconds=1),\n ReadType.Average))\n\n# obtain a raw value from the scale using the median of 100 samples\nnum = hx.read(Options(\n 100,\n ReadType.Median))\n\n# obtain a Mass object using the median of three samples\n# all four statements below are equivalent\nm = hx.weight()\nm = hx.weight(3)\nm = hx.weight(Options())\nm = hx.weight(Options(\n 3,\n ReadType.Median))\n\n# Options can also be created separately\nopts = Options()\nopts.timeout = timedelta(seconds=5)\nopts.stratType = StrategyType.Time\nm = hx.weight(opts)\n```\n\n## Install\n\n1. Install [libhx711](https://github.com/endail/hx711)\n\n2. `pip3 install --upgrade hx711-rpi-py`\n\n## Calibrate\n\nThere 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:\n\n```console\npi@raspberrypi:~ $ wget https://raw.githubusercontent.com/endail/hx711-rpi-py/master/src/calibrate.py\npi@raspberrypi:~ $ python3 calibrate.py [data pin] [clock pin]\n```\n\nSubstitute `[data pin]` and `[clock pin]` with the [GPIO pin numbers](https://pinout.xyz/) which are connected to the HX711's data pin and clock pin, respectively.\n\n## Documentation\n\nAs the Python code relies upon the [underlying C++ library](https://github.com/endail/hx711#documentation), 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](src/bindings.cpp).\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python bindings for Raspberry Pi HX711 C++ Library",
"version": "1.65.0",
"project_urls": {
"Homepage": "https://github.com/endail/hx711-rpi-py"
},
"split_keywords": [
"hx711",
"raspberry-pi",
"sensor",
"weight",
"load-cell"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "deb5afe7e5ef662a9aaf07d85b8f04bf02b223a6d19114171661636c7d5cbd09",
"md5": "c72f3a9faa75efefe66dc98501133439",
"sha256": "10d15b6f6e7b7480a12cf15cb793fc2e804142fa80ff29927987bd972b7e2ac1"
},
"downloads": -1,
"filename": "hx711_rpi_py-1.65.0-cp311-cp311-linux_armv6l.whl",
"has_sig": false,
"md5_digest": "c72f3a9faa75efefe66dc98501133439",
"packagetype": "bdist_wheel",
"python_version": "cp311",
"requires_python": ">=3.6, <4",
"size": 154562,
"upload_time": "2024-01-21T12:31:34",
"upload_time_iso_8601": "2024-01-21T12:31:34.702426Z",
"url": "https://files.pythonhosted.org/packages/de/b5/afe7e5ef662a9aaf07d85b8f04bf02b223a6d19114171661636c7d5cbd09/hx711_rpi_py-1.65.0-cp311-cp311-linux_armv6l.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "2749f64b71716922ebcd0551dfb1c6a06da222faf2396150a00fecba28c7bff2",
"md5": "d293fe85e3b1eb0e258d57270888f282",
"sha256": "2dd3abe960cb04df5e5ea36d0789db91fbbf6ce4d31df8f0dcd49ce13922d9c6"
},
"downloads": -1,
"filename": "hx711_rpi_py-1.65.0-cp311-cp311-linux_armv7l.whl",
"has_sig": false,
"md5_digest": "d293fe85e3b1eb0e258d57270888f282",
"packagetype": "bdist_wheel",
"python_version": "cp311",
"requires_python": ">=3.6, <4",
"size": 154560,
"upload_time": "2024-01-21T12:31:22",
"upload_time_iso_8601": "2024-01-21T12:31:22.998310Z",
"url": "https://files.pythonhosted.org/packages/27/49/f64b71716922ebcd0551dfb1c6a06da222faf2396150a00fecba28c7bff2/hx711_rpi_py-1.65.0-cp311-cp311-linux_armv7l.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "dbcb7426f6621b9a2ef616e3eb7dbc68073504a9b81658d877158b81233cff3a",
"md5": "31ac42037d7d696e4a1699931646be63",
"sha256": "fafe804a6deda31f5a6476eba59a0f39ee75bafab5c6c158a475a9e8407ed2d6"
},
"downloads": -1,
"filename": "hx711-rpi-py-1.65.0.tar.gz",
"has_sig": false,
"md5_digest": "31ac42037d7d696e4a1699931646be63",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6, <4",
"size": 6668,
"upload_time": "2024-01-21T12:31:25",
"upload_time_iso_8601": "2024-01-21T12:31:25.023705Z",
"url": "https://files.pythonhosted.org/packages/db/cb/7426f6621b9a2ef616e3eb7dbc68073504a9b81658d877158b81233cff3a/hx711-rpi-py-1.65.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-21 12:31:25",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "endail",
"github_project": "hx711-rpi-py",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "hx711-rpi-py"
}
JSON
