Update docs for xgzp68xx component.

Author: ned14

components/sensor/xgzp68xx.rst

@@ -1,20 +1,56 @@
-CFSensor XGZP68xx Series Differential Pressure Sensor
-=====================================================
+CFSensor XGZP68xx Non-C Series Differential Pressure Sensor
+===========================================================
 
 .. seo::
-    :description: Instructions for setting up the CFSensor XGZP68xx Series Differential Pressure sensor.
+    :description: Instructions for setting up the CFSensor XGZP68xx Non-C Series Differential Pressure sensor.
     :image: 6897d.jpg
     :keywords: XGZP68xx, XGZP6897, XGZP6899, XGZP6899D, XGZP6897D
 
-The XGZP68xx Differential Pressure sensor allows you to use digital differential pressure sensors such as the 6899D
-(`datasheet <https://cfsensor.com/wp-content/uploads/2022/11/XGZP6899D-Pressure-Sensor-V2.8.pdf>`__) or 
-6897D Series (`datasheet <https://cfsensor.com/wp-content/uploads/2022/11/XGZP6897D-Pressure-Sensor-V2.7.pdf>`__)
-sensors with ESPHome. The sensors pressure ranges are specified in the datasheets.
+CFSensor makes multiple generations of sensors with identical model numbers such as the 6899D or
+6897D, but unfortunately with completely different I²C interfaces. You can identify which from
+the part number:
 
-Calibrating the sensor can be done by checking the value that is returned when
-the ports are open to the air. This value should be 0. If it is not, you can use the offset option to correct the
+- XGZP6897D001KPDPN is the non-C series, which this component supports.
+- XGZP6897D\ **C**\ 001KPDPN is the C series, which this component does NOT support.
+
+Another way of telling the difference is the I²C address:
+
+- If the device is one of the non-C series, it appears at I²C address ``0x6d``.
+- If the device is one of the C series, it appears at I²C address ``0x58``.
+
+Unfortunately CFSensor have removed from their website the datasheets for the non-C series of sensors.
+You will need to specifically find the older datasheet from another source. **The v3.1 or
+later datasheets from CFSensor describe the C series which is a completely different device
+even though it has an identical model number to the <= v3.0 device**.
+
+The sensors come in a series of pressure ranges. The now hard to find datasheet lists
+a table of pressure ranges to ``k_value``, which you will need to set in your configuration:
+
+- -0.5 kPa to +0.5 kPa (``k_value = 16384``)
+- -1 kPa to +1 kPa (``k_value = 8192``)
+- -2.5 kPa to +2.5 kPa (``k_value = 2048``)
+- -5 kPa to +5 kPa (``k_value = 1024``)
+- -10 kPa to +10 kPa (``k_value = 512``)
+- -50 kPa to +50 kPa (``k_value = 128``)
+
+On power up, the sensor will read an offset. You will need to calibrate the sensor which can be done
+by checking the value that is returned when the ports are open to the air. You can use the offset option to correct the
 reading. For example, if your sensor is reading -40Pa when the ports are disconnected, you can set the offset to 40.
 
+If the sensor is running for a time, you will find that the zero point does drift after a while,
+especially if the sensor is used to detect pressure shocks.
+Designing in a way to periodically equalise the pressure between the ports so a new offset can be
+determined would be wise.
+
+This non-C generation of XGZP68xx sensors is now available at a very good price from the usual
+sources — indeed currently nothing comes close in terms of bang for the buck for differential
+pressure sensors. Be aware that when air is moving, turbulence generates quite a bit more noise
+than the datasheet suggests. For a 9 m/sec air flow at less than 100 Pa pressure difference,
+2% *per port* seems typical, so if both high and low ports are
+connected then a total 4% noise would result. For a sensor range -500 Pa to +500 Pa, that means
+readings bounce around by +/- 20 Pa which is a significant fraction of a 100 Pa total pressure
+difference.
+
 .. figure:: images/6897d.jpg
     :align: center
     :width: 30.0%
@@ -31,11 +67,13 @@ To use the sensor, set up an :ref:`I²C Bus <i2c>` and connect the sensor to the
     # Example configuration entry
     # It uses a filter offset to calibrate the sensor
     sensor:
-      - platform: xgzp68xx
+      - platform: xgzp68xx_v2
+        k_value: 16384
         temperature:
             name: "Temperature"
         pressure:
             name: "Differential Pressure"
+            oversampling: "32768x"
             filters:
                 - offset: 40.5
 
@@ -44,13 +82,14 @@ Configuration variables:
 
 - **temperature** (*Optional*): All options from :ref:`Sensor <config-sensor>`.
 - **pressure** (*Optional*): All options from :ref:`Sensor <config-sensor>`.
-- **k_value** (*Optional*, int): The K value comes from the datasheet. It will default to 4096 if not specified, which is appropriate for a sensor with a range of +/- 0.5kPa.
+    - **oversampling** (*Optional*): One of ``256x``, ``512x``, ``1024x``, ``2048x``, ``4096x``, ``8192x``, ``16384x``, ``32768x``. It is not possible to disable oversampling. If not specified, this defaults to ``4096x``.
+- **k_value** (*Optional*, int): The K value comes from the table above. It will default to 4096 if not specified.
 - **update_interval** (*Optional*, :ref:`config-time`): The interval to check the sensor. Defaults to ``60s``.
 
 
 See Also
 --------
 - `esphome-pressure device <https://github.com/gcormier/esphome-pressure/>`__
 - :ref:`sensor-filters`
-- :apiref:`sdp3x/sdp3x.h`
+- :apiref:`xgzp6xx_v2/xgzp6xx_v2.h`
 - :ghedit:`Edit`