Skip to content

Update mcp3204.md #5510

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 1 commit into
base: current
Choose a base branch
from
Draft

Update mcp3204.md #5510

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
114 changes: 61 additions & 53 deletions content/components/sensor/mcp3204.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,77 +1,85 @@
---
description: "Instructions for setting up MCP3204 & MCP3208 12-Bit Analog to Digital Converter in ESPHome."
title: "MCP3204 & MCP3208 12-Bit A/D Converters"
params:
seo:
.. seo::

Check failure on line 1 in content/components/sensor/mcp3204.md

View workflow job for this annotation

GitHub Actions / build 

First line in a file should be a top-level heading [Context: ".. seo::"]
description: Instructions for setting up MCP3204 & MCP3208 12-Bit Analog to Digital Converter in ESPHome.
image: mcp3204.jpg
---

The Microchip Technology Inc. MCP3204 & MCP3208 devices are successive approximation 12-bit Analog-to-Digital (A/D)
converters with on-board sample and hold circuitry. This component is common for both device types.
Configure both devices as MCP3204 and observe the maximum number of channels as per variant used.
MCP3204 & MCP3208 12-Bit A/D Converters
=======================================
Comment on lines +1 to +6
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🔴 Critical

Fix markdown lint error MD041: First line should be a top-level heading.

The pipeline is failing because the file begins with a reStructuredText directive (.. seo::) rather than a top-level heading. The markdown linter expects a heading as the first element.

Move the SEO block below the title or restructure the file to start with the top-level heading:

-.. seo::
-
-    description: Instructions for setting up MCP3204 & MCP3208 12-Bit Analog to Digital Converter in ESPHome.
-    image: mcp3204.jpg
-
 MCP3204 & MCP3208 12-Bit A/D Converters
 =======================================
+
+.. seo::
+
+    description: Instructions for setting up MCP3204 & MCP3208 12-Bit Analog to Digital Converter in ESPHome.
+    image: mcp3204.jpg
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
.. seo::
description: Instructions for setting up MCP3204 & MCP3208 12-Bit Analog to Digital Converter in ESPHome.
image: mcp3204.jpg
---
The Microchip Technology Inc. MCP3204 & MCP3208 devices are successive approximation 12-bit Analog-to-Digital (A/D)
converters with on-board sample and hold circuitry. This component is common for both device types.
Configure both devices as MCP3204 and observe the maximum number of channels as per variant used.
MCP3204 & MCP3208 12-Bit A/D Converters
=======================================
MCP3204 & MCP3208 12-Bit A/D Converters
=======================================
.. seo::
description: Instructions for setting up MCP3204 & MCP3208 12-Bit Analog to Digital Converter in ESPHome.
image: mcp3204.jpg
🧰 Tools
🪛 GitHub Actions: Lint

[error] 1-1: Markdown lint failed: MD041 - First line in a file should be a top-level heading. Context: '.. seo::'

🪛 GitHub Check: build

[failure] 1-1:
First line in a file should be a top-level heading [Context: ".. seo::"]

🤖 Prompt for AI Agents 
In content/components/sensor/mcp3204.md lines 1-6 the file starts with a
reStructuredText SEO directive which triggers markdown-lint MD041 because the
first line must be a top-level heading; fix by moving the ".. seo::" block below
the main title (keep the "MCP3204 & MCP3208 12-Bit A/D Converters" as the very
first line preceded by a single "#"/underlined level-1 heading per your repo
style), ensure a blank line between the title and the SEO block, and verify the
file now begins with the top-level heading so the linter passes.


{{< img src="mcp3204.jpg" alt="Image" width="50.0%" class="align-center" >}}
The Microchip Technology Inc. MCP3204 & MCP3208 devices are successive approximation 12-bit Analog-to-Digital (A/D)
converters with on-board sample and hold circuitry. This ESPHome component provides support for both device types.
You may configure both devices as :code:`mcp3204` and select the channel count per your variant.

{{< anchor "mcp3204-component" >}}
.. figure:: mcp3204.jpg
:align: center
:width: 50.0%
:alt: MCP3204 image

## Component/Hub
Component/Hub
-------------

The MCP3204 component allows you to use MCP3204 or MCP3208 12-Bit A/D Converter
([datasheet](https://ww1.microchip.com/downloads/en/DeviceDoc/21298e.pdf)) in ESPHome.
(`datasheet <https://ww1.microchip.com/downloads/en/DeviceDoc/21298e.pdf>`_) in ESPHome.
The MCP3204 is a 4-channel and MCP3208 is an 8-channel device.
It uses the [SPI Bus](#spi) for communication.
It uses the :doc:`SPI Bus <spi>` for communication.

Once configured, you can use any of the 4 or 8 pins (depending on device variant) as sensors for your projects.

Once configured, you can use any of the 4 or 8 pins (depending on device variant) as
sensors for your projects.
Each pin will respond with a voltage calculated off of the :code:`reference_voltage` (default is 3.3V).
The voltage is calculated as :code:`reference_voltage * value / 4096` (the percentage of VREF for a 12-bit ADC).

Each pin will respond with a voltage calculated off of the `reference_voltage` (default is 3.3V).
It calculates the voltage by multiplying the `reference_voltage * value` on the pin (basically the percentage of VREF)
Usually, you will set :code:`reference_voltage` to the VREF pin voltage.

Most configurations will set the `reference_voltage` = VREF pin
.. code-block:: yaml

```yaml
# Example configuration entry
mcp3204:
cs_pin: GPIOXX
reference_voltage: 3.3V
```
mcp3204:

Check failure on line 34 in content/components/sensor/mcp3204.md

View workflow job for this annotation

GitHub Actions / build 

Code block style [Expected: fenced; Actual: indented]
cs_pin: GPIOXX
reference_voltage: 3.3V
Comment on lines +34 to +36
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

Use fenced code block style instead of indented.

The build tool reports that code block style should be fenced (with triple backticks), not indented.

Apply this diff to use fenced code block syntax:

-.. code-block:: yaml
-
-    mcp3204:
-        cs_pin: GPIOXX
-        reference_voltage: 3.3V
+.. code-block:: yaml
+
+    mcp3204:
+      cs_pin: GPIOXX
+      reference_voltage: 3.3V

Committable suggestion skipped: line range outside the PR's diff.

🧰 Tools
🪛 GitHub Check: build

[failure] 34-34:
Code block style [Expected: fenced; Actual: indented]

🤖 Prompt for AI Agents 
In content/components/sensor/mcp3204.md around lines 34 to 36, the YAML example
is written as an indented code block; replace it with a fenced code block using
triple backticks (```yaml) before the block and closing triple backticks after
it so the build tool recognizes the fenced style, preserving the exact content
and indentation inside the fenced block.


### Configuration variables
Configuration variables:

- **id** (**Required**, [ID](#config-id)): The id to use for this MCP3204 component.
- **cs_pin** (**Required**, [Pin Schema](#config-pin_schema)): The SPI cable select pin to use.
- **reference_voltage** (*Optional*, float): The reference voltage. Defaults to `3.3V`.
- **id** (**Required**, :ref:`config-id`): The id to use for this MCP3204 component.
- **cs_pin** (**Required**, :ref:`config-pin_schema`): The SPI cable select pin to use.
- **reference_voltage** (*Optional*, float): The reference voltage. Defaults to :code:`3.3V`.

## Sensor
Sensor
------

The `mcp3204` sensor allows you to use your MCP3204 or MCP3208 12-Bit A/D Converter sensors with ESPHome.
First, setup a [MCP3204 Hub](#mcp3204-component) for your MCP3204/8 sensor and then use this
The :code:`mcp3204` sensor platform allows you to use MCP3204 or MCP3208 12-Bit A/D sensor channels with ESPHome.
First, setup an :ref:`MCP3204 Hub <mcp3204-component>` for your MCP3204/8 sensor and then use this
sensor platform to create individual sensors that will report the voltage to Home Assistant.

```yaml
# Example config of sensors.
# This is a small 1.5v solar panel power rail attached to pin 0
# of the MCP3204
sensor:
- platform: mcp3204 # Attached to pin 0 of the MCP3204.
id: solar_voltage
number: 0 # MCP3204 pin number
.. code-block:: yaml

sensor:

Check failure on line 53 in content/components/sensor/mcp3204.md

View workflow job for this annotation

GitHub Actions / build 

Code block style [Expected: fenced; Actual: indented]
- platform: mcp3204 # Single-ended mode: pin 0 of MCP3204
id: solar_voltage
number: 0

# Pin 7 of MCP3208 in single-ended mode (for MCP3208, use pin numbers 0-7)
- platform: mcp3204
id: supply_voltage
number: 7

# Differential mode: Measures voltage between channel 0 (IN+) and channel 1 (IN–)
- platform: mcp3204
id: differential_sensor
number: 0 # Channel 0 (IN+), paired with 1 (IN–) in differential mode
diff_mode: true # Enable differential mode
name: "Differential Voltage CH0–CH1"
Comment on lines +51 to +68
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

Use fenced code block style instead of indented.

The build tool reports that code block style should be fenced (with triple backticks), not indented for the sensor examples block.

The indented code block structure appears correct for reStructuredText, but verify with the build configuration whether fenced blocks are required for consistency with the documentation style guide.

🧰 Tools
🪛 GitHub Check: build

[failure] 53-53:
Code block style [Expected: fenced; Actual: indented]

🤖 Prompt for AI Agents 
In content/components/sensor/mcp3204.md around lines 51 to 68, the sensor
example uses an indented reStructuredText code-block; update it to use a fenced
code block with triple backticks and the yaml language tag (```yaml) so the
build tool accepts the block; preserve the same inner YAML content and
indentation, replace the leading ".. code-block:: yaml" and its indented content
with a fenced block opening and closing lines, and ensure there is a blank line
after the opening fence if required by the renderer.


# In case MCP3208 is used. you can specify pin number > 4
- platform: mcp3204 # Attached to pin 7 of the MCP3208.
id: supply_voltage
number: 7 # MCP3208 pin number
```
Configuration variables:

### Configuration variables
- **mcp3204_id** (**Required**, :ref:`config-id`): ID of the parent MCP3204 component.
- **number** (**Required**, int): The channel number (0-3 for MCP3204, 0-7 for MCP3208).
- **diff_mode** (*Optional*, bool): Enables differential mode. If :code:`true`, the ADC measures the voltage difference between the selected channel and its paired channel (see chip datasheet). Defaults to :code:`false` (single-ended mode).
- **update_interval** (*Optional*, :ref:`config-time`): Interval to update the sensor. Defaults to :code:`60s`.
- All other options from :ref:`Sensor <config-sensor>`.

- **mcp3204_id** (**Required**, [ID](#config-id)): The id of the parent MCP3204 component.
- **number** (**Required**, int): The pin number of the MCP3204
- **update_interval** (*Optional*, [Time](#config-time)): The interval to check the sensor. Defaults to `60s`.
- All other options from [Sensor](#config-sensor).
.. note::
In differential mode, channel pairing depends on MCP3204/3208 datasheet. The voltage reading represents the difference between the positive input (IN+) and negative input (IN-). In single-ended mode, ADC measures each channel against ground.

## See Also
See Also
--------

- [SPI Bus](#spi)
- {{< apiref "mcp3204/mcp3204.h" "mcp3204/mcp3204.h" >}}
- :doc:`SPI Bus <spi>`
- :apiref:`mcp3204/mcp3204.h`