From cca0aa7e9b69a58d0e4be94cac28066b9cf21fd0 Mon Sep 17 00:00:00 2001
From: Greg Cormier <gcormier@gmail.com>
Date: Thu, 10 Aug 2023 01:04:25 -0400
Subject: [PATCH] Docs - new sensor Panasonic GCJA5 (#3011)

Co-authored-by: Jesse Hills <3060199+jesserockz@users.noreply.github.com>
---
 components/sensor/gcja5.rst | 51 +++++++++++++++++++++++++++++++++++++
 images/gcja5.svg            |  1 +
 index.rst                   |  1 +
 3 files changed, 53 insertions(+)
 create mode 100644 components/sensor/gcja5.rst
 create mode 100644 images/gcja5.svg

diff --git a/components/sensor/gcja5.rst b/components/sensor/gcja5.rst
new file mode 100644
index 000000000..104a8776c
--- /dev/null
+++ b/components/sensor/gcja5.rst
@@ -0,0 +1,51 @@
+Panasonic SN-GCJA5 Particulate Matter Sensor
+============================================
+
+.. seo::
+    :description: Instructions for setting up Panasonic SN-GCJA5 Particulate matter sensors
+    :image: gcja5.svg
+
+The ``gcja5`` sensor platform allows you to use your Panasonic SN-GCJA5 laser based particulate matter sensor
+(`datasheet <https://na.industrial.panasonic.com/products/sensors/air-quality-gas-flow-sensors/lineup/laser-type-pm-sensor/series/123557/model/123559>`__)
+sensors with ESPHome.
+
+As the communication with the GCJA5 is done using UART, you need
+to have an :ref:`UART bus <uart>` in your configuration with the ``rx_pin`` connected to the SEND/TX. Additionally, you need to set the baud rate to 9600, and you
+MUST have `EVEN`` parity.
+
+The sensor itself will push values every second. You may wish to :ref:`filter <sensor-filters>` this value to reduce the amount of data you are ingesting.
+The sensor will internally track changes to the Laser Diode and Photo Diode over time to adjust and ensure accuracy.
+Based on continous runtime, the sensor is rated to last at least 5 years.
+
+.. code-block:: yaml
+
+    # Example configuration entry
+
+    sensor:
+      - platform: gcja5
+        pm_1_0:
+          name: "Particulate Matter <1.0µm Concentration"
+        pm_2_5:
+          name: "Particulate Matter <2.5µm Concentration"
+        pm_10_0:
+          name: "Particulate Matter <10.0µm Concentration"
+
+Configuration variables:
+------------------------
+
+- **pm_1_0_std** (*Optional*): Use the concentration of particulates of size less than 1.0µm in µg per cubic meter at standard particle.
+  All options from :ref:`Sensor <config-sensor>`.
+- **pm_2_5_std** (*Optional*): Use the concentration of particulates of size less than 2.5µm in µg per cubic meter at standard particle.
+  All options from :ref:`Sensor <config-sensor>`.
+- **pm_10_0_std** (*Optional*): Use the concentration of particulates of size less than 10.0µm in µg per cubic meter at standard particle.
+  All options from :ref:`Sensor <config-sensor>`.
+- **pm_1_0** (*Optional*): Use the concentration of particulates of size less than 1.0µm in µg per cubic meter under atmospheric environment.
+
+
+See Also
+--------
+
+- :doc:`/components/sensor/gcja5`
+- :ref:`sensor-filters`
+- :apiref:`gcja5/gcja5.h`
+- :ghedit:`Edit`
diff --git a/images/gcja5.svg b/images/gcja5.svg
new file mode 100644
index 000000000..11328b2c9
--- /dev/null
+++ b/images/gcja5.svg
@@ -0,0 +1 @@
+<svg width="283.101" height="72.401" viewBox="0 0 283.101 72.401" xmlns="http://www.w3.org/2000/svg"><g id="svgGroup" stroke-linecap="round" fill-rule="evenodd" font-size="9pt" stroke="#000" stroke-width="0.25mm" fill="#000" style="stroke:#000;stroke-width:0.25mm;fill:#000"><path d="M 53.201 5.7 L 49.701 13.6 Q 45.501 11.3 41.151 9.8 A 27.36 27.36 0 0 0 35.051 8.48 A 34.225 34.225 0 0 0 31.501 8.3 A 20.13 20.13 0 0 0 24.014 9.671 A 18.919 18.919 0 0 0 20.301 11.65 A 20.295 20.295 0 0 0 14.976 17.068 A 27.457 27.457 0 0 0 12.551 21.5 A 31.614 31.614 0 0 0 10.505 28.231 Q 9.902 31.363 9.751 34.955 A 58.311 58.311 0 0 0 9.701 37.4 Q 9.701 44.709 11.669 50.163 A 26.036 26.036 0 0 0 12.301 51.75 A 24.18 24.18 0 0 0 15.233 56.797 A 19.102 19.102 0 0 0 19.501 60.9 A 17.93 17.93 0 0 0 29.31 64.086 A 21.993 21.993 0 0 0 30.101 64.1 A 22.762 22.762 0 0 0 35.698 63.437 A 18.835 18.835 0 0 0 40.051 61.75 A 40.361 40.361 0 0 0 43.053 59.967 Q 45.338 58.463 46.901 56.9 L 46.901 41.6 L 32.401 41.6 L 32.401 34.1 L 55.901 34.1 L 55.901 71.2 L 47.501 71.2 L 47.501 64.2 A 35.883 35.883 0 0 1 43.122 67.492 A 47.354 47.354 0 0 1 39.001 69.85 A 23.594 23.594 0 0 1 29.594 72.35 A 28.131 28.131 0 0 1 27.901 72.4 A 26.572 26.572 0 0 1 18.588 70.8 A 24.511 24.511 0 0 1 13.501 68.2 Q 7.201 64 3.601 56.25 A 37.529 37.529 0 0 1 0.693 46.68 A 51.837 51.837 0 0 1 0.001 38 A 56.301 56.301 0 0 1 0.836 28.083 A 42.572 42.572 0 0 1 3.801 18.25 A 32.73 32.73 0 0 1 9.585 9.302 A 29.455 29.455 0 0 1 14.751 4.85 Q 21.901 0 32.001 0 Q 38.501 0 43.601 1.6 Q 48.701 3.2 53.201 5.7 Z M 240.101 67.2 L 244.801 59.5 A 28.895 28.895 0 0 0 250.578 62.679 A 32.164 32.164 0 0 0 251.001 62.85 Q 254.401 64.2 258.701 64.2 A 18.948 18.948 0 0 0 263.449 63.636 A 13.678 13.678 0 0 0 269.501 60.35 A 12.805 12.805 0 0 0 273.591 51.061 A 17.128 17.128 0 0 0 273.601 50.5 A 14.735 14.735 0 0 0 272.758 45.425 A 12.876 12.876 0 0 0 269.351 40.35 A 13.782 13.782 0 0 0 263.901 37.297 Q 260.965 36.4 257.201 36.4 L 244.801 36.4 L 244.801 1.2 L 279.401 1.2 L 279.401 9.3 L 253.301 9.3 L 253.301 28.3 L 258.301 28.3 A 37.701 37.701 0 0 1 264.481 28.781 Q 267.947 29.357 270.837 30.624 A 22.674 22.674 0 0 1 271.651 31 A 21.393 21.393 0 0 1 277.072 34.702 A 18.764 18.764 0 0 1 280.151 38.5 A 20.024 20.024 0 0 1 283.021 47.504 A 24.706 24.706 0 0 1 283.101 49.5 A 25.044 25.044 0 0 1 282.24 56.182 A 21.101 21.101 0 0 1 280.051 61.35 Q 277.001 66.5 271.501 69.45 A 24.425 24.425 0 0 1 263.883 71.985 A 32.353 32.353 0 0 1 258.601 72.4 A 46.433 46.433 0 0 1 253.925 72.177 Q 250.713 71.852 248.101 71.05 Q 243.701 69.7 240.101 67.2 Z M 116.301 3.6 L 113.401 11.6 Q 110.301 10.1 107.051 9.2 Q 104.258 8.427 100.615 8.318 A 40.705 40.705 0 0 0 99.401 8.3 A 21.173 21.173 0 0 0 91.496 9.755 A 19.981 19.981 0 0 0 87.951 11.6 A 21.167 21.167 0 0 0 81.585 18.181 A 26.978 26.978 0 0 0 80.001 21.1 Q 77.101 27.3 77.101 36.1 Q 77.101 44.5 79.951 50.8 A 25.677 25.677 0 0 0 83.537 56.628 A 21.423 21.423 0 0 0 87.851 60.6 A 19.703 19.703 0 0 0 98.996 64.097 A 23.894 23.894 0 0 0 99.401 64.1 A 33.715 33.715 0 0 0 103.371 63.879 Q 105.847 63.585 107.901 62.9 Q 111.501 61.7 114.901 59.8 L 117.801 67.7 A 37.561 37.561 0 0 1 113.306 69.745 A 47.894 47.894 0 0 1 109.351 71.05 A 33.592 33.592 0 0 1 104.385 72.041 Q 101.904 72.355 99.106 72.395 A 57.414 57.414 0 0 1 98.301 72.4 A 32.384 32.384 0 0 1 88.976 71.099 A 27.961 27.961 0 0 1 82.201 68.05 A 28.6 28.6 0 0 1 72.324 57.605 A 34.916 34.916 0 0 1 71.301 55.65 A 37.611 37.611 0 0 1 68.201 45.933 Q 67.426 41.668 67.401 36.814 A 62.816 62.816 0 0 1 67.401 36.5 Q 67.401 25.8 71.351 17.55 Q 75.301 9.3 82.551 4.65 A 29.371 29.371 0 0 1 95.231 0.239 A 37.292 37.292 0 0 1 99.501 0 A 45.639 45.639 0 0 1 104.559 0.268 A 35.2 35.2 0 0 1 108.601 0.95 A 38.224 38.224 0 0 1 116.075 3.495 A 35.605 35.605 0 0 1 116.301 3.6 Z M 230.601 68.7 L 221.901 72.2 L 214.101 52.2 L 181.701 52.2 L 173.901 72 L 165.801 68.7 L 193.201 1.2 L 203.601 1.2 L 230.601 68.7 Z M 121.801 66.6 L 126.401 59.3 A 16.858 16.858 0 0 0 130.471 62.416 A 19.43 19.43 0 0 0 131.201 62.8 A 13.114 13.114 0 0 0 135.075 64.06 A 11.941 11.941 0 0 0 136.901 64.2 A 10.741 10.741 0 0 0 140.408 63.653 A 8.936 8.936 0 0 0 144.501 60.75 Q 147.301 57.3 147.301 49.1 L 147.301 1.2 L 156.801 1.2 L 156.801 48.1 A 47.346 47.346 0 0 1 156.373 54.698 Q 155.282 62.431 151.401 66.6 A 17.93 17.93 0 0 1 139.608 72.286 A 24.68 24.68 0 0 1 137.201 72.4 A 23.443 23.443 0 0 1 129.123 71.017 A 22.405 22.405 0 0 1 128.551 70.8 A 22.827 22.827 0 0 1 124.628 68.818 A 18.183 18.183 0 0 1 121.801 66.6 Z M 197.901 10.6 L 184.701 44.2 L 211.001 44.2 L 197.901 10.6 Z" vector-effect="non-scaling-stroke"/></g></svg>
\ No newline at end of file
diff --git a/index.rst b/index.rst
index 8f56b32cd..bc7f3bc98 100644
--- a/index.rst
+++ b/index.rst
@@ -174,6 +174,7 @@ Air Quality
     AirThings BLE, components/sensor/airthings_ble, airthings_logo.png, Radon, CO2, Volatile organics
     CCS811, components/sensor/ccs811, ccs811.jpg, CO2 & Volatile organics
     EE895, components/sensor/ee895, EE895.png,  CO2 & Temperature & Pressure
+    GCJA5, components/sensor/gcja5, gcja5.svg, Particulate
     HM3301, components/sensor/hm3301, hm3301.jpg, Particulate
     MH-Z19, components/sensor/mhz19, mhz19.jpg, CO2 & Temperature
     MiCS-4514, components/sensor/mics_4514, mics_4514.jpg, Gas concentration