sitemon 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (53) hide show
  1. sitemon-0.1.0/.editorconfig +24 -0
  2. sitemon-0.1.0/.gitattributes +20 -0
  3. sitemon-0.1.0/.gitignore +33 -0
  4. sitemon-0.1.0/CHANGELOG.md +29 -0
  5. sitemon-0.1.0/CLA.md +91 -0
  6. sitemon-0.1.0/CONTRIBUTING.md +58 -0
  7. sitemon-0.1.0/LICENSE +21 -0
  8. sitemon-0.1.0/PKG-INFO +244 -0
  9. sitemon-0.1.0/README.md +199 -0
  10. sitemon-0.1.0/deploy/agent.example.toml +81 -0
  11. sitemon-0.1.0/deploy/hub.example.toml +130 -0
  12. sitemon-0.1.0/pyproject.toml +82 -0
  13. sitemon-0.1.0/sitemon/__init__.py +22 -0
  14. sitemon-0.1.0/sitemon/_cli.py +279 -0
  15. sitemon-0.1.0/sitemon/_duration.py +34 -0
  16. sitemon-0.1.0/sitemon/_events.py +230 -0
  17. sitemon-0.1.0/sitemon/_systemd.py +35 -0
  18. sitemon-0.1.0/sitemon/agent/__init__.py +1 -0
  19. sitemon-0.1.0/sitemon/agent/ami.py +266 -0
  20. sitemon-0.1.0/sitemon/agent/aredn.py +49 -0
  21. sitemon-0.1.0/sitemon/agent/runtime.py +504 -0
  22. sitemon-0.1.0/sitemon/agent/sensors/__init__.py +1 -0
  23. sitemon-0.1.0/sitemon/agent/sensors/base.py +22 -0
  24. sitemon-0.1.0/sitemon/agent/sensors/bme280.py +197 -0
  25. sitemon-0.1.0/sitemon/agent/sensors/factory.py +129 -0
  26. sitemon-0.1.0/sitemon/agent/sensors/gpio.py +80 -0
  27. sitemon-0.1.0/sitemon/agent/sensors/i2c.py +117 -0
  28. sitemon-0.1.0/sitemon/agent/sensors/ina.py +118 -0
  29. sitemon-0.1.0/sitemon/agent/sensors/sim.py +105 -0
  30. sitemon-0.1.0/sitemon/agent/store.py +195 -0
  31. sitemon-0.1.0/sitemon/config.py +429 -0
  32. sitemon-0.1.0/sitemon/hub/__init__.py +1 -0
  33. sitemon-0.1.0/sitemon/hub/alerts.py +135 -0
  34. sitemon-0.1.0/sitemon/hub/channels.py +94 -0
  35. sitemon-0.1.0/sitemon/hub/db.py +276 -0
  36. sitemon-0.1.0/sitemon/hub/ingest.py +252 -0
  37. sitemon-0.1.0/sitemon/hub/rules.py +266 -0
  38. sitemon-0.1.0/sitemon/hub/server.py +494 -0
  39. sitemon-0.1.0/sitemon/hub/static/app.js +214 -0
  40. sitemon-0.1.0/sitemon/hub/static/index.html +19 -0
  41. sitemon-0.1.0/sitemon/hub/static/style.css +77 -0
  42. sitemon-0.1.0/sitemon/hub/summary.py +55 -0
  43. sitemon-0.1.0/sitemon/py.typed +0 -0
  44. sitemon-0.1.0/tests/__init__.py +0 -0
  45. sitemon-0.1.0/tests/conftest.py +198 -0
  46. sitemon-0.1.0/tests/test_agent.py +543 -0
  47. sitemon-0.1.0/tests/test_ami_aredn.py +203 -0
  48. sitemon-0.1.0/tests/test_config.py +106 -0
  49. sitemon-0.1.0/tests/test_events.py +96 -0
  50. sitemon-0.1.0/tests/test_hub.py +776 -0
  51. sitemon-0.1.0/tests/test_hub_hardening.py +673 -0
  52. sitemon-0.1.0/tests/test_sensors_hw.py +620 -0
  53. sitemon-0.1.0/tests/test_store.py +190 -0
@@ -0,0 +1,24 @@
1
+ # https://editorconfig.org
2
+ root = true
3
+
4
+ [*]
5
+ charset = utf-8
6
+ end_of_line = lf
7
+ insert_final_newline = true
8
+ trim_trailing_whitespace = true
9
+ indent_style = space
10
+ indent_size = 4
11
+
12
+ [*.rs]
13
+ indent_size = 4
14
+ max_line_length = 100
15
+
16
+ [*.{js,ts,json,svelte,css,html,yml,yaml}]
17
+ indent_size = 2
18
+
19
+ [*.md]
20
+ # Markdown uses trailing double-space for hard line breaks.
21
+ trim_trailing_whitespace = false
22
+
23
+ [Makefile]
24
+ indent_style = tab
@@ -0,0 +1,20 @@
1
+ # Normalise line endings to LF everywhere, in the repository *and* in the
2
+ # working tree, on every platform. Without this, Git on Windows defaults to
3
+ # core.autocrlf=true and checks files out with CRLF, which breaks byte-exact
4
+ # test fixtures and shell scripts ("bad interpreter: /bin/sh^M").
5
+ # Modern Windows editors all handle LF, so forcing it costs nothing.
6
+ * text=auto eol=lf
7
+ *.sh text eol=lf
8
+ # batch files are the exception: cmd.exe misreads labels and long lines in
9
+ # LF-only .cmd/.bat files, so they check out with CRLF
10
+ *.cmd text eol=crlf
11
+ *.bat text eol=crlf
12
+
13
+ # Binary assets
14
+ *.png binary
15
+ *.ico binary
16
+ *.icns binary
17
+ *.gif binary
18
+ *.msi binary
19
+ *.exe binary
20
+ *.londopy binary
@@ -0,0 +1,33 @@
1
+ # OS
2
+ .DS_Store
3
+ Thumbs.db
4
+ desktop.ini
5
+
6
+ # Editors
7
+ .idea/
8
+ .vscode/
9
+ *.swp
10
+
11
+ # Python
12
+ __pycache__/
13
+ *.egg-info/
14
+ .venv/
15
+ .pytest_cache/
16
+ .mypy_cache/
17
+ .ruff_cache/
18
+ dist/
19
+ build/
20
+
21
+ # Local runtime data (event logs, hub database)
22
+ *.db
23
+ *.db-wal
24
+ *.db-shm
25
+ /data/
26
+
27
+ # Secrets: site signing keys, AMI passwords, webhook URLs, Anubis key
28
+ .env
29
+ *.key
30
+ config.toml
31
+ !deploy/**/*.example.toml
32
+ deploy/hub/hub.toml
33
+ deploy/hub/hub.env
@@ -0,0 +1,29 @@
1
+ # Changelog
2
+
3
+ All notable changes to sitemon are listed here. The format follows
4
+ [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow
5
+ [Semantic Versioning](https://semver.org/spec/v2.0.0.html). The section for a version is
6
+ what appears on its GitHub release page. Validated in CI by
7
+ [patchnotes](https://github.com/Londopy/patchnotes).
8
+
9
+ ## [Unreleased]
10
+
11
+ ## [0.1.0] - 2026-11-19
12
+
13
+ ### Added
14
+
15
+ - Site agent: INA226/INA219 power, BME280 environment, door and water inputs,
16
+ AllStar state over AMI (localhost only) and AREDN node state, with simulated
17
+ backends for testing without hardware.
18
+ - Signed, sequence-numbered event log with batched SQLite writes and
19
+ store-and-forward sync to every configured hub.
20
+ - Door and water inputs are debounced (`switch_debounce`, 2 s by default).
21
+ - Hub: signature checks, rules for thresholds, rate of change, state changes and
22
+ silent sites, alert de-duplication and warn -> critical escalation.
23
+ - `hold` on a rule: the condition must last that long before an alert opens.
24
+ - Alerts to Discord, ntfy and email, each channel sent independently; weekly
25
+ summary to Discord.
26
+ - Dashboard with a tile and sparklines per site, and CSV export per sensor.
27
+
28
+ [Unreleased]: https://github.com/Londopy/sitemon/compare/v0.1.0...HEAD
29
+ [0.1.0]: https://github.com/Londopy/sitemon/releases/tag/v0.1.0
sitemon-0.1.0/CLA.md ADDED
@@ -0,0 +1,91 @@
1
+ # sitemon Contributor License Agreement
2
+
3
+ Thank you for contributing to sitemon. This agreement clarifies the rights
4
+ you grant on the material you contribute, so that the project can accept it,
5
+ distribute it, and keep its license. You keep the copyright in your
6
+ contribution; you are not asked to assign it.
7
+
8
+ sitemon is released under the MIT License (`LICENSE`). This agreement lets the
9
+ project continue to distribute your contribution under that license, and, if
10
+ it ever needs to, under another open-source license approved by the Open
11
+ Source Initiative; it does not let the project take your contribution
12
+ private.
13
+
14
+ By opening a pull request and confirming the agreement in the pull request
15
+ (the CLA check asks you to), you accept the terms below for that
16
+ contribution and every later one you make to this repository.
17
+
18
+ ## 1. Definitions
19
+
20
+ "You" is the person or legal entity accepting this agreement. "Contribution"
21
+ is any original work of authorship, including changes to existing work, that
22
+ you intentionally submit to sitemon for inclusion: code, documentation,
23
+ examples, tests, translations. "Submit" means sending it to the project by
24
+ pull request, issue, or another channel the maintainers use. "Londopy" is
25
+ the project's copyright holder and maintainer.
26
+
27
+ ## 2. Copyright license
28
+
29
+ You grant Londopy and every recipient of sitemon a perpetual, worldwide,
30
+ non-exclusive, royalty-free, irrevocable copyright license to reproduce your
31
+ Contribution, prepare derivative works of it, display it, perform it,
32
+ sublicense it, and distribute it and the derivative works, under the
33
+ MIT License or another OSI-approved open-source license.
34
+
35
+ ## 3. Patent license
36
+
37
+ You grant Londopy and every recipient of sitemon a perpetual, worldwide,
38
+ non-exclusive, royalty-free, irrevocable patent license to make, use, sell,
39
+ offer to sell, import, and otherwise transfer your Contribution, alone or
40
+ combined with sitemon, for any patent claims you can license that your
41
+ Contribution alone or in that combination necessarily infringes. If anyone
42
+ starts patent litigation claiming that your Contribution or sitemon infringes
43
+ a patent, the patent licenses granted to that party under this agreement end
44
+ on the day the litigation is filed.
45
+
46
+ ## 4. What you represent
47
+
48
+ - You are entitled to grant these licenses. If your employer has rights in
49
+ your Contribution, your employer has permitted you to submit it, or has
50
+ waived those rights, or has signed this agreement for you.
51
+ - The Contribution is your original work, except for material you clearly
52
+ identify as someone else's, together with its license and any
53
+ restrictions you know of. Third-party material must be under a license
54
+ compatible with the MIT License.
55
+ - You will tell the maintainers if you learn that any of the above is no
56
+ longer accurate.
57
+
58
+ ## 5. AI-assisted contributions
59
+
60
+ If you used an AI tool (a code generator, a language model, an assistant of
61
+ any kind) to produce any part of a Contribution, then:
62
+
63
+ - you disclose it in the pull request, in the form the pull request template
64
+ asks for: which tool, and what it did;
65
+ - you have read and understood what the tool produced, and you submit it as
66
+ your own work under this agreement, with the same representations as for
67
+ anything you wrote yourself; the tool is not a party to this agreement and
68
+ is not an author of the Contribution;
69
+ - you have not included output that reproduces someone else's work under a
70
+ license incompatible with the MIT License, or that you have no right to license.
71
+
72
+ The project accepts AI-assisted contributions on these terms and rejects
73
+ undisclosed ones. Authorship in commits and files names people; a tool is
74
+ not listed as an author or co-author.
75
+
76
+ ## 6. No warranty, no obligation
77
+
78
+ Your Contribution is provided as is, without warranty of any kind, unless
79
+ you say otherwise in writing. You are not required to support it, and the
80
+ project is not required to accept it: the maintainers decide what merges.
81
+
82
+ ## 7. Signing
83
+
84
+ The CLA check on your first pull request asks you to comment with the
85
+ sentence it shows; that comment is your acceptance, recorded with your
86
+ GitHub account on the `cla-signatures` branch of this repository. A company
87
+ contributing on behalf of its employees can instead open an issue naming
88
+ the covered GitHub accounts, or contact the maintainer (Londopy) through
89
+ GitHub.
90
+
91
+ Questions go in an issue.
@@ -0,0 +1,58 @@
1
+ # Contributing to sitemon
2
+
3
+ Issues and pull requests are welcome.
4
+
5
+ ## Before you open a pull request
6
+
7
+ - Set up: `python -m venv .venv`, activate it, then `pip install -e ".[dev]"`.
8
+ - Test: `pytest -m "not slow"` (no hardware needed: sensors and AMI are simulated).
9
+ - Lint and type-check: `ruff check .` and `mypy sitemon`.
10
+
11
+ The one rule that shapes everything: **sitemon is a monitor, not a controller.** It
12
+ reads; it does not key transmitters or change repeater settings. Relay outputs
13
+ (phase 2) are signed, time-limited and watchdogged, and must never become a path
14
+ to transmitter control over amateur RF.
15
+ - Add a line under `## [Unreleased]` in [CHANGELOG.md](CHANGELOG.md) if the change is
16
+ something a user would notice. The changelog is checked in CI by
17
+ [patchnotes](https://github.com/Londopy/patchnotes).
18
+ - Fill in the pull request template, including the **AI tools** section.
19
+ - Sign the [CLA](CLA.md) when the check asks (once).
20
+
21
+ ## AI-assisted contributions
22
+
23
+ You may use AI tools to help write a contribution. Three rules, which the
24
+ CLA makes binding:
25
+
26
+ - **Say so in the pull request.** The template has a section for it: which
27
+ tool, and what it did (drafted the change, wrote the tests, explained the
28
+ code, translated the docs, wrote the description). "None" is a fine answer.
29
+ A check on every pull request fails until the section is filled in.
30
+ - **You are the author.** Read and understand everything the tool produced
31
+ before you submit it; you are answerable for it in review exactly as for
32
+ code you typed. A pull request whose author cannot explain a change is
33
+ sent back. Commits and files name people, not tools: an AI tool is never
34
+ listed as an author or co-author, and commits carry no "Generated with"
35
+ footers. The check rejects both.
36
+ - **No laundering.** Do not submit output that reproduces someone else's
37
+ work under a license incompatible with this project's license, or that you
38
+ have no right to license. If a tool hands you a recognizable chunk of
39
+ another project, leave it out.
40
+
41
+ An undisclosed AI-assisted contribution is closed when discovered, whatever
42
+ its quality. Disclosed ones are reviewed like any other, and labeled
43
+ `ai-assisted`: the tests are the bar.
44
+
45
+ The same goes for issues: if an AI tool wrote or summarized a bug report,
46
+ say so in it.
47
+
48
+ ## Contributor License Agreement
49
+
50
+ Your first pull request gets a comment from the CLA check asking you to
51
+ accept [`CLA.md`](CLA.md) by replying with one sentence. You keep the
52
+ copyright in your work; the agreement gives the project a license to
53
+ distribute it under its license (or another OSI-approved license, never a
54
+ proprietary one) and a patent license for what your contribution
55
+ necessarily uses, and it records that the work is yours to give,
56
+ AI-assisted or not. Every author of a commit in the pull request signs once,
57
+ and that covers all their later pull requests. Companies contributing on
58
+ behalf of employees can open an issue naming the covered accounts instead.
sitemon-0.1.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Londopy
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
sitemon-0.1.0/PKG-INFO ADDED
@@ -0,0 +1,244 @@
1
+ Metadata-Version: 2.5
2
+ Name: sitemon
3
+ Version: 0.1.0
4
+ Summary: Power, environment, door, AllStar and AREDN monitoring for repeater sites.
5
+ Project-URL: Homepage, https://github.com/Londopy/sitemon
6
+ Project-URL: Repository, https://github.com/Londopy/sitemon
7
+ Project-URL: Bug Tracker, https://github.com/Londopy/sitemon/issues
8
+ Author: Londopy
9
+ License-Expression: MIT
10
+ License-File: LICENSE
11
+ Keywords: allstarlink,amateur-radio,aredn,monitoring,raspberry-pi,repeater
12
+ Classifier: Development Status :: 3 - Alpha
13
+ Classifier: Intended Audience :: System Administrators
14
+ Classifier: Intended Audience :: Telecommunications Industry
15
+ Classifier: License :: OSI Approved :: MIT License
16
+ Classifier: Operating System :: POSIX :: Linux
17
+ Classifier: Programming Language :: Python :: 3
18
+ Classifier: Programming Language :: Python :: 3.11
19
+ Classifier: Programming Language :: Python :: 3.12
20
+ Classifier: Programming Language :: Python :: 3.13
21
+ Classifier: Topic :: Communications :: Ham Radio
22
+ Classifier: Topic :: System :: Monitoring
23
+ Classifier: Typing :: Typed
24
+ Requires-Python: >=3.11
25
+ Requires-Dist: aiohttp>=3.9
26
+ Requires-Dist: cryptography>=41
27
+ Provides-Extra: all
28
+ Requires-Dist: gpiozero>=2.0; extra == 'all'
29
+ Requires-Dist: hypothesis>=6; extra == 'all'
30
+ Requires-Dist: mypy>=1.10; extra == 'all'
31
+ Requires-Dist: pytest-asyncio>=0.23; extra == 'all'
32
+ Requires-Dist: pytest>=8; extra == 'all'
33
+ Requires-Dist: ruff>=0.5; extra == 'all'
34
+ Requires-Dist: smbus2>=0.4; extra == 'all'
35
+ Provides-Extra: dev
36
+ Requires-Dist: hypothesis>=6; extra == 'dev'
37
+ Requires-Dist: mypy>=1.10; extra == 'dev'
38
+ Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
39
+ Requires-Dist: pytest>=8; extra == 'dev'
40
+ Requires-Dist: ruff>=0.5; extra == 'dev'
41
+ Provides-Extra: pi
42
+ Requires-Dist: gpiozero>=2.0; extra == 'pi'
43
+ Requires-Dist: smbus2>=0.4; extra == 'pi'
44
+ Description-Content-Type: text/markdown
45
+
46
+ # sitemon
47
+
48
+ [![CI](https://github.com/Londopy/sitemon/actions/workflows/ci.yml/badge.svg)](https://github.com/Londopy/sitemon/actions/workflows/ci.yml)
49
+ [![Release](https://img.shields.io/github/v/release/Londopy/sitemon)](https://github.com/Londopy/sitemon/releases)
50
+ [![PyPI](https://img.shields.io/pypi/v/sitemon)](https://pypi.org/project/sitemon/)
51
+ [![Python](https://img.shields.io/pypi/pyversions/sitemon)](https://pypi.org/project/sitemon/)
52
+ [![License](https://img.shields.io/github/license/Londopy/sitemon)](LICENSE)
53
+ ![Platform](https://img.shields.io/badge/platform-Raspberry%20Pi%20%7C%20Linux-informational)
54
+
55
+ **Find out a repeater site is in trouble before someone keys up and nothing answers.**
56
+
57
+ sitemon is a small agent for the Raspberry Pi at each repeater or AllStar site, plus a hub that
58
+ watches all of them. The agent watches supply voltage and current, temperature and humidity, the
59
+ door, AllStar node state and the local AREDN node. The hub alerts people (Discord, ntfy, email) and
60
+ shows every site on one page. It keeps working over flaky links: readings queue at the site and
61
+ catch up when any path returns.
62
+
63
+ ```console
64
+ $ sitemon demo
65
+ Dashboard: http://127.0.0.1:8470 (data in /tmp/sitemon-demo-1a2b; Ctrl+C to stop)
66
+ ```
67
+
68
+ ## Features
69
+
70
+ - **Power:** battery, solar and PSU rails via INA226 (or INA219 for lower voltage).
71
+ - **Environment:** temperature, humidity and pressure via BME280.
72
+ - **Door and water:** any reed switch or float switch on a GPIO pin.
73
+ - **AllStar:** keyed state, linked nodes and uptime over AMI, on localhost only, with an AMI user
74
+ that can query status and nothing else. Registration status is an opt-in extra.
75
+ - **AREDN:** node reachability, firmware, links and RF links from the local node.
76
+ - **Rules:** thresholds with hysteresis, slow trends ("battery fell 0.3 V in a week"), state
77
+ changes, sensor faults, and silent sites.
78
+ - **Alerts:** one message when something breaks, one when it escalates, one when it's fixed.
79
+ Queued and retried when the hub's internet path is down.
80
+ - **Dashboard:** a tile per site with sparklines, a plain-language status, a page per site with
81
+ 7-day charts and alert history, and CSV export for every sensor. Weekly summary to Discord.
82
+ - **Built for transmitter sites:** I2C error recovery, chips re-initialised after RF-induced
83
+ resets, systemd watchdog, batched writes to spare the SD card.
84
+
85
+ ## Install
86
+
87
+ On each site's Pi (ASL3 / Raspberry Pi OS bookworm ship Python 3.11):
88
+
89
+ ```bash
90
+ python3 -m venv /opt/sitemon
91
+ /opt/sitemon/bin/pip install "sitemon[pi]"
92
+ ```
93
+
94
+ On the hub (any Linux box on the mesh, or a small VPS):
95
+
96
+ ```bash
97
+ python3 -m venv /opt/sitemon
98
+ /opt/sitemon/bin/pip install sitemon
99
+ ```
100
+
101
+ [deploy/README.md](deploy/README.md) has the full walk-through: wiring, the AMI user,
102
+ systemd units and a read-only root. Public hub deployments sit behind
103
+ [Anubis](https://github.com/TecharoHQ/anubis) to keep AI scrapers off; see `deploy/hub/`.
104
+
105
+ ## Usage
106
+
107
+ 1. On the site, make its signing key and note the public key it prints:
108
+
109
+ ```bash
110
+ sitemon keygen --out /etc/sitemon/site.key
111
+ ```
112
+
113
+ 2. Add the site and its public key to the hub config, and point the agent at the hub
114
+ (examples in [deploy/](deploy/)).
115
+
116
+ 3. Check both configs, then start the services:
117
+
118
+ ```bash
119
+ sitemon check /etc/sitemon/agent.toml
120
+ systemctl enable --now sitemon-agent
121
+ ```
122
+
123
+ Each site also serves a small status page on `127.0.0.1:8471` for whoever is standing in the
124
+ shack.
125
+
126
+ ## Configuration
127
+
128
+ | File | Where |
129
+ |---|---|
130
+ | Agent | `/etc/sitemon/agent.toml` ([example](deploy/agent.example.toml)) |
131
+ | Hub | `/etc/sitemon/hub.toml` ([example](deploy/hub.example.toml)) |
132
+ | Site key | `/etc/sitemon/site.key` (0600, made by `sitemon keygen`) |
133
+
134
+ Secrets never go in the TOML: the AMI password, webhook URLs and SMTP password are read from an
135
+ environment variable (`*_env`) or a file (`*_file`), so a config can be pasted into a bug report
136
+ as-is.
137
+
138
+ ```toml
139
+ # hub.toml (excerpt)
140
+ [[rules]]
141
+ name = "Battery low"
142
+ metric = "batt.v" # <sensor name>.<value>
143
+ below = 12.2 # warn
144
+ critical_below = 11.8
145
+ hysteresis = 0.1 # stays open until 12.3 V, so it doesn't flap
146
+ hold = "2m" # must stay low 2 minutes; a key-up sag never alerts
147
+ unit = "V"
148
+
149
+ [[rules]]
150
+ name = "Battery falling"
151
+ type = "rate"
152
+ metric = "batt.v"
153
+ window = "7d" # compare with a week ago...
154
+ smooth = "1d" # ...using daily averages, so the solar cycle cancels out
155
+ drop = 0.3
156
+ unit = "V"
157
+ ```
158
+
159
+ ## How is this different from Allmon3 or a PacketFlux SiteMonitor?
160
+
161
+ | | Allmon3 / Supermon | PacketFlux / NetGuardian | sitemon |
162
+ |---|---|---|---|
163
+ | AllStar link and keyed state | ✅ | ❌ | ✅ |
164
+ | Site power, temperature, door | ❌ | ✅ | ✅ |
165
+ | Every site on one page | ❌ | via your NMS | ✅ |
166
+ | Alerts when a site goes silent | ❌ | via your NMS | ✅ |
167
+ | Keeps readings through a link outage | ❌ | ❌ | ✅ |
168
+ | Cost per site, excluding the Pi | free | $130+ | about $40-80 in parts |
169
+
170
+ sitemon doesn't replace Allmon3; run both. It reads AMI the same way, read-only.
171
+
172
+ ## What it will not do
173
+
174
+ - **Control the repeater.** sitemon is a monitor. Relay outputs (remote reboot, planned) will be
175
+ signed, time-limited and watchdogged, and won't be offered over amateur RF links without a
176
+ proper auxiliary station (47 CFR 97.213).
177
+ - **Encrypt data over the mesh.** Part 97 doesn't allow it. Everything is signed instead, so the
178
+ hub can tell a real reading from a forged one.
179
+ - **Measure RF power precisely.** Forward and reflected trend alarms are planned; calibrated
180
+ absolute power is not.
181
+
182
+ ## How it works
183
+
184
+ ```
185
+ [site] sensors --I2C/GPIO--> Pi: sitemon agent <--AMI 127.0.0.1-- Asterisk (app_rpt)
186
+ | <--HTTP-- AREDN node /a/sysinfo
187
+ | signed events, SQLite queue
188
+ [path] AREDN mesh / cellular / internet: every configured hub gets every event
189
+ [hub] verify signatures -> rules -> alerts (Discord, ntfy, email) -> dashboard
190
+ ```
191
+
192
+ - **Every event is signed** (Ed25519) and numbered with a per-site counter that never repeats,
193
+ even after a power cut. The hub stores each number once, so a retried upload is harmless.
194
+ - **Time without a trusted clock:** each event carries the agent's monotonic clock as well as its
195
+ wall clock. The hub learns the offset from each upload and places events by that, so a Pi that
196
+ boots without NTP after an outage still files its readings at the right time.
197
+ - **Store-and-forward:** the agent keeps each event until every configured hub (say, one on the
198
+ mesh and one on the internet) confirms it has it, backing off separately for each while its
199
+ path is down.
200
+ - **Silence is an alarm:** the hub raises it from its own clock, because a dead site can't report
201
+ itself.
202
+
203
+ ## Building from source
204
+
205
+ ```bash
206
+ git clone https://github.com/Londopy/sitemon
207
+ cd sitemon
208
+ python -m venv .venv && . .venv/bin/activate
209
+ pip install -e ".[dev]"
210
+ pytest && ruff check . && mypy sitemon
211
+ ```
212
+
213
+ No hardware needed: the tests use simulated sensors and a fake AMI server.
214
+
215
+ ## Layout
216
+
217
+ ```
218
+ sitemon/
219
+ _events.py # events, Ed25519 signing, upload envelope
220
+ config.py # agent and hub TOML
221
+ agent/
222
+ runtime.py # sampling loops, heartbeat, sync, local status page
223
+ store.py # SQLite event queue, never-repeating sequence numbers
224
+ ami.py # read-only AMI client (loopback only)
225
+ aredn.py # AREDN sysinfo
226
+ sensors/ # INA226/219, BME280, GPIO, I2C recovery, simulated sensors
227
+ hub/
228
+ ingest.py # signature checks, de-duplication, time placement
229
+ rules.py # thresholds, trends, states, faults, silence
230
+ alerts.py # de-duplication, escalation, outbox
231
+ channels.py # Discord, ntfy, email
232
+ server.py # HTTP API, dashboard, CSV, background loops
233
+ static/ # dashboard (plain HTML/JS/CSS)
234
+ deploy/ # example configs, systemd units, hub Docker + Anubis
235
+ tests/
236
+ ```
237
+
238
+ ## Contributing
239
+
240
+ See [CONTRIBUTING.md](CONTRIBUTING.md). The short version: it's a monitor, not a controller.
241
+
242
+ ## License
243
+
244
+ MIT — see [LICENSE](LICENSE).