1.. _comparator_api:
2
3Comparator
4##########
5
6Overview
7********
8
9An analog comparator compares the voltages of two analog signals connected to its negative and
10positive inputs. If the voltage at the positive input is higher than the negative input, the
11comparator's output will be high, otherwise, it will be low.
12
13Comparators can typically set a trigger which triggers on output changes. This trigger can
14either invoke a callback, or its status can be polled.
15
16Related configuration options:
17
18* :kconfig:option:`CONFIG_COMPARATOR`
19
20Configuration
21*************
22
23Embedded comparators can typically be configured at runtime. When enabled, an initial
24configuration must be provided using the devicetree. At runtime, comparators can have their
25configuration updated using device driver specific APIs. The configuration will be applied
26when the comparator is resumed.
27
28Power management
29****************
30
31Comparators are enabled using power management. When resumed, the comparator will actively
32compare its inputs, producing an output and detecting edges. When suspended, the comparator
33will be inactive.
34
35Comparator shell
36****************
37
38The comparator shell provides the ``comp`` command with a set of subcommands for the
39:ref:`shell <shell_api>` module.
40
41The ``comp`` shell command provides the following subcommands:
42
43* ``get_output`` See :c:func:`comparator_get_output`
44* ``set_trigger`` See :c:func:`comparator_set_trigger`
45* ``await_trigger`` Awaits trigger using the following flow:
46
47  * Set trigger callback using :c:func:`comparator_set_trigger_callback`
48  * Await callback or time out after default or optionally provided timeout
49  * Clear trigger callback using :c:func:`comparator_set_trigger_callback`
50* ``trigger_is_pending`` See :c:func:`comparator_trigger_is_pending`
51
52Related configuration options:
53
54* :kconfig:option:`CONFIG_SHELL`
55* :kconfig:option:`CONFIG_COMPARATOR_SHELL`
56* :kconfig:option:`CONFIG_COMPARATOR_SHELL_AWAIT_TRIGGER_DEFAULT_TIMEOUT`
57* :kconfig:option:`CONFIG_COMPARATOR_SHELL_AWAIT_TRIGGER_MAX_TIMEOUT`
58
59.. note::
60   The power management shell can optionally be enabled alongside the comparator shell.
61
62   Related configuration options:
63
64   * :kconfig:option:`CONFIG_PM_DEVICE`
65   * :kconfig:option:`CONFIG_PM_DEVICE_SHELL`
66
67API Reference
68*************
69
70.. doxygengroup:: comparator_interface
71