HX711 Load Cell Amplifier
=========================

.. seo::
    :description: Instructions for setting up HX711 load cell amplifiers with esphomelib
    :image: hx711.png
    :keywords: HX711

The ``hx711`` sensor platform allows you to use your HX711
load cell amplifier
(`datasheet <https://www.mouser.com/ds/2/813/hx711_english-1022875.pdf>`__, `Sparkfun`_) with esphomelib

.. figure:: images/hx711-full.jpg
    :align: center
    :target: `Sparkfun`_
    :width: 60.0%

    HX711 Load Cell Amplifier. Image by `Sparkfun`_ licensed and re-distributed under `CC BY 2.0 <https://creativecommons.org/licenses/by/2.0/>`__.

.. _Sparkfun: https://www.sparkfun.com/products/13879

Connect ``GND`` to ``GND``, ``VCC`` to ``3.3V`` and the other three ``MISO`` (or ``SO`` for short),
``CS`` and ``CLOCK`` (or ``SCK``) to free GPIO pins.

.. code-block:: yaml

    # Example configuration entry
    sensor:
      - platform: hx711
        name: "HX711 Value"
        dout_pin: D0
        clk_pin: D1
        gain: 128
        update_interval: 60s

Configuration variables:
------------------------

- **name** (**Required**, string): The name for the load cell sensor.
- **dout_pin** (**Required**, :ref:`Pin Schema <config-pin_schema>`): The DOUT (or DAT) pin.
- **clk_pin** (**Required**, :ref:`Pin Schema <config-pin_schema>`): The CLK pin.
- **update_interval** (*Optional*, :ref:`config-time`): The interval to check the sensor. Defaults to ``60s``.

- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
- All other options from :ref:`Sensor <config-sensor>` and :ref:`MQTT Component <config-mqtt-component>`.


Converting Units
----------------

As the HX711 does not have any calibration data, you have to convert the measurement to units yourself.
To calibrate the sensor:

1. Place nothing or a known mass on the sensor, for example ``0kg``
2. Wait for the data to arrive in the logs and write down the value. For example ``120``.
3. Place another (different) known mass on the sensor, for example ``1kg``
4. Again wait for the data to arrive and note the value, for example ``810``.

Once you've done those steps, you can use the ``map`` function to map the incoming value to the calibrated one:

.. code-block:: yaml

    # Example configuration entry
    sensor:
      - platform: hx711
        # ... Other HX711 options
        filters:
          - lambda: |-
              auto first_mass = 0.0; // first known mass was 0kg
              auto first_value = 120.0; // value for the first known mass was 120
              auto second_mass = 1.0; // second mass was 1kg
              auto second_value = 810.0; // second value was 810

              return map(x, first_value, second_value, first_mass, second_mass);
        unit_of_measurement: kg

Replace the masses and values ``120.0``, ``810.0``, etc with your values.

See Also
--------

- :ref:`sensor-filters`
- :doc:`adc`
- :apiref:`sensor/hx711.h`
- `HX711 Library <https://github.com/bogde/HX711>`__ by `@bogde <https://github.com/bogde>`__
- :ghedit:`Edit`

.. disqus::