wattop 0.1.0__tar.gz

wattop-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+config.toml
+*.csv
+*.parquet

wattop-0.1.0/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+All notable changes to wattop are recorded here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- CPU and memory graphs, sourced from the Processor Information counterset and
+  `GlobalMemoryStatusEx` on Windows and from `/proc/stat` and `/proc/meminfo` on
+  Linux. Both emit the same channel keys, so the dashboard is the same screen on
+  either platform.
+- `s` shows or hides the per-rail and per-zone sensor panels. `--details` starts
+  a run with them open; `show_details` in `config.toml` makes that the default.
+- A test suite, and CI across Linux and Windows on both x86-64 and ARM64.
+- Apache-2.0 licence, and packaging metadata good enough to publish.
+
+### Fixed
+- Quitting could print a traceback: the poll timer kept firing during teardown
+  and repainted widgets that had already gone.
+- `--list` reported rate-derived channels, such as processor utilisation, as a
+  flat zero. It took a single sample, which gave them no interval to divide by.
+- A misspelled `group` or `role` in `[overrides]` was accepted silently, so the
+  channel was sampled and logged but never appeared on screen. It now warns.
+- `rich` is declared as a dependency. It was imported directly by the dashboard
+  and happened to resolve only because Textual pulls it in.
+
+### Changed
+- The Textual floor is now 2.1, which is the oldest release the dashboard has
+  actually been exercised against, rather than the 0.80 that was never tested.
+
+### Removed
+- `block_graph` and its glyph tables, superseded by the braille renderer.

wattop-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Sravan Pannala
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

wattop-0.1.0/NOTICE

@@ -0,0 +1,9 @@
+wattop
+Copyright 2026 Sravan Pannala
+
+Licensed under the Apache License, Version 2.0. See the LICENSE file for the
+full terms.
+
+This product bundles no third-party source. At runtime it depends on Textual
+and Rich (Textualize, MIT licensed), which are installed separately and are
+not distributed as part of this work.

wattop-0.1.0/PKG-INFO

@@ -0,0 +1,345 @@
+Metadata-Version: 2.5
+Name: wattop
+Version: 0.1.0
+Summary: btop-style terminal power monitor: power in/out, volts and amps, per-rail SoC power
+Project-URL: Homepage, https://github.com/sravanpannala/wattop
+Project-URL: Repository, https://github.com/sravanpannala/wattop
+Project-URL: Issues, https://github.com/sravanpannala/wattop/issues
+Project-URL: Changelog, https://github.com/sravanpannala/wattop/blob/main/CHANGELOG.md
+Author-email: Sravan Pannala <sra.djoker@gmail.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Keywords: arm64,battery,energy,hwmon,monitor,power,rapl,sensors,snapdragon,terminal,tui,watts
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: System :: Hardware
+Classifier: Topic :: System :: Monitoring
+Classifier: Topic :: System :: Power (UPS)
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: rich>=13
+Requires-Dist: textual>=2.1
+Provides-Extra: parquet
+Requires-Dist: pyarrow>=17; extra == 'parquet'
+Description-Content-Type: text/markdown
+
+# wattop
+
+A btop-style terminal power monitor: **power in, power out, volts and amps**, next to the processor
+and memory load that explains them, plus whatever per-rail SoC power the machine is willing to tell
+you about.
+
+**No administrator rights, no kernel driver, no signed helper — on any platform.** That is the part
+worth leading with. Every Windows tool that reports CPU power today goes through a ring-0 driver, and
+the one they nearly all use now carries a published vulnerability and is a Defender signature. wattop
+reads a performance counter and a device IOCTL, both as a normal user, at about 0.1 ms a sample.
+
+It exists because of a gap on Windows specifically. Mainline btop on **Linux** does show battery and
+CPU watts, and does it well; `btop4win` does not, because the watts code path was never ported —
+it reads `GetSystemPowerStatus()`, which gives percent and time remaining and nothing else. `bottom`
+shows battery watts on all three platforms but no volts, no amps, and no per-rail power. Neither has
+a plugin system, so there is no way to add a sensor short of recompiling.
+
+Windows on ARM is the sharpest case: Snapdragon laptops expose measured board-level power rails that
+nothing else reads, and the tools people reach for either do not build for ARM64 or report no power
+at all there.
+
+**Prior art worth knowing about**, because wattop is not first and does not claim to be. On macOS,
+[jolt](https://github.com/jordond/jolt), [macmon](https://github.com/vladkens/macmon) and
+[mactop](https://github.com/context-labs/mactop) are all good, native, and better than wattop will be
+there. On Linux, [s-tui](https://github.com/amanusk/s-tui) has graphed CPU watts for years. What none
+of them do is Windows, and none of them graph a *measured* charger-input rail. See
+[Where wattop fits](#where-wattop-fits).
+
+```
+╭─ OUT  System ────────────────────────────────────────────────────────╮
+│  60.0                                                                │
+│                                                                      │
+│                                                                      │
+│            ⢀⣀⣠⣤⣶⣶⣤⣤⣀⣀              ⢀⣀⣤⣤⣴⣶⣤⣤⣤⣀⡀           ⢀⣠⣤⣤⣴⣴⣤⣤⣄⡀  │
+│        ⢀⣠⣴⣾⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣷⣦⣤⣀⣀⣀⣀⢀⣀⣠⣤⣶⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣷⣶⣦⣤⣤⣤⣤⣴⣶⣶⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣶│
+│       ⣾⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿│
+│   0.0 ⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿│
+╰───────────────────────────────────────────────── 22.93 W ████░░░░░░ ─╯
+╭─ BATT  Battery ──────────────────────────────────────────────────────╮
+│  25.0  ⢀⣀  ⢀                                                         │
+│       ⣿⣿⣿⣿⣿⣿⣿⣿⣿⣾⣷⣶⣷⣶⣶⣶⣴⣶⣤⣤⣤⣤⣄⣠⣀⣀⣀⢀⣀                                  │
+│       ⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣷⣾⣶⣶⣤⣤⣤⣄⣀⡀⡀⡀                    │
+│       ⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣷⣷⣶⣦⣴⣤⣄⣀           │
+│       ⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣷⣾⣶⣤⣤⣀⣀⣀ │
+│       ⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿│
+│   0.0 ⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿│
+╰───────────────────────────────────────────────── +7.59 W ███░░░░░░░ ─╯
+╭─ CPU  Processor ─────────────────────────────────────────────────────╮
+│ 100.0         ⣀⣠⣤⣀⡀                   ⣀⣠⣄⣀⡀                 ⣀⣠⣤⣀⡀    │
+│            ⢀⣴⣾⣿⣿⣿⣿⣿⣶⣄              ⢀⣴⣾⣿⣿⣿⣿⣿⣶⣄            ⢀⣴⣾⣿⣿⣿⣿⣿⣶⣄  │
+│          ⣀⣴⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣷⣄⡀         ⣠⣴⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣷⣦⡀       ⣠⣶⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣷⣄│
+│       ⢀⣤⣾⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣦⣄⣀  ⢀⣀⣤⣾⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣶⣦⣤⣤⣤⣴⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿│
+│   0.0 ⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿│
+╰──────────────────────────────────────────────────── 47 % █████░░░░░ ─╯
+╭─ MEM  In use ────────────────────────────────────────────────────────╮
+│  15.6                                                                │
+│                    ⣀⣀⣀⡀             ⢀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣠⣤⣤⣤⣤⣤⣤⣤⣤⣤⣤⣤⣤⣤│
+│       ⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿│
+│       ⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿│
+│   0.0 ⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿│
+╰──────────────────────────────────────────────── 11.01 GB ███████░░░ ─╯
+╭─ IN  Charger in ─────────────────────────────────────────────────────╮
+│  60.0 ⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿│
+│       ⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿│
+│   0.0 ⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿│
+╰───────────────────────────────────────────────── 59.45 W ██████████ ─╯
+╭─ TEMP  Hottest sensor ───────────────────────────────────────────────╮
+│ 100.0                                                                │
+│            ⣀⣀⣀⣤⣤⣤⣤⣤⣤⣤⣤⣤⣤⣤⣤⣤⣤⣄⣀⣀⣀⣀⣀⣤⣤⣤⣤⣤⣤⣤⣤⣶⣶⣶⣦⣶⣦⣤⣤⣤⣤⣤⣤⣤⣤⣤⣤⣤⣤⣤⣤⣤⣶⣤⣤⣤⣤⣤│
+│  40.0 ⣶⣶⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿│
+╰─────────────────────────────────────────────── 69.3 degC █████░░░░░ ─╯
+Voltage 8.630 V  Current +5.220 A  ██████████████░░░░  78.6%  49.4/62.9 Wh  charging
+```
+
+Six graphs, three rows, in the order they earn: **OUT** and **BATT** are the two that actually move,
+so they take the top row at 30% of the window each. **CPU** and **MEM** sit under them at 22%, since
+what the machine is doing is the explanation for what it is drawing and the two want reading
+together. **IN** and **TEMP** get 16% on the bottom row — the charger rail sits at its ceiling most
+of the time and the hottest sensor moves slowly, so both are read as a number more often than as a
+shape. Retune per role in `config.toml`:
+
+```toml
+[graphs]
+power_out = 0.3
+battery_power = 0.3
+cpu = 0.2
+memory = 0.2
+```
+
+`--graph-height N` pins every graph instead.
+
+The panel of per-rail power and per-zone temperatures under the graphs starts closed. Press `s` to
+open it, `--details` to start a run with it open, or set `show_details = true` in `config.toml` to
+make that the default. Closed is the default because on most machines those rows are a screenful of
+numbers that rarely move, and they are rows the graphs wanted; the one thing they were read for at a
+glance already survives as **TEMP**. Either way the channels are always sampled and always reach
+`--list`, `--once`, `--json` and `--log`. If per-rail SoC power is the reason you are here, turn it
+on and leave it on.
+
+Every power graph is floored at zero on a fixed axis, so bar height means watts and one frame is
+comparable to the last. **OUT** and **BATT** sit on a two-rung ladder: 0-25 W by default, which is
+where the machine spends most of its life and where a single tall axis would squash everything into
+the bottom third, and 0-60 W for as long as the window on screen holds a sample above 25 W. Each
+picks its own rung from its own window, so a burst on one leaves the other where it was, and once
+the burst scrolls off the axis drops back. **IN** keeps the ceiling its rail declares, and **CPU**
+and **MEM** keep theirs: there is nothing above 100% of a processor and nothing above the RAM the
+machine has, so both axes are the real limit rather than a guess, and the memory graph prints the
+installed total as its top label. **TEMP** is the one graph that does not start at zero -- it runs a
+fixed 40-100 degC, since the hottest sensor in a running machine never approaches zero and silicon
+throttles just under 100, so the panel height is all live range and doubles as "how close to too
+hot". Both bounds are printed on the axis, so what you are looking at is never ambiguous.
+
+**BATT** plots magnitude — how hard the battery is working — and lets colour carry the direction:
+amber discharging, green charging. Pin any ceiling you would rather set yourself with
+`[overrides."<key>"] nominal_max`, and the ladder steps aside.
+
+## What it can read
+
+**Windows on a Snapdragon X Elite** — this is the good case. Windows surfaces the platform's EMI
+(Energy Meter Interface) channels as ordinary performance counters, so the charger input rail is
+*measured*, not inferred:
+
+| Channel | Source |
+|---|---|
+| `emi.PSU_USB` | power in, from the USB-C charger |
+| `emi.SYS` | system rail |
+| `emi.USBC_TOTAL`, `emi.CPU_CLUSTER_0..2`, `emi.GPU` | per-rail SoC power |
+| `batt.power` / `.voltage` / `.current` / `.charge` / `.level` / `.temp` / `.cycles` | the battery device, via `IOCTL_BATTERY_QUERY_STATUS` |
+| `batt.eta.avg` | time left, from battery watts averaged over a growing window |
+| `cpu.util` | `% Processor Time` off the `Processor Information` counterset |
+| `mem.used` / `mem.total` | physical memory, from `GlobalMemoryStatusEx` |
+
+Battery `Rate` is signed, so discharging falls out of the sign and current is a real division rather
+than an estimate. Everything works **without administrator rights** and costs about 0.1 ms a sample.
+
+CPU is the not-idle fraction, the same thing btop counts and the same thing `/proc/stat` gives on
+Linux. Windows also offers `% Processor Utility`, which scales that by the frequency actually
+delivered -- it is what Task Manager shows, and it tracks the **OUT** graph more closely, because a
+core parked at its lowest clock and never quite idle is 100% busy and a couple of watts. Measured on
+this laptop, idling at about a third of nominal, Utility reads about a third of Time for the same
+work. wattop shows Time anyway: a CPU number that disagrees three-to-one with every other load meter
+on the machine costs more than the tighter correlation buys.
+
+The one reading wattop computes rather than reads is **time left**. Windows will hand you a
+`BatteryEstimatedTime`, but it is derived from the instantaneous rate, and an idle machine breathing
+between 15 and 25 W makes that estimate swing by the better part of an hour from one second to the
+next -- measured here, 55 minutes of swing across 45 seconds of sitting still. So `batt.eta.avg`
+averages the *watts* over a window that grows to five minutes from the last plug/unplug and rolls
+after that, and divides once. Averaging the rate rather than the estimate is the point: time left is
+hyperbolic in power, so a single near-idle sample is an absurd ETA but an unremarkable watt figure.
+The same average against the charging rate gives a time to full, which Windows does not offer at
+all. Set `eta_window` in `config.toml` to trade steadiness against how fast it notices a new load.
+
+**Linux** — `/sys/class/hwmon` is walked and everything found is exposed, so the headline number on
+an AMD APU is `power1_average` from the `amdgpu` node (package power, the same PPT figure `ryzenadj`
+reports, no root needed). RAPL via powercap is picked up when readable, and laptops additionally get
+`/sys/class/power_supply`. CPU and memory come from `/proc/stat` and `/proc/meminfo` under the
+same two keys the Windows pair uses, so the dashboard is the same screen on both.
+
+Be aware of what a Ryzen AI Max+ 395 desktop **cannot** give you: no voltage or current anywhere
+(Zen 5 uses SVI3 and no in-tree driver reads it), and no true "power in" (a desktop has no charger
+rail, and the Framework EC exposes no PSU wattage). For real wall power there, point the
+`http_json` source at a smart plug — see below.
+
+## Where wattop fits
+
+|  | Windows | Linux | macOS |
+|---|---|---|---|
+| [btop](https://github.com/aristocratos/btop) | no build | battery + CPU watts | no watts |
+| [btop4win](https://github.com/aristocratos/btop4win) | percent only, no watts | — | — |
+| [bottom](https://github.com/ClementTsang/bottom) | battery watts, one static row | same | same |
+| [jolt](https://github.com/jordond/jolt) | not supported | yes | best in class |
+| [macmon](https://github.com/vladkens/macmon) / [mactop](https://github.com/context-labs/mactop) | — | — | yes |
+| [s-tui](https://github.com/amanusk/s-tui) | — | CPU watts, graphed | — |
+| **wattop** | **measured rails + battery, no admin, including ARM64** | hwmon / powercap / sysfs | **not supported** |
+
+So the honest claim is not "the first power monitor in a terminal". It is four narrower things:
+
+1. **Measured, not estimated.** The common fallback elsewhere is CPU percent multiplied by the
+   chip's rated power. wattop reads a hardware shunt, or shows nothing.
+2. **Power *in*, not just power out.** The charger rail is a measured reading, so
+   `[[derived]] expr = "emi.PSU_USB - emi.SYS - batt.power"` gives you charger loss.
+3. **Volts and amps**, which nothing else currently graphs in a terminal.
+4. **No admin, no driver, anywhere.**
+
+**macOS is not supported.** wattop runs there and exits cleanly saying it found no sensors. Adding it
+would mean a fifth entrant into the one platform that is already well served; the tools above are
+native code and sudoless and get it right. Use one of those.
+
+## Install
+
+```console
+$ uvx wattop                 # run it without installing anything
+$ uv tool install wattop     # or keep it on PATH
+```
+
+[uv](https://docs.astral.sh/uv/) installs its own Python, so this works on a machine with none. If
+you would rather use what you have, `pipx install wattop` and `pip install wattop` both work; wattop
+needs Python 3.11 or newer.
+
+There is one wheel and it is `py3-none-any` — the same file serves Windows x64 and ARM64, Linux
+x86-64 and aarch64, with no compiled extension anywhere.
+
+Optional: `wattop[parquet]` logs to Parquet instead of CSV. It has no Windows ARM64 wheel, so on a
+Snapdragon machine stick to CSV.
+
+### From source
+
+```console
+$ git clone https://github.com/sravanpannala/wattop && cd wattop
+$ uv sync && uv run wattop
+```
+
+On Windows ARM64, pin the native interpreter explicitly — `uv` itself is an x86_64 build and will
+otherwise hand you an emulated Python:
+
+```console
+$ uv venv --python cpython-3.12-windows-aarch64
+$ uv sync
+```
+
+## Usage
+
+```console
+$ wattop                     # the live dashboard
+$ wattop --list              # every channel discovered, with its group and role
+$ wattop --once              # one snapshot, then exit
+$ wattop --once --json       # ... as JSON, for a script or an OSD
+$ wattop --json -n 60        # a stream of JSON lines
+$ wattop --log power.csv     # append samples to CSV (or .parquet with the extra)
+$ wattop --details           # start with the per-rail sensor panels open
+$ wattop -i 0.25             # faster sampling
+```
+
+In the TUI: `q` quit, `p` pause, `s` show or hide the per-rail and per-zone sensor panels,
+`+`/`-` change the interval.
+
+`--once` takes about two seconds on Windows, nearly all of it waiting for the performance counters to
+advance — a rate counter yields nothing until a second sample exists, and that is the data source's
+floor, not Python's. Fine for a script or a log; too slow for a shell prompt that runs it every
+command.
+
+`--log` writes its header from the channels discovered at startup and skips it when the file
+already has one, so start a new file rather than appending to a log written before a machine
+grew a sensor -- the new columns land in the middle of the row, not at the end.
+
+## Adding a reading
+
+The UI never names a sensor. It lays out by **group** (`in`, `out`, `battery`, `system`, `rails`,
+`thermal`) and headlines whatever fills each **role** (`power_in`, `power_out`, `battery_power`,
+`battery_voltage`, `battery_current`, `battery_charge`, `battery_level`, `battery_eta`, `ac_online`,
+`temperature`, `cpu`, `memory`). So a new reading only ever needs to declare where it belongs, and
+the display follows. `rails` and `thermal` are sampled but not drawn, so anything you want on
+screen wants one of the other groups or a role -- including a rail you miss, which
+`[overrides."emi.GPU"] group = "other"` puts back.
+
+That makes adding one come in three sizes.
+
+**1. Nothing.** A new instance of an already-wrapped source is discovered on its own — another
+`Energy Meter` rail after a firmware update, another `hwmon` node after a kernel bump.
+
+**2. A config stanza.** Copy `config.example.toml` to `config.toml` (or
+`~/.config/wattop/config.toml`, or `%APPDATA%\wattop\config.toml`):
+
+```toml
+[[sensor]]
+source = "http_json"                              # a Tasmota smart plug: real wall watts
+url     = "http://plug.lan/cm?cmnd=Status%2010"
+pointer = "/StatusSNS/ENERGY/Power"
+key = "wall"; label = "Wall"; unit = "W"; group = "in"; role = "power_in"
+
+[[derived]]
+key = "efficiency"; label = "Charger loss"; unit = "W"; group = "other"
+expr = "emi.PSU_USB - emi.SYS - batt.power"
+```
+
+Generic sources: `sysfs` (a number in a file), `exec` (a command), `http_json` (an endpoint),
+`pdh` (any Windows performance counter, wildcards included). `[[derived]]` computes channels from
+other channels; `[overrides."key"]` relabels or regroups a built-in one.
+
+**3. A new file in `wattop/sources/`.** Only needed for a genuinely new OS API. Implement four
+methods, add `@register`, and change nothing else:
+
+```python
+@register
+class MySource:
+    name = "my_source"
+    def available(self) -> bool: ...      # cheap probe; False means "skip me quietly"
+    def channels(self) -> list[Channel]: ...
+    def read(self) -> dict[str, float]: ...
+    def close(self) -> None: ...
+```
+
+A source that fails to construct, discover or read is logged and skipped — a broken sensor never
+costs you the rest of the dashboard. Run with `--debug` to see what declined and why.
+
+## Layout
+
+```
+wattop/core/      Channel + Source protocol, registry, sampler, config, derived expressions
+wattop/sources/   win_energy_meter, win_battery, win_thermal, win_system,
+                  linux_hwmon, linux_powercap, linux_power_supply, linux_system,
+                  generic (sysfs/exec/http_json/pdh)
+wattop/ui/        the Textual dashboard
+wattop/render.py  sparklines, bars, the text tables used by --list and --once
+```
+
+## Licence
+
+Apache-2.0. See [LICENSE](LICENSE).