@alteriom/painlessmesh 2.0.2 → 2.1.0

package/CHANGELOG.md

@@ -7,6 +7,219 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.1.0] - 2026-09-15
+
+`sendToInternet()` you can build a notifier on (#463). One user's WhatsApp
+alerts through CallMeBot kept failing, and the hardware rig showed why in the
+library: a request whose reply was slow was sent again -- one call reached the
+server four times --, a long reply was cut before the service said what it did,
+and a chunked reply reached the application with its transfer framing. 2.1.0
+issues each request once, retries only what cannot arrive twice, honours
+Retry-After, gives every attempt one request id, and hands the application the
+whole result: status, the service's own words, whether a resend is safe, and
+how many attempts it took. **Upgrade if a node of yours sends to the
+Internet.**
+
+**One behaviour change to read before upgrading:** the library no longer
+decides from a reply's words whether a service did what you asked. A CallMeBot
+"Too many requests" page under HTTP 201 is `success == true`, as HTTP says;
+read the reply in your sketch with the new result callback, as
+`examples/sendToInternet/callmebot.h` does. Wire-compatible with 2.0 nodes: the
+new ack and request fields are optional and ignored by older nodes. Validated
+on the six-family hardware rig, including a real WhatsApp delivered through
+the mesh and a real CallMeBot refusal reaching the application intact.
+
+### Changed
+
+- **`sendToInternet()` no longer retries a request the server may already
+  have.** A read timeout or a connection lost after the request was sent used
+  to count as a "network error" and was retried up to three times; on the
+  hardware rig one timed-out send reached the server four times, which for a
+  message service is four messages, or one message and three refusals. The
+  gateway now tells the origin node whether the identical request may be sent
+  again (`GatewayAckPackage::retryable`, JSON `"retry"`), and says yes only
+  when it cannot have arrived -- connection refused, a failure before the
+  request went out -- or when the server said it did not take it: HTTP 429 and
+  503. A 500, 502 or 504 is no longer retried. The error of a transport
+  failure that was not retried ends "(the request may have reached the
+  server; not retried)", and resending is the application's decision.
+  Acks from gateways that predate the field keep their old reading, except
+  that a 2xx is never retried.
+- **The library no longer judges a response body.** 2.0.3 matched
+  CallMeBot's "Too many requests" page inside the gateway and reported that
+  HTTP 201 as a failure. Whether a reply means what an application wanted is
+  that service's language, not HTTP's, so the gateway now applies HTTP's
+  meaning of the status (200, 201, 202 and 204 succeed; 203, 205-299 are
+  unverified failures) and carries the body to the application instead. **A
+  CallMeBot rate-limit refusal under HTTP 201 is therefore `success == true`
+  again at the library level.** The sendToInternet example reads CallMeBot's
+  reply itself (`examples/sendToInternet/callmebot.h`); a sketch that relied
+  on 2.0.3's check should do the same with the new result callback.
+
+### Added
+
+- **`sendToInternet()` with an `InternetResult` callback.** Besides
+  `success`, `httpStatus` and `error`, the result carries `response` -- the
+  start of the response body as one line, on success as well as failure --
+  `retryable`, `attempts` and `messageId`. The three-argument callback is
+  unchanged. The response travels in the ack as `"resp"` and the error
+  excerpt keeps the end of a long body as well as its start, so a verdict
+  after an echo of the request survives (#463): the gateway keeps the first
+  512 and the last 256 bytes of a body, not only its start, and removes
+  chunked transfer framing -- CallMeBot answers chunked, and its reply reached
+  the application as "a6 ... Message queued ... 0". `PAINLESSMESH_HAS_INTERNET_RESULT`
+  is defined, so code that also builds against older releases can `#ifdef` it.
+- **Retry-After.** A 429 or 503 retry waits at least as long as the server's
+  `Retry-After` (delay-seconds); a server that asks for more than 60 s gets no
+  automatic retry, and the error says when it wants the request back. The
+  request's timeout moves with the wait, so the invited retry is not timed
+  out first.
+- **Request ids.** Every attempt at one call carries the same `X-Request-Id`
+  and `Idempotency-Key` header (`pm-<origin>-<messageId>-<nonce>`), so a
+  service that honours idempotency keys drops a copy and a log can count
+  retries. The nonce is drawn per call and travels in the request (`"nonce"`),
+  so ids stay unique after the 16-bit message-id counter wraps; a request from
+  an older node keeps `pm-<origin>-<messageId>`.
+  Message ids now start at a random point each boot, so the first request
+  after a reboot does not reuse the key of the boot before.
+- **Test point:** the ledger counts requests per tag and records their
+  request ids, and `/retry-after/{seconds}` refuses a tag once with 429 and
+  `Retry-After`, then accepts it and records whether the retry came early.
+- **sendToInternet example:** alerts once per O2 episode and at most every
+  10 minutes, backs off 15 minutes after a CallMeBot refusal, tags the
+  startup message per boot, URL-encodes the phone number, and no longer
+  prints the API key. `callmebot.h` names CallMeBot's "APIKey is invalid"
+  reply (seen from the hardware rig) instead of calling it unrecognised.
+
+### Fixed
+
+- **A gateway's own request completed inside its HTTP handler.** A bridge or
+  shared gateway serving its own `sendToInternet()` delivered the result from
+  inside the gateway handler, while its `HTTPClient`, `WiFiClient` and response
+  buffers were still allocated; on an ESP8266 with ~11 KB free the
+  application's callback could not allocate what it built (hardware rig). The
+  local acknowledgment now completes from the scheduler, after the handler has
+  freed.
+- **`InternetResult::attempts` and `retryable` describe what was sent.**
+  `attempts` counts only a request that left the node, and a request that
+  never did -- refused for want of a mesh or a gateway, or whose every routing
+  attempt failed -- is reported safe to resend.
+
+- **`SentBuffer::requestLength(0)` answered 1, not 0.** `buffer_length - 1`
+  leaves room for the terminator `toCharArray()` always writes; on an
+  unsigned zero it wraps to `SIZE_MAX`, `min()` then picks the message, and
+  a caller with no room at all is told one byte is available -- which the
+  method's own contract forbids ("<= the requested length") and `read()`
+  acts on, writing `length + 1` bytes. Found because the randomised buffer
+  scenario draws its length from `runif(0, ...)`: it asked for zero about
+  once in sixty runs and failed CI on pull requests nowhere near the buffer.
+
+- **A node that lost its last connection waited 15 s before it scanned**
+  (#459). `connectToAP()` logs "scan rate set to fast" and sets a
+  `0.5 * SCAN_INTERVAL` period -- fifteen seconds, and the shortest of a set
+  of long ones; "slow" is four intervals. For a node that still has a live
+  connection that is soon enough. For one with none it is the whole cost of
+  the outage, and it is paid while its neighbours still route to it until
+  their own `NODE_TIMEOUT`, so unicasts addressed to it are accepted by the
+  sender and dropped. Caught on the hardware rig: an ESP32-C3 closed its only
+  uplink on a momentary nodeSync contradiction, logged the "fast" line 12 ms
+  later, and did not scan for exactly 15 000 ms -- 16.2 s out of the mesh,
+  answering an empty node list, while the scan that eventually ran found five
+  mesh APs at -30 to -58 dBm and associated 1.2 s later. A node with no live
+  connections now scans at once, once per outage (`layout::liveSubs()` is the
+  test, and a node that is simply alone falls back to the interval rather
+  than scanning back to back).
+
+## [2.0.3] - 2026-09-11
+
+`sendToInternet()` fixes from one user's WhatsApp integration (#450, #452,
+#453), and one the hardware rig found while validating them. **Upgrade if a
+node of yours is a bridge or relays to the Internet**: on 2.0.2 a bridge's own
+sends were refused for 30 s after boot, a service that answered a refusal with
+HTTP 201 was reported as delivered, a destination that does not resolve
+stalled an ESP32 gateway on every attempt, and a bridge that rebooted as a
+regular node swallowed every request its peers still sent it. Every fix was
+reproduced first -- against the new HTTP test point, which CI now runs, or
+over real TCP on the desktop -- and is covered by a row on the hardware farm.
+
+### Fixed
+
+- **A bridge's own `sendToInternet()` was refused for the first 30 s after
+  `initAsBridge()`** (#450). The Internet health check is armed one line after
+  `stationManual()` re-issues `WiFi.begin()`, so its first probe ran while the
+  station was still associating and failed, and the next was a full interval
+  away. Every send from the bridge in that window fell through to the mesh
+  path and was refused with "No active mesh connections" -- #445 again, with
+  a 30 s hole instead of forever. `sendToInternet()` and the retry path now
+  spend one on-demand probe per interval when the flag says no, and the
+  station's got-IP event re-probes at once on a bridge or shared gateway.
+- **A gateway reported a refusal as delivered, and every failure as a bare
+  number** (#450, #452). The gateway decided on the HTTP status alone and
+  discarded the response body. CallMeBot's WhatsApp API answers "Too many
+  requests" with HTTP 201 and HTTP 203, the same page under both, so a refused
+  message sent through a gateway on 2.0.2 could be reported as delivered; and
+  it answers HTTP 208 to messages it never delivers, which 2.0.2 reported as
+  "Ambiguous response" with nothing to say why. The gateway now reads the
+  start of the body (bounded to 512 bytes and 250 ms). Only 200, 201, 202 and
+  204 count as delivered, and not when the body says the service refused the
+  request; every other 2xx is a failure. Every failure reaches the origin
+  node's callback with a one-line, tag-free excerpt of the body -- for example
+  `HTTP 201: service refused the request: Oops! Too many requests...` or
+  `HTTP 208: not a delivery the gateway can confirm: ...` -- and is logged at
+  ERROR level, so a sketch on the default log levels sees what the service
+  said.
+- **A destination whose name does not resolve stalled an ESP32 gateway on
+  every attempt** (#453). A failed lookup surfaced as `connection refused`
+  after the resolver's own patience, which this library cannot bound on ESP32,
+  and every attempt -- the origin node's retries and, since the bridge fix
+  above, the bridge's own sends -- paid it again, until relayed requests timed
+  out on their origin nodes. An ESP32 gateway now resolves the host once,
+  reports `DNS lookup failed for <host>`, and refuses that host for 60 s
+  without another lookup. ESP8266 is unchanged: its core bounds the lookup by
+  the HTTP timeout. The gateway blocking budget is unchanged.
+- **A bridge that rebooted as a regular node swallowed every Internet request
+  routed to it.** Found on the hardware rig while validating this release. A
+  bridge that reboots, crashes, loses power or is reflashed announces nothing
+  -- only a bridge stepping down in-process sends `leaving` -- so its peers
+  kept it in their bridge list for the 60 s they trust a status, and could
+  prefer it over a live bridge on RSSI. A regular node had no handler for
+  gateway requests and dropped them without a reply; each sender waited out
+  its 30 s request timeout and reported "Request timed out". Every node now
+  answers a gateway request it cannot serve with
+  `Node <id> is not an Internet gateway`; the sender forgets that node as a
+  gateway and sends again at once through the next one, without spending a
+  retry. When it knows no other gateway, the request rides the ordinary retry
+  backoff -- on the rig the live bridge was advertised half a second later --
+  and fails with `No Internet gateway available: ...` only when none appears.
+- **Mismatched log format arguments in `routePackage()`** (CodeQL
+  `cpp/wrong-type-format-argument`). A message that failed to parse was logged
+  with its `size_t` lengths through `%d`/`%u` -- the wrong width on 64-bit
+  hosts -- and with its `DeserializationError` object passed through `%u`,
+  undefined behaviour on every platform, in the ArduinoJson 7 path every
+  current build compiles as well as the legacy one CodeQL flagged.
+
+### Changed
+
+- **The mock HTTP server is now the gateway test point.** It keeps a delivery
+  ledger (`GET /requests/{tag}`) and emulates CallMeBot's status quirks
+  (`GET /callmebot/whatsapp.php`, profile chosen by `apikey`). The desktop CI
+  job starts it and `PAINLESSMESH_TESTPOINT` points the suite at it, so the
+  library's delivery verdict is checked against what the service actually did,
+  not against a table of status codes. The Alteriom farm's gateway probe serves
+  the same routes.
+- **`Mesh::sendGatewayAck()` is public and portable.** It moved from the ESP
+  gateway code into `painlessmesh::Mesh`, because every node now needs it to
+  answer a request it cannot serve.
+- **`Log()` is format-checked in the desktop build.** The test build marks it
+  printf-like, so CI's `-Wall -Werror` rejects an argument that does not match
+  its specifier. Device builds are unchanged: on ESP-IDF 5 `uint32_t` is
+  `unsigned long`, and every `%u` of a node id would warn there.
+- **`sendToInternet` example.** The startup WhatsApp retries every 30 s until
+  a gateway with Internet is known instead of firing once before a regular
+  node has joined, and the cloud endpoint moved to a `CLOUD_URL` define whose
+  placeholder is skipped with a message rather than reported as
+  `connection refused`.
+
 ## [2.0.2] - 2026-09-08
 
 Two gateway defects that reached users on 2.0.1, both in code the desktop test

package/CONTRIBUTING.md

@@ -2,13 +2,55 @@
 
 ## Branches
 
-- `main` holds released code. A push to `main` that carries a version bump,
-  or whose head commit message starts with `release:`, is what tags and
-  publishes a release (see [RELEASE_GUIDE.md](RELEASE_GUIDE.md)).
-- `Feat/next-release` is the integration branch for the next version. Open
-  pull requests against it.
-- Work happens on short-lived feature branches (`fix/…`, `feat/…`, `docs/…`)
-  cut from `Feat/next-release`.
+| Branch | What it is | Lifetime |
+|---|---|---|
+| `main` | the released line. A push carrying a version-file change, or whose head commit starts with `release:`, tags and publishes (see [RELEASE_GUIDE.md](RELEASE_GUIDE.md)) | permanent |
+| `release/<major>.x` | one major line — `release/3.x` while 3.0 is being built, and the same branch afterwards for patches to 2.x once `main` has moved on | as long as that major is being built or supported |
+| `release/<version>` | preparing one release: the version files, the changelog date | short-lived |
+| `fix/…` `feat/…` `docs/…` `ci/…` `test/…` `refactor/…` `chore/…` | one change | short-lived |
+
+**Open pull requests against `main`** unless the change belongs to a major
+line that has its own branch, in which case open them against that. This is
+also what the repository does in practice: every fix since #448 was merged to
+`main`.
+
+`Feat/next-release` is retired. It was where v2 was built while `main` still
+carried v1, which is exactly the job `release/<major>.x` now names; it holds
+nothing `main` does not, and leaving it there sent contributors at a branch
+27 commits behind.
+
+### Naming
+
+- **`type/short-slug`**, lowercase, hyphens — never underscores or capitals.
+  The type is one of the [Conventional Commits](https://www.conventionalcommits.org/)
+  types this repository already uses in commit subjects, so a branch and the
+  commits on it agree about what they are.
+- **An issue number goes at the end** when there is one: `fix/rejoin-459`.
+  A slug that says only the area (`fix/critical-bugs`) tells a later reader
+  nothing about what was wrong.
+- **No `v` in a branch name.** Tags carry it (`v2.0.3`); branches do not
+  (`release/2.0.4`, `release/3.x`). 2.0.2 shipped from `release/2.0.2` and
+  2.0.3 from `release/v2.0.3` — pick the one without.
+- **Tool-generated prefixes** (`copilot/…`, `claude/…`, `dependabot/…`) are
+  left as the tool makes them. They are ordinary short-lived work branches
+  and are deleted on merge like any other.
+
+### Status
+
+A branch is deleted when its pull request merges — by whoever merges it, or
+by GitHub's automatic branch deletion. Anything still on the remote is
+either live work or something that was forgotten, and the two look identical
+from a branch list, so:
+
+```bash
+./scripts/branch-status.sh          # every remote branch: ahead, behind, age, unmerged work
+./scripts/branch-status.sh --stale  # only the ones with nothing of their own
+```
+
+`ahead` counts commits `main` does not have; `unmerged` counts those whose
+change is not in `main` under any commit, which is the number that matters
+after a squash merge. A branch with `unmerged=0` can be deleted without
+losing anything.
 
 Maintainers merge quickly, often as a squash. Push every commit you describe
 before you describe it, and cut follow-up work from the merged base rather
@@ -16,7 +58,8 @@ than from a stale branch.
 
 ## Submit a pull request
 
-- Point the pull request at `Feat/next-release`, not `main`.
+- Point the pull request at `main`, or at the major line's own branch when
+  the change belongs to one (see [Branches](#branches)).
 - Say what was wrong, how you know (a log, a test, a measurement), and what
   the change does about it. For anything that touches the radio, routing,
   the gateway or OTA, the evidence is a serial log or a run on the
@@ -55,6 +98,21 @@ and OTA behaviour is validated on the Alteriom hardware-in-the-loop farm; a
 maintainer runs it on a pull request by adding the `run-hil` label, and the
 release gate is three consecutive clean runs of the whole suite.
 
+### The HTTP test point
+
+`test/mock-http-server/server.py` is the controlled Internet destination for
+`sendToInternet()` tests at every level. It answers the way real services do,
+including the ways they get it wrong (its CallMeBot emulation returns refusals
+as HTTP 201 and 203, as the real API does), and it keeps a delivery ledger:
+`GET /requests/{tag}` says whether the service actually accepted a request.
+The desktop CI job starts one and exports `PAINLESSMESH_TESTPOINT`, and
+`catch_issue450_testpoint_semantics` makes real HTTP requests to it and
+requires the library's verdict to match the ledger. The farm's gateway probe
+serves the same routes with the same record shape, so a hardware row and a
+desktop scenario are measured against one source of truth. When a gateway bug
+comes in, add the service behaviour that exposed it to the server first, then
+the test that fails against it.
+
 ### Adding tests for new features
 
 1. **Unit tests**: add to `test/catch/` for new components.

package/README.md

@@ -596,9 +596,11 @@ These are the message types used by applications built on painlessMesh:
 - **Event Coordination** - Synchronized displays, distributed processing
 - **Bridge Networks** - Connect mesh to WiFi/Internet/MQTT - [📖 Bridge Guide](BRIDGE_TO_INTERNET.md)
 
-## Latest Release: v2.0.2 (September 8, 2026)
+## Latest Release: v2.0.3 (September 11, 2026)
 
-**Two gateway fixes — upgrade if any node of yours is a bridge.** On 2.0.1 a bridge could not reach the Internet through its own uplink at all (`initAsBridge()` never started the health checker that `sendToInternet()`'s local path depends on, so a bridge with no peer yet failed with "No active mesh connections"), and any request that failed *below* HTTP — refused, unresolvable, timed out — was reported to the origin node as `HTTP 65535`, a truncated `-1`, which also stopped it from being retried. Both are now asserted on the hardware rig, including a bridge with no mesh peer at all.
+**`sendToInternet()` fixes — upgrade if any node of yours is a bridge or relays to the Internet.** On 2.0.2 a bridge's own sends were refused with "No active mesh connections" for the first 30 s after `initAsBridge()`, because the health check's first probe ran while the station was still associating. The gateway also decided delivery on the HTTP status alone: CallMeBot answers a refusal with HTTP 201, so a message it refused could be reported as sent, and every failure reached the origin node as a bare number. The gateway now reads the start of the response body, counts only 200/201/202/204 without a refusing body as delivered, and hands every failure to your callback with the service's own words. A destination whose name does not resolve no longer stalls an ESP32 gateway on every attempt: it is refused for 60 s after one failed lookup. And a bridge that reboots, crashes or is reflashed as a regular node no longer swallows the requests its peers still send it for a minute: it answers that it is not a gateway, and the sender moves to the next one at once.
+
+**2.0.2 — two gateway fixes.** On 2.0.1 a bridge could not reach the Internet through its own uplink at all (`initAsBridge()` never started the health checker that `sendToInternet()`'s local path depends on, so a bridge with no peer yet failed with "No active mesh connections"), and any request that failed *below* HTTP — refused, unresolvable, timed out — was reported to the origin node as `HTTP 65535`, a truncated `-1`, which also stopped it from being retried. Both are now asserted on the hardware rig, including a bridge with no mesh peer at all.
 
 **2.0.1 — a packaging fix over 2.0.0, no library behaviour changed.** 2.0.0's installation instructions named a PlatformIO package that has no 2.0.0 (`alteriom/…` stops at 1.10.0; releases go out under `sparck75`), and its GitHub release carried no library archive because the upload was refused by an immutable release.
 

package/RELEASE_GUIDE.md

@@ -38,13 +38,23 @@ These files must always contain the same semantic version:
 - `library.properties`
 - `library.json`
 - `package.json`
+- `package-lock.json` (the root `version` and `packages[""].version`)
+- `src/AlteriomPainlessMesh.h` (the version string and the MAJOR/MINOR/PATCH
+  defines a sketch compiles against)
+- `doxygen/Doxyfile` (`PROJECT_NUMBER`, the number on every generated API page)
 
-Use the repository script to change them together:
+Use the repository script to change them together; it updates all six and then
+verifies they agree:
 
 ```bash
 ./scripts/bump-version.sh patch
+./scripts/bump-version.sh patch 2.0.3 --yes   # no prompt, for CI or an agent
 ```
 
+`jq` is used when it is installed and awk otherwise, and both paths change only
+the package's own version — never a dependency range. `test/ci/test_bump_version.sh`
+holds that, and the Code Quality job runs it.
+
 You may use `minor`, `major`, or an explicit version when the release plan
 requires it. Version 2.0 patch releases must remain wire-compatible with the
 2.0 protocol.

package/examples/sendToInternet/README.md

@@ -64,6 +64,55 @@ if (mesh.hasInternetConnection()) {
 }
 ```
 
+### Reading the reply: the whole result
+
+`success` means HTTP 200, 201, 202 or 204 -- what HTTP calls a success. It
+does not mean the service did what you wanted: CallMeBot, for one, answers
+"Too many requests" under HTTP 201. Pass a callback that takes an
+`InternetResult` to get the start of the response body as well, and decide
+in your sketch:
+
+```cpp
+#include "callmebot.h"  // from this example
+
+mesh.sendToInternet(url, "", [](const painlessmesh::InternetResult& result) {
+  // result.messageId, result.success, result.httpStatus, result.error,
+  // result.response (the body, as one line), result.retryable, result.attempts
+  const auto reply = callmebot::judge(result.httpStatus, result.response);
+  if (reply.accepted) {
+    Serial.println("CallMeBot queued the message");
+  } else {
+    Serial.printf("Not sent: %s -- CallMeBot said: %s\n", reply.meaning,
+                  result.response.c_str());
+  }
+});
+```
+
+`callmebot.h` is part of the example, not the library: it knows CallMeBot's
+wording ("Message queued", "Too many requests", "Your Account is Paused",
+"APIKey is invalid")
+and that its HTTP 208 has not meant a delivery. The desktop test suite checks
+it against the CallMeBot-shaped test point in `test/mock-http-server/`.
+
+### Retries and duplicates
+
+The library issues each request **once**, and retries only when a retry
+cannot deliver it twice:
+
+| What happened | Retried? |
+|---|---|
+| Connection refused, or a send failure before the request went out | yes |
+| Gateway without Internet, a host that does not resolve | no -- a retry within seconds fails the same way |
+| HTTP 429 or 503 (the server did not take it) | yes, not before `Retry-After` |
+| Read timeout, connection lost after sending | **no** -- the server may have it |
+| Any other status, including every 2xx and 500 | no |
+
+A request that was not retried reports `retryable == false`; a transport error
+says "(the request may have reached the server; not retried)". Resending is
+then your call, knowing it may arrive twice. Every attempt at one call carries
+the same `X-Request-Id` and `Idempotency-Key` header, so a service that honours
+idempotency keys drops the copy, and a log can tell a retry from a second send.
+
 ### Sending JSON to REST API
 
 ```cpp
@@ -143,7 +192,8 @@ mesh.sendToInternet("https://api.callmebot.com/...", "", callback);
 
 1. Verify your Callmebot API key is correct
 2. Ensure phone number includes country code (e.g., `+1234567890`)
-3. Check HTTP status code in callback (200 = success)
+3. Print `result.response` in the callback: CallMeBot says why in the body,
+   and HTTP 200/201 alone does not mean it sent anything
 4. URL-encode special characters in the message
 
 ### Gateway shows "no internet access" but WiFi is connected
@@ -187,10 +237,12 @@ The callback provides `httpStatus` to indicate the result:
 
 **FAILURE (success = false):**
 - `203 Non-Authoritative Information` - **Cached/proxied response, NOT actual delivery**
-- `4xx` - Client error (bad request, unauthorized, not found, etc.)
-- `5xx` - Server error (service unavailable, gateway timeout, etc.)
 
-⚠️ **Important:** HTTP 203 is treated as **FAILURE** because it indicates the response came from a cache or proxy, not from the actual WhatsApp API server. If you see `HTTP Status: 203`, the message was **NOT delivered**.
+⚠️ **The status alone does not say whether WhatsApp got the message.** CallMeBot answers a refusal (for example "Too many requests") with HTTP 201 or HTTP 203, the same error page under both, and it has answered HTTP 208 to messages that never arrived (issues #450 and #452). The library reports HTTP's meaning -- 201 is a success, 203 and 208 are not -- and hands your callback the start of the body in `result.response`. The sketch's `callmebot::judge()` reads that body: `✅ WhatsApp message queued by CallMeBot` only when CallMeBot said "Message queued", and otherwise `❌ WhatsApp message not sent` followed by what CallMeBot said.
+
+**The sketch paces its alerts.** CallMeBot is free and rate-limited. The sketch sends one WhatsApp when O2 falls below the threshold, not one per reading, never more than one every 10 minutes per node, and waits 15 minutes after "Too many requests" or a paused account. Several nodes with the same API key share CallMeBot's limit; raise `ALERT_MIN_INTERVAL_MS` accordingly.
+
+Also replace `CLOUD_URL` at the top of the sketch: the placeholder `api.example.com` does not resolve, and until you change it the sketch skips the cloud send and says so instead of reporting `connection refused` every minute.
 
 ## Files
 

package/examples/sendToInternet/callmebot.h

@@ -0,0 +1,139 @@
+//************************************************************
+// callmebot.h - what a CallMeBot WhatsApp reply means
+//
+// painlessMesh reports what HTTP says: the status, whether a retry could
+// deliver the request twice, and the start of the response body. Whether
+// WhatsApp will actually show the message is CallMeBot's business, and
+// CallMeBot does not put it in the status code:
+//
+//   * a rate-limit refusal comes back as HTTP 201 or HTTP 203 with an
+//     "Oops! Too many requests" page (probed 2026-09-10, painlessMesh #450);
+//   * HTTP 208 came back four times for messages that never arrived (#452);
+//   * a paused account answers with the request echoed back and, at the end,
+//     "Your Account is Paused ... send the word 'resume'" (#463);
+//   * an API key CallMeBot does not know answers HTTP 203 with the request
+//     echoed back and "APIKey is invalid. Please create a new one ..."
+//     (observed from the hardware rig, 2026-09-15);
+//   * a message CallMeBot accepted answers "Message queued".
+//
+// So the sketch reads the reply with judge() below. It is plain C++ over the
+// status and the body text, with no Arduino or network calls, so the desktop
+// test suite checks it (test/catch/catch_callmebot_example.cpp) against the
+// same CallMeBot-shaped test point the hardware farm uses.
+//
+// The phrases are CallMeBot's, observed or documented at the dates above. If
+// CallMeBot changes its wording, a reply lands in Verdict::Unrecognized and
+// the sketch prints what the service said -- it never guesses "sent".
+//************************************************************
+#ifndef SENDTOINTERNET_CALLMEBOT_H
+#define SENDTOINTERNET_CALLMEBOT_H
+
+#include "painlessmesh/gateway.hpp"
+
+namespace callmebot {
+
+enum class Verdict {
+  /** CallMeBot accepted the message ("Message queued"). */
+  Queued,
+  /** "Too many requests": nothing was sent; wait before the next message. */
+  RateLimited,
+  /** The account is paused: send "resume" to the bot; resending won't help. */
+  AccountPaused,
+  /** The API key is not one CallMeBot knows: get a new one; resending won't help. */
+  InvalidApiKey,
+  /** HTTP 208: in the field this never meant a delivery, whatever the body. */
+  NotDelivered,
+  /** No HTTP reply at all; the library's error says why. */
+  NoReply,
+  /** A reply this file does not know. Treated as not sent. */
+  Unrecognized
+};
+
+struct Judgement {
+  Verdict verdict;
+  /** True only for Verdict::Queued. */
+  bool accepted;
+  /**
+   * Minimum wait before the sketch sends CallMeBot anything else, in ms.
+   * Non-zero after a refusal, so a sketch does not turn one refusal into a
+   * stream of them.
+   */
+  uint32_t holdOffMs;
+  /** One line for the serial log. */
+  const char* meaning;
+};
+
+/** How long to leave CallMeBot alone after it said "Too many requests". */
+static const uint32_t RATE_LIMIT_HOLD_OFF_MS = 15UL * 60UL * 1000UL;
+
+inline bool isHttpSuccess(uint16_t status) {
+  return status == 200 || status == 201 || status == 202 || status == 204;
+}
+
+/**
+ * Read a CallMeBot reply.
+ *
+ * @param httpStatus InternetResult::httpStatus (0 when no reply arrived)
+ * @param response   InternetResult::response, the start of the body
+ */
+inline Judgement judge(uint16_t httpStatus, const TSTRING& response) {
+  using painlessmesh::gateway::responseContains;
+
+  if (httpStatus == 0) {
+    return {Verdict::NoReply, false, 0,
+            "no reply from CallMeBot; it may or may not have received the request"};
+  }
+  // Refusals first: they arrive under success statuses too.
+  if (responseContains(response, "Too many requests")) {
+    return {Verdict::RateLimited, false, RATE_LIMIT_HOLD_OFF_MS,
+            "CallMeBot refused: too many requests"};
+  }
+  if (responseContains(response, "Account is Paused") ||
+      responseContains(response, "send the word 'resume'")) {
+    return {Verdict::AccountPaused, false, RATE_LIMIT_HOLD_OFF_MS,
+            "CallMeBot account paused: send 'resume' to the CallMeBot bot on WhatsApp"};
+  }
+  if (responseContains(response, "APIKey is invalid")) {
+    // Nothing a retry changes: hold off like a refusal, so a sketch with a
+    // wrong key does not call the API once a minute until someone notices.
+    return {Verdict::InvalidApiKey, false, RATE_LIMIT_HOLD_OFF_MS,
+            "CallMeBot rejected the API key: get a new one from CallMeBot and set WHATSAPP_APIKEY"};
+  }
+  // Before the success text: a 208 carrying "Message queued" still did not
+  // arrive in the field.
+  if (httpStatus == 208) {
+    return {Verdict::NotDelivered, false, 0,
+            "CallMeBot answered HTTP 208; such messages have not arrived"};
+  }
+  if (isHttpSuccess(httpStatus) && responseContains(response, "Message queued")) {
+    return {Verdict::Queued, true, 0, "CallMeBot queued the message"};
+  }
+  return {Verdict::Unrecognized, false, 0,
+          "CallMeBot's reply is not one this sketch recognises; not counted as sent"};
+}
+
+/**
+ * The URL with the API key replaced, for printing. A serial log gets pasted
+ * into issues; the key should not go with it.
+ */
+inline TSTRING redactApiKey(const TSTRING& url) {
+#if defined(PAINLESSMESH_BOOST)
+  const auto start = url.find("apikey=");
+  if (start == TSTRING::npos) return url;
+  const auto valueStart = start + 7;
+  auto end = url.find('&', valueStart);
+  if (end == TSTRING::npos) end = url.length();
+  return url.substr(0, valueStart) + "***" + url.substr(end);
+#else
+  const int start = url.indexOf("apikey=");
+  if (start < 0) return url;
+  const int valueStart = start + 7;
+  int end = url.indexOf('&', valueStart);
+  if (end < 0) end = url.length();
+  return url.substring(0, valueStart) + "***" + url.substring(end);
+#endif
+}
+
+}  // namespace callmebot
+
+#endif  // SENDTOINTERNET_CALLMEBOT_H