Merge main into ota-admin: tools split, WITH_RX_POWERSAVING

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
tthandClaude Opus 5.5 committed 2026-11-13 16:12:20 +01:00
commit 81d7f600d8
53 files changed
+7121 -64

No files matched your search

@@ -12,10 +12,29 @@ runs:
key: ${{ runner.os }}-pio
- name: Install Python
id: python
continue-on-error: true
uses: actions/setup-python@v6
with:
python-version: '3.13'
# CUSTOM (TeTeHacko): setup-python's build for the runner OS can need a
# newer CPU than the runner host has ("CPU ISA level is lower than
# required"); fall back to the image's own python3 in a venv
- name: Python fallback
if: steps.python.outcome == 'failure'
shell: bash
run: |
set -euo pipefail
venv="$RUNNER_TEMP/pyenv"
if ! python3 -m venv "$venv"; then
apt-get update -qq
apt-get install -y -qq python3 python3-venv
python3 -m venv --clear "$venv"
fi
echo "$venv/bin" >>"$GITHUB_PATH"
"$venv/bin/python" --version
- name: Install PlatformIO
shell: bash
run: |
+5 -2
View File
@@ -5,12 +5,15 @@
# PLATFORMIO_BUILD_FLAGS after each env's flags: last -D wins.
#
# 869.432/62.5/SF7/CR5; repeater + room server: zero-hop advert off, flood
# advert 25 h, af 9 (= 10 % duty cycle); repeater: regions cz,cs next to *.
# advert 25 h, AIRTIME_FACTOR 9 (= `dutycycle` 10 %); repeater: regions cz,cs next to *.
# Path hash 2 B is this fork's default anyway. TX power stays the board's.
# FILTER_CHANNEL_PSKS = [channel_filter] in platformio.ini (#meshcore, Public,
# #test -- public keys): compiles the repeater's `filter` (deny-forward by
# sender name); inert until an operator adds a name.
PUB_FLAGS='-D LORA_FREQ=869.432 -D LORA_BW=62.5 -D LORA_SF=7 -D LORA_CR=5
# WITH_RX_POWERSAVING compiles `set radio.rxps` (SX1262 RX duty cycle); off
# until an operator sets it.
PUB_FLAGS='-D WITH_RX_POWERSAVING
-D LORA_FREQ=869.432 -D LORA_BW=62.5 -D LORA_SF=7 -D LORA_CR=5
-D ADVERT_INTERVAL_DEFAULT=0 -D FLOOD_ADVERT_INTERVAL_DEFAULT=25
-D AIRTIME_FACTOR_DEFAULT=9.0 -D DEFAULT_REGIONS=\"cz,cs\"
-D FILTER_CHANNEL_PSKS=\"2fa78a5aef618e7c2a78f0ab5c8869b3,8b3387e9c5cdea6ac9e5edbaa115cd72,9cd8fcf22a47333b591d96a2b848b73f\"'
+155 -37
View File
@@ -11,8 +11,13 @@
#
# Runs on every push to main -- the export pushes there only after an
# upstream merge (private repo, tth-upstream-sync) -- and by hand.
# Release tag tth-<sha8>, titled with the stamped version (v1.18.0-tth<sha>);
# the newest KEEP releases stay, older ones are deleted.
# Release tag v1.18.0+tth.<commit date>[.n] (the n-th release of that day),
# titled "v1.18.0+tth · 12. 11. 2026"; assets carry the tag in their names, the
# body the version the node reports (`ver`: v1.18.0-tth<sha>). Until 12. 11.
# 2026 the tags were tth-<sha8>; pruning and the changelog know both;
# the newest KEEP releases stay, older ones are deleted. The body is a
# changelog since the previous release: our own commits, then the upstream
# PRs the upstream merges brought in.
# nRF52: .uf2 (drag onto the bootloader drive) and .zip (DFU over BLE or
# serial); ESP32: -merged.bin (fresh install at 0x0) and .bin (update).
name: pub-release
@@ -62,39 +67,58 @@ jobs:
- name: Commit and tag
id: src
env:
TOKEN: ${{ secrets.GITEA_TOKEN || github.token }}
REPLACE: ${{ github.event.inputs.replace }}
run: |
set -euo pipefail
git fetch -q --tags
sha=$(git rev-parse HEAD)
echo "sha=$sha" >>"$GITHUB_OUTPUT"
echo "tag=tth-${sha:0:8}" >>"$GITHUB_OUTPUT"
git describe --tags --abbrev=0 --match '*v[0-9]*' HEAD
- name: Release exists?
env:
TOKEN: ${{ secrets.GITEA_TOKEN || github.token }}
TAG: ${{ steps.src.outputs.tag }}
REPLACE: ${{ github.event.inputs.replace }}
run: |
set -euo pipefail
# upstream base as tools/build_version.py finds it: "companion-v1.18.0" -> v1.18.0
desc=$(git describe --tags --abbrev=0 --match '*v[0-9]*' --exclude '*+tth*' --exclude 'backup/*' HEAD)
[[ $desc =~ v[0-9].* ]] && base=${BASH_REMATCH[0]} || base=$desc
# the COMMIT's date (Prague), so a rebuild of the same commit keeps its tag
day=$(TZ=Europe/Prague git show -s --format=%cd --date=format-local:%Y%m%d HEAD)
human=$(TZ=Europe/Prague git show -s --format=%cd --date=format-local:'%-d. %-m. %Y' HEAD)
api="$GITEA/api/v1/repos/$GITHUB_REPOSITORY"
auth="header = \"Authorization: token $TOKEN\""
id=$(curl -sS --config - "$api/releases/tags/$TAG" <<<"$auth" | jq -r '.id // empty')
if [ -n "$id" ]; then
if [ "$REPLACE" != "true" ]; then
echo "::error::release $TAG already exists (id $id); set replace=true to rebuild it"
exit 1
enc() { jq -rn --arg s "$1" '$s|@uri'; }
# v1.18.0+tth.20261112, a second release of the day .2, ...
n=1
while :; do
tag="$base+tth.$day"
[ "$n" -eq 1 ] || tag="$tag.$n"
rel=$(curl -sS --config - "$api/releases/tags/$(enc "$tag")" <<<"$auth")
id=$(jq -r '.id // empty' <<<"$rel")
[ -n "$id" ] || break
if [ "$(jq -r .target_commitish <<<"$rel")" = "$sha" ]; then
if [ "$REPLACE" != "true" ]; then
echo "::error::release $tag already exists (id $id); set replace=true to rebuild it"
exit 1
fi
curl -sSf --config - -X DELETE "$api/releases/$id" <<<"$auth"
curl -sSf --config - -X DELETE "$api/tags/$(enc "$tag")" <<<"$auth" || true
echo "removed old $tag"
break
fi
curl -sSf --config - -X DELETE "$api/releases/$id" <<<"$auth"
curl -sSf --config - -X DELETE "$api/tags/$TAG" <<<"$auth" || true
echo "removed old $TAG"
fi
n=$((n + 1))
done
title="$base+tth · $human"
[ "$n" -eq 1 ] || title="$title ($n)"
echo "release $tag: $title (commit $sha)"
{
echo "sha=$sha"
echo "tag=$tag"
echo "title=$title"
} >>"$GITHUB_OUTPUT"
- name: Setup Build Environment
uses: ./.github/actions/setup-build-environment
- name: Build and package
id: build
env:
TAG: ${{ steps.src.outputs.tag }}
run: |
set -euo pipefail
source .github/fw-flags.sh
@@ -111,15 +135,15 @@ jobs:
b=".pio/build/$env"
if [ -f "$b/firmware.zip" ]; then # nRF52
python3 bin/uf2conv/uf2conv.py "$b/firmware.hex" -c -o "$b/firmware.uf2" -f 0xADA52840
cp "$b/firmware.uf2" "$dist/$env$suffix-$sha.uf2"
cp "$b/firmware.zip" "$dist/$env$suffix-$sha.zip"
cp "$b/firmware.uf2" "$dist/$env$suffix-$TAG.uf2"
cp "$b/firmware.zip" "$dist/$env$suffix-$TAG.zip"
v=$(grep -m1 -aoE 'v[0-9]+\.[0-9]+\.[0-9]+-tth[0-9a-f]+\+?' "$b/firmware.elf" || true)
case "$v" in *+) echo "::error::$env is dirty ($v)"; exit 1 ;; esac
[ -n "$version" ] || version="$v"
else # ESP32
PLATFORMIO_BUILD_FLAGS="$PUB_FLAGS $2" pio run -t mergebin -e "$env"
cp "$b/firmware.bin" "$dist/$env$suffix-$sha.bin"
cp "$b/firmware-merged.bin" "$dist/$env$suffix-$sha-merged.bin"
cp "$b/firmware.bin" "$dist/$env$suffix-$TAG.bin"
cp "$b/firmware-merged.bin" "$dist/$env$suffix-$TAG-merged.bin"
fi
echo "::endgroup::"
}
@@ -135,34 +159,128 @@ jobs:
TOKEN: ${{ secrets.GITEA_TOKEN || github.token }}
SHA: ${{ steps.src.outputs.sha }}
TAG: ${{ steps.src.outputs.tag }}
TITLE: ${{ steps.src.outputs.title }}
VERSION: ${{ steps.build.outputs.version }}
run: |
set -euo pipefail
api="$GITEA/api/v1/repos/$GITHUB_REPOSITORY"
auth="header = \"Authorization: token $TOKEN\""
note='BLE PIN 123456 and admin password "password" are placeholders: change them after flashing.
*-observer: repeater with a BLE console (OFF after flashing: set a PIN, then send ble on) and the
rxlog / pktlog rings for the repeater observer.
Czech mesh defaults (meshcore.cz): 869.432 MHz / 62.5 kHz / SF7 / CR5; repeater: zero-hop advert off,
flood advert 25 h, af 9 (10 % duty cycle), regions cz + cs. Apply to a fresh or erased node only.'
body=$(printf '%s\n\ncommit %s, run %s\n\n%s\nWhat this fork changes against upstream: see README.md.\n' \
"$VERSION" "$SHA" "$GITHUB_RUN_NUMBER" "$note")
jq -n --arg t "$TAG" --arg c "$SHA" --arg n "$VERSION" --arg b "$body" \
readme="$GITEA/$GITHUB_REPOSITORY#o-tomto-forku-meshcore-tth"
note=$(cat <<EOF
- **BLE PIN \`123456\` a admin heslo \`password\` jsou zástupné.** Po nahrání je změň: \`password <nové>\` (nejvýš 15
znaků), \`ble pin <6 číslic>\`.
- **Výchozí nastavení pro český mesh** ([meshcore.cz](https://meshcore.cz/)): 869,432 MHz / 62,5 kHz / SF7 / CR5;
repeater a room server: zero-hop advert vypnutý, flood advert á 25 h, duty cycle 10 % (\`get dutycycle\`); repeater:
regiony \`cz\` a \`cs\`. **Platí jen pro nový nebo smazaný uzel** – nové nahrání ponechá uložené nastavení.
- **\`*-observer\`**: repeater s BLE konzolí a buffery \`rxlog\` / \`pktlog\` pro repeater observer. BLE je po nahrání
vypnuté: nejdřív \`ble pin\`, pak \`ble on\`.
- **RX duty cycle** (\`set radio.rxps\`, jen SX1262) je zabudovaný a vypnutý.
- Ověření: \`ver\` ukáže verzi z řádku *Verze v uzlu* výše. Co fork mění proti upstreamu: [README]($readme).
<details><summary>English</summary>
- **BLE PIN \`123456\` and admin password \`password\` are placeholders.** Change them after flashing: \`password
<new>\` (15 characters at most), \`ble pin <6 digits>\`.
- **Czech mesh defaults** ([meshcore.cz](https://meshcore.cz/)): 869.432 MHz / 62.5 kHz / SF7 / CR5; repeater and room
server: zero-hop advert off, flood advert every 25 h, 10 % duty cycle (\`get dutycycle\`); repeater: regions \`cz\`
and \`cs\`. **A fresh or erased node only** – a reflash keeps the saved settings.
- **\`*-observer\`**: repeater with a BLE console and the \`rxlog\` / \`pktlog\` rings for the repeater observer. BLE
is off after flashing: \`ble pin\` first, then \`ble on\`.
- **RX duty cycle** (\`set radio.rxps\`, SX1262 only) is built in and off.
- Check: \`ver\` shows the version from the *Verze v uzlu* (node version) line above. What the fork changes against
upstream: [README]($readme).
</details>
EOF
)
web="$GITEA/$GITHUB_REPOSITORY"
gh=https://github.com/meshcore-dev/MeshCore
max=60
# changelog against the newest older release that HEAD descends from
prev="" base=""
while read -r t c; do
if [ "$c" != "$SHA" ] && git merge-base --is-ancestor "$c" "$SHA" 2>/dev/null; then
prev=$t base=$c
break
fi
done < <(curl -sSf --config - "$api/releases?limit=50" <<<"$auth" |
jq -r --arg t "$TAG" 'map(select(.tag_name | startswith("tth-") or test("[+]tth[.]")) | select(.tag_name != $t))
| sort_by(.created_at) | reverse | .[] | "\(.tag_name) \(.target_commitish)"')
# no older release: the last 20 commits of our own line
[ -n "$base" ] || base=$(git rev-list --first-parent --max-count=21 "$SHA" | tail -1)
# ours: commits on our main itself (first parent); a merge of one of
# our own branches (feat/...) is unfolded into the branch's commits,
# an upstream merge is left to the upstream list below
fmt="- %s ([%h]($web/commit/%H))"
ours=""
for c in $(git log --first-parent --format=%H "$base..$SHA"); do
if git rev-parse -q --verify "$c^2" >/dev/null; then
git log -1 --format=%s "$c" | grep -q '^Merge upstream' && continue
ours+=$(git log --no-merges --format="$fmt" "$c^1..$c^2")$'\n'
else
ours+=$(git log -1 --format="$fmt" "$c")$'\n'
fi
done
ours=${ours%$'\n'}
# upstream: the first-parent line of each merged upstream branch,
# PR merges as their title, direct commits as their subject
declare -A seen=()
ups=()
for m in $(git log --first-parent --merges --grep='^Merge upstream' --format=%H "$base..$SHA"); do
for c in $(git log --first-parent --format=%H "$m^1..$m^2"); do
s=$(git log -1 --format=%s "$c")
if [[ $s =~ ^Merge\ pull\ request\ \#([0-9]+)\ from\ ([^/]+)/(.*)$ ]]; then
pr=${BASH_REMATCH[1]}
[ -z "${seen[$pr]:-}" ] || continue
seen[$pr]=1
t=$(git log -1 --format=%b "$c" | sed -n '/./{p;q}')
ups+=("- ${t:-${BASH_REMATCH[3]}} ([#$pr]($gh/pull/$pr), ${BASH_REMATCH[2]})")
elif [[ $s != Merge* ]]; then
[ -z "${seen[$c]:-}" ] || continue
seen[$c]=1
ups+=("- $s ([${c:0:7}]($gh/commit/$c))")
fi
done
done
n=${#ups[@]}
body=$(
echo "$TITLE"
echo
echo "Verze v uzlu · \`ver\`: $VERSION"
echo
if [ -n "$prev" ]; then
echo "Od předchozího vydání · since [$prev]($web/releases/tag/$(jq -rn --arg s "$prev" '$s|@uri'))"
echo
fi
echo "### Změny forku · fork changes"
echo "${ours:-- žádné · none}"
echo
echo "### Z upstreamu MeshCore · from upstream ($n)"
[ "$n" -gt 0 ] && printf '%s\n' "${ups[@]:0:$max}" || echo "- žádné · none"
[ "$n" -le "$max" ] || echo "- … a dalších $((n - max)) · and $((n - max)) more"
echo
echo "### Po flashi · after flashing"
echo
echo "$note"
echo
echo "commit $SHA, run $GITHUB_RUN_NUMBER"
)
jq -n --arg t "$TAG" --arg c "$SHA" --arg n "$TITLE" --arg b "$body" \
'{tag_name: $t, target_commitish: $c, name: $n, body: $b}' >"$RUNNER_TEMP/rel.json"
id=$(curl -sSf --config - -X POST -H 'Content-Type: application/json' \
--data-binary "@$RUNNER_TEMP/rel.json" "$api/releases" <<<"$auth" | jq -r .id)
for f in dist/*; do
curl -sSf --config - -X POST -F "attachment=@$f" \
"$api/releases/$id/assets?name=$(basename "$f")" <<<"$auth" >/dev/null
"$api/releases/$id/assets?name=$(jq -rn --arg s "${f##*/}" '$s|@uri')" <<<"$auth" >/dev/null
echo "uploaded $(basename "$f")"
done
echo "released $TAG = $VERSION (id $id)"
# keep the newest $KEEP, oldest go (with their tags)
curl -sSf --config - "$api/releases?limit=50" <<<"$auth" |
jq -r --argjson k "$KEEP" 'map(select(.tag_name | startswith("tth-")))
jq -r --argjson k "$KEEP" 'map(select(.tag_name | startswith("tth-") or test("[+]tth[.]")))
| sort_by(.created_at) | reverse | .[$k:][] | "\(.id) \(.tag_name)"' |
while read -r old_id old_tag; do
curl -sSf --config - -X DELETE "$api/releases/$old_id" <<<"$auth"
curl -sSf --config - -X DELETE "$api/tags/$old_tag" <<<"$auth" || true
curl -sSf --config - -X DELETE "$api/tags/$(jq -rn --arg s "$old_tag" '$s|@uri')" <<<"$auth" || true
echo "pruned $old_tag"
done
+1 -1
View File
@@ -29,5 +29,5 @@ __pycache__/
# PID soubor lokálního helperu (běhový balast, ne konfigurace)
ether.pid
# data z pochůzkových testů (tools/walk.sh fetch) — polohy, necommitovat
# data z pochůzkových testů (.tth/tools/walk.sh fetch) — polohy, necommitovat
walk-data/
+55 -12
View File
@@ -76,11 +76,27 @@ označený `CUSTOM (TeTeHacko)`. Nic z toho nemění protokol na rádiu.
a záznam o hardfaultu přežijí teplý reset (`.noinit`); `clkreboot`.
* Na solárních uzlech žádná blikající LED a pomalejší BLE advertising; stav
baterie jako ikona na konci advertovaného jména (volitelné).
* Volitelný RX duty cycle (`set radio.rxps`, port PowerSaving z EasySkyMesh):
SX1262 mezi krátkými okny poslechu spí. Ve veřejných buildech je zabudovaný
a **vypnutý**; `max` na lavici ušetřil ~2,3 mA bez ztráty paketů
([docs/power.md](docs/power.md)). Jen SX1262, ne LR1110 (T1000-E).
* Podpěťová pojistka při startu (`PWRMGT_VOLTAGE_BOOTLOCK`) je na nRF52
**vypnutá**, stejně jako v upstreamu od v1.18.0
([#2377](https://github.com/meshcore-dev/MeshCore/pull/2377)): pevný práh
3,3 V nepouštěl k životu uzly na LiFePO4 nebo LTO. Firmware tak naběhne na
jakékoli chemii článku; před hlubokým vybitím má chránit BMS nebo ochranná
destička článku. Konfigurovatelná pojistka podle chemie čeká na upstream
([#2088](https://github.com/meshcore-dev/MeshCore/pull/2088)).
### Senzory a companiony
* `simple_sensor`: telemetrie z externí stanice po UART
(`BudkaLinkSensorManager`, jeden LPP kanál na veličinu), `sensor read`.
* Senzory, které jinak měří nepřetržitě (INA219, INA226, INA260, INA3221,
BMP280), mezi čteními telemetrie spí a měří jen na vyžádání (nápad a první
patch pro INA219: Alkel Brostl). Čipy INA se rozlišují podle ID, takže
INA226 už se nedetekuje jako INA219. Odpor bočníku se nastavuje za běhu
a ukládá se: `sensor set ina.shunt <mΩ>`.
* Companion: `gps duty` přežije reboot, export klíče a PIN jsou na
neověřeném USB spojení zamčené, kopie data sestavení má hlídanou délku.
KISS modem: oprava o jedna vedle při zkracování jména.
@@ -93,7 +109,7 @@ uzel nepotřebuje obvyklé kolečko nastavování:
* rádio 869,432 MHz / 62,5 kHz / SF7 / CR5 (všechny buildy);
* repeater a room server: zero-hop advert vypnutý, flood advert každých 25 h,
`af 9` (10% duty cycle);
duty cycle 10 % (`get dutycycle` → `10.0%`; zastaralé `af` je 9);
* repeater: regiony `cz` a `cs` vedle `*` – vlastní `cz-<kraj>` přidáš přes
`region put cz-xxx cz` + `region save`;
* 2bajtové path hashe (výchozí v tomto forku);
@@ -120,10 +136,14 @@ Releasy do `tth-654d53f3` `ble pin` nemají: BLE tam nech vypnuté a používej
### Nahrání releasu
Soubory jsou v [Releases](https://git.rfa.cz/tth-pub/meshcore-tth/releases),
jedna sada pro každou desku a roli (`<deska>_<role>-<sha>`): `.zip` a `.uf2`
pro nRF52, `.bin` pro ESP32 (`-merged.bin` je celý obraz pro prázdnou desku,
obyčejný `.bin` aktualizace). Kontrolní součty jsou v `SHA256SUMS`.
Soubory jsou v [Releases](https://git.rfa.cz/tth-pub/meshcore-tth/releases).
Release se jmenuje podle upstreamové verze a data, např.
`v1.18.0+tth.20261112` (druhý téhož dne `.2`), a v popisu má změny od
předchozího releasu. Pro každou desku a roli je jedna sada
(`<deska>_<role>-<release>`, např. `Xiao_nrf52_repeater-v1.18.0+tth.20261112.zip`):
`.zip` a `.uf2` pro nRF52, `.bin` pro ESP32 (`-merged.bin` je celý obraz pro
prázdnou desku, obyčejný `.bin` aktualizace). Kontrolní součty jsou
v `SHA256SUMS`. Releasy do 12. 11. 2026 se jmenovaly `tth-<sha>`.
**nRF52 (XIAO, RAK4631, SenseCAP Solar, T1000-E, T114) přes
[webový flasher MeshCore](https://flasher.meshcore.io)** – Chrome, Edge nebo
@@ -136,7 +156,8 @@ Chromium na počítači (Web Serial; ne Firefox ani Safari):
4. Klikni na **Flash!** a vyber ten nový port. Zhruba 30 s, pak se deska
restartuje do nového firmwaru.
5. **Console** ve flasheru (nebo jakýkoli sériový terminál, 115200) ověří
výsledek: `ver` ukáže `v1.xx.x-tth<sha>`, sha odpovídá názvu souboru.
výsledek: `ver` ukáže `v1.xx.x-tth<sha>`, stejně jako řádek „Verze v uzlu“
v popisu releasu.
**Neklikej na Erase Flash**, pokud nechceš nový uzel: smaže identitu (klíč
uzlu a všechno, co ho zná) i veškeré nastavení. Obyčejné nahrání je zachová.
@@ -237,11 +258,28 @@ twice a day; everything below is on top of that. Our code is marked
hardfault record survive a warm reset (`.noinit`); `clkreboot`.
* No blinking LED and slower BLE advertising on solar nodes; battery level as
an icon at the end of the advertised name (opt-in).
* Optional RX duty cycle (`set radio.rxps`, ported from EasySkyMesh
PowerSaving): the SX1262 sleeps between short listening windows. Built into
the public releases and **off**; `max` saved ~2.3 mA on the bench with no
packet loss ([docs/power.md](docs/power.md)). SX1262 only, not the LR1110
(T1000-E).
* The nRF52 boot undervoltage lock (`PWRMGT_VOLTAGE_BOOTLOCK`) is **off**,
as in upstream since v1.18.0
([#2377](https://github.com/meshcore-dev/MeshCore/pull/2377)): its fixed
3.3 V threshold kept LiFePO4 and LTO nodes from booting. The firmware boots
on any cell chemistry; deep-discharge protection is up to the BMS or the
cell's protection board. A configurable, chemistry-aware lock is waiting
for upstream ([#2088](https://github.com/meshcore-dev/MeshCore/pull/2088)).
### Sensors and companions
* `simple_sensor`: telemetry from an external station over UART
(`BudkaLinkSensorManager`, one LPP channel per meter), `sensor read`.
* Sensors that would otherwise convert continuously (INA219, INA226, INA260,
INA3221, BMP280) sleep between telemetry reads and measure on demand (idea
and first INA219 patch: Alkel Brostl). INA chips are told apart by their ID,
so an INA226 is no longer taken for an INA219. The shunt is set at runtime
and saved: `sensor set ina.shunt <mOhm>`.
* Companion: `gps duty` persists, key export / PIN gated on an unauthenticated
USB link, bounded build-date copy. KISS modem: off-by-one in the name clamp.
@@ -253,7 +291,7 @@ freshly flashed node does not need the usual round of settings:
* radio 869.432 MHz / 62.5 kHz / SF7 / CR5 (all builds);
* repeater and room server: zero-hop advert off, flood advert every 25 h,
`af 9` (10 % duty cycle);
10 % duty cycle (`get dutycycle` → `10.0%`; the deprecated `af` reads 9);
* repeater: regions `cz` and `cs` next to `*` -- add your own `cz-<kraj>`
with `region put cz-xxx cz` + `region save`;
* 2-byte path hashes (this fork's default);
@@ -280,10 +318,14 @@ up to `tth-654d53f3` do not have `ble pin`: keep BLE off there and use USB.
### Flashing a release
Files are in [Releases](https://git.rfa.cz/tth-pub/meshcore-tth/releases),
one set per board and role (`<board>_<role>-<sha>`): `.zip` and `.uf2` for
nRF52 boards, `.bin` for ESP32 (`-merged.bin` is the full image for a blank
board, the plain `.bin` an update). `SHA256SUMS` lists the checksums.
Files are in [Releases](https://git.rfa.cz/tth-pub/meshcore-tth/releases).
A release is named after the upstream version and the date, e.g.
`v1.18.0+tth.20261112` (a second one that day `.2`), and its notes list the
changes since the previous release. One set per board and role
(`<board>_<role>-<release>`, e.g. `Xiao_nrf52_repeater-v1.18.0+tth.20261112.zip`):
`.zip` and `.uf2` for nRF52 boards, `.bin` for ESP32 (`-merged.bin` is the
full image for a blank board, the plain `.bin` an update). `SHA256SUMS` lists
the checksums. Releases up to 12. 11. 2026 were named `tth-<sha>`.
**nRF52 (XIAO, RAK4631, SenseCAP Solar, T1000-E, T114) with the
[MeshCore web flasher](https://flasher.meshcore.io)** -- Chrome, Edge or
@@ -296,7 +338,8 @@ Chromium on a computer (Web Serial; not Firefox or Safari):
4. Click **Flash!** and pick that new port. About 30 s, then the board
restarts into the new firmware.
5. **Console** in the flasher (or any serial terminal, 115200) checks the
result: `ver` shows `v1.xx.x-tth<sha>`, the sha from the file name.
result: `ver` shows `v1.xx.x-tth<sha>`, the same as the "Verze v uzlu"
(node version) line in the release notes.
**Do not click Erase Flash** unless you want a new node: it wipes the
identity (the node's key and everything that knows it) together with all
+1 -1
View File
@@ -40,7 +40,7 @@ Budka `mc_tx` pad → XIAO **D0**, GND ↔ GND, each board on its own USB. A
A line with a bad checksum is dropped whole; a value not refreshed for 2 min is
left out. Meter channels stay reserved while a meter is missing.
Read it with `tools/budka_telem.py <companion-port> <sensor-name>`. The sensor
Read it with `.tth/tools/budka_telem.py <companion-port> <sensor-name>`. The sensor
answers only clients in its ACL — a request from anyone else is dropped
(`recv matches no peers` in a `MESH_DEBUG` build). Add the companion from the
sensor's USB console with `setperm <companion-pubkey> 1`, or log in as admin.
+57
View File
@@ -545,6 +545,45 @@ so the icon and the Grafana percentage tell one story.
---
#### View or change the RX duty cycle (rxps) -- CUSTOM (TeTeHacko)
**Usage:**
- `get radio.rxps`
- `set radio.rxps off|on|balanced|max`
- `set radio.rxps level <1-10> [preamble <16|32>]`
- `set radio.rxps max preamble <16|32>`
The SX1262 sleeps between short listening windows (`SetRxDutyCycle`) instead
of listening all the time, and stays awake through a packet once it hears a
preamble. Ported from EasySkyMesh PowerSaving v18 (IoTThinks). Repeater, room
server and sensor; SX1262 only (an LR11x0 reports `supported=no`). Present
only in builds with `-D WITH_RX_POWERSAVING` (the public releases have it) and
off until you set it; the setting is saved.
**Parameters:**
- `on` (= `conservative`, level 3), `balanced` (level 6), `max` (level 8): the
higher the level, the longer the sleep. The named presets assume senders
with a 16-symbol preamble (the MeshCore default), so they are safe on a
mixed mesh.
- `level <n>`: the same scale by number; without `preamble` it follows the SF.
9 (`overdrive`) and 10 (`riskyWorkingMax`) are past the datasheet's timing
condition -- 10 is known to lose packets.
- `<rx_us> <sleep_us>`: raw window lengths.
`get radio.rxps` shows the requested and the effective state
(`desired=on,effective=armed`), the window lengths and two error counters. If
arming fails three times in a row, the radio falls back to continuous RX by
itself (`effective=continuous`, `fail` counts up). The noise-floor calibration
also runs in continuous RX.
**Default:** `off`
**Note:** Measured 12. 11. 2026 on a XIAO nRF52840 + Wio-SX1262 at 5 V
(866.5 MHz / SF8 / BW62.5, A/B/A/B, 15 min cells): `max` saves **~2.3 mA**
(cell repeatability 0.3 mA). A 3-board zero-hop test lost nothing on `max`
(0/240 over two runs, the second on the public release). See `docs/power.md`.
---
### Routing
#### View or change this node's repeat flag
@@ -1271,6 +1310,24 @@ Covers serial NMEA receivers (`MicroNMEALocationProvider`).
---
#### Set the INA current sensor's shunt resistor
**Usage:**
- `sensor get ina.shunt`
- `sensor set ina.shunt <mOhm>`
**Parameters:**
- `mOhm`: the shunt on the module, in milliohms (`10` for a shunt marked `R010`,
`100` for `R100`); `0` = the build's value (100 mOhm unless the build sets
`TELEM_INA219_SHUNT_VALUE` / `TELEM_INA226_SHUNT_VALUE` / `TELEM_INA3221_SHUNT_VALUE`)
**Note:** Listed only when an INA219, INA226 or INA3221 was detected at boot.
Saved, applies at once and survives a reboot; it also works over the mesh as
admin, and on a companion as the custom variable `ina.shunt`. With the wrong value
the current is off by the ratio -- LaskaKit's INA226 modules carry 10 mOhm, the
default assumes 100. Current is reported in steps of 1 mA (CayenneLPP).
---
### Bridge (When bridge support is compiled in)
#### View the compiled bridge type
+46 -3
View File
@@ -13,7 +13,7 @@ figures are.
| **GPS running continuously** | **46.0 mA** (spread 43.7-47.5) | `gps duty` recovers 42-45 of it |
| BLE advertising + Bluefruit's blinking LED | see below | defaults changed, LED off, 1 s interval |
| `powersaving on` (MCU light sleep) | **~1 mA, not separable from zero** | keep it on (free), but it is not a lever |
| RX duty cycle (EasySkyMesh "rxps") | ~2 mA on our SF7 preset | **not worth pre-release code** whose failure mode is a deaf repeater |
| RX duty cycle (`set radio.rxps`, from EasySkyMesh) | **~2.3 mA** at `max` (XIAO, 12. 11. 2026) | opt-in, off by default: worth it on a small panel, see below |
| `radio.rxgain off` | ~0.7 mA | **no** — 1-3 dB of sensitivity is what a mast node is for |
| FEM LNA control | n/a | SenseCap has no FEM, only an RXEN switch |
@@ -89,12 +89,55 @@ Bench boards keep both upstream behaviours (`-D RPT_BLE_CONN_LED=1`,
stands: ship with BLE **on**, verify the node on site, and only then turn it off
over the mesh — otherwise a node that does not come up has no way in.
## RX duty cycle (rxps)
Ported from EasySkyMesh PowerSaving v18 behind `-D WITH_RX_POWERSAVING` (the
public releases have it), SX1262 only, **off until set**. The radio listens in
short windows and sleeps between them, staying awake through a packet once it
hears a preamble; after three failed arms it falls back to continuous RX by
itself. Commands: `docs/cli_commands.md`, `radio.rxps`.
Measured 12. 11. 2026 on a XIAO nRF52840 + Wio-SX1262 (not the SenseCAP of
the rest of this page), bench preset 866.5 MHz / SF8 / BW62.5, fed at 5 V
through an INA226 (10 mOhm) read every 5 s; the only other load was a UC96 on
the XIAO's USB port. A/B/A/B, 15 min cells, the first 2 min of each dropped:
| cell | rxps | mean | median |
|---|---|---|---|
| 1 | off | 33.84 mA | 32.2 mA |
| 2 | max | 31.31 mA | 30.5 mA |
| 3 | off | 33.53 mA | 32.5 mA |
| 4 | max | 31.36 mA | 30.3 mA |
`max` (level 8) against the mean of its neighbours: **-2.4 / -2.2 mA**, pooled
-2.35 mA (medians -1.95 mA); off vs off differs by 0.3 mA, max vs max by
0.05 mA. That is the radio's share, so it carries over to other SX1262 boards
in absolute terms; the 33 mA base is this bench (meter, BLE advertising), not
a node. Behind the XIAO's linear regulator the battery sees the same current:
~7-8 mW at 3.3 V.
Reception: a 3-board zero-hop matrix (x1, x3, x4; rxps switched on x1 and x4,
x3 the reference with rxps off; 20 rounds per phase, each link witnessed by
another board), run twice -- on the development build, then repeated on the
public release `v1.18.0+tth.20261112` (`ver` v1.18.0-tthd4afea1):
| phase | development build | public release | together |
|---|---|---|---|
| rxps off | 0/120 | 1/120 | 1/240 |
| `on` (level 3) | 1/120 | 2/120 | 3/240 |
| `max` (level 8) | 0/120 | 0/120 | **0/240** |
rxps stayed armed throughout, no error counts. Single losses happen with rxps
off as well, and of the three at level 3 one was on x3, which had rxps off: the
bench shows no degradation at any level. Not measured: mixed SF/preamble senders, a busy
live mesh. On a mast, where 2 mA of ~24 is not the problem, leave it off.
## MCU sleep
`powersaving on` makes the nRF52 wait in WFE between events (it wakes on any
interrupt, including LoRa DIO1). Upstream ships it **off**, and it was missing
from our provisioning, so every node built from that file ran the core at 64 MHz
around the clock. It is now in `tools/provision/repeater-cz-silent.txt`.
around the clock. It is now in our provisioning file.
**But it buys about 1 mA, not the 3-4 that seemed obvious.** Measured with GPS
held off so its sync windows could not pollute the cells: paired estimate
@@ -128,5 +171,5 @@ drain directly costs collected frames.
40.9 mA against 24.1-24.5 in its neighbours). Put `gps off` in every cell of
such a run and restore `gps duty` afterwards.
See `tools/README.md` (`power_ab.py`) for the alternating-cell design that makes
See `tools/power_ab.py --help` for the alternating-cell design that makes
these deltas trustworthy in the first place.
+4
View File
@@ -1928,6 +1928,10 @@ void MyMesh::handleCmdFrame(size_t len) {
savePrefs();
}
#endif
if (strcmp(sp, "ina.shunt") == 0) { // CUSTOM (TeTeHacko): survives a reboot
_prefs.ina_shunt_mohm = atof(np);
savePrefs();
}
writeOKFrame();
} else {
writeErrFrame(ERR_CODE_ILLEGAL_ARG);
+2
View File
@@ -53,6 +53,7 @@ public:
uint8_t default_scope_key[16];
float tz_offset = 0;
float adc_multiplier = 0; // battery ADC multiplier, 0 = board default
float ina_shunt_mohm = 0; // CUSTOM (TeTeHacko): INA shunt in mOhm, 0 = build default
#ifdef ENABLE_WIFI_INTERFACE
#ifndef WIFI_SSID
#define WIFI_SSID ""
@@ -225,6 +226,7 @@ private:
def("tel_env", _parent->telemetry_mode_env);
def("tz_offset", _parent->tz_offset);
def("adc_mult", _parent->adc_multiplier);
def("ina_shunt", _parent->ina_shunt_mohm);
}
public:
CompanionPrefs(NodePrefs* parent) : _parent(parent) { }
+1
View File
@@ -319,6 +319,7 @@ void setup() {
#if ENV_INCLUDE_GPS == 1
the_mesh.applyGpsPrefs();
#endif
sensors.applyInaShunt(the_mesh.getNodePrefs()->ina_shunt_mohm); // CUSTOM (TeTeHacko)
#ifdef DISPLAY_CLASS
ui_task.begin(disp, &sensors, the_mesh.getNodePrefs()); // still want to pass this in as dependency, as prefs might be moved
+14
View File
@@ -1525,6 +1525,9 @@ void MyMesh::begin(FILESYSTEM *fs) {
radio_driver.setParams(_prefs.freq, _prefs.bw, _prefs.sf, _prefs.cr);
radio_driver.setTxPower(_prefs.tx_power_dbm);
#ifdef WITH_RX_POWERSAVING
_prefs.getRadioPrefs()->applyRxPowerSaving(_prefs.sf, _prefs.bw); // CUSTOM (TeTeHacko)
#endif
radio_driver.setRxBoostedGainMode(_prefs.rx_boosted_gain);
MESH_DEBUG_PRINTLN("RX Boosted Gain Mode: %s",
@@ -1540,6 +1543,7 @@ void MyMesh::begin(FILESYSTEM *fs) {
#if ENV_INCLUDE_GPS == 1
applyGpsPrefs();
#endif
sensors.applyInaShunt(_prefs.ina_shunt_mohm); // CUSTOM (TeTeHacko)
}
void MyMesh::sendFloodScoped(const TransportKey& scope, mesh::Packet* pkt, uint32_t delay_millis, uint8_t path_hash_size) {
@@ -1948,12 +1952,18 @@ void MyMesh::loop() {
if (set_radio_at && millisHasNowPassed(set_radio_at)) { // apply pending (temporary) radio params
set_radio_at = 0; // clear timer
radio_driver.setParams(pending_freq, pending_bw, pending_sf, pending_cr);
#ifdef WITH_RX_POWERSAVING
_prefs.getRadioPrefs()->applyRxPowerSaving(pending_sf, pending_bw); // timing is in symbols
#endif
MESH_DEBUG_PRINTLN("Temp radio params");
}
if (revert_radio_at && millisHasNowPassed(revert_radio_at)) { // revert radio params to orig
revert_radio_at = 0; // clear timer
radio_driver.setParams(_prefs.freq, _prefs.bw, _prefs.sf, _prefs.cr);
#ifdef WITH_RX_POWERSAVING
_prefs.getRadioPrefs()->applyRxPowerSaving(_prefs.sf, _prefs.bw);
#endif
MESH_DEBUG_PRINTLN("Radio params restored");
}
@@ -1981,6 +1991,10 @@ void MyMesh::loop() {
bool MyMesh::hasPendingWork() const {
#if defined(WITH_BRIDGE)
if (bridge.isRunning()) return true; // bridge needs WiFi radio, can't sleep
#endif
#ifdef WITH_RX_POWERSAVING
// no MCU sleep while the noise-floor window samples RSSI
if (radio_driver.isRxPowerSavingCalibrationActive()) return true;
#endif
return _mgr->getOutboundTotal() > 0;
}
+10
View File
@@ -746,6 +746,9 @@ void MyMesh::begin(FILESYSTEM *fs) {
radio_driver.setParams(_prefs.freq, _prefs.bw, _prefs.sf, _prefs.cr);
radio_driver.setTxPower(_prefs.tx_power_dbm);
#ifdef WITH_RX_POWERSAVING
_prefs.getRadioPrefs()->applyRxPowerSaving(_prefs.sf, _prefs.bw); // CUSTOM (TeTeHacko)
#endif
radio_driver.setRxBoostedGainMode(_prefs.rx_boosted_gain);
board.attachDynamicPrefs(_prefs.getCustom());
@@ -758,6 +761,7 @@ void MyMesh::begin(FILESYSTEM *fs) {
#if ENV_INCLUDE_GPS == 1
applyGpsPrefs();
#endif
sensors.applyInaShunt(_prefs.ina_shunt_mohm); // CUSTOM (TeTeHacko)
}
void MyMesh::sendFloodScoped(const TransportKey& scope, mesh::Packet* pkt, uint32_t delay_millis, uint8_t path_hash_size) {
@@ -1083,12 +1087,18 @@ void MyMesh::loop() {
if (set_radio_at && millisHasNowPassed(set_radio_at)) { // apply pending (temporary) radio params
set_radio_at = 0; // clear timer
radio_driver.setParams(pending_freq, pending_bw, pending_sf, pending_cr);
#ifdef WITH_RX_POWERSAVING
_prefs.getRadioPrefs()->applyRxPowerSaving(pending_sf, pending_bw);
#endif
MESH_DEBUG_PRINTLN("Temp radio params");
}
if (revert_radio_at && millisHasNowPassed(revert_radio_at)) { // revert radio params to orig
revert_radio_at = 0; // clear timer
radio_driver.setParams(_prefs.freq, _prefs.bw, _prefs.sf, _prefs.cr);
#ifdef WITH_RX_POWERSAVING
_prefs.getRadioPrefs()->applyRxPowerSaving(_prefs.sf, _prefs.bw);
#endif
MESH_DEBUG_PRINTLN("Radio params restored");
}
+10
View File
@@ -862,6 +862,9 @@ void SensorMesh::begin(FILESYSTEM* fs) {
radio_driver.setParams(_prefs.freq, _prefs.bw, _prefs.sf, _prefs.cr);
radio_driver.setTxPower(_prefs.tx_power_dbm);
#ifdef WITH_RX_POWERSAVING
_prefs.getRadioPrefs()->applyRxPowerSaving(_prefs.sf, _prefs.bw); // CUSTOM (TeTeHacko)
#endif
board.attachDynamicPrefs(_prefs.getCustom());
@@ -873,6 +876,7 @@ void SensorMesh::begin(FILESYSTEM* fs) {
#if ENV_INCLUDE_GPS == 1
applyGpsPrefs();
#endif
sensors.applyInaShunt(_prefs.ina_shunt_mohm); // CUSTOM (TeTeHacko)
}
bool SensorMesh::formatFileSystem() {
@@ -1023,12 +1027,18 @@ void SensorMesh::loop() {
if (set_radio_at && millisHasNowPassed(set_radio_at)) { // apply pending (temporary) radio params
set_radio_at = 0; // clear timer
radio_driver.setParams(pending_freq, pending_bw, pending_sf, pending_cr);
#ifdef WITH_RX_POWERSAVING
_prefs.getRadioPrefs()->applyRxPowerSaving(pending_sf, pending_bw);
#endif
MESH_DEBUG_PRINTLN("Temp radio params");
}
if (revert_radio_at && millisHasNowPassed(revert_radio_at)) { // revert radio params to orig
revert_radio_at = 0; // clear timer
radio_driver.setParams(_prefs.freq, _prefs.bw, _prefs.sf, _prefs.cr);
#ifdef WITH_RX_POWERSAVING
_prefs.getRadioPrefs()->applyRxPowerSaving(_prefs.sf, _prefs.bw);
#endif
MESH_DEBUG_PRINTLN("Radio params restored");
}
+4
View File
@@ -413,6 +413,10 @@ void CommonCLI::handleCommand(uint32_t sender_timestamp, char* command, char* re
const char *key = (num > 0) ? parts[0] : "";
const char *value = (num > 1) ? parts[1] : "null";
if (_sensors->setSettingValue(key, value)) {
if (strcmp(key, "ina.shunt") == 0) { // CUSTOM (TeTeHacko): survives a reboot
_prefs->ina_shunt_mohm = atof(value);
savePrefs();
}
strcpy(reply, "ok");
} else {
strcpy(reply, "can't find custom var");
+15
View File
@@ -68,8 +68,12 @@ public:
uint8_t advert_loc_policy = 0;
uint32_t discovery_mod_timestamp = 0;
float adc_multiplier = 0;
float ina_shunt_mohm = 0; // CUSTOM (TeTeHacko): INA shunt in mOhm, 0 = build default
char owner_info[120];
uint8_t rx_boosted_gain = 0; // power settings
#ifdef WITH_RX_POWERSAVING
RxPowerSavingConfig rxps; // CUSTOM (TeTeHacko): RX duty cycle, off by default
#endif
uint8_t radio_fem_rxgain = 0; // LoRa FEM RX gain setting
uint8_t radio_fem_txgain = 0; // LoRa FEM TX gain setting
uint8_t path_hash_mode = 0; // which path mode to use when sending
@@ -124,10 +128,20 @@ private:
def("agc_int", _parent->agc_reset_interval);
def("hash_mode", _parent->path_hash_mode);
def("multi_ack", _parent->multi_acks);
#ifdef WITH_RX_POWERSAVING
def("rxps_en", _parent->rxps.enabled);
def("rxps_rx_us", _parent->rxps.rx_us);
def("rxps_sleep_us", _parent->rxps.sleep_us);
def("rxps_level", _parent->rxps.level);
def("rxps_preamble", _parent->rxps.preamble);
#endif
def("rsilence", _parent->radio_silence_min);
}
public:
RadioPrefs(NodePrefs* parent) : _parent(parent) { }
#ifdef WITH_RX_POWERSAVING
RxPowerSavingConfig* getRxPowerSavingConfig() override { return &_parent->rxps; }
#endif
// CommonRadioPrefs interface
float getFreq() const override { return _parent->freq; }
void setFreq(float f) override { _parent->freq = f; markDirty(); }
@@ -225,6 +239,7 @@ private:
protected:
void structure() override {
def("adc_mult", _parent->adc_multiplier);
def("ina_shunt", _parent->ina_shunt_mohm);
def("pwr_sav_en", _parent->powersaving_enabled);
def("bicon", _parent->batt_icon);
def("bicon_lo", _parent->batt_icon_lo);
+66
View File
@@ -3,6 +3,9 @@
#include "Utils.h"
#include "target.h"
#include <ctype.h>
#ifdef WITH_RX_POWERSAVING
#include "radiolib/RXPowerSavingCLI.h"
#endif
namespace {
@@ -17,8 +20,35 @@ bool looksLikeANumber(const char* s) {
return isdigit((unsigned char)*s) || *s == '.';
}
#ifdef WITH_RX_POWERSAVING
RxPowerSavingControl* rxpsControl() {
#ifdef WRAPPER_CLASS
return &radio_driver;
#else
return nullptr;
#endif
}
#endif
} // namespace
#ifdef WITH_RX_POWERSAVING
bool CommonRadioPrefs::applyRxPowerSaving(uint8_t sf, float bw) {
_active_sf = sf;
_active_bw = bw;
RxPowerSavingConfig* config = getRxPowerSavingConfig();
if (!config) return false;
// temporary radio parameters must not overwrite the saved automatic periods
RxPowerSavingConfig active = *config;
return applyRxPowerSavingConfig(&active, sf, bw, rxpsControl());
}
bool CommonRadioPrefs::isRxPowerSavingCalibrationActive() const {
const auto* control = rxpsControl();
return control && control->isRxPowerSavingCalibrationActive();
}
#endif
bool CommonRadioPrefs::getByKey(const char* key, char* value, size_t max_len) {
if (strcmp(key, "fem_rxgain") == 0) {
snprintf(value, max_len, "%d", (uint32_t)getFEMRxGain());
@@ -45,6 +75,30 @@ bool CommonRadioPrefs::setByKey(const char* key, const char* value) {
}
bool CommonRadioPrefs::handleCommand(const char* command, uint32_t sender_timestamp, char* reply) {
#ifdef WITH_RX_POWERSAVING
if (strncmp(command, "get radio.rxps", 14) == 0 && (command[14] == 0 || command[14] == ' ')) {
const char* suffix = command + 14;
while (*suffix == ' ') ++suffix;
if (*suffix) return false;
auto* config = getRxPowerSavingConfig();
if (!config) { strcpy(reply, "Error: unsupported"); return true; }
const uint8_t sf = _active_sf ? _active_sf : getSpreadFactor();
const float bw = _active_sf ? _active_bw : getBandwidth();
RxPowerSavingConfig active = *config;
normalizeRxPowerSavingConfig(&active, sf, bw,
rxPowerSavingCaptureCost(rxpsControl()), rxPowerSavingTransition(rxpsControl()));
RXPowerSavingCLI::get(&active, rxpsControl(), sf, bw, reply, 160);
return true;
}
if (strncmp(command, "set radio.rxps ", 15) == 0) {
auto* config = getRxPowerSavingConfig();
if (!config) { strcpy(reply, "Error: unsupported"); return true; }
if (RXPowerSavingCLI::set(command + 15,
_active_sf ? _active_sf : getSpreadFactor(), _active_sf ? _active_bw : getBandwidth(),
config, rxpsControl(), reply, 160)) markDirty();
return true;
}
#endif
if (strcmp(command, "get radio") == 0) {
char freq[16], bw[16];
strcpy(freq, StrHelper::ftoa(getFreq()));
@@ -66,7 +120,19 @@ bool CommonRadioPrefs::handleCommand(const char* command, uint32_t sender_timest
setCodingRate(cr);
setFreq(freq);
setBandwidth(bw);
#ifdef WITH_RX_POWERSAVING
// the RXPS timing is in symbols: a new SF/BW can make it invalid
auto* rxps = getRxPowerSavingConfig();
const bool timing_ok = !rxps || !rxps->enabled || normalizeRxPowerSavingConfig(
rxps, sf, bw, rxPowerSavingCaptureCost(rxpsControl()), rxPowerSavingTransition(rxpsControl()));
if (!timing_ok && rxpsControl()) {
rxpsControl()->setRxPowerSaving(false, rxps->rx_us, rxps->sleep_us);
rxpsControl()->setRxPowerSavingConfigError(true);
}
strcpy(reply, timing_ok ? "OK - reboot to apply" : "OK - reboot to apply; RXPS continuous: invalid timing");
#else
strcpy(reply, "OK - reboot to apply");
#endif
} else {
strcpy(reply, "Error, invalid radio params");
}
+16
View File
@@ -1,9 +1,16 @@
#pragma once
#include "ConfigSerializer.h"
#include "KeyValueStore.h"
#ifdef WITH_RX_POWERSAVING
#include "radiolib/RXPowerSaving.h"
#endif
class CommonRadioPrefs : public ConfigSerializer, public KeyValueStore {
bool _is_dirty = false;
#ifdef WITH_RX_POWERSAVING
uint8_t _active_sf = 0; // what the radio runs now (tempradio differs from prefs)
float _active_bw = 0;
#endif
protected:
CommonRadioPrefs() { }
public:
@@ -64,6 +71,15 @@ public:
bool handleCommand(const char* command, uint32_t sender_timestamp, char* reply);
#ifdef WITH_RX_POWERSAVING
// CUSTOM (TeTeHacko): RXPS, see radiolib/RXPowerSaving.h. Prefs that carry an
// RXPS config override getRxPowerSavingConfig(); apply after every change of
// the radio's SF/BW (the timing is in symbols).
virtual RxPowerSavingConfig* getRxPowerSavingConfig() { return nullptr; }
bool applyRxPowerSaving(uint8_t sf, float bw);
bool isRxPowerSavingCalibrationActive() const;
#endif
bool setByKey(const char* key, const char* value) override; // for dynamic key/value access
bool getByKey(const char* key, char* value, size_t max_len) override;
};
+10
View File
@@ -1,6 +1,7 @@
#pragma once
#include <CayenneLPP.h>
#include <stdio.h>
#include "sensors/LocationProvider.h"
#define TELEM_PERM_BASE 0x01 // 'base' permission includes battery
@@ -60,6 +61,15 @@ public:
// With a periodic collector that costs one cycle and needs no scheduling.
virtual void requestLocationRefresh() { }
// CUSTOM (TeTeHacko): the INA shunt (mOhm) from prefs back into the driver
// after boot; 0 = keep the build's value. A no-op without an INA chip.
void applyInaShunt(float mohm) {
if (mohm <= 0) return;
char v[16];
snprintf(v, sizeof(v), "%.3f", mohm);
setSettingValue("ina.shunt", v);
}
// Live I2C scan, written into dest as text. Returns the number of devices
// that answered, or -1 when the platform has no bus to scan.
//
+65
View File
@@ -2,6 +2,9 @@
#include <RadioLib.h>
#include "MeshCore.h"
#ifdef WITH_RX_POWERSAVING
#include "RXPowerSaving.h" // MC_TCXO_DELAY_US
#endif
class CustomSX1262 : public SX1262 {
uint32_t _preambleMillis = 66;
@@ -12,6 +15,68 @@ class CustomSX1262 : public SX1262 {
public:
CustomSX1262(Module *mod) : SX1262(mod) { }
#ifdef WITH_RX_POWERSAVING
// CUSTOM (TeTeHacko): RXPS support, from EasySkyMesh PowerSaving v18.
// The sleep -> RX transition RadioLib subtracts from a duty-cycle sleep;
// protected in the RadioLib base, read through here.
uint32_t getTcxoDelay() const { return tcxoDelay; }
// RadioLib's begin() installs a 5000 us TCXO startup delay, which is also the
// floor of every duty-cycle sleep. MC_TCXO_DELAY_US (1600, 4x the worst of
// five measured modules) is written afterwards and the RC calibrations redone.
// Every variant reaches the radio through this class (std_init() calls it).
int16_t begin(float freq = 434.0, float bw = 125.0, uint8_t sf = 9, uint8_t cr = 7,
uint8_t syncWord = RADIOLIB_SX126X_SYNC_WORD_PRIVATE, int8_t power = 10,
uint16_t preambleLength = 8, float tcxoVoltage = 1.6,
bool useRegulatorLDO = false) {
int16_t state = SX1262::begin(freq, bw, sf, cr, syncWord, power, preambleLength,
tcxoVoltage, useRegulatorLDO);
if (state == RADIOLIB_ERR_NONE) state = applyMeshCoreTcxoDelay();
return state;
}
// tcxoVoltage read back from the chip object: begin() zeroes it when it falls
// back to an XTAL, and a TCXO supply on DIO3 of a board without one is worse
// than a long delay.
int16_t applyMeshCoreTcxoDelay() {
if (tcxoVoltage <= 0.0f) return RADIOLIB_ERR_NONE;
int16_t state = setTCXO(tcxoVoltage, MC_TCXO_DELAY_US);
RADIOLIB_ASSERT(state);
state = calibrate(RADIOLIB_SX126X_CALIBRATE_ALL);
delay(50);
return state;
}
int16_t startReceiveDutyCycle(uint32_t rxPeriod, uint32_t sleepPeriod,
RadioLibIrqFlags_t irqFlags = RADIOLIB_IRQ_RX_DEFAULT_FLAGS,
RadioLibIrqFlags_t irqMask = RADIOLIB_IRQ_RX_DEFAULT_MASK) {
int16_t state = SX1262::startReceiveDutyCycle(rxPeriod, sleepPeriod, irqFlags, irqMask);
if (state == RADIOLIB_ERR_NONE) {
// RadioLib stages RX through standby, which leaves a host-controlled
// RXEN switch in IDLE; set it back to RX for the whole duty cycle.
this->mod->setRfSwitchState(Module::MODE_RX);
}
return state;
}
// BUSY is high in the duty cycle's sleep phase.
bool isChipBusy() {
uint32_t busy = this->mod->getGpio();
return busy != RADIOLIB_NC && this->mod->hal->digitalRead(busy);
}
int16_t stopRTC() {
uint8_t rtcStop = 0x00;
int16_t state = writeRegister(RADIOLIB_SX126X_REG_RTC_CTRL, &rtcStop, 1);
RADIOLIB_ASSERT(state);
uint8_t rtcEvent = 0;
state = readRegister(RADIOLIB_SX126X_REG_EVENT_MASK, &rtcEvent, 1);
RADIOLIB_ASSERT(state);
rtcEvent |= 0x02;
return writeRegister(RADIOLIB_SX126X_REG_EVENT_MASK, &rtcEvent, 1);
}
#endif
#ifdef RP2040_PLATFORM
bool std_init(SPIClassRP2040* spi = NULL)
#else
@@ -12,7 +12,19 @@ class CustomSX1262Wrapper : public RadioLibWrapper {
public:
CustomSX1262Wrapper(CustomSX1262& radio, mesh::MainBoard& board) : RadioLibWrapper(radio, board) { }
#ifdef WITH_RX_POWERSAVING
// The duty-cycle sleep floor is this board's TCXO delay + 1000 us (RadioLib
// subtracts it from the sleep; below it the register underflows).
uint32_t rxPowerSavingTransitionUs() const override {
return ((CustomSX1262 *)_radio)->getTcxoDelay() + 1000;
}
bool supportsRxPowerSaving() const override { return true; }
#endif
void setParams(float freq, float bw, uint8_t sf, uint8_t cr) override {
#ifdef WITH_RX_POWERSAVING
prepareForRadioConfig();
#endif
((CustomSX1262 *)_radio)->setFrequency(freq);
((CustomSX1262 *)_radio)->setSpreadingFactor(sf);
((CustomSX1262 *)_radio)->setBandwidth(bw);
@@ -29,8 +41,17 @@ public:
return crc;
}
bool isReceivingPacket() override {
#ifdef WITH_RX_POWERSAVING
// In the sleep phase (BUSY high) an SPI probe of the IRQ flags would wake the
// chip and break the cycle -- and there is nothing to receive. Outside RXPS
// this stays a real channel check: Dispatcher::checkSend() relies on it.
if (_rx_ps_armed && ((CustomSX1262 *)_radio)->isChipBusy()) return false;
#endif
return ((CustomSX1262 *)_radio)->isReceiving();
}
#ifdef WITH_RX_POWERSAVING
bool isChipBusy() override { return ((CustomSX1262 *)_radio)->isChipBusy(); }
#endif
#if defined(LORA_POLL_IRQ) || defined(PIN_DIAG)
// CUSTOM (TeTeHacko): SX126x native status bits. TIMEOUT is in the mask because
// an RX window that expires has to end the wait too -- with the DIO1 line dead
@@ -42,8 +63,10 @@ public:
float getCurrentRSSI() override {
return ((CustomSX1262 *)_radio)->getRSSI(false);
}
#ifndef WITH_RX_POWERSAVING // with it, the base class answers from the values cached at RX
float getLastRSSI() const override { return ((CustomSX1262 *)_radio)->getRSSI(); }
float getLastSNR() const override { return ((CustomSX1262 *)_radio)->getSNR(); }
#endif
float packetScore(float snr, int packet_len) override {
int sf = ((CustomSX1262 *)_radio)->spreadingFactor;
@@ -51,11 +74,17 @@ public:
}
uint8_t getSpreadingFactor() const override { return ((CustomSX1262 *)_radio)->spreadingFactor; }
virtual void powerOff() override {
#ifdef WITH_RX_POWERSAVING
if (_rx_ps_armed) stopReceiveDutyCycle();
#endif
((CustomSX1262 *)_radio)->sleep(false);
}
bool supportsRxBoostedGain() const override { return true; }
bool setRxBoostedGainMode(bool en) override {
#ifdef WITH_RX_POWERSAVING
prepareForRadioConfig();
#endif
return ((CustomSX1262 *)_radio)->setRxBoostedGainMode(en) == RADIOLIB_ERR_NONE;
}
bool getRxBoostedGainMode() const override {
@@ -64,6 +93,26 @@ public:
void doResetAGC() override { sx126xResetAGC((SX126x *)_radio, getRxBoostedGainMode()); }
#ifdef WITH_RX_POWERSAVING
protected:
int16_t armDutyCycle(RadioLibIrqFlags_t irq_flags, RadioLibIrqFlags_t irq_mask,
uint32_t* eff_rx_us, uint32_t* eff_sleep_us) override {
// RadioLib programs exactly what is asked (it subtracts the wake-up
// transition from the sleep internally).
*eff_rx_us = _rx_ps_rx_us;
*eff_sleep_us = _rx_ps_sleep_us;
return ((CustomSX1262 *)_radio)->startReceiveDutyCycle(_rx_ps_rx_us, _rx_ps_sleep_us, irq_flags, irq_mask);
}
int16_t stopDutyCycleHardware() override {
int16_t standby_err = _radio->standby();
int16_t rtc_err = ((CustomSX1262 *)_radio)->stopRTC();
return standby_err != RADIOLIB_ERR_NONE ? standby_err : rtc_err;
}
// continuous RX keeps the preamble-detect IRQ, like CustomSX1262::startReceive()
int16_t startContinuousReceive() override { return ((CustomSX1262 *)_radio)->startReceive(); }
public:
#endif
#ifdef RADIO_DIAG
protected:
// CUSTOM (TeTeHacko): `radiostat`, chip side. mode: 2 STBY_RC, 3 STBY_XOSC,
+251
View File
@@ -0,0 +1,251 @@
// CUSTOM (TeTeHacko): from EasySkyMesh PowerSaving v18 (IoTThinks/MeshCore,
// MIT, https://github.com/IoTThinks/MeshCore/tree/PowerSaving-v18) -- RXPS, the
// SX126x/LR11x0 RX duty cycle. Compiled only with -D WITH_RX_POWERSAVING.
#ifdef WITH_RX_POWERSAVING
#include "RXPowerSaving.h"
#include <math.h>
static uint32_t ceilRxPowerSavingValue(float value) {
uint32_t rounded = (uint32_t)value;
return value > (float)rounded ? rounded + 1 : rounded;
}
// Both radios program their duty cycle in 15.625 us ticks and truncate the
// microsecond value on the way in, so a period of 10013 us is really 10000 us
// on air while the CLI happily reports 10013. Snapping to the nearest tick and
// returning the smallest microsecond value that still lands on it makes the
// reported periods the ones the hardware runs - which matters here, because the
// register value turned out to be what a duty-cycle defect keys on, not the
// microseconds we asked for.
static uint32_t rxPowerSavingTickToUs(uint64_t tick) {
if (tick == 0) tick = 1;
return (uint32_t)((tick * 125 + 7) / 8); // ceil(tick * 15.625)
}
static uint32_t snapRxPowerSavingToTick(uint32_t us) {
return rxPowerSavingTickToUs(((uint64_t)us * 8 + 62) / 125); // nearest
}
// Rounding the listen window to the *nearest* tick can shave a few microseconds
// off, and the timer guard below has no room to give: it must hold with the
// register values the radio actually runs. So that one rounds up.
static uint32_t snapRxPowerSavingUpToTick(uint32_t us) {
return rxPowerSavingTickToUs(((uint64_t)us * 8 + 124) / 125); // ceil
}
bool isValidRxPowerSavingPeriod(uint32_t us) {
return us >= RX_POWERSAVING_MIN_PERIOD_US && us <= RX_POWERSAVING_MAX_PERIOD_US;
}
uint8_t rxPowerSavingPreambleForSF(uint8_t sf) {
return sf <= 8 ? 32 : 16;
}
bool isRxPowerSavingNumeric(const char* value) {
if (value == nullptr || *value == 0) return false;
while (*value) {
if (*value < '0' || *value > '9') return false;
value++;
}
return true;
}
float rxPowerSavingCaptureCost(const RxPowerSavingControl* control) {
return control != nullptr ? control->rxPowerSavingCaptureCostSymbols()
: RX_POWERSAVING_CAPTURE_COST_SYMBOLS;
}
uint32_t rxPowerSavingTransition(const RxPowerSavingControl* control) {
return control != nullptr ? control->rxPowerSavingTransitionUs()
: RX_POWERSAVING_TRANSITION_US;
}
// rxPeriod register values measured to break SetRxDutyCycle on SX1262: the
// radio latches the preamble and then never validates a header, losing 35% of
// packets at SF6 and all of them at SF7. Both were reproduced on two boards
// with an LR1110 witnessing 100% of the same transmissions, and both bands are
// exactly one tick wide - 639 and 641 are lossless.
//
// This list is certainly incomplete: about thirty values were sampled out of
// the thousands a profile can generate. Levels 1-10 do not need it because the
// timer guard makes any value safe; it exists only for the unguarded maximum,
// where it is the one protection left.
static const uint32_t RX_POWERSAVING_BAD_RX_TICKS[] = {320, 640};
static uint32_t avoidBadRxPowerSavingTick(uint32_t rx_us) {
const uint32_t tick = (rx_us * 8) / 125;
for (uint32_t bad : RX_POWERSAVING_BAD_RX_TICKS) {
// One tick longer costs 15.625 us of listening and steps clear of the band.
if (tick == bad) return (uint32_t)((((uint64_t)tick + 1) * 125 + 7) / 8);
}
return rx_us;
}
bool calcRxPowerSavingLevel(uint8_t level, uint8_t sf, float bw, uint8_t preamble,
uint32_t* rx_us, uint32_t* sleep_us,
float capture_cost_symbols, uint32_t transition_us) {
if (rx_us == nullptr || sleep_us == nullptr || level < 1 ||
level > RX_POWERSAVING_RISKY_WORKING_MAX_LEVEL || sf < 5 || sf > 12 ||
!isfinite(bw) || bw <= 0.0f || !isfinite(capture_cost_symbols) ||
capture_cost_symbols <= 0 || capture_cost_symbols >= preamble || transition_us >= RX_POWERSAVING_MAX_PERIOD_US || (preamble != 16 && preamble != 32)) {
return false;
}
const bool unguarded = isRxPowerSavingUnguardedLevel(level);
const float symbol_us = (1000.0f * (float)(1UL << sf)) / bw;
if (!isfinite(symbol_us) || symbol_us * 64.0f > (float)(UINT32_MAX / 8)) return false;
// Worst case a preamble starts the instant an RX window closes, so the part
// that survives into the next window is `preamble - sleep`. The absolute
// limit is therefore reached when that equals the chip's capture cost; the
// unguarded levels are pinned to geometries measured at or past that point,
// which is why they still need it.
const float sleep_edge_symbols = (float)preamble - capture_cost_symbols;
float sleep_symbols;
float rx_symbols = 0.0f; // only used by the unguarded levels
if (unguarded) {
// Kept on the old interpolation because that is the geometry the bench
// measured: overdrive is the top of the profile, and `riskyWorkingMax` is
// the point past it where delivery started to fall.
float amount = 1.0f;
if (isRxPowerSavingRiskyWorkingMaxLevel(level)) {
const float virtual_level = preamble == 16 ? RX_POWERSAVING_RISKY_WORKING_MAX_VIRTUAL_P16
: RX_POWERSAVING_RISKY_WORKING_MAX_VIRTUAL_P32;
amount = (virtual_level - 1.0f) / 9.0f;
}
const float rx_start_symbols = preamble == 16 ? 12.0f : 16.0f;
const float sleep_start_symbols = preamble == 16 ? 2.0f : 15.0f;
rx_symbols = rx_start_symbols + amount * (8.0f - rx_start_symbols);
sleep_symbols = sleep_start_symbols + amount * (sleep_edge_symbols - sleep_start_symbols);
} else {
// Guarded levels state their catch directly, so the sleep is just what is
// left of the preamble - no capture cost involved. The pad makes the node
// catch a fifth of a symbol more than promised, which is what keeps the
// generated register pairs off the defective ones.
const float catch_symbols = rxPowerSavingLevelCatch(level, preamble);
// A level that undertakes to catch less than this radio needs to latch is
// not usable: say so rather than return a geometry that cannot work.
if (catch_symbols < capture_cost_symbols) return false;
sleep_symbols = (float)preamble - catch_symbols - RX_POWERSAVING_MARGIN_PAD_SYMBOLS;
if (sleep_symbols < 0.0f) sleep_symbols = 0.0f;
}
*sleep_us = (uint32_t)(sleep_symbols * symbol_us);
// Below the hardware floor the duty cycle cannot be armed at all: the driver
// returns -708 and the wrapper quietly runs continuous RX, so the node keeps
// reporting power saving while spending full RX current. Just above that the
// SX1262 arms with ERR_NONE and then detects no preambles at all, which is
// worse. Measured floor: 6050-6100 us dead, 6200 us and up lossless.
const uint32_t min_sleep_us = transition_us + RX_POWERSAVING_MIN_SLEEP_MARGIN_US;
if (*sleep_us < min_sleep_us) {
if ((float)min_sleep_us > sleep_edge_symbols * symbol_us) {
// Even zero margin would not fit above the floor: no level of this
// profile can duty cycle at this SF/BW. Say so instead of returning
// something that will silently fall back.
return false;
}
// The floor eats into the margin. Levels below it collapse onto one point;
// the reply still reports the periods, so the loss of margin is visible.
*sleep_us = min_sleep_us;
}
*sleep_us = transition_us + snapRxPowerSavingToTick(*sleep_us - transition_us);
// SetRxDutyCycle timer guard, straight out of the SX1261/2 datasheet: on
// preamble detection the radio restarts its timer with 2*rxPeriod +
// sleepPeriod (register values), and the packet dies if the header does not
// arrive inside it. The datasheet states the requirement as
// Tpreamble + Theader <= 2 * rxPeriod + sleepPeriod
// Measured: when it holds, no period value causes trouble. When it is broken
// the SX1262 usually gets away with it - but not always, and the exceptions
// are a single register tick wide. rxPeriod 640 (exactly 10.000 ms) loses
// 60-65% of packets at SF6 and everything at SF7, on two different boards,
// while 639 and 641 are lossless; rxPeriod 320 behaves the same way. Nothing
// in the register value predicts which ticks misbehave, so satisfy the
// condition instead of dodging the values. The listen window is therefore not
// a free parameter on the guarded scale - it is whatever the condition needs.
const float sync_symbols =
sf <= 6 ? RX_POWERSAVING_SYNC_SYMBOLS_LOW_SF : RX_POWERSAVING_SYNC_SYMBOLS;
const float need_us =
((float)preamble + sync_symbols + RX_POWERSAVING_HEADER_SYMBOLS +
RX_POWERSAVING_TIMER_SLACK_SYMBOLS) * symbol_us;
// Work in the radio's own units: the driver truncates (sleep - transition) to
// 15.625 us ticks, so the microsecond difference overstates the programmed
// sleep by up to one tick - enough to leave the condition short on every
// level of a profile.
const uint32_t sleep_ticks = ((*sleep_us - transition_us) * 8) / 125;
const float programmed_sleep_us = (float)sleep_ticks * RX_POWERSAVING_TICK_US;
if (unguarded) {
*rx_us = ceilRxPowerSavingValue(rx_symbols * symbol_us);
} else {
const float min_rx_us = (need_us - programmed_sleep_us) / 2.0f;
*rx_us = ceilRxPowerSavingValue(min_rx_us > 0.0f ? min_rx_us : symbol_us);
}
*rx_us = snapRxPowerSavingUpToTick(*rx_us);
if (unguarded) *rx_us = avoidBadRxPowerSavingTick(*rx_us);
return true;
}
void ensureRxPowerSavingDefaults(uint32_t* rx_us, uint32_t* sleep_us) {
if (!isValidRxPowerSavingPeriod(*rx_us)) *rx_us = RX_POWERSAVING_DEFAULT_RX_US;
if (!isValidRxPowerSavingPeriod(*sleep_us)) *sleep_us = RX_POWERSAVING_DEFAULT_SLEEP_US;
}
bool recalcRxPowerSavingFromLevel(uint8_t level, uint8_t sf, float bw, uint8_t preamble,
uint32_t* rx_us, uint32_t* sleep_us,
float capture_cost_symbols, uint32_t transition_us) {
if (level < 1 || level > RX_POWERSAVING_RISKY_WORKING_MAX_LEVEL) return false;
if (preamble == 0) preamble = rxPowerSavingPreambleForSF(sf);
uint32_t calculated_rx_us = 0;
uint32_t calculated_sleep_us = 0;
if (!calcRxPowerSavingLevel(level, sf, bw, preamble, &calculated_rx_us, &calculated_sleep_us,
capture_cost_symbols, transition_us) ||
!isValidRxPowerSavingPeriod(calculated_rx_us) ||
!isValidRxPowerSavingPeriod(calculated_sleep_us)) {
return false;
}
*rx_us = calculated_rx_us;
*sleep_us = calculated_sleep_us;
return true;
}
bool normalizeRxPowerSavingConfig(RxPowerSavingConfig* config, uint8_t sf, float bw,
float capture_cost_symbols, uint32_t transition_us) {
if (config == nullptr || sf < 5 || sf > 12 || !isfinite(bw) || bw <= 0) return false;
RxPowerSavingConfig proposed = *config;
proposed.enabled = proposed.enabled ? 1 : 0;
if (proposed.level > RX_POWERSAVING_RISKY_WORKING_MAX_LEVEL) {
proposed.level = RX_POWERSAVING_BALANCED_LEVEL;
}
if (proposed.preamble != 0 && proposed.preamble != 16 && proposed.preamble != 32) {
proposed.preamble = RX_POWERSAVING_PROFILE_PREAMBLE;
}
if (proposed.level == 0) {
if (!isValidRxPowerSavingPeriod(proposed.rx_us) ||
!isValidRxPowerSavingPeriod(proposed.sleep_us)) return false;
} else if (!recalcRxPowerSavingFromLevel(proposed.level, sf, bw, proposed.preamble,
&proposed.rx_us, &proposed.sleep_us,
capture_cost_symbols, transition_us)) {
return false;
}
*config = proposed;
return true;
}
bool applyRxPowerSavingConfig(RxPowerSavingConfig* config, uint8_t sf, float bw,
RxPowerSavingControl* control) {
if (config == nullptr) return false;
const bool valid = !config->enabled || normalizeRxPowerSavingConfig(
config, sf, bw, rxPowerSavingCaptureCost(control), rxPowerSavingTransition(control));
if (control == nullptr) return !config->enabled;
const bool accepted = control->setRxPowerSaving(
config->enabled && valid, config->rx_us, config->sleep_us);
control->setRxPowerSavingConfigError(!valid);
return valid && accepted;
}
#endif // WITH_RX_POWERSAVING
+278
View File
@@ -0,0 +1,278 @@
// CUSTOM (TeTeHacko): from EasySkyMesh PowerSaving v18 (IoTThinks/MeshCore,
// MIT, https://github.com/IoTThinks/MeshCore/tree/PowerSaving-v18) -- RXPS, the
// SX126x/LR11x0 RX duty cycle. Compiled only with -D WITH_RX_POWERSAVING.
#pragma once
#include <stdint.h>
static constexpr uint32_t RX_POWERSAVING_DEFAULT_RX_US = 65625UL;
static constexpr uint32_t RX_POWERSAVING_DEFAULT_SLEEP_US = 60000UL;
static constexpr uint32_t RX_POWERSAVING_MIN_PERIOD_US = 1000UL;
static constexpr uint32_t RX_POWERSAVING_MAX_PERIOD_US = 30000000UL;
// The level scale is a catch dial, in symbols of the sender's preamble.
//
// Level N means: "at least this many symbols of the sender's preamble land
// inside an open RX window." That is the quantity the radio actually needs -
// a preamble is latched once enough of it has been heard - so the level states
// the requirement directly instead of stating a distance from an edge.
//
// The arithmetic follows from that in one step. Worst case, a preamble starts
// the instant an RX window closes, so what survives into the next window is
// `preamble - sleep`. Requiring that to be at least the level's catch gives
//
// sleep = preamble - catch
//
// and the chip's capture cost never enters the geometry. It becomes a
// validation instead: a level is usable when its catch is at least the cost.
// The floor of the scale is 8 symbols precisely because that is what the
// slower of the two families needs (LR11x0 8, SX126x 6), so **every level
// means the same geometry on both radios** - which the previous margin-based
// scale could not do, because the cost sat inside its formula.
//
// The two profiles get their own ladders. On a 16-symbol preamble there are
// only 8 symbols to spend between the floor and the whole preamble, so the
// steps are single symbols; on a 32-symbol preamble there are 24, so the low
// levels can take much larger strides where reception is guaranteed anyway.
static constexpr uint8_t RX_POWERSAVING_GUARDED_LEVELS = 8;
static constexpr float RX_POWERSAVING_LEVEL_CATCH_P16[RX_POWERSAVING_GUARDED_LEVELS] = {
15.0f, 14.0f, 13.0f, 12.0f, 11.0f, 10.0f, 9.0f, 8.0f
};
static constexpr float RX_POWERSAVING_LEVEL_CATCH_P32[RX_POWERSAVING_GUARDED_LEVELS] = {
24.0f, 20.0f, 16.0f, 14.0f, 12.0f, 10.0f, 9.0f, 8.0f
};
// Smallest catch any guarded level asks for, and the reason it is 8: the
// LR11x0 needs 8 symbols to latch where the SX126x needs 6.
static constexpr float RX_POWERSAVING_MIN_CATCH_SYMBOLS = 8.0f;
// On top of the ladder, every guarded level sleeps this much less than the
// arithmetic demands - so it catches 0.2 symbols more than its level promises.
// The reason is not capture safety: it is that specific register pairs the
// calculation lands on are defective (preamble latched, header never
// validated) in the same way isolated rxPeriod ticks 320 and 640 are. Nudging
// every generated geometry off those points cost 0.05 mA and took the worst
// measured cell from 3.33% packet loss to 0.11% across the whole ladder.
// Levels 9 and 10 are exempt - their geometries are pinned to bench
// measurements and shifting them would invalidate that data.
static constexpr float RX_POWERSAVING_MARGIN_PAD_SYMBOLS = 0.2f;
// Past the guarded scale sit two settings that break the datasheet's
// SetRxDutyCycle timer condition on purpose. Overdrive is lossless and 4-12
// percentage points cheaper in duty cycle; `riskyWorkingMax` is the measured
// working edge and drops ~2% of packets by design.
static constexpr uint8_t RX_POWERSAVING_OVERDRIVE_LEVEL = 9;
static constexpr uint8_t RX_POWERSAVING_RISKY_WORKING_MAX_LEVEL = 10;
static constexpr float RX_POWERSAVING_RISKY_WORKING_MAX_VIRTUAL_P32 = 11.0f;
static constexpr float RX_POWERSAVING_RISKY_WORKING_MAX_VIRTUAL_P16 = 10.25f;
// Top of the guarded scale: catches the ladder floor of 8 symbols (8.2 with
// the pad), the cheapest setting that still meets the datasheet condition and
// still works on both radio families. The CLI calls it `max`.
static constexpr uint8_t RX_POWERSAVING_MAX_LEVEL = RX_POWERSAVING_GUARDED_LEVELS;
static constexpr uint8_t RX_POWERSAVING_CONSERVATIVE_LEVEL = 3; // catches 13 (P16) / 16 (P32)
static constexpr uint8_t RX_POWERSAVING_BALANCED_LEVEL = 6; // catches 10 (P16) / 10 (P32)
static constexpr uint8_t RX_POWERSAVING_PROFILE_PREAMBLE = 16;
static constexpr uint8_t RX_POWERSAVING_MAX_CONSEC_ARM_FAILURES = 3;
// Symbols of a sender's preamble consumed before a packet can be latched:
// ~2 to latch the preamble plus ~2 lost to RX-window startup, measured on
// SX1262 at SF8/BW62.5. Capture needs sleep <= sender_preamble - this.
// Note this is well below the 8 symbols RadioLib quotes (SX126x.h) - that
// figure is the datasheet's margin for *reliable* latching, not the floor.
//
// Chip dependent, so it belongs with the driver rather than with each board:
// a wrapper overrides rxPowerSavingCaptureCostSymbols() and every variant using
// that radio picks it up. LR1110 needs about one symbol more - on the bench it
// held 300/300 at a margin of 7.78 symbols and started dropping packets at
// 6.89, for both profiles, where SX1262 is clean down to 6.
static constexpr float RX_POWERSAVING_CAPTURE_COST_SYMBOLS = 6.0f;
static constexpr float RX_POWERSAVING_CAPTURE_COST_SYMBOLS_LR11X0 = 8.0f;
// TCXO startup delay handed to SetDIO3AsTCXOCtrl (SX126x DS 13.3.6) /
// SetTcxoMode (LR11x0 UM 6.3.2). RadioLib defaults it to 5000 us and nothing
// overrode it, so every board paid 5 ms on every duty-cycle wake whatever
// crystal was fitted. Measured lowest working value on five modules: T096 400,
// Tracker V2 300, Waveshare 150, ThinkNode M3 200, T1000-E 200 us - so 1600
// keeps 4x margin over the worst of them.
//
// One knob for the whole tree, in `arduino_base`, because it is a property of
// the parts MeshCore is built with rather than of any one board. A variant that
// needs its own value defines it in its own build_flags and the later -D wins.
#ifndef MC_TCXO_DELAY_US
#define MC_TCXO_DELAY_US 1600
#endif
// Sleep -> RX transition: RadioLib subtracts tcxoDelay + 1000 us from the
// requested sleep before writing the register, and the hardware spends that
// long saving context, restarting the XTAL and locking the PLL. Everything
// below derives from it, so a board that knows its real TCXO delay overrides
// one method and both the sleep floor and the timer guard follow.
static constexpr uint32_t RX_POWERSAVING_TRANSITION_US = MC_TCXO_DELAY_US + 1000;
// Slack the timer guard leaves on top of the datasheet condition, in symbols.
//
// Closing the condition exactly is not enough. The calculator lands on register
// pairs that satisfy it by a hair and still lose packets: rx=2476/sleep=2455
// ticks clears it by 22 us at 0.12 symbol and drops 2-6% on every SX1262 tried,
// while moving any one component clears the fault. It is the same family as the
// isolated bad ticks 320 and 640 - the condition does not predict which pairs
// misbehave, so the answer is to stop generating geometries that sit on its
// edge. One whole symbol of slack is what the bench evidence supports.
#ifndef MC_RXPS_TIMER_SLACK_SYMBOLS
#define MC_RXPS_TIMER_SLACK_SYMBOLS 1.0f
#endif
static constexpr float RX_POWERSAVING_TIMER_SLACK_SYMBOLS = MC_RXPS_TIMER_SLACK_SYMBOLS;
// Both radio families program their duty cycle in these units, and truncate the
// microsecond value on the way in. Everything the timer guard compares has to
// be expressed in whole ticks or it comes out short by a fraction of one.
static constexpr float RX_POWERSAVING_TICK_US = 15.625f;
// Margin above the transition before a duty cycle actually works; see below.
static constexpr uint32_t RX_POWERSAVING_MIN_SLEEP_MARGIN_US = 250;
// Symbols between the end of the sender's preamble and the end of the header:
// the LoRa sync word plus the 8-symbol explicit header. SF5/SF6 use a longer
// sync word than SF7 and above. Used by the SetRxDutyCycle timer guard.
static constexpr float RX_POWERSAVING_SYNC_SYMBOLS_LOW_SF = 6.25f;
static constexpr float RX_POWERSAVING_SYNC_SYMBOLS = 4.25f;
static constexpr float RX_POWERSAVING_HEADER_SYMBOLS = 8.0f;
// Shortest sleep that actually produces a working duty cycle.
//
// RadioLib subtracts tcxoDelay + 1000 us from the requested sleep before
// writing the register. At or below that the register underflows and arming
// fails with RADIOLIB_ERR_INVALID_SLEEP_PERIOD (-708), after which the wrapper
// falls back to continuous RX while the config still says power saving is on.
// Measured on SX1262: the P16 profile fails to arm on levels 1-5 at SF6 and on
// levels 1-2 at SF7, exactly where that bound predicts.
//
// But arming successfully is NOT the boundary. Just above it the SX1262 accepts
// the command, returns ERR_NONE, and then detects **zero** preambles - a
// silently deaf receiver, which is worse than the honest -708. Measured twice,
// on two different SF and RX windows: sleep 6050-6100 us is dead, 6200 us and
// everything above it is lossless (40/40 at every value up to 21617 us). The
// chip needs roughly 200 us of *programmed* sleep, i.e. ~12 register ticks, so
// this leaves 250 us of margin on top of the transition time.
//
// The default assumes the 5000 us TCXO delay RadioLib installs; a wrapper that
// can read its radio overrides this with the board's real value.
static constexpr uint32_t RX_POWERSAVING_MIN_SLEEP_US =
RX_POWERSAVING_TRANSITION_US + RX_POWERSAVING_MIN_SLEEP_MARGIN_US;
class RxPowerSavingArmRetryState {
uint8_t _consecutive_failures = 0;
public:
bool canAttempt() const {
return _consecutive_failures < RX_POWERSAVING_MAX_CONSEC_ARM_FAILURES;
}
void recordSuccess() { _consecutive_failures = 0; }
void recordFailure() {
if (_consecutive_failures < RX_POWERSAVING_MAX_CONSEC_ARM_FAILURES) {
_consecutive_failures++;
}
}
void reset() { _consecutive_failures = 0; }
uint8_t consecutiveFailures() const { return _consecutive_failures; }
};
struct RxPowerSavingConfig {
uint8_t enabled = 0;
uint32_t rx_us = RX_POWERSAVING_DEFAULT_RX_US;
uint32_t sleep_us = RX_POWERSAVING_DEFAULT_SLEEP_US;
uint8_t level = RX_POWERSAVING_BALANCED_LEVEL;
uint8_t preamble = RX_POWERSAVING_PROFILE_PREAMBLE;
};
struct RxPowerSavingStatus {
bool supported = false;
bool armed = false;
int16_t last_error = 0;
uint32_t arm_failures = 0;
// Periods the radio actually runs with. A driver may clamp the requested
// values to satisfy a hardware constraint, so these can differ from the
// configured rx_us/sleep_us. Zero means "nothing armed yet".
uint32_t effective_rx_us = 0;
uint32_t effective_sleep_us = 0;
};
class RxPowerSavingControl {
public:
virtual ~RxPowerSavingControl() = default;
virtual bool setRxPowerSaving(bool enabled, uint32_t rx_us, uint32_t sleep_us) {
(void)rx_us;
(void)sleep_us;
return !enabled;
}
virtual RxPowerSavingStatus getRxPowerSavingStatus() const { return {}; }
virtual void setRxPowerSavingConfigError(bool invalid) { (void)invalid; }
virtual bool isRxPowerSavingCalibrationActive() const { return false; }
// Symbols of the sender's preamble consumed before a packet can be latched.
// Overridden per radio family; see RX_POWERSAVING_CAPTURE_COST_SYMBOLS.
virtual float rxPowerSavingCaptureCostSymbols() const {
return RX_POWERSAVING_CAPTURE_COST_SYMBOLS;
}
// Sleep -> RX transition of this radio, in microseconds. The sleep floor and
// the SetRxDutyCycle timer guard are both derived from it, so a wrapper that
// can read its own tcxoDelay only needs to override this one method.
virtual uint32_t rxPowerSavingTransitionUs() const {
return RX_POWERSAVING_TRANSITION_US;
}
};
// Margin this level asks for, in symbols. Only meaningful on the guarded scale.
// Symbols of the sender's preamble this level undertakes to catch. The two
// profiles have separate ladders, so the profile has to be passed in; anything
// other than 16 or 32 is treated as the 16-symbol profile, matching the
// validation in calcRxPowerSavingLevel().
inline float rxPowerSavingLevelCatch(uint8_t level, uint8_t preamble) {
if (level < 1 || level > RX_POWERSAVING_GUARDED_LEVELS) return 0.0f;
return preamble == 32 ? RX_POWERSAVING_LEVEL_CATCH_P32[level - 1]
: RX_POWERSAVING_LEVEL_CATCH_P16[level - 1];
}
inline bool isRxPowerSavingOverdriveLevel(uint8_t level) {
return level == RX_POWERSAVING_OVERDRIVE_LEVEL;
}
inline bool isRxPowerSavingRiskyWorkingMaxLevel(uint8_t level) {
return level == RX_POWERSAVING_RISKY_WORKING_MAX_LEVEL;
}
// Both levels past the guarded scale run outside the datasheet's timer
// condition. Worth surfacing wherever a level is reported.
inline bool isRxPowerSavingUnguardedLevel(uint8_t level) {
return level >= RX_POWERSAVING_OVERDRIVE_LEVEL;
}
bool isValidRxPowerSavingPeriod(uint32_t us);
uint8_t rxPowerSavingPreambleForSF(uint8_t sf);
bool isRxPowerSavingNumeric(const char* value);
// capture_cost_symbols defaults to the SX126x figure so callers without a radio
// handy still compile; anything holding a RxPowerSavingControl should pass
// rxPowerSavingCaptureCost(control) instead.
float rxPowerSavingCaptureCost(const RxPowerSavingControl* control);
uint32_t rxPowerSavingTransition(const RxPowerSavingControl* control);
bool calcRxPowerSavingLevel(uint8_t level, uint8_t sf, float bw, uint8_t preamble,
uint32_t* rx_us, uint32_t* sleep_us,
float capture_cost_symbols = RX_POWERSAVING_CAPTURE_COST_SYMBOLS,
uint32_t transition_us = RX_POWERSAVING_TRANSITION_US);
void ensureRxPowerSavingDefaults(uint32_t* rx_us, uint32_t* sleep_us);
bool recalcRxPowerSavingFromLevel(uint8_t level, uint8_t sf, float bw, uint8_t preamble,
uint32_t* rx_us, uint32_t* sleep_us,
float capture_cost_symbols = RX_POWERSAVING_CAPTURE_COST_SYMBOLS,
uint32_t transition_us = RX_POWERSAVING_TRANSITION_US);
bool normalizeRxPowerSavingConfig(RxPowerSavingConfig* config, uint8_t sf, float bw,
float capture_cost_symbols = RX_POWERSAVING_CAPTURE_COST_SYMBOLS,
uint32_t transition_us = RX_POWERSAVING_TRANSITION_US);
// The requested configuration survives a timing failure; only the radio falls back.
bool applyRxPowerSavingConfig(RxPowerSavingConfig* config, uint8_t sf, float bw,
RxPowerSavingControl* control);
static constexpr int16_t RX_POWERSAVING_ERR_TIMING = -10001;
+274
View File
@@ -0,0 +1,274 @@
// CUSTOM (TeTeHacko): from EasySkyMesh PowerSaving v18 (IoTThinks/MeshCore,
// MIT, https://github.com/IoTThinks/MeshCore/tree/PowerSaving-v18) -- RXPS, the
// SX126x/LR11x0 RX duty cycle. Compiled only with -D WITH_RX_POWERSAVING.
#ifdef WITH_RX_POWERSAVING
#include "RXPowerSavingCLI.h"
#include <Utils.h>
#include <limits.h>
#include <math.h>
#include <stdio.h>
#include <string.h>
// Suffix printed after the level so an unguarded profile is never mistaken for
// an ordinary one, in both the `set` echo and the `get` report.
static const char* rxPowerSavingLevelTag(uint8_t level) {
if (isRxPowerSavingRiskyWorkingMaxLevel(level)) return "(riskyWorkingMax)";
if (isRxPowerSavingOverdriveLevel(level)) return "(overdrive)";
return "";
}
static bool parseRxPowerSavingUint32(const char* value, uint32_t* parsed) {
if (parsed == nullptr || !isRxPowerSavingNumeric(value)) return false;
uint32_t result = 0;
while (*value) {
uint32_t digit = (uint32_t)(*value++ - '0');
if (result > (UINT32_MAX - digit) / 10U) return false;
result = result * 10U + digit;
}
*parsed = result;
return true;
}
bool RXPowerSavingCLI::set(const char* value, uint8_t sf, float bw,
RxPowerSavingConfig* config, RxPowerSavingControl* control,
char* reply, size_t reply_size) {
if (value == nullptr || config == nullptr || reply == nullptr || reply_size == 0) return false;
RxPowerSavingConfig proposed = *config;
uint8_t level = 0;
uint8_t preamble = rxPowerSavingPreambleForSF(sf);
bool level_requested = false;
bool preamble_overridden = false;
ensureRxPowerSavingDefaults(&proposed.rx_us, &proposed.sleep_us);
if (strcmp(value, "off") == 0) {
proposed.enabled = 0;
} else if (strcmp(value, "on") == 0 || strcmp(value, "conservative") == 0) {
proposed.enabled = 1;
level = RX_POWERSAVING_CONSERVATIVE_LEVEL;
preamble = RX_POWERSAVING_PROFILE_PREAMBLE;
level_requested = true;
preamble_overridden = true;
} else if (strcmp(value, "max") == 0) {
// Top of the guarded scale. Like every named preset it assumes the worst
// case a mixed network can present - a sender using a 16-symbol preamble -
// so at SF<=8 it is markedly less economical than `level 10`, which follows
// the SF and picks the 32-symbol profile. `max preamble 32` gets that back.
proposed.enabled = 1;
level = RX_POWERSAVING_MAX_LEVEL;
preamble = RX_POWERSAVING_PROFILE_PREAMBLE;
level_requested = true;
preamble_overridden = true;
} else if (strcmp(value, "overdrive") == 0) {
// One step past the guarded scale: measured lossless, outside the
// datasheet's timer condition. Same worst-case preamble as the presets above.
proposed.enabled = 1;
level = RX_POWERSAVING_OVERDRIVE_LEVEL;
preamble = RX_POWERSAVING_PROFILE_PREAMBLE;
level_requested = true;
preamble_overridden = true;
} else if (strcmp(value, "riskyWorkingMax") == 0) {
// This one is not lossless, so the risk is explicit in its name. Same
// worst-case preamble as the presets above.
proposed.enabled = 1;
level = RX_POWERSAVING_RISKY_WORKING_MAX_LEVEL;
preamble = RX_POWERSAVING_PROFILE_PREAMBLE;
level_requested = true;
preamble_overridden = true;
} else if (strcmp(value, "balanced") == 0) {
proposed.enabled = 1;
level = RX_POWERSAVING_BALANCED_LEVEL;
preamble = RX_POWERSAVING_PROFILE_PREAMBLE;
level_requested = true;
preamble_overridden = true;
} else {
char input[128];
if (strlen(value) >= sizeof(input)) {
snprintf(reply, reply_size,
"ERROR: use off|on|conservative|balanced|max|overdrive|riskyWorkingMax|level <1-10>|<rx_us> <sleep_us>");
return false;
}
strcpy(input, value);
const char* parts[4];
int count = mesh::Utils::parseTextParts(input, parts, 4, ' ');
uint32_t first = 0;
uint32_t second = 0;
if (count == 1 && parseRxPowerSavingUint32(parts[0], &first)) {
if (first < 1 || first > RX_POWERSAVING_RISKY_WORKING_MAX_LEVEL) {
snprintf(reply, reply_size, "ERROR: level range is 1-%u (or max|overdrive|riskyWorkingMax); preamble is 16 or 32",
RX_POWERSAVING_RISKY_WORKING_MAX_LEVEL);
return false;
}
level = (uint8_t)first;
level_requested = true;
proposed.enabled = 1;
} else if (count >= 2 && strcmp(parts[1], "preamble") == 0 &&
(strcmp(parts[0], "max") == 0 || strcmp(parts[0], "overdrive") == 0 ||
strcmp(parts[0], "riskyWorkingMax") == 0)) {
if (count != 3 || !parseRxPowerSavingUint32(parts[2], &first) ||
(first != 16 && first != 32)) {
snprintf(reply, reply_size, "ERROR: use %s preamble <16|32>", parts[0]);
return false;
}
level = strcmp(parts[0], "overdrive") == 0 ? RX_POWERSAVING_OVERDRIVE_LEVEL
: strcmp(parts[0], "max") == 0 ? RX_POWERSAVING_MAX_LEVEL
: RX_POWERSAVING_RISKY_WORKING_MAX_LEVEL;
preamble = (uint8_t)first;
level_requested = true;
preamble_overridden = true;
proposed.enabled = 1;
} else if (count == 2 && strcmp(parts[0], "level") == 0 &&
parseRxPowerSavingUint32(parts[1], &first)) {
if (first < 1 || first > RX_POWERSAVING_RISKY_WORKING_MAX_LEVEL) {
snprintf(reply, reply_size, "ERROR: level range is 1-%u (or max|overdrive|riskyWorkingMax); preamble is 16 or 32",
RX_POWERSAVING_RISKY_WORKING_MAX_LEVEL);
return false;
}
level = (uint8_t)first;
level_requested = true;
proposed.enabled = 1;
} else if (count == 4 && strcmp(parts[0], "level") == 0 &&
parseRxPowerSavingUint32(parts[1], &first) &&
strcmp(parts[2], "preamble") == 0 &&
parseRxPowerSavingUint32(parts[3], &second)) {
if (first < 1 || first > RX_POWERSAVING_RISKY_WORKING_MAX_LEVEL ||
(second != 16 && second != 32)) {
snprintf(reply, reply_size, "ERROR: level range is 1-%u (or max|overdrive|riskyWorkingMax); preamble is 16 or 32",
RX_POWERSAVING_RISKY_WORKING_MAX_LEVEL);
return false;
}
level = (uint8_t)first;
preamble = (uint8_t)second;
level_requested = true;
preamble_overridden = true;
proposed.enabled = 1;
} else if (count == 2 && parseRxPowerSavingUint32(parts[0], &first) &&
parseRxPowerSavingUint32(parts[1], &second)) {
proposed.rx_us = first;
proposed.sleep_us = second;
proposed.enabled = 1;
} else {
snprintf(reply, reply_size,
"ERROR: use off|on|conservative|balanced|max|overdrive|riskyWorkingMax|level <1-10>|<rx_us> <sleep_us>");
return false;
}
}
if (proposed.enabled && (sf < 5 || sf > 12 || !isfinite(bw) || bw <= 0)) {
if (control) {
control->setRxPowerSaving(false, proposed.rx_us, proposed.sleep_us);
control->setRxPowerSavingConfigError(true);
}
snprintf(reply, reply_size, "ERROR: invalid SF/BW for RXPS");
return false;
}
if (level_requested &&
!recalcRxPowerSavingFromLevel(level, sf, bw, preamble,
&proposed.rx_us, &proposed.sleep_us,
rxPowerSavingCaptureCost(control),
rxPowerSavingTransition(control))) {
// Level and preamble were validated above, so the only way to get here is
// that no sleep exists which both arms the hardware and still lets a
// preamble of this length be caught - i.e. the symbol is too short for RXPS
// at this SF/BW. Saying "level range is 1-10" would send the user hunting
// for the wrong thing.
if (control) {
control->setRxPowerSaving(false, proposed.rx_us, proposed.sleep_us);
control->setRxPowerSavingConfigError(true);
}
snprintf(reply, reply_size, "ERROR: RXPS does not fit this SF/BW with preamble %lu",
(unsigned long)preamble);
return false;
}
if (!isValidRxPowerSavingPeriod(proposed.rx_us) ||
!isValidRxPowerSavingPeriod(proposed.sleep_us)) {
snprintf(reply, reply_size, "ERROR: range is %lu-%lu us",
(unsigned long)RX_POWERSAVING_MIN_PERIOD_US,
(unsigned long)RX_POWERSAVING_MAX_PERIOD_US);
return false;
}
bool applied = control != nullptr
? control->setRxPowerSaving(proposed.enabled != 0, proposed.rx_us, proposed.sleep_us)
: proposed.enabled == 0;
if (!applied) {
snprintf(reply, reply_size, "ERROR: RX powersaving unsupported");
return false;
}
if (control) control->setRxPowerSavingConfigError(false);
if (level_requested) {
proposed.level = level;
proposed.preamble = preamble_overridden ? preamble : 0;
} else if (strcmp(value, "off") != 0) {
proposed.level = 0;
proposed.preamble = 0;
}
*config = proposed;
snprintf(reply, reply_size, "OK - %s,level=%lu%s,preamble=%lu,rx=%lu,sleep=%lu",
config->enabled ? "on" : "off", (unsigned long)config->level,
rxPowerSavingLevelTag(config->level),
(unsigned long)config->preamble, (unsigned long)config->rx_us,
(unsigned long)config->sleep_us);
return true;
}
void RXPowerSavingCLI::get(const RxPowerSavingConfig* config,
const RxPowerSavingControl* control,
uint8_t sf, float bw, char* reply, size_t reply_size) {
if (config == nullptr || reply == nullptr || reply_size == 0) return;
RxPowerSavingStatus status = control != nullptr
? control->getRxPowerSavingStatus()
: RxPowerSavingStatus{};
// Preamble symbols the node actually catches. Not simply the number the level
// asked for: the sleep floor can shorten the sleep further, and at SF6 with
// the 16-symbol profile that collapses the first few levels onto the same
// point. Reporting the requested value there would be a lie.
char margin[24];
margin[0] = 0;
if (status.last_error == 0 && isValidRxPowerSavingPeriod(config->sleep_us) &&
config->level >= 1 && config->level <= RX_POWERSAVING_GUARDED_LEVELS &&
sf >= 5 && sf <= 12 && isfinite(bw) && bw > 0.0f) {
const uint8_t preamble = config->preamble ? config->preamble : rxPowerSavingPreambleForSF(sf);
const float symbol_us = (1000.0f * (float)(1UL << sf)) / bw;
const float effective = (float)preamble - (float)config->sleep_us / symbol_us;
// No %f on this platform's printf, and rounding the whole and fractional
// parts separately overflows: 4.999 came out as "4.10".
const float scaled = effective * 10.0f + (effective < 0.0f ? -0.5f : 0.5f);
if (isfinite(scaled) && scaled > (float)INT_MIN && scaled < (float)INT_MAX) {
const int tenths = (int)scaled;
snprintf(margin, sizeof(margin), ",catch=%d.%d", tenths / 10,
tenths < 0 ? -(tenths % 10) : tenths % 10);
}
}
// Overdrive has to be visible here, otherwise it reads as an ordinary level
// and nobody remembers it runs outside the datasheet rule.
int len = snprintf(reply, reply_size,
"> desired=%s,effective=%s,supported=%s,err=%d,fail=%lu,level=%lu%s%s,preamble=%lu,rx=%lu,sleep=%lu",
config->enabled ? "on" : "off", status.armed ? "armed" : "continuous",
status.supported ? "yes" : "no", (int)status.last_error,
(unsigned long)status.arm_failures, (unsigned long)config->level,
rxPowerSavingLevelTag(config->level), margin,
(unsigned long)config->preamble, (unsigned long)config->rx_us,
(unsigned long)config->sleep_us);
// Only report the periods the hardware really runs with when a driver had to
// clamp them - printing them always would not fit the 160 byte reply buffer.
if (len > 0 && (size_t)len < reply_size && status.armed &&
(status.effective_rx_us != config->rx_us ||
status.effective_sleep_us != config->sleep_us)) {
snprintf(reply + len, reply_size - (size_t)len, ",erx=%lu,eslp=%lu",
(unsigned long)status.effective_rx_us,
(unsigned long)status.effective_sleep_us);
}
}
#endif // WITH_RX_POWERSAVING
+18
View File
@@ -0,0 +1,18 @@
// CUSTOM (TeTeHacko): from EasySkyMesh PowerSaving v18 (IoTThinks/MeshCore,
// MIT, https://github.com/IoTThinks/MeshCore/tree/PowerSaving-v18) -- RXPS, the
// SX126x/LR11x0 RX duty cycle. Compiled only with -D WITH_RX_POWERSAVING.
#pragma once
#include <stddef.h>
#include "RXPowerSaving.h"
class RXPowerSavingCLI {
public:
static bool set(const char* value, uint8_t sf, float bw, RxPowerSavingConfig* config,
RxPowerSavingControl* control, char* reply, size_t reply_size);
// sf/bw are needed to turn the stored periods back into symbols, which is
// what the level scale is expressed in.
static void get(const RxPowerSavingConfig* config, const RxPowerSavingControl* control,
uint8_t sf, float bw, char* reply, size_t reply_size);
};
+249
View File
@@ -11,6 +11,12 @@
#define NUM_NOISE_FLOOR_SAMPLES 64
#define SAMPLING_THRESHOLD 14
#ifdef WITH_RX_POWERSAVING
#define NF_CALIB_INTERVAL_MS 60000UL // continuous-RX window for the noise floor, this often
#define NF_CALIB_TIMEOUT_MS 5000UL // ... and at most this long
#define NF_CALIB_SETTLE_MS 20UL // RSSI settles after leaving the duty cycle
#endif
static volatile uint8_t state = STATE_IDLE;
#ifdef RADIO_DIAG
static volatile uint32_t diag_isr_count = 0; // DIO1 edges that reached the MCU
@@ -56,6 +62,9 @@ uint32_t RadioLibWrapper::getRngSeed() {
}
void RadioLibWrapper::setTxPower(int8_t dbm) {
#ifdef WITH_RX_POWERSAVING
prepareForRadioConfig(); // PA config is a standby-only command
#endif
#if defined(USE_LR2021)
// Upstream 114093ee: on LR2021, setOutputPower() writes the PA config and
// TxParams, which are standby-only commands, and recvRaw() keeps state ==
@@ -73,6 +82,9 @@ void RadioLibWrapper::setTxPower(int8_t dbm) {
}
void RadioLibWrapper::idle() {
#ifdef WITH_RX_POWERSAVING
if (_rx_ps_armed) stopReceiveDutyCycle();
#endif
_radio->standby();
state = STATE_IDLE; // need another startReceive()
}
@@ -99,6 +111,13 @@ void RadioLibWrapper::resetAGC() {
// make sure we're not mid-receive of packet!
if ((state & STATE_INT_READY) != 0 || isReceivingPacket()) return;
#ifdef WITH_RX_POWERSAVING
if (_rx_ps_armed) stopReceiveDutyCycle();
// Duty cycling never samples RSSI outside a calibration window, so the
// reconvergence below has to have one: schedule it now. (Upstream RXPS
// recalibrates synchronously here -- up to ~0.3 s blocking the main loop.)
_nf_last_calib = 0;
#endif
doResetAGC();
state = STATE_IDLE; // trigger a startReceive()
@@ -143,6 +162,25 @@ void RadioLibWrapper::loop() {
pollIrq();
#endif
#ifdef WITH_RX_POWERSAVING
if (_rx_ps_restart_pending && (state & ~STATE_INT_READY) != STATE_TX_WAIT &&
!isPacketPendingOrReceiving()) {
_rx_ps_restart_pending = false;
requestRestartRecv();
}
noiseFloorCalibCheck();
if (state == STATE_RX && _num_floor_samples < NUM_NOISE_FLOOR_SAMPLES) {
// no RSSI while duty cycling (the chip sleeps between windows), nor in the
// settle time right after a calibration window opened
if (!_rx_ps_armed && !(_nf_calib_active && (long)(millis() - _nf_sample_from) < 0) &&
!isReceivingPacket()) {
sampleNoiseFloorOnce();
}
} else if (publishNoiseFloor()) {
if (_nf_calib_active) endNoiseFloorCalib(millis());
}
#else
if (state == STATE_RX && _num_floor_samples < NUM_NOISE_FLOOR_SAMPLES) {
if (!isReceivingPacket()) {
int rssi = getCurrentRSSI();
@@ -162,13 +200,18 @@ void RadioLibWrapper::loop() {
MESH_DEBUG_PRINTLN("RadioLibWrapper: noise_floor = %d", (int)_noise_floor);
#endif
}
#endif
}
void RadioLibWrapper::startRecv() {
#if defined(USE_LR2021)
_radio->standby(); // without this LR2021 can throw -706 when calling startReceive after hardware CAD when side detectors are enabled
#endif
#ifdef WITH_RX_POWERSAVING
int err = startReceiveMode();
#else
int err = _radio->startReceive();
#endif
if (err == RADIOLIB_ERR_NONE) {
state = STATE_RX;
} else {
@@ -176,6 +219,175 @@ void RadioLibWrapper::startRecv() {
}
}
#ifdef WITH_RX_POWERSAVING
// Clear the RX/idle state so the next loop calls startRecv() again, without
// dropping a STATE_INT_READY the ISR may raise meanwhile: a plain
// `state = STATE_IDLE` loses that flag -- and a received packet -- when setFlag()
// fires between the test and the store.
void RadioLibWrapper::requestRestartRecv() {
noInterrupts();
if ((state & ~STATE_INT_READY) != STATE_TX_WAIT) {
state &= STATE_INT_READY;
}
interrupts();
}
bool RadioLibWrapper::isPacketPendingOrReceiving() {
return (state & STATE_INT_READY) != 0 || isReceivingPacket();
}
void RadioLibWrapper::sampleNoiseFloorOnce() {
int rssi = getCurrentRSSI();
if (rssi < _noise_floor + SAMPLING_THRESHOLD) {
_num_floor_samples++;
_floor_sample_sum += rssi;
}
}
bool RadioLibWrapper::publishNoiseFloor() {
if (_num_floor_samples < NUM_NOISE_FLOOR_SAMPLES || _floor_sample_sum == 0) return false;
_noise_floor = _floor_sample_sum / NUM_NOISE_FLOOR_SAMPLES;
if (_noise_floor < -120) {
_noise_floor = -120; // clamp to lower bound of -120dBi
}
_floor_sample_sum = 0;
#ifdef MESH_DEBUG_NOISE_FLOOR
MESH_DEBUG_PRINTLN("RadioLibWrapper: noise_floor = %d", (int)_noise_floor);
#endif
return true;
}
void RadioLibWrapper::noiseFloorCalibCheck() {
unsigned long now = millis();
if (_nf_calib_active) {
if (!_rx_ps_enabled || (long)(now - _nf_calib_deadline) >= 0) {
endNoiseFloorCalib(now);
} else if (_rx_ps_armed && !isPacketPendingOrReceiving()) {
requestRestartRecv(); // a packet delayed the switch to continuous RX
}
} else if (_rx_ps_enabled && _rx_ps_armed && state == STATE_RX &&
(_nf_last_calib == 0 || now - _nf_last_calib >= NF_CALIB_INTERVAL_MS) &&
!isPacketPendingOrReceiving()) {
_nf_calib_active = true;
_nf_calib_deadline = now + NF_CALIB_TIMEOUT_MS;
_nf_sample_from = now + NF_CALIB_SETTLE_MS;
_num_floor_samples = 0;
_floor_sample_sum = 0;
requestRestartRecv(); // startReceiveMode() goes continuous while calibrating
}
}
void RadioLibWrapper::endNoiseFloorCalib(unsigned long now) {
_nf_calib_active = false;
_nf_last_calib = now;
if (!isPacketPendingOrReceiving()) requestRestartRecv();
}
int16_t RadioLibWrapper::startReceiveMode() {
// A preamble that arrived after the scheduler's idle check must not be
// aborted by stopping the duty cycle for a calibration window.
if (_nf_calib_active && _rx_ps_armed && isPacketPendingOrReceiving()) {
return RADIOLIB_ERR_NONE;
}
if (_rx_ps_armed) stopReceiveDutyCycle();
if (!_rx_ps_enabled || _nf_calib_active) {
_rx_ps_armed = false;
const int16_t err = startContinuousReceive();
_rx_ps_last_error = err;
return err;
}
if (!_rx_ps_arm_retry.canAttempt()) {
// arming failed repeatedly: continuous RX until the config changes
_rx_ps_armed = false;
const int16_t err = startContinuousReceive();
if (err != RADIOLIB_ERR_NONE) _rx_ps_last_error = err;
return err;
}
const RadioLibIrqFlags_t irq_flags =
RADIOLIB_IRQ_RX_DEFAULT_FLAGS | (1UL << RADIOLIB_IRQ_PREAMBLE_DETECTED);
const RadioLibIrqFlags_t irq_mask =
(1UL << RADIOLIB_IRQ_RX_DONE) | (1UL << RADIOLIB_IRQ_TIMEOUT) |
(1UL << RADIOLIB_IRQ_CRC_ERR) | (1UL << RADIOLIB_IRQ_HEADER_ERR);
uint32_t eff_rx_us = _rx_ps_rx_us;
uint32_t eff_sleep_us = _rx_ps_sleep_us;
int16_t err = armDutyCycle(irq_flags, irq_mask, &eff_rx_us, &eff_sleep_us);
if (err == RADIOLIB_ERR_NONE) {
_rx_ps_armed = true;
_rx_ps_last_error = RADIOLIB_ERR_NONE;
_rx_ps_arm_retry.recordSuccess();
_rx_ps_eff_rx_us = eff_rx_us;
_rx_ps_eff_sleep_us = eff_sleep_us;
return err;
}
_rx_ps_armed = false;
_rx_ps_last_error = err;
_rx_ps_eff_rx_us = 0;
_rx_ps_eff_sleep_us = 0;
n_rx_ps_arm_failures++;
_rx_ps_arm_retry.recordFailure();
MESH_DEBUG_PRINTLN("RadioLibWrapper: startReceiveDutyCycle(%d), continuous RX fallback", err);
stopDutyCycleHardware();
int16_t fallback_err = startContinuousReceive();
if (fallback_err != RADIOLIB_ERR_NONE) _rx_ps_last_error = fallback_err;
return fallback_err;
}
void RadioLibWrapper::stopReceiveDutyCycle() {
int16_t err = stopDutyCycleHardware();
_rx_ps_armed = false;
_rx_ps_eff_rx_us = 0;
_rx_ps_eff_sleep_us = 0;
if (err != RADIOLIB_ERR_NONE) _rx_ps_last_error = err;
}
bool RadioLibWrapper::isPacketReady() {
if (!_rx_ps_armed) return true;
return _radio->checkIrq(RADIOLIB_IRQ_RX_DONE) != 0;
}
void RadioLibWrapper::prepareForRadioConfig() {
if (!_rx_ps_armed) return;
stopReceiveDutyCycle();
requestRestartRecv();
}
bool RadioLibWrapper::setRxPowerSaving(bool enabled, uint32_t rx_us, uint32_t sleep_us) {
if (enabled && (!isValidRxPowerSavingPeriod(rx_us) || !isValidRxPowerSavingPeriod(sleep_us))) {
_rx_ps_enabled = false;
_rx_ps_last_error = RX_POWERSAVING_ERR_TIMING;
requestRestartRecv();
return false;
}
if (enabled && !supportsRxPowerSaving()) return false;
_rx_ps_enabled = enabled;
_rx_ps_rx_us = rx_us;
_rx_ps_sleep_us = sleep_us;
_rx_ps_last_error = RADIOLIB_ERR_NONE;
_rx_ps_arm_retry.reset(); // new config, a fresh chance for the hardware
_rx_ps_restart_pending = true;
if ((state & ~STATE_INT_READY) != STATE_TX_WAIT && !isPacketPendingOrReceiving()) {
_rx_ps_restart_pending = false;
requestRestartRecv();
}
return true;
}
RxPowerSavingStatus RadioLibWrapper::getRxPowerSavingStatus() const {
RxPowerSavingStatus status;
status.supported = supportsRxPowerSaving();
status.armed = _rx_ps_armed;
status.last_error = _rx_ps_config_error ? RX_POWERSAVING_ERR_TIMING : _rx_ps_last_error;
status.arm_failures = n_rx_ps_arm_failures;
status.effective_rx_us = _rx_ps_eff_rx_us;
status.effective_sleep_us = _rx_ps_eff_sleep_us;
return status;
}
#endif
bool RadioLibWrapper::isInRecvMode() const {
return (state & ~STATE_INT_READY) == STATE_RX;
}
@@ -183,7 +395,20 @@ bool RadioLibWrapper::isInRecvMode() const {
int RadioLibWrapper::recvRaw(uint8_t* bytes, int sz) {
int len = 0;
if (state & STATE_INT_READY) {
#ifdef WITH_RX_POWERSAVING
// While duty cycling DIO1 also carries timeouts; only a real RX_DONE has data.
if (isPacketReady()) {
if (_rx_ps_armed) stopReceiveDutyCycle();
len = _radio->getPacketLength();
if (len > 0) {
_last_snr = _radio->getSNR();
_last_rssi = _radio->getRSSI();
_last_metrics_valid = true;
}
}
#else
len = _radio->getPacketLength();
#endif
if (len > 0) {
if (len > sz) { len = sz; }
int err = _radio->readData(bytes, len);
@@ -210,12 +435,16 @@ int RadioLibWrapper::recvRaw(uint8_t* bytes, int sz) {
}
if (state != STATE_RX) {
#ifdef WITH_RX_POWERSAVING
startRecv(); // duty cycle or continuous, as configured
#else
int err = _radio->startReceive();
if (err == RADIOLIB_ERR_NONE) {
state = STATE_RX;
} else {
MESH_DEBUG_PRINTLN("RadioLibWrapper: error: startReceive(%d)", err);
}
#endif
}
return len;
}
@@ -225,6 +454,9 @@ uint32_t RadioLibWrapper::getEstAirtimeFor(int len_bytes) {
}
bool RadioLibWrapper::startSendRaw(const uint8_t* bytes, int len) {
#ifdef WITH_RX_POWERSAVING
if (_rx_ps_armed) stopReceiveDutyCycle();
#endif
_board->onBeforeTransmit();
int err = _radio->startTransmit((uint8_t *) bytes, len);
if (err == RADIOLIB_ERR_NONE) {
@@ -320,10 +552,19 @@ int RadioLibWrapper::probeDio1(uint32_t* irq_out, int* dio1_level, int* probe_le
bool RadioLibWrapper::isChannelActive() {
// int.thresh: RSSI-based interference detection (relative to noise floor)
#ifdef WITH_RX_POWERSAVING
// no RSSI read while the duty-cycling chip sleeps (BUSY high)
if (_threshold != 0 && !(_rx_ps_armed && isChipBusy()) &&
getCurrentRSSI() > _noise_floor + _threshold) return true;
#else
if (_threshold != 0 && getCurrentRSSI() > _noise_floor + _threshold) return true;
#endif
// cad: hardware channel activity detection
if (_cad_enabled) {
#ifdef WITH_RX_POWERSAVING
if (_rx_ps_armed) stopReceiveDutyCycle();
#endif
int16_t result = performChannelScan();
// scanChannel() triggers DIO interrupt (CAD done) which sets STATE_INT_READY
// via setFlag() ISR. Clear it before restarting RX so recvRaw() doesn't
@@ -337,9 +578,17 @@ bool RadioLibWrapper::isChannelActive() {
}
float RadioLibWrapper::getLastRSSI() const {
#ifdef WITH_RX_POWERSAVING
if (_last_metrics_valid) return _last_rssi;
if (_rx_ps_armed) return 0;
#endif
return _radio->getRSSI();
}
float RadioLibWrapper::getLastSNR() const {
#ifdef WITH_RX_POWERSAVING
if (_last_metrics_valid) return _last_snr;
if (_rx_ps_armed) return 0;
#endif
return _radio->getSNR();
}
+76 -1
View File
@@ -2,6 +2,15 @@
#include <Mesh.h>
#include <RadioLib.h>
#ifdef WITH_RX_POWERSAVING
// CUSTOM (TeTeHacko): RX duty cycle ("RXPS"), ported from EasySkyMesh PowerSaving
// v18 (IoTThinks/MeshCore, MIT). Build-flag only and off at runtime by default:
// without the flag this class is byte-for-byte what it was. See RXPowerSaving.h.
#include "RXPowerSaving.h"
#if defined(LORA_POLL_IRQ)
#error "WITH_RX_POWERSAVING and LORA_POLL_IRQ do not mix: polling the IRQ register wakes a duty-cycling chip"
#endif
#endif
#ifdef USE_CC310_HW_CRYPTO
#include <Adafruit_nRFCrypto.h>
@@ -11,7 +20,11 @@ struct PacketMillis {
uint32_t payloadMillis; // header-valid -> rx-done deadline
};
class RadioLibWrapper : public mesh::Radio {
class RadioLibWrapper : public mesh::Radio
#ifdef WITH_RX_POWERSAVING
, public RxPowerSavingControl
#endif
{
protected:
PhysicalLayer* _radio;
mesh::MainBoard* _board;
@@ -26,6 +39,51 @@ protected:
void idle();
void startRecv();
#ifdef WITH_RX_POWERSAVING
// RXPS state. _rx_ps_enabled = what the config asks for, _rx_ps_armed = the
// chip is duty cycling right now (cleared by anything that takes it out).
bool _rx_ps_restart_pending = false;
bool _rx_ps_config_error = false;
bool _rx_ps_enabled = false;
bool _rx_ps_armed = false;
uint32_t _rx_ps_rx_us = RX_POWERSAVING_DEFAULT_RX_US;
uint32_t _rx_ps_sleep_us = RX_POWERSAVING_DEFAULT_SLEEP_US;
uint32_t _rx_ps_eff_rx_us = 0; // periods the driver actually armed with
uint32_t _rx_ps_eff_sleep_us = 0;
int16_t _rx_ps_last_error = 0;
uint32_t n_rx_ps_arm_failures = 0;
RxPowerSavingArmRetryState _rx_ps_arm_retry;
// Noise floor while duty cycling: RSSI cannot be sampled in the sleep phase,
// so every NF_CALIB_INTERVAL the receiver goes continuous for a short window.
bool _nf_calib_active = false;
unsigned long _nf_last_calib = 0;
unsigned long _nf_calib_deadline = 0;
unsigned long _nf_sample_from = 0;
// RSSI/SNR of the last packet, read at RX: reading the registers later, with
// the chip asleep between windows, would wake it and return nothing useful.
float _last_rssi = 0, _last_snr = 0;
bool _last_metrics_valid = false;
void requestRestartRecv();
bool isPacketPendingOrReceiving();
void prepareForRadioConfig();
void sampleNoiseFloorOnce();
bool publishNoiseFloor();
void noiseFloorCalibCheck();
void endNoiseFloorCalib(unsigned long now);
int16_t startReceiveMode();
void stopReceiveDutyCycle();
// eff_rx_us/eff_sleep_us report the periods the driver really programmed.
virtual int16_t armDutyCycle(RadioLibIrqFlags_t irq_flags, RadioLibIrqFlags_t irq_mask,
uint32_t* eff_rx_us, uint32_t* eff_sleep_us) {
(void)irq_flags; (void)irq_mask; (void)eff_rx_us; (void)eff_sleep_us;
return RADIOLIB_ERR_UNSUPPORTED;
}
virtual int16_t stopDutyCycleHardware() { return _radio->standby(); }
virtual int16_t startContinuousReceive() { return _radio->startReceive(); }
virtual bool isPacketReady();
virtual bool isChipBusy() { return false; }
#endif
#ifdef LORA_POLL_IRQ
void pollIrq(); // CUSTOM (TeTeHacko): DIO1-less completion detection, see .cpp
#endif
@@ -41,7 +99,17 @@ public:
}
void begin() override;
#ifdef WITH_RX_POWERSAVING
virtual void powerOff() { if (_rx_ps_armed) stopReceiveDutyCycle(); _radio->sleep(); }
virtual bool supportsRxPowerSaving() const { return false; }
void setRxPowerSavingConfigError(bool invalid) override { _rx_ps_config_error = invalid; }
bool setRxPowerSaving(bool enabled, uint32_t rx_us, uint32_t sleep_us) override;
RxPowerSavingStatus getRxPowerSavingStatus() const override;
bool isRxPowerSavingCalibrationActive() const override { return _nf_calib_active; }
#else
virtual void powerOff() { _radio->sleep(); }
#endif
int recvRaw(uint8_t* bytes, int sz) override;
uint32_t getEstAirtimeFor(int len_bytes) override;
bool startSendRaw(const uint8_t* bytes, int len) override;
@@ -89,7 +157,14 @@ public:
void kickRx();
uint32_t getPacketsRecvErrors() const { return n_recv_errors; }
uint32_t getPacketsSent() const { return n_sent; }
#ifdef WITH_RX_POWERSAVING
void resetStats() {
n_recv = n_sent = n_recv_errors = n_rx_ps_arm_failures = 0;
_rx_ps_arm_retry.reset(); // a fresh set of arm attempts, see startReceiveMode()
}
#else
void resetStats() { n_recv = n_sent = n_recv_errors = 0; }
#endif
virtual float getLastRSSI() const override;
virtual float getLastSNR() const override;
@@ -114,6 +114,9 @@ static Adafruit_INA3221 INA3221;
#ifndef TELEM_INA219_ADDRESS
#define TELEM_INA219_ADDRESS 0x40 // INA219 single channel current sensor I2C address
#endif
#ifndef TELEM_INA219_SHUNT_VALUE
#define TELEM_INA219_SHUNT_VALUE 0.100 // CUSTOM (TeTeHacko): what Adafruit's calibration assumes
#endif
#include <Adafruit_INA219.h>
static Adafruit_INA219 INA219(TELEM_INA219_ADDRESS);
#endif
@@ -146,6 +149,18 @@ static class INA226 INA226_ALT(TELEM_INA226_ALT_ADDR(TELEM_INA226_ADDRESS), TELE
static class INA226* active_ina226 = &INA226; // `class`: the object INA226 hides the type
#endif
#if ENV_INCLUDE_INA219 || ENV_INCLUDE_INA226 || ENV_INCLUDE_INA3221
// CUSTOM (TeTeHacko): the shunt is a property of the module, not of the
// firmware -- `sensor set ina.shunt <mOhm>`, kept in prefs (ina_shunt), 0 = the
// build's value for the chip. INA219/INA226 current is computed here from the
// shunt voltage (as in the Chytra Budka), so a new value needs no recalibration;
// INA3221 gets it through its driver.
static float ina_shunt_mohm = 0;
static float ina_shunt_ohm(float build_default) {
return ina_shunt_mohm > 0 ? ina_shunt_mohm / 1000.0f : build_default;
}
#endif
#if ENV_INCLUDE_MLX90614
#ifndef TELEM_MLX90614_ADDRESS
#define TELEM_MLX90614_ADDRESS 0x5A // MLX90614 IR temperature sensor I2C address
@@ -326,7 +341,7 @@ static void query_lps22hb(uint8_t ch, uint8_t, CayenneLPP& lpp) {
static uint8_t init_ina3221(TwoWire* wire, uint8_t addr) {
if (!INA3221.begin(addr, wire)) return 0;
for (int i = 0; i < TELEM_INA3221_NUM_CHANNELS; i++) {
INA3221.setShuntResistance(i, TELEM_INA3221_SHUNT_VALUE);
INA3221.setShuntResistance(i, ina_shunt_ohm(TELEM_INA3221_SHUNT_VALUE));
}
// Each enabled hardware channel becomes its own telemetry channel.
uint8_t enabled = 0;
@@ -401,9 +416,11 @@ static void query_ina219(uint8_t ch, uint8_t, CayenneLPP& lpp) {
// begin() selects 12-bit single-sample bus and shunt conversions, 532 us each:
// 3 ms covers the wake-up and one fresh pair with margin.
delay(3);
lpp.addVoltage(ch, active_ina219->getBusVoltage_V());
lpp.addCurrent(ch, active_ina219->getCurrent_mA() / 1000.0f);
lpp.addPower(ch, active_ina219->getPower_mW() / 1000.0f);
const float volts = active_ina219->getBusVoltage_V();
const float amps = active_ina219->getShuntVoltage_mV() / 1000.0f / ina_shunt_ohm(TELEM_INA219_SHUNT_VALUE);
lpp.addVoltage(ch, volts);
lpp.addCurrent(ch, amps);
lpp.addPower(ch, volts * amps);
active_ina219->powerSave(true);
}
#endif
@@ -451,9 +468,11 @@ static void query_ina226(uint8_t ch, uint8_t, CayenneLPP& lpp) {
ina->shutDown();
return;
}
lpp.addVoltage(ch, ina->getBusVoltage());
lpp.addCurrent(ch, ina->getCurrent_mA() / 1000.0f);
lpp.addPower(ch, ina->getPower_mW() / 1000.0f);
const float volts = ina->getBusVoltage();
const float amps = ina->getShuntVoltage() / ina_shunt_ohm(TELEM_INA226_SHUNT_VALUE);
lpp.addVoltage(ch, volts);
lpp.addCurrent(ch, amps);
lpp.addPower(ch, volts * amps);
ina->shutDown();
}
#endif
@@ -820,11 +839,21 @@ bool EnvironmentSensorManager::querySensors(uint8_t requester_permissions, Cayen
}
// CUSTOM (TeTeHacko): an INA chip whose shunt `ina.shunt` applies to is active.
bool EnvironmentSensorManager::hasShuntIna() const {
for (int j = 0; j < _active_sensor_count; j++) {
const char* n = _active_sensors[j].name;
if (n && (strcmp(n, "INA219") == 0 || strcmp(n, "INA226") == 0 || strcmp(n, "INA3221") == 0)) return true;
}
return false;
}
int EnvironmentSensorManager::getNumSettings() const {
int settings = 0;
#if ENV_INCLUDE_GPS
if (gps_detected) settings += 1; // GPS enablement
#endif
if (hasShuntIna()) settings += 1; // ina.shunt
return settings;
}
@@ -835,6 +864,7 @@ const char* EnvironmentSensorManager::getSettingName(int i) const {
return "gps";
}
#endif
if (hasShuntIna() && i == settings++) return "ina.shunt";
return NULL;
}
@@ -849,10 +879,34 @@ const char* EnvironmentSensorManager::getSettingValue(int i) const {
return _location->isGpsOn() ? "1" : "0";
}
#endif
#if ENV_INCLUDE_INA219 || ENV_INCLUDE_INA226 || ENV_INCLUDE_INA3221
if (hasShuntIna() && i == settings++) {
static char buf[16]; // mOhm; 0 = the build's value
snprintf(buf, sizeof(buf), "%.3f", ina_shunt_mohm);
return buf;
}
#endif
return NULL;
}
bool EnvironmentSensorManager::setSettingValue(const char* name, const char* value) {
#if ENV_INCLUDE_INA219 || ENV_INCLUDE_INA226 || ENV_INCLUDE_INA3221
if (strcmp(name, "ina.shunt") == 0) {
if (!hasShuntIna()) return false;
// a number of mOhm, 0 = the build's value; atof() alone would take "nan"
const char* c = value;
if (!((*c >= '0' && *c <= '9') || *c == '.')) return false;
float mohm = atof(value);
if (!(mohm >= 0.0f && mohm <= 10000.0f)) return false;
ina_shunt_mohm = mohm;
#if ENV_INCLUDE_INA3221
for (int i = 0; i < TELEM_INA3221_NUM_CHANNELS; i++) {
INA3221.setShuntResistance(i, ina_shunt_ohm(TELEM_INA3221_SHUNT_VALUE));
}
#endif
return true;
}
#endif
#if ENV_INCLUDE_GPS
if (gps_detected && strcmp(name, "gps") == 0) {
if (strcmp(value, "0") == 0) {
@@ -58,4 +58,5 @@ public:
const char* getSettingValue(int i) const override;
bool setSettingValue(const char* name, const char* value) override;
int scanI2C(char* dest, size_t max_len) override;
bool hasShuntIna() const; // CUSTOM (TeTeHacko): `ina.shunt` applies
};
+61
View File
@@ -0,0 +1,61 @@
<!-- SPDX-License-Identifier: MIT -->
# tools/
Host-side tools for MeshCore nodes of this fork: consoles, flashing, bench
tests and diagnostics. Every script answers `--help` without touching a port,
a node or the network.
## Your boards: the local config
The tools carry no board serial, MAC or host of anyone's bench. Names like
`b1` resolve through one file outside the repo:
~/.config/meshcore-tools/config.ini (or $MESHCORE_TOOLS_CONFIG)
Start from [`config.example.ini`](config.example.ini); the format and the shell
interface are in `mctools_config.py --help`. Without a config everything still
works with full USB serial numbers, BLE MACs and port paths. Two fields matter
for safety: `protect` (flashing tools refuse the board unless told to) and
`refuse` (console tools do not open it at all, e.g. the radio of an observer
running other firmware). No secrets go in there.
Serial ports are always matched in `/dev/serial/by-id` by the USB serial
number: a `ttyACM` number changes with every replug and would point a tool at
a different board.
## Consoles
| tool | what |
|---|---|
| `serial_cli.py` | text console over USB: send commands, print the replies |
| `ble_cli.py` | the same console over BLE (Nordic UART); needs a bonded node |
| `ble_pair.py` | non-interactive BLE pairing by PIN (bluetoothctl over a pty) |
| `serial_tcp_proxy.py` | a board's USB console on a localhost TCP port, for a board on another host (SSH tunnel) |
## Flashing
| tool | what |
|---|---|
| `flash_node.sh` | flash any board: picks USB DFU, UF2 or BLE from what the board is doing, refuses `protect`ed boards |
| `xiao_uf2_flash.sh` | XIAO nRF52840 through its UF2 drive, to a named board, verified by reading the version back |
| `xiao_serial_dfu.sh` | XIAO with a text console over USB serial DFU: no drive, no mount, no root |
| `ble_flash_node.sh` | BLE OTA of a node out of reach of a cable, with the checks around it (silence, services, version) |
| `ble_dfu.py` | legacy Nordic DFU over BLE for the Adafruit nRF52 bootloader (buttonless, both phases) |
| `build_version.py` | PlatformIO pre-script: real version and build time for `ver` |
## Bench and diagnostics
| tool | what |
|---|---|
| `board_probe.py` | what runs on each board on USB, and whether that changed |
| `fleet_test.py` | regression smoke test of the bench boards after a firmware change |
| `bench_soak.py` | long run: who hears whom over time, when a board reboots or goes deaf |
| `radio_stall_watch.py` | watch a `RADIO_DIAG` node until its receiver stalls |
| `mesh_sniffer.py` | passive sniffer: every frame the radio hears, decoded on the host |
| `preset_trace.py` | TRACE along a fixed path on a chosen radio preset |
| `fw_room_smoke.py` | smoke test of a firmware room server over the air |
| `power_ab.py` | A/B current measurement with a UC96 meter (alternating cells) |
| `companion_backup.py` | back up a companion (contacts, channels, settings) before flashing, diff and restore after |
| `gen_node_id.py` | a node identity whose path hash collides with no known repeater |
`fleet.py` and `mctools_config.py` are the shared board lookup.
+247
View File
@@ -0,0 +1,247 @@
#!/usr/bin/env python3
# SPDX-License-Identifier: MIT
"""Dlouhý běh lavice: kdo koho slyší, v čase, a kdy deska rebootuje nebo ohluchne.
Vzniklo 23. 9. 2026 kvůli second-mast: po OTA na nový firmware přestala přijímat
(`recv 0`) a na zerohop hlásila `sent 0` + `tx_timeout 4`, přestože ob2 vedle ní
slyšel všechny čtyři adverty. Rádio vysílalo, ale IRQ se nedostalo do MCU.
`fleet_test.py` je jednorázový snímek za pár sekund -- tohle je stejná otázka
položená stokrát za sebou, protože chyba přišla až po minutách běhu.
tools/bench_soak.py --boards b1,b2 --hours 8
tools/bench_soak.py --period 30 --out /tmp/soak # all bench boards of the config
Co dělá, v kolech (každých --period s, vysílá jedna deska, dokola):
1. snímek `stats-packets` a `stats-core` na všech deskách,
2. vysílající pošle `advert.zerohop` (nikdo ho nerebroadcastuje, takže
„B slyšel A" nejde splnit přes třetí desku a netřeba sahat na `repeat`),
3. po --settle s druhý snímek.
Orákulum je vždy JINÁ deska: slyšel = `recv` příjemce vzrostl. Vlastní `sent`
vysílajícího se jen zapisuje vedle -- u second-mast lhal (0, zatímco vysílala).
Konzole se drží otevřené celou dobu a KAŽDÝ řádek jde s časem do logu, takže se
zachytí i to, co deska vypíše sama (boot `RESETREAS`, `!!! HARDFAULT`). Když
deska zmizí z USB, nástroj to zapíše a čeká, až se vrátí -- nic nerestartuje.
Nic nemění: žádné `set`, žádné `reboot`. Prefs pro test nastav předem ručně.
PAST (z fleet_test.py): na testované desce nesmí viset BLE klient -- USB a BLE
konzole dělí jeden buffer a prokládají znaky.
"""
import argparse
import glob
import json
import os
import re
import signal
import sys
import threading
import time
from datetime import datetime, timezone
sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
from board_probe import _open as open_port
from fleet import serial_for
FLAG_RE = re.compile(r"boot:|RESETREAS|HARDFAULT|LOCKUP|WATCHDOG", re.IGNORECASE)
def now():
return datetime.now(timezone.utc).isoformat(timespec="seconds")
class Board:
"""Jedna konzole: čtecí vlákno loguje vše, `cmd()` sbírá odpověď z okna."""
def __init__(self, name, log_fh, events):
self.name = name
self.sn = serial_for(name)
self.log = log_fh
self.events = events
self.s = None
self.lines = [] # řádky od posledního cmd()
self.lock = threading.Lock()
self.stop = False
self.up = False
threading.Thread(target=self._reader, daemon=True).start()
def _path(self):
hits = [p for p in glob.glob("/dev/serial/by-id/*") if self.sn in p]
return hits[0] if len(hits) == 1 else None
def _event(self, kind, **kw):
ev = {"t": now(), "board": self.name, "event": kind, **kw}
self.events.append(ev)
self.log.write(json.dumps(ev, ensure_ascii=False) + "\n")
self.log.flush()
print(f"[{ev['t']}] {self.name}: {kind} {kw if kw else ''}", flush=True)
def _reader(self):
buf = b""
while not self.stop:
if self.s is None:
p = self._path()
if p:
try:
self.s = open_port(p)
if self.up is False and self.events is not None:
self._event("usb_up", port=os.path.basename(p))
self.up = True
except Exception:
self.s = None
time.sleep(1)
continue
try:
d = self.s.read(4096)
except Exception as e:
self._event("usb_gone", err=str(e)[:80])
self.up = False
try:
self.s.close()
except Exception:
pass
self.s = None
continue
if not d:
time.sleep(0.02)
continue
buf += d
while b"\n" in buf:
raw, buf = buf.split(b"\n", 1)
line = raw.decode("utf-8", "replace").rstrip("\r")
if not line.strip():
continue
self.log.write(f"{now()} {self.name} | {line}\n")
if FLAG_RE.search(line):
self._event("flagged_line", line=line[:200])
with self.lock:
self.lines.append(line)
self.log.flush()
def cmd(self, text, window=1.5):
if self.s is None:
return None
with self.lock:
self.lines = []
try:
self.s.write((text + "\r").encode())
except Exception:
return None
time.sleep(window)
with self.lock:
return "\n".join(self.lines)
def stats(self):
out = {}
for c in ("stats-packets", "stats-core"):
r = self.cmd(c)
m = re.search(r"\{.*\}", r or "")
if not m:
return None
try:
out.update(json.loads(m.group(0)))
except ValueError:
return None
return out
def main():
ap = argparse.ArgumentParser(description=__doc__,
formatter_class=argparse.RawDescriptionHelpFormatter)
ap.add_argument("--boards", default=None,
help="desky z lokalniho configu, čárkou (default: všechny role=bench bez refuse)")
ap.add_argument("--hours", type=float, default=8.0)
ap.add_argument("--period", type=float, default=60.0, help="s mezi koly")
ap.add_argument("--settle", type=float, default=4.0, help="s po advertu")
ap.add_argument("--out", default=".", help="adresář na log + JSONL")
a = ap.parse_args()
if a.boards is None:
from mctools_config import by_role
a.boards = ",".join(n for n, b in by_role("bench").items() if b.get("serial") and not b.get("refuse"))
if not a.boards:
ap.error("no --boards and no role=bench board in the local config (tools/mctools_config.py)")
os.makedirs(a.out, exist_ok=True)
stamp = datetime.now().strftime("%Y%m%d-%H%M%S")
log = open(os.path.join(a.out, f"soak-{stamp}.log"), "a")
rounds_fh = open(os.path.join(a.out, f"soak-{stamp}.jsonl"), "a")
events = []
boards = [Board(n.strip(), log, events) for n in a.boards.split(",")]
if len(boards) < 2:
sys.exit("potřeba aspoň dvě desky -- svědkem musí být JINÁ deska")
stop = {"v": False}
signal.signal(signal.SIGINT, lambda *_: stop.update(v=True))
signal.signal(signal.SIGTERM, lambda *_: stop.update(v=True))
time.sleep(3)
last_up = {}
pairs = {} # (tx, rx) -> [heard, tried]
miss_streak = {} # (tx, rx) -> po sobě jdoucí neslyšení
reboots = {b.name: 0 for b in boards}
txto = {b.name: 0 for b in boards}
t_end = time.time() + a.hours * 3600
rnd = 0
while not stop["v"] and time.time() < t_end:
t0 = time.time()
tx = boards[rnd % len(boards)]
before = {b.name: b.stats() for b in boards}
ok = tx.cmd("advert.zerohop", window=1.0)
time.sleep(a.settle)
after = {b.name: b.stats() for b in boards}
rec = {"t": now(), "round": rnd, "tx": tx.name,
"tx_cmd_ok": bool(ok and "OK" in ok), "heard": {}, "boards": {}}
for b in boards:
s0, s1 = before[b.name], after[b.name]
rec["boards"][b.name] = s1
if s1 and "uptime_secs" in s1:
u = s1["uptime_secs"]
if b.name in last_up and u < last_up[b.name]:
reboots[b.name] += 1
b._event("reboot", uptime_before=last_up[b.name], uptime_now=u)
last_up[b.name] = u
if s0 and s1:
d_to = s1.get("tx_timeout", 0) - s0.get("tx_timeout", 0)
if d_to > 0:
txto[b.name] += d_to
b._event("tx_timeout", delta=d_to)
if b is tx or not (s0 and s1):
continue
heard = s1.get("recv", 0) - s0.get("recv", 0) >= 1
rec["heard"][b.name] = heard
key = (tx.name, b.name)
h = pairs.setdefault(key, [0, 0])
h[1] += 1
h[0] += int(heard)
miss_streak[key] = 0 if heard else miss_streak.get(key, 0) + 1
if miss_streak[key] == 3:
b._event("deaf?", tx=tx.name, streak=3,
note="3 kola po sobě neslyšel -- ověř svědkem")
tb, ta = before[tx.name], after[tx.name]
if tb and ta:
rec["tx_sent_delta"] = ta.get("sent", 0) - tb.get("sent", 0)
rounds_fh.write(json.dumps(rec, ensure_ascii=False) + "\n")
rounds_fh.flush()
rnd += 1
time.sleep(max(0.0, a.period - (time.time() - t0)))
for b in boards:
b.stop = True
summary = {
"rounds": rnd,
"pairs": {f"{k[0]}->{k[1]}": f"{v[0]}/{v[1]}" for k, v in sorted(pairs.items())},
"reboots": reboots,
"tx_timeouts": txto,
"events": len(events),
}
print(json.dumps(summary, ensure_ascii=False, indent=1))
rounds_fh.write(json.dumps({"summary": summary}, ensure_ascii=False) + "\n")
bad = any(v for v in reboots.values()) or any(v for v in txto.values()) or \
any(v[0] < v[1] for v in pairs.values())
sys.exit(1 if bad else 0)
if __name__ == "__main__":
main()
+184
View File
@@ -0,0 +1,184 @@
#!/usr/bin/env python3
# SPDX-License-Identifier: MIT
"""Text console of a MeshCore node over BLE (Nordic UART Service).
The same console you get on USB serial, but wireless -- which is the only way
in once a node is mounted somewhere without a cable. Works against any build
that has `BLE_PIN_CODE` set (repeater, room server, companion_radio_ble).
Why this exists as a tool rather than a snippet: the NUS write has a size limit
that is easy to miss and fails in a misleading way (see CHUNK below), and the
BlueZ/bleak connect path needs retries to be usable for anything longer than a
single command. Every ad-hoc script re-learned both the hard way.
# single command (a MAC, or a board name from the local config)
ble_cli.py AA:BB:CC:DD:EE:10 ver
ble_cli.py hill-rpt ver
# several, one connection
ble_cli.py AA:BB:CC:DD:EE:10 "get radio" "get name" stats-radio
# from a file, one command per line, '#' comments ignored
ble_cli.py AA:BB:CC:DD:EE:10 -f provision.txt
# {epoch} expands to the host's current unix time -- the point being that a
# provisioning FILE can carry `time {epoch}`, which a shell cannot reach
ble_cli.py AA:BB:CC:DD:EE:10 "time {epoch}"
# keep reconnecting per command (slow, but survives a flaky link)
ble_cli.py AA:BB:CC:DD:EE:10 --per-command "gps on" "set af 9"
PAIRING: the console characteristics are SECMODE_ENC_WITH_MITM, so the node
must be bonded first or the connect pops a passkey dialog on the desktop:
bluetoothctl --agent KeyboardOnly # then: pair <MAC>, enter the BLE PIN
`erase` on the node wipes the bond too (bonds live in InternalFS), so re-pair
after one.
CAUTION: one console at a time. USB and BLE read into the same command buffer
in the firmware (`simple_repeater/main.cpp`, "commands share the buffer"), so
two consoles at once interleave into one line and can crash the node.
"""
import argparse
import asyncio
import sys
import time
from bleak import BleakClient, BleakScanner
NUS_RX = "6e400002-b5a3-f393-e0a9-e50e24dcca9e" # write (host -> node)
NUS_TX = "6e400003-b5a3-f393-e0a9-e50e24dcca9e" # notify (node -> host)
# A NUS write carries at most ATT_MTU-3 bytes, and BlueZ will not split it for
# you. At the default MTU of 23 that is 20 bytes -- and MeshCore nodes are
# routinely left at 23. A longer write is rejected with
# "[org.bluez.Error.Failed] Failed to initiate write", which reads like a
# dropped link rather than "your command was too long": commands up to 18
# characters work and everything longer fails, deterministically. Hence chunking
# every write, always.
CHUNK = 20
def log(*a):
print(*a, file=sys.stderr, flush=True)
async def send(client, buf, cmd, wait):
buf.clear()
# {epoch} -> host unix time, expanded HERE rather than at parse time so that
# it is the time the command is actually sent: --per-command reconnects cost
# seconds each, and a whole -f file can take minutes.
#
# It exists for `time {epoch}` in a provisioning file. -f reads lines verbatim,
# so a `$(date +%s)` in one is sent as literal text and the node answers
# "Unknown command" -- which is why the clock line in a provisioning file
# was a commented-out note telling you to substitute the epoch by hand. Every
# clock in this firmware is volatile without GPS or an I2C RTC, and a node
# whose RTC still says May 2024 has its adverts dropped as replays.
cmd = cmd.replace("{epoch}", str(int(time.time())))
data = (cmd + "\r\n").encode()
for i in range(0, len(data), CHUNK):
await client.write_gatt_char(NUS_RX, data[i:i + CHUNK], response=False)
await asyncio.sleep(0.15)
await asyncio.sleep(wait)
out = bytes(buf).decode("utf-8", "replace").strip()
# the node echoes nothing, but replies are prefixed "-> " or "> "
for p in ("-> ", "> "):
if out.startswith(p):
out = out[len(p):]
# the EXPANDED command goes back too, so the printout says what was really
# sent rather than the `{epoch}` template
return cmd, out.strip()
async def run(mac, cmds, wait, per_command, tries):
async def connect():
last = None
for attempt in range(tries):
try:
dev = await BleakScanner.find_device_by_address(mac, timeout=20)
if dev is None:
# a connected peripheral stops advertising; a stale link on
# the adapter is the usual reason it cannot be found
raise RuntimeError(f"{mac} not advertising (already connected?)")
c = BleakClient(dev, timeout=30)
await c.connect()
return c
except Exception as e: # noqa: BLE001
last = e
log(f" [connect {attempt + 1}/{tries}] {type(e).__name__}: {e}")
await asyncio.sleep(4)
raise SystemExit(f"cannot connect to {mac}: {last}")
results = []
if per_command:
for cmd in cmds:
c = await connect()
try:
buf = bytearray()
await c.start_notify(NUS_TX, lambda _h, d: buf.extend(d))
results.append(await send(c, buf, cmd, wait))
finally:
await c.disconnect()
await asyncio.sleep(2)
else:
c = await connect()
try:
buf = bytearray()
await c.start_notify(NUS_TX, lambda _h, d: buf.extend(d))
for cmd in cmds:
results.append(await send(c, buf, cmd, wait))
finally:
await c.disconnect()
return results
def _mac(key):
"""A board name from the local config (tools/mctools_config.py) -> its MAC.
Optional on purpose: ble_flash_node.sh --via copies this file ALONE to a
remote host, where there is no config and a MAC is given anyway."""
try:
from mctools_config import mac_for
except ImportError:
return key
return mac_for(key) or key
def main():
ap = argparse.ArgumentParser(description=__doc__,
formatter_class=argparse.RawDescriptionHelpFormatter)
ap.add_argument("mac", help="BLE address of the node, or its name in the local config")
ap.add_argument("cmds", nargs="*", help="console commands")
ap.add_argument("-f", "--file", help="read commands from a file, one per line")
ap.add_argument("-w", "--wait", type=float, default=3.0,
help="seconds to collect the reply (default 3; raise for "
"paged output like rxlog/nodes)")
ap.add_argument("--per-command", action="store_true",
help="reconnect for every command -- slower, but survives a "
"link that drops mid-sequence")
ap.add_argument("--tries", type=int, default=5, help="connect attempts")
# intermixed, not plain parse_args: with a trailing `cmds` of nargs="*", an
# option BETWEEN the MAC and the commands (`<MAC> -w 8 rxlog`, the form this
# tool's own help suggests) makes argparse on Python <= 3.12 drop the
# commands with "unrecognized arguments". 3.13 fixed it, so it works on an
# Arch workstation and fails on the Debian hosts (bridge-host, cabin-host) that are
# the only way to reach a mast node -- exactly where you cannot debug it.
a = ap.parse_intermixed_args()
a.mac = _mac(a.mac)
cmds = list(a.cmds)
if a.file:
with open(a.file) as fh:
cmds += [ln.strip() for ln in fh
if ln.strip() and not ln.lstrip().startswith("#")]
if not cmds:
ap.error("no commands given")
for cmd, out in asyncio.run(run(a.mac, cmds, a.wait, a.per_command, a.tries)):
print(f"{cmd}\t{out}")
if __name__ == "__main__":
main()
+363
View File
@@ -0,0 +1,363 @@
#!/usr/bin/env python3
# SPDX-License-Identifier: MIT
"""Legacy Nordic DFU (SDK ~11, dfu_version 0.5) over BLE pro Adafruit nRF52 bootloader.
Generický BlueZ adaptér přes bleak (bez Nordic donglu).
Fáze 1: připoj běžící APP, enable notify na 1531, zapiš 0x01 (buttonless) → reboot do bootloaderu.
Fáze 2: reconnect na bootloader (advertuje 1530 DFU svc), proveď START/INIT/IMAGE(PRN)/VALIDATE/ACTIVATE.
BLE DFU je flaky (dropnutá receipt notif → přenos spadne). Fáze 2 se proto
auto-retryuje: po pádu pošle RESET (bootloader → čistý IDLE) a zkusí znovu.
Použití: ble_dfu.py <zip> <ble-mac> [phase1|phase2]
phase1 JEN buttonless reboot do bootloaderu, pak skončí (flash si dodělá
volající — po USB je to ~20 s místo minut po BLE)
phase2 přeskočí fázi 1 (buttonless) — použij když uzel UŽ visí v bootloaderu
(advertuje SCAP_DFU), např. po přerušeném DFU. Zotavení bez power-cycle.
"""
import asyncio
import os
import re
import struct
import sys
import zipfile
from bleak import BleakClient, BleakScanner
DFU_SVC = "00001530-1212-efde-1523-785feabcd123"
CP_UUID = "00001531-1212-efde-1523-785feabcd123" # control point (write+notify)
PKT_UUID = "00001532-1212-efde-1523-785feabcd123" # packet (write-no-resp)
# opcody
START_DFU, INIT_DFU, RECEIVE_FW, VALIDATE, ACTIVATE_RESET, RESET, REPORT, PKT_RCPT_REQ = 1,2,3,4,5,6,7,8
RESP, PKT_RCPT = 0x10, 0x11
class Notif:
def __init__(self): self.q = asyncio.Queue()
def cb(self, _h, data): self.q.put_nowait(bytes(data))
async def wait(self, timeout=30):
return await asyncio.wait_for(self.q.get(), timeout)
def log(*a): print(*a, flush=True)
async def expect_resp(nf, opcode, timeout=30):
while True:
d = await nf.wait(timeout)
if d and d[0] == RESP and d[1] == opcode:
if d[2] != 1:
raise RuntimeError(f"DFU resp opcode {opcode} status {d[2]} (fail)")
return d
if d and d[0] == PKT_RCPT:
continue # receipt, ignoruj tady
log(" (neočekávaná notif:", d.hex(), ")")
def mac_plus_one(mac):
p = mac.upper().split(":")
p[-1] = "%02X" % ((int(p[-1], 16) + 1) & 0xFF)
return ":".join(p)
async def find(mac, want_dfu=False, timeout=30):
"""Najdi zařízení. POZOR: běžící APP inzeruje DFU službu taky (kvůli
buttonless), takže 'want_dfu' NESMÍ matchovat jen podle DFU svc -> spletl by
si app s bootloaderem. Bootloader advertuje SCAP_DFU na MAC+1 (SenseCap na
stožáru) NEBO AdaDFU na TÉŽE MAC (XIAO, novější SenseCap Solar).
ADRESA JE POVINNÁ. Dřív stačil název obsahující "DFU" bez ohledu na adresu a
bralo se prostě první zařízení ze skenu -- s víc deskami v bootloaderu
najednou to sáhne na cizí. Stalo se: cíl CE:72:…:02, připojilo se
FE:11:…:C4. Zachytilo se to jen proto, že se log četl ručně; o pár sekund
později by START_DFU přepsal jinou desku."""
boot_mac = mac_plus_one(mac)
log(f" scan (want_dfu={want_dfu}, mac={mac}, boot={boot_mac})...")
devs = await BleakScanner.discover(timeout=timeout, return_adv=True)
cand, rejected = [], []
for d, adv in devs.values():
addr = d.address.upper()
has_dfu = DFU_SVC in [u.lower() for u in (adv.service_uuids or [])]
name = (d.name or adv.local_name or "")
if want_dfu:
if not has_dfu:
continue
looks_like_dfu = "DFU" in name.upper()
right_addr = addr in (boot_mac, mac.upper())
if looks_like_dfu and right_addr:
cand.append((d, adv, 0))
elif looks_like_dfu:
rejected.append(f"{addr} {name!r}")
elif addr == mac.upper():
cand.append((d, adv, 1))
cand.sort(key=lambda x: x[2])
for d, adv, _ in cand:
log(f" kandidát: {d.address} {d.name!r} dfu={DFU_SVC in [u.lower() for u in (adv.service_uuids or [])]}")
if rejected:
log(f" (v bootloaderu i CIZÍ desky, ignoruji: {', '.join(rejected)})")
return cand[0][0] if cand else None
async def connect_app(mac, tries=5):
"""Scan + connect s opakováním, jako to dělá ble_cli.py.
Jediný pokus NESTAČÍ a stálo to 22. 8. 2026 hodinu na second-mast: BLE konzole
(`ble_cli.py ver`) na tomtéž uzlu a z téhož hostu prošla bez zaváhání, kdežto
DFU umřelo na `TimeoutError` z `local_disconnect_monitor_event.wait()`. Rozdíl
NEBYL v uzlu, v bondu ani ve vzdálenosti (−64 dBm) — jen v tom, že ble_cli
connect opakuje a tady se zkoušel jednou. Vypadá to jako mrtvá deska, a není.
"""
last = None
for attempt in range(tries):
try:
dev = await BleakScanner.find_device_by_address(mac, timeout=25)
if dev is None:
# připojený peripheral přestane advertovat -- obvyklý důvod je
# viset spojení na adaptéru
raise RuntimeError("APP nenalezen ve scanu (už připojený?)")
c = BleakClient(dev, timeout=30)
await c.connect()
return c
except Exception as e: # noqa: BLE001
last = e
log(f" [connect {attempt + 1}/{tries}] {type(e).__name__}: {str(e)[:60]}")
await asyncio.sleep(4)
raise RuntimeError(f"APP nenalezen ve scanu / connect selhal: {last}")
async def phase1_buttonless(mac):
log("== FÁZE 1: buttonless reboot do bootloaderu ==")
c = await connect_app(mac)
try:
log(" připojen k APP, is_connected:", c.is_connected)
svcs = [s.uuid.lower() for s in c.services]
if DFU_SVC not in svcs:
raise RuntimeError("APP nemá DFU službu 1530")
nf = Notif()
await c.start_notify(CP_UUID, nf.cb) # write-authorize vyžaduje notify enabled
try:
await c.write_gatt_char(CP_UUID, bytes([START_DFU]), response=True)
except Exception as e:
log(" (write 0x01 → disconnect, očekávané):", type(e).__name__)
finally:
# write 0x01 uzel odpojí sám, takže disconnect() tu obvykle jen uklízí
try:
await c.disconnect()
except Exception: # noqa: BLE001
pass
log(" APP odpojen, čekám na reboot bootloaderu...")
await asyncio.sleep(4)
class ImageDone(Exception):
"""Bootloader potvrdil celý image dřív, než smyčka došla na PRN práh."""
class ChunkTooBig(Exception):
"""Bootloader neodpověděl na první receipt -> nezvládá velké pakety."""
async def send_image(c, nf, pkt_char, data, prn=8, chunk=None):
if chunk is None:
mtu = getattr(c, "mtu_size", 23) or 23
chunk = max(20, mtu - 3)
log(f" posílám image {len(data)} B, chunk {chunk} B, PRN {prn}")
sent = 0
since_rcpt = 0
total = len(data)
for off in range(0, total, chunk):
piece = data[off:off+chunk]
await c.write_gatt_char(pkt_char, piece, response=False)
sent += len(piece)
since_rcpt += 1
if prn and since_rcpt >= prn:
since_rcpt = 0
# počkej na receipt [0x11, <4B received>]
while True:
try:
d = await nf.wait(60)
except asyncio.TimeoutError:
# Ticho po PRVNÍ skupině = bootloader ty pakety vůbec
# nepobral. Není to congestion, ale velikost: legacy DFU
# (SDK 11) na některých bootloaderech bere jen 20 B, a když
# BlueZ vyjedná MTU 247, posíláme 244 B a přenos umře pod
# 48 kB. Pozorováno: XIAO nRF52840 (AdaDFU, MTU 247) padá,
# SenseCap Solar (AdaDFU, MTU zůstane 23) i mast-three
# (SCAP_DFU na MAC+1, MTU 247) jedou. Volající to zkusí
# znovu s 20 B.
if sent <= prn * chunk and chunk > 20:
raise ChunkTooBig()
raise
if d and d[0] == PKT_RCPT:
got = struct.unpack("<I", d[1:5])[0]
if got != sent:
raise RuntimeError(f"PRN mismatch: bootloader {got} vs poslal {sent}")
break
# Poslední skupina nemusí na PRN práh dosáhnout: bootloader pak
# místo receiptu pošle rovnou úspěšnou RESP(RECEIVE_FW). To je
# konec přenosu, ne chyba.
if d and d[0] == RESP and d[1] == RECEIVE_FW and d[2] == 1:
log(f" image potvrzen bootloaderem na {sent}/{total} B")
raise ImageDone()
if d and d[0] == RESP:
raise RuntimeError(f"nečekaná RESP během image: {d.hex()}")
if (sent // chunk) % 200 == 0:
log(f" {sent}/{total} B ({100*sent//total} %)")
log(f" image odesláno {sent}/{total} B")
async def phase2_dfu(mac, fw_bin, fw_dat, chunk=None):
log("== FÁZE 2: DFU na bootloaderu ==")
dev = None
for attempt in range(6):
dev = await find(mac, want_dfu=True, timeout=12)
if dev:
break
log(f" bootloader zatím nenalezen (pokus {attempt+1})...")
if not dev:
raise RuntimeError("bootloader (DFU svc) nenalezen ve scanu")
async with BleakClient(dev, timeout=30) as c:
log(" připojen k bootloaderu:", dev.address, "mtu:", getattr(c, "mtu_size", "?"))
try:
await c._backend._acquire_mtu() # BlueZ: vyjednej větší MTU
log(" MTU po acquire:", getattr(c, "mtu_size", "?"))
except Exception as e:
log(" (_acquire_mtu:", type(e).__name__, e, ")")
nf = Notif()
await c.start_notify(CP_UUID, nf.cb)
# START_DFU (application)
await c.write_gatt_char(CP_UUID, bytes([START_DFU, 0x04]), response=True)
await c.write_gatt_char(PKT_UUID, struct.pack("<III", 0, 0, len(fw_bin)), response=False)
await expect_resp(nf, START_DFU)
log(" START ok")
# INIT packet
await c.write_gatt_char(CP_UUID, bytes([INIT_DFU, 0x00]), response=True)
await c.write_gatt_char(PKT_UUID, fw_dat, response=False)
await c.write_gatt_char(CP_UUID, bytes([INIT_DFU, 0x01]), response=True)
await expect_resp(nf, INIT_DFU)
log(" INIT ok")
# PRN
prn = 8
await c.write_gatt_char(CP_UUID, bytes([PKT_RCPT_REQ]) + struct.pack("<H", prn), response=True)
# RECEIVE image
await c.write_gatt_char(CP_UUID, bytes([RECEIVE_FW]), response=True)
try:
await send_image(c, nf, PKT_UUID, fw_bin, prn=prn, chunk=chunk)
await expect_resp(nf, RECEIVE_FW, timeout=90)
except ImageDone:
pass # RESP(RECEIVE_FW) už dorazila uvnitř send_image
# ChunkTooBig se TADY neresi. Restart od START_DFU uvnitr tehoz spojeni
# bootloader odmitne se status 2 = INVALID_STATE -- stavovy automat uz je
# v "receiving" a dostat ho zpatky do IDLE umi jen RESET (opcode 6) plus
# nove spojeni. Vyhazuje se ven, main() to zopakuje s vynucenymi 20 B.
log(" IMAGE ok")
# VALIDATE
await c.write_gatt_char(CP_UUID, bytes([VALIDATE]), response=True)
await expect_resp(nf, VALIDATE)
log(" VALIDATE ok")
# ACTIVATE & reset
try:
await c.write_gatt_char(CP_UUID, bytes([ACTIVATE_RESET]), response=True)
except Exception as e:
log(" (ACTIVATE → disconnect, očekávané):", type(e).__name__)
log("== HOTOVO: bootloader aktivoval nový firmware a rebootuje ==")
async def reset_bootloader(mac):
"""Poke a stuck bootloader with RESET (opcode 6) so it reboots into a clean
DFU IDLE. After an interrupted image transfer the Adafruit bootloader keeps
its 'receiving image' state, so a fresh START_DFU returns INVALID_STATE;
this soft-reset clears the state machine (the GPREGRET flag survives, so it
re-enters DFU) and lets the next attempt start clean."""
log(" RESET bootloaderu (opcode 6) → čistý DFU IDLE...")
for att in range(4):
try:
dev = await find(mac, want_dfu=True, timeout=12)
if not dev:
await asyncio.sleep(2)
continue
async with BleakClient(dev, timeout=25) as c:
try:
await c.start_notify(CP_UUID, lambda _h, _d: None)
except Exception:
pass
try:
await c.write_gatt_char(CP_UUID, bytes([RESET]), response=True)
log(" RESET zapsán")
except Exception as e:
log(f" RESET write → {type(e).__name__} (reboot, očekávané)")
return True
except Exception as e:
log(f" RESET pokus {att+1}: {type(e).__name__} {str(e)[:50]}")
await asyncio.sleep(2)
return False
async def recover_to_bootloader(mac):
"""Get the node back into a clean DFU state, whichever way RESET left it.
reset_bootloader() on its own is not enough, and the two board families
differ: after RESET the SenseCap bootloader stays in DFU (the GPREGRET flag
survives), while the XIAO boots the APPLICATION instead. Assuming the
SenseCap behaviour made every XIAO retry scan forever for a bootloader that
was no longer there -- observed on bench-board, where the 20 B fallback could
never get started because the RESET that arms it also ended DFU mode.
So: reset, and if the bootloader is gone, ask the application to go back."""
await reset_bootloader(mac)
await asyncio.sleep(6)
dev = await find(mac, want_dfu=True, timeout=12)
if dev:
return
log(" po RESETu bootloader pryč (naběhla APP) → buttonless znovu")
await phase1_buttonless(mac)
async def main():
zippath, mac = sys.argv[1], sys.argv[2]
mode = sys.argv[3] if len(sys.argv) > 3 else ""
skip_phase1 = mode == "phase2"
# `phase1` = jen prepni uzel do bootloaderu a skonci. Ma to smysl u desky,
# ktera je zaroven na USB: BLE OTA trva jednotky az patnact minut podle MTU,
# kdezto po USB je to ~20 s. BLE se tedy pouzije jen na to, na co USB nestaci
# -- companion build nema textovou konzoli, takze `dfu` prikazem ho tam
# neposles. Tuhle kombinaci pouziva tools/flash_node.sh.
if mode == "phase1":
await phase1_buttonless(mac)
log("== uzel je v bootloaderu; flash dokonci volajici (napr. po USB) ==")
return
z = zipfile.ZipFile(zippath)
fw_bin = z.read("firmware.bin")
fw_dat = z.read("firmware.dat")
log(f"firmware.bin {len(fw_bin)} B, firmware.dat {len(fw_dat)} B, cíl {mac}")
# STALENESS GUARD. `pio run` builds firmware.zip, `pio run -t create_uf2`
# builds firmware.uf2, and NEITHER refreshes the other. Flashing one board
# from the .zip and another from the .uf2 then silently gives them different
# firmware -- that is how x3 ended up 50 min behind the rest of the fleet,
# missing a command the others had. firmware.elf is relinked by every build,
# so it is the reference.
elf = os.path.join(os.path.dirname(os.path.abspath(zippath)), "firmware.elf")
if os.path.exists(elf) and os.path.getmtime(elf) > os.path.getmtime(zippath):
sys.exit(f"CHYBA: {os.path.basename(zippath)} je STARŠÍ než firmware.elf — "
f"nalil bys starý obraz.\n"
f" Sprav: pio run -e <env> && pio run -e <env> -t create_uf2")
# Put the version on the record BEFORE it lands on the board, not after.
m = re.search(rb"v[0-9]+\.[0-9]+\.[0-9]+-tth[0-9a-f]+\+?", fw_bin)
if m:
log(f" verze v obrazu: {m.group(0).decode()}")
if skip_phase1:
log("== FÁZE 1 přeskočena (uzel už v bootloaderu) ==")
else:
await phase1_buttonless(mac)
# BLE DFU je flaky — přenos občas spadne uprostřed (dropnutá receipt notif).
# Auto-retry: po pádu vyresetuj bootloader do IDLE a zkus phase2 znovu.
ATTEMPTS = 6
chunk = None # None = mtu-3; prepne se na 20 po ChunkTooBig
for i in range(ATTEMPTS):
try:
await phase2_dfu(mac, fw_bin, fw_dat, chunk=chunk)
return # hotovo
except ChunkTooBig:
# Tenhle bootloader nebere mtu-3 velke pakety. Nejde to zachranit
# v behu -- START_DFU podruhe vrati status 2 (INVALID_STATE) --
# takze RESET, nove spojeni a znovu, natvrdo po 20 B.
log("!! bootloader nezvlada velke pakety -> opakuji s 20 B")
chunk = 20
await recover_to_bootloader(mac)
except Exception as e:
log(f"!! DFU pokus {i+1}/{ATTEMPTS} selhal: {type(e).__name__}: {str(e)[:80]}")
if i == ATTEMPTS - 1:
raise
await recover_to_bootloader(mac)
if {"-h", "--help"} & set(sys.argv[1:]):
print(__doc__.strip())
sys.exit(0)
asyncio.run(main())
+259
View File
@@ -0,0 +1,259 @@
#!/usr/bin/env bash
# SPDX-License-Identifier: MIT
# Ostrý flash MeshCore uzlu přes BLE OTA, celý postup na jeden příkaz.
#
# Existuje proto, že samotné `ble_dfu.py` je jen přenos obrazu. Kolem něj je
# pokaždé stejných šest věcí, a každá z nich už jednou něco stála:
#
# 1. ČISTÝ STROM. Verze ze špinavého stromu má `+` a na stožáru pak nepoznáš,
# co na uzlu je. Skript odmítne pokračovat.
# 2. PŘEDLETOVÁ KONTROLA prefs. Prefs v InternalFS přebíjejí build flagy a
# flash je NEPŘEPÍŠE — takže se musí přečíst PŘED i PO a porovnat.
# 3. TICHO u uzlu s odpojenou antenou (`--require-silence`). Vysílání do
# odpojené antény poškozuje PA; build je mlčící z konstrukce, ale prefs to
# přebijou, takže se ticho ověřuje na uzlu, ne v ini.
# 4. UVOLNĚNÍ LINKU. Zastavit službu (most) NESTAČÍ, spojení drží BlueZ.
# 5. OVĚŘENÍ VERZE proti obrazu, ne "vypadá to dobře".
# 6. VRÁCENÍ SLUŽBY do provozu a kontrola, že zase teče.
#
# Použití:
# tools/ble_flash_node.sh --env SenseCap_Solar_repeater --mac AA:BB:CC:DD:EE:10 \
# --require-silence
#
# tools/ble_flash_node.sh --env SenseCap_Solar_repeater \
# --mac AA:BB:CC:DD:EE:11 --via gateway-host \
# --python /opt/ble-bridge/venv/bin/python \
# --stop-service ble-bridge.service
#
# --check-only jen přečte stav uzlu a skončí (nic nemění, nic neflashuje)
#
# `--via` flashuje ze vzdáleného hostu, protože BLE má metry: mast-three je
# v dosahu bridge-host, ne pracovní stanice. Nic se tam neinstaluje — použije se
# python, který na hostu už je (`--python`).
set -euo pipefail
ENV_NAME=""
MAC=""
VIA=""
PY="python3"
STOP_SVC=""
REQUIRE_SILENCE=0
CHECK_ONLY=0
REPO="$(cd "$(dirname "$(readlink -f "$0")")/.." && pwd)"
while [ $# -gt 0 ]; do
case "$1" in
--env)
ENV_NAME="$2"
shift 2
;;
--mac)
MAC="$2"
shift 2
;;
--via)
VIA="$2"
shift 2
;;
--python)
PY="$2"
shift 2
;;
--stop-service)
STOP_SVC="$2"
shift 2
;;
--require-silence)
REQUIRE_SILENCE=1
shift
;;
--check-only)
CHECK_ONLY=1
shift
;;
-h | --help)
sed -n '3,33p' "$0"
exit 0
;;
*)
echo "neznámý argument: $1" >&2
exit 2
;;
esac
done
[ -n "$MAC" ] || {
echo "chybí --mac" >&2
exit 2
}
[ -n "$ENV_NAME" ] || [ "$CHECK_ONLY" = 1 ] || {
echo "chybí --env" >&2
exit 2
}
PIO="${PIO:-$HOME/.platformio/penv/bin/pio}"
CLI_CMDS=(ver "get name" "get repeat" "get advert.interval" "get flood.advert.interval" "get freq")
# Konzole uzlu: buď lokálně, nebo na hostu z --via (tam se nahrají nástroje).
# timeout: ble_cli.py sám žádný nemá. 27. 9. 2026 na mast-three visel připojený
# a hluchý 35 minut, most celou dobu stál a flash se k DFU vůbec nedostal.
NODE_CLI_TIMEOUT=${NODE_CLI_TIMEOUT:-180}
node_cli() {
if [ -n "$VIA" ]; then
# shellcheck disable=SC2029
ssh "$VIA" "timeout $NODE_CLI_TIMEOUT $PY /tmp/ble_cli.py $MAC $(printf '%q ' "$@")" 2>/dev/null
else
timeout "$NODE_CLI_TIMEOUT" "$PY" "$REPO/tools/ble_cli.py" "$MAC" "$@" 2>/dev/null
fi
}
pref() { grep -E "^$1[[:space:]]" <<<"$2" | cut -f2- | tr -d '\r'; }
if [ -n "$VIA" ]; then
scp -q -p "$REPO/tools/ble_cli.py" "$VIA:/tmp/" || {
echo "scp ble_cli.py selhalo" >&2
exit 1
}
fi
# Uvolnit link MUSÍ být PŘED předletovou kontrolou: když linku drží most, na
# konzoli se nedostaneš ani ty. A když cokoli dál selže, služba se musí vrátit
# do provozu — proto trap, ne "restart na konci".
SVC_STOPPED=0
restore_svc() {
[ "$SVC_STOPPED" = 1 ] || return 0
echo "== vracím $STOP_SVC ==" >&2
ssh "$VIA" "systemctl start $STOP_SVC" >/dev/null 2>&1 || true
SVC_STOPPED=0
}
trap restore_svc EXIT
if [ -n "$STOP_SVC" ] && [ "$CHECK_ONLY" = 0 ]; then
echo "== uvolnění linku ($STOP_SVC) =="
# Zastavit službu NESTAČÍ — spojení drží BlueZ, další připojení pak selže.
ssh "$VIA" "systemctl stop $STOP_SVC; bluetoothctl disconnect $MAC >/dev/null 2>&1 || true; sleep 3"
SVC_STOPPED=1
fi
echo "== stav uzlu $MAC =="
BEFORE="$(node_cli "${CLI_CMDS[@]}")" || {
echo "uzel neodpovídá na BLE konzoli" >&2
exit 1
}
echo "$BEFORE" | sed 's/^/ /'
V_BEFORE="$(pref ver "$BEFORE")"
REPEAT_BEFORE="$(pref 'get repeat' "$BEFORE")"
ADV_BEFORE="$(pref 'get advert.interval' "$BEFORE")"
FADV_BEFORE="$(pref 'get flood.advert.interval' "$BEFORE")"
if [ "$REQUIRE_SILENCE" = 1 ]; then
if [ "$ADV_BEFORE" != "0" ] || [ "$FADV_BEFORE" != "0" ] || [ "$REPEAT_BEFORE" != "off" ]; then
cat >&2 <<EOF
STOP: --require-silence, ale uzel není tichý
advert.interval=$ADV_BEFORE flood.advert.interval=$FADV_BEFORE repeat=$REPEAT_BEFORE
U uzlu s odpojenou antenou to znamená vysílání do odpojené antény po rebootu.
Umlč ho a spusť znovu:
set advert.interval 0 / set flood.advert.interval 0 / set repeat off
EOF
exit 1
fi
echo " ticho ověřeno (0/0/off)"
fi
[ "$CHECK_ONLY" = 1 ] && {
echo "== --check-only, končím =="
exit 0
}
echo "== build $ENV_NAME =="
DIRTY="$(cd "$REPO" && git status --porcelain | wc -l)"
if [ "$DIRTY" != "0" ]; then
echo "STOP: strom není čistý ($DIRTY změn) — verze by dostala '+' a na uzlu" >&2
echo " by pak nešlo poznat, co na něm je. Commitni, nebo stashni." >&2
exit 1
fi
(cd "$REPO" && "$PIO" run -e "$ENV_NAME" >/dev/null) || {
echo "build selhal" >&2
exit 1
}
ZIP="$REPO/.pio/build/$ENV_NAME/firmware.zip"
ELF="$REPO/.pio/build/$ENV_NAME/firmware.elf"
# Bez roury schválně. `strings "$ELF" | grep -m1 ...` tady padalo na SIGPIPE
# (exit 141): grep po prvním nálezu rouru zavře, `strings` ji dostane a
# `set -o pipefail` z toho udělá pád celého skriptu -- uprostřed flashe, se
# zastaveným mostem. Je to race, takže to roky procházelo; spuštěné hned po
# `pio run` ale selhalo 3/3 (21. 9. 2026, mast-three, dvakrát v ostrém běhu).
# `grep -a` čte ELF přímo, žádná roura = není co zavřít.
# `|| true`, protože skript běží pod `set -e`: bez toho by neúspěšný grep
# skript ukončil rovnou na tomhle přiřazení a STOP hláška o dva řádky níž by
# se nikdy nevypsala — operátor by dostal holý nenulový exit uprostřed flashe,
# klidně už se zastaveným mostem.
V_EXPECT="$(grep -m1 -aoE 'v[0-9]+\.[0-9]+\.[0-9]+-tth[0-9a-f]*\+?' "$ELF" || true)"
# `grep -m1 -o` zastaví po prvním ŘÁDKU, ale vypíše z něj VŠECHNY shody. ELF
# má .rodata oddělenou nulami bez newline, takže dvakrát vražený literál verze
# dá dvouřádkový V_EXPECT, porovnání s `ver` z uzlu pak nesedí a povedený OTA
# se ohlásí jako chyba. Necháváme první řádek.
V_EXPECT="${V_EXPECT%%$'\n'*}"
[ -n "$V_EXPECT" ] || {
echo "STOP: v obrazu není stampovaná verze (env bez stampingu?)" >&2
exit 1
}
echo " obraz: $V_EXPECT ($(stat -c%s "$ZIP") B)"
echo " na uzlu teď: $V_BEFORE"
echo "== DFU =="
if [ -n "$VIA" ]; then
scp -q -p "$ZIP" "$REPO/tools/ble_dfu.py" "$VIA:/tmp/"
ssh "$VIA" "cd /tmp && nohup timeout 1500 $PY /tmp/ble_dfu.py /tmp/firmware.zip $MAC > /tmp/dfu_$MAC.log 2>&1 &" || true
until ssh "$VIA" "grep -qE 'HOTOVO|SELHALO|Traceback' /tmp/dfu_$MAC.log" 2>/dev/null; do sleep 20; done
ssh "$VIA" "tail -4 /tmp/dfu_$MAC.log" | sed 's/^/ /'
ssh "$VIA" "grep -q HOTOVO /tmp/dfu_$MAC.log" || {
echo "DFU SELHALO — zotavení: ble_dfu.py … phase2" >&2
exit 1
}
else
"$PY" "$REPO/tools/ble_dfu.py" "$ZIP" "$MAC" | tail -4 | sed 's/^/ /'
fi
echo "== ověření po flashi =="
for _ in $(seq 1 30); do
sleep 10
AFTER="$(node_cli "${CLI_CMDS[@]}" || true)"
[ -n "$(pref ver "$AFTER")" ] && break
done
echo "$AFTER" | sed 's/^/ /'
V_AFTER="$(pref ver "$AFTER")"
FAIL=0
case "$V_AFTER" in
"$V_EXPECT"*) echo " verze OK" ;;
*)
echo " CHYBA: uzel hlásí '$V_AFTER', čekáno '$V_EXPECT'" >&2
FAIL=1
;;
esac
# Prefs flash nepřepisuje, takže rozdíl = něco je špatně (nebo si je uzel resetoval).
for p in repeat:REPEAT advert.interval:ADV flood.advert.interval:FADV; do
key="${p%%:*}"
var="${p##*:}"
b_var="${var}_BEFORE"
before="${!b_var}"
after="$(pref "get $key" "$AFTER")"
if [ "$before" != "$after" ]; then
echo " CHYBA: $key se změnil: '$before' -> '$after'" >&2
FAIL=1
fi
done
[ "$FAIL" = 0 ] && echo " prefs beze změny"
if [ "$SVC_STOPPED" = 1 ]; then
echo "== vrácení služby =="
restore_svc
sleep 15
ssh "$VIA" "systemctl is-active $STOP_SVC" | sed 's/^/ /'
echo " a ověř DATA, ne jen službu:"
echo " ssh $VIA \"journalctl -u $STOP_SVC --since -5min | grep 'full scrape'\""
fi
[ "$FAIL" = 0 ] || exit 1
echo "== HOTOVO: $MAC na $V_AFTER =="
+200
View File
@@ -0,0 +1,200 @@
#!/usr/bin/env python3
# SPDX-License-Identifier: MIT
"""Non-interactive BLE pairing by PIN, driving bluetoothctl over a pty.
A MeshCore node's console characteristics are SECMODE_ENC_WITH_MITM, so the
first connection to an unpaired node raises a passkey dialog on the desktop --
useless from a script. This registers its own KeyboardOnly agent and answers
the prompt.
ble_pair.py AA:BB:CC:DD:EE:10 # one node
ble_pair.py AA:BB:CC:DD:EE:10 hill-rpt # MACs or config board names
The PIN comes from platformio.local.ini ([secrets] ble_pin) and is never
printed. That is the same value the firmware was built with, so a node whose
PIN does not match here was built from a different tree.
WHY A SCRIPT, AND WHY STATE-DRIVEN: the first version marched through
bluetoothctl on a fixed schedule and sent `pair` before the agent was
registered. The passkey prompt then went to the default agent and the node
stayed unpaired -- with no error anywhere. Every step here waits for the
output that proves the previous one landed.
BONDING IS NOT ONLY FOR THE CONSOLE. The buttonless-DFU control point is
declared with the same SECMODE_ENC_WITH_MITM
(`helpers/nrf52/SerialBLEInterface.cpp`), so `ble_dfu.py` phase 1 cannot write
its trigger to an unpaired node either. It fails as a plain write error, which
does not look like "you are not bonded".
AFTERWARDS, DISCONNECT BEFORE FLASHING. bluetoothctl leaves the node
*connected* once pairing succeeds, and a connected peripheral stops
advertising -- so `ble_dfu.py` immediately fails its scan with "APP nenalezen
ve scanu". Run `bluetoothctl disconnect <MAC>` first.
ble_pair.py <MAC> && bluetoothctl disconnect <MAC> && ble_dfu.py fw.zip <MAC>
DOCK-QUIET NODES ADVERTISE ONLY WHEN UNDOCKED. On dual USB/BLE companion
builds (T1000-E, Wio L1), BLE advertising is suppressed while a USB host holds
DTR high. Unplug USB, or hold the port open with DTR deasserted, or nothing on
this page will find the node.
"""
import atexit
import os
import pty
import re
import select
import signal
import sys
import time
INI = os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))),
"platformio.local.ini")
def read_pin():
# A node built from an env that does not take [secrets] (e.g. a companion env
# that keeps the variant's default BLE_PIN_CODE) needs a different PIN. Give
# it as a FILE, not a value, so it stays out of argv, env dumps and history.
pin_file = os.environ.get("BLE_PIN_FILE")
if pin_file:
with open(pin_file) as fh:
pin = fh.read().strip()
if not pin.isdigit():
sys.exit(f"BLE_PIN_FILE {pin_file} does not hold a numeric PIN")
return pin
try:
with open(INI) as fh:
lines = fh.readlines()
except FileNotFoundError:
sys.exit(f"{INI} not found -- it holds the real PIN and is git-ignored")
pin = None
for line in lines: # last one wins, same as PlatformIO
m = re.match(r"\s*ble_pin\s*=\s*(\d+)", line)
if m:
pin = m.group(1)
if not pin:
sys.exit(f"no [secrets] ble_pin in {INI}")
return pin
def _mac(key):
"""A board name from the local config (tools/mctools_config.py) -> its MAC.
Optional on purpose: ble_flash_node.sh --via copies this file ALONE to a
remote host, where there is no config and a MAC is given anyway."""
try:
from mctools_config import mac_for
except ImportError:
return key
return mac_for(key) or key
def main():
macs = [_mac(m) for m in sys.argv[1:]]
if not macs:
sys.exit(f"usage: {os.path.basename(sys.argv[0])} <MAC> [MAC...]")
pin = read_pin()
pid, fd = pty.fork()
if pid == 0:
os.execvp("bluetoothctl", ["bluetoothctl"])
def drain(seconds, want=None, mac=None):
"""Read for `seconds` (or until `want` matches), answering prompts."""
end = time.time() + seconds
hit = None
while time.time() < end:
r, _, _ = select.select([fd], [], [], 0.4)
if not r:
continue
try:
chunk = os.read(fd, 4096).decode("utf-8", "replace")
except OSError:
break
clean = re.sub(r"\x1b\[[0-9;?]*[a-zA-Z]", "", chunk)
for ln in clean.splitlines():
t = ln.strip()
if not t or "RSSI" in t or t.startswith("[NEW] Device"):
continue # scan noise
if pin and pin in t: # bluetoothctl echoes the typed passkey
t = t.replace(pin, "******")
print(" bt|", t[:110], flush=True)
low = clean.lower()
if "passkey" in low or "enter pin" in low or "pin code" in low:
os.write(fd, (pin + "\n").encode())
print(" -> PIN sent", flush=True)
elif "(yes/no)" in low:
os.write(fd, b"yes\n")
print(" -> confirmed", flush=True)
if want and mac and re.search(want, clean, re.I) and mac in clean:
hit = True
break
if "failed" in low and mac and mac.lower() in low:
hit = False
break
return hit
def send(cmd, wait=1.5, want=None, mac=None):
os.write(fd, (cmd + "\n").encode())
print(f"$ {cmd}", flush=True)
return drain(wait, want, mac)
# ÚKLID MUSÍ PROBĚHNOUT I PŘI ZABITÍ. Registrovaný `default-agent` odpovídá
# na CIZÍ párovací požadavky a `scan on` drží discovery -- když se skript
# zabije uprostřed (stalo se 22. 8. 2026 vlastním `timeout 60`), zůstane
# hostitel v tomhle stavu a začne se chovat jako párovatelné zařízení pro
# okolí. Na notebooku na vzdálené stanoviště z toho vyskočil párovací požadavek na televizi.
def cleanup(*_a):
try:
for c in ("scan off", "pairable off", "discoverable off",
"agent off", "quit"):
os.write(fd, (c + "\n").encode())
time.sleep(0.4)
except OSError:
pass
atexit.register(cleanup)
for _sig in (signal.SIGTERM, signal.SIGINT, signal.SIGHUP):
signal.signal(_sig, lambda *_a: sys.exit(130))
send("agent KeyboardOnly", 2)
send("default-agent", 2)
failed = []
for mac in macs:
print(f"===== {mac} =====", flush=True)
send(f"remove {mac}", 3) # a stale bond makes `pair` a no-op
send("scan on", 1)
# ČEKEJ, DOKUD HO SKEN NEUVIDÍ, ne pevných pár sekund. `remove` smaže
# i objevené zařízení, takže `pair` hned poté řekne "Device <mac> not
# available" — a to vypadá úplně stejně jako špatný PIN. Repeater navíc
# po 30 s přepne z rychlého advertisingu na pomalý, takže se do krátkého
# okna netrefí. Stálo to 22. 8. 2026 dvě hodiny hledání na dvou hostech.
if drain(45, want=r"Device", mac=mac):
print(" (uzel ve skenu, páruju)", flush=True)
else:
print(f" POZOR: {mac} se za 45 s ve skenu neobjevil — `pair` nejspíš "
f"skončí na 'not available'. Uzel neadvertuje?", flush=True)
ok = send(f"pair {mac}", 45, want=r"Bonded: yes|Pairing successful", mac=mac)
print(f" paired: {ok}", flush=True)
if not ok:
failed.append(mac)
send("scan off", 1)
send(f"trust {mac}", 3)
# `agent off` odregistruje KeyboardOnly agenta -- bez toho by host dál
# odpovídal na cizí párovací požadavky, dokud bluetoothctl neskončí
send("agent off", 1)
send("quit", 1)
os.close(fd)
if failed:
print("NOT PAIRED: " + ", ".join(failed))
print("A wrong PIN and a node that stopped advertising look the same "
"here -- check both.")
sys.exit(1)
print("done -- disconnect before running ble_dfu.py")
if __name__ == "__main__":
if {"-h", "--help"} & set(sys.argv[1:]):
print(__doc__.strip())
sys.exit(0)
main()
+433
View File
@@ -0,0 +1,433 @@
#!/usr/bin/env python3
# SPDX-License-Identifier: MIT
"""Otisk XIAO desek na USB: co na které z nich BĚŽÍ, a jestli se to změnilo.
tools/board_probe.py --all
tools/board_probe.py --all --compare <soubor s predchozim otiskem>
tools/board_probe.py --all --compare <soubor> --expect-changed <serial>
Vzniklo 1. 9. 2026 poté, co `pio run -t upload --upload-port <x4>` ohlásil
FAILED a obraz přistál na **x2**, desce, která na té příkazové řádce nebyla.
Poznat to šlo až po hodině: x2 přestal odpovídat konzoli i companion protokolu
a vypadal jako zaseklý, přitom na něm normálně běžel KISS modem, který ani
jedno z toho nemá. Tři replugy nepomohly a pomoct nemohly.
Otisk je proto přes VŠECHNY protokoly, které na těch deskách jezdí, ne jen přes
ten, který zrovna čekáme:
text MeshCore repeater/analyzer `ver` -> v1.17.1-tth...
companion MeshCore companion_radio CMD_DEVICE_QUERY (bez textové konzole)
kiss examples/kiss_modem SetHardware GetVersion (0x11 -> 0x91)
modem openhop_modem port `XIAO-Wio-SX1262`, mlčí na vše
bootloader UF2 port bez "Studio" / se "Sense"
`modem` a `bootloader` se poznají podle JMÉNA portu, ne podle idProduct: obojí
drží 0044 a AGENTS.md čte 0044 jako bootloader, což pro openhop_modem neplatí.
"""
import argparse
import glob
import multiprocessing
import os
import re
import struct
import sys
import time
try:
import serial
except ImportError:
sys.exit("chybi pyserial")
# Kolik sekund nejvys smi trvat otisk CELE sbernice.
# Musi pokryt PLNY cyklus jedne desky: settle 0,9 + text 1,2 + companion 1,5 +
# KISS 1,2 + GetDeviceName 1,2 = ~6 s (zmereno 2. 9. 2026 na x4: 6,4 s, tri behy
# za sebou stejne). S kratsim deadlinem se posledni protokol nestihne a deska se
# oznaci jako "visi", i kdyz normalne odpovida -- presne to se stalo KISS modemu
# na x4 pri BOARD_PROBE_DEADLINE=6.
PROBE_DEADLINE = float(os.environ.get("BOARD_PROBE_DEADLINE", "12"))
def usb_boards():
"""[(serial, port, board, state_hint)] pro kazdou desku flotily na USB.
Typ desky i rezim se poznaji z JMENA portu, protoze idProduct lze -- 0044
drzi jak UF2 bootloader XIAO, tak openhop_modem, coz je aplikace. A na
T1000-E je to jmeno primo obracene, nez by clovek cekal:
Seeed_Studio_XIAO_nRF52840_<sn> XIAO, aplikace (MeshCore build)
Seeed_XIAO_nRF52840_Sense_<sn> XIAO, bootloader
Seeed_XIAO-Wio-SX1262_<sn> XIAO, openhop_modem (APLIKACE, ne boot)
Seeed_Studio_T1000-E-BOOT_<sn> T1000-E, APLIKACE <- "-BOOT" ma aplikace!
Seeed_Studio_T1000-E_<sn> T1000-E, bootloader (+ UF2 disk T1000-E)
"""
pats = [
# (regex na jmeno portu, deska, stav)
(r"Seeed_Studio_T1000-E-BOOT_", "t1000e", "app"),
(r"Seeed_Studio_T1000-E_", "t1000e", "boot"),
(r"Seeed_XIAO-Wio-SX1262_", "xiao", "modem"),
(r"Seeed_Studio_XIAO_nRF52840_", "xiao", "app"),
(r"Seeed_XIAO_nRF52840", "xiao", "boot"),
(r"Wio|TRACKER", "wio-l1", "app"),
]
out = []
for port in sorted(glob.glob("/dev/serial/by-id/*")):
name = os.path.basename(port)
m = re.search(r"_([0-9A-F]{16})-if00", name)
if not m:
continue # ESP32 a spol. -- neni to nase nRF52 flotila
for rx, board, state in pats:
if re.search(rx, name):
out.append((m.group(1), port, board, state))
break
return out
def port_busy(dev):
"""Drzi ten port jiny proces? Vrati jeho pid, nebo None.
Sahat na port, ktery uz nekdo ma otevreny, neni jen zbytecne -- je to
SKODLIVE. 2. 9. 2026 tenhle probe otevrel port, na kterem openHop drzel KISS
spojeni; demon zahlasil "multiple access on port", oznacil link za degradovany
a nakonec si RADIO VYPNUL (`Radio is disabled`) a nesl si to v repeater.db,
takze to neresil ani restart kontejneru. Kontrola stavu nesmi rozbit to, co
kontroluje.
Ctou se /proc/*/fd, takze to nepotrebuje root ani lsof; cizi procesy pod jinym
UID neuvidime, ale docker tady bezi pod nasim (--user $(id -u)), takze ten ano.
"""
try:
real = os.path.realpath(dev)
except OSError:
return None
me = os.getpid()
for pid in os.listdir("/proc"):
if not pid.isdigit() or int(pid) == me:
continue
d = f"/proc/{pid}/fd"
try:
entries = os.listdir(d)
except OSError:
continue
for fd in entries:
try:
if os.path.realpath(f"{d}/{fd}") == real:
return pid
except OSError:
continue
return None
def _open(port):
s = serial.Serial(port, 115200, timeout=0)
s.dtr = True
s.rts = True
time.sleep(0.9)
s.reset_input_buffer()
return s
def _drain(s, w):
buf, t = b"", time.time()
while time.time() - t < w:
try:
d = s.read(8192)
except Exception:
# "device reports readiness to read but returned no data" -- deska
# se odpojila uprostred cteni. Vracime, co uz mame; neni to duvod
# shodit cely otisk.
break
if d:
buf += d
else:
time.sleep(0.02)
return buf
def _kiss_frame(raw, resp_code):
"""Vrat KISS ramec zacinajici 0xC0, jehoz treti bajt je `resp_code`.
Bez tohohle se raw[1]/raw[2] cetly z offsetu 0, tedy z toho, co v bufferu
zbylo po predchozim protokolu -- a odpoved se dala minout i kdyz prisla.
"""
i = -1
while True:
i = raw.find(bytes([0xC0]), i + 1)
if i < 0:
return raw
fr = raw[i:]
if len(fr) > 4 and fr[1] == 0x06 and fr[2] == resp_code:
return fr
def probe(port):
"""('text'|'companion'|'kiss'|'nic', verze) -- zkusí protokoly po řadě."""
try:
s = _open(port)
except Exception as e:
return ("nedostupny", type(e).__name__)
try:
# Prvni prikaz po otevreni portu se casto ztrati, proto to prazdne CRLF.
s.write(b"\r\n")
time.sleep(0.4)
s.reset_input_buffer()
s.write(b"ver\r\n")
txt = _drain(s, 1.2).decode(errors="replace")
m = re.search(r"(v\d+\.\d+\.\d+-tth[0-9a-f]+\+?)", txt)
if m:
return ("text", m.group(1))
s.reset_input_buffer()
s.write(b"<" + struct.pack("<H", 2) + bytes([22, 10])) # CMD_DEVICE_QUERY
s.flush()
raw = _drain(s, 1.5)
# Rámec se hleda podle CELE hlavicky, ne podle prvniho '>' v bufferu.
# Driv stacilo, aby za '>' byly dva bajty a neprazdny zbytek, a vratilo se
# ("companion", "?") -- takze opozdena radka textove konzole nebo
# MESH_DEBUG_PRINTLN se ctla jako companion ramec. flash_node.sh pak
# porovnal "?" s ocekavanou verzi a oznamil "FLASH SE NEAPLIKOVAL" na
# desce, na ktere bezel spravny firmware -- presne ta trida falesne
# diagnozy, kvuli ktere tenhle nastroj vznikl.
#
# Prohledavaji se VSECHNY vyskyty '>' a uzna se jen plnohodnotny
# RESP_DEVICE_INFO (kod 13, aspon 80 B, delka souhlasi s tim, co dorazilo).
i = -1
while True:
i = raw.find(b">", i + 1)
if i < 0:
break
if len(raw) < i + 3:
continue
ln = struct.unpack("<H", raw[i + 1:i + 3])[0]
fr = raw[i + 3:i + 3 + ln]
if len(fr) == ln and ln >= 80 and fr[0] == 13: # RESP_DEVICE_INFO
return ("companion", fr[60:80].split(b"\0")[0].decode(errors="replace"))
s.reset_input_buffer()
s.write(bytes([0xC0, 0x06, 0x11, 0xC0])) # KISS GetVersion
raw = _drain(s, 1.2)
# Kotvit na ZACATEK KISS ramce (0xC0), ne na offset 0: pred odpovedi muze
# lezet zbytek predchoziho vystupu a raw[1]/raw[2] by pak cetly cizi bajty.
raw = _kiss_frame(raw, 0x91)
if len(raw) > 4 and raw[1] == 0x06 and raw[2] == 0x91:
# GetVersion (0x11) vrací verzi KISS PROTOKOLU, ne našeho buildu --
# ta je k nerozeznání mezi dvěma různými firmwary. Stampovaná verze
# jede v GetDeviceName (0x16), viz KissModem::handleGetDeviceName.
s.reset_input_buffer()
s.write(bytes([0xC0, 0x06, 0x16, 0xC0])) # KISS GetDeviceName
nm = _kiss_frame(_drain(s, 1.2), 0x96)
if len(nm) > 4 and nm[1] == 0x06 and nm[2] == 0x96:
txt = nm[3:-1].decode(errors="replace")
m = re.search(r"(v\d+\.\d+\.\d+-tth[0-9a-f]+\+?)", txt)
if m:
return ("kiss", m.group(1))
return ("kiss", txt.strip() or "?")
# Starší KISS build bez stampované verze v GetDeviceName.
return ("kiss", "proto" + ".".join(str(b) for b in raw[3:-1]))
return ("nic", "-")
finally:
try:
s.close()
except Exception:
pass
def _probe_one(sn, port, board, state):
"""Otisk jedne desky. Bezi ve VLASTNIM PROCESU (viz fingerprint)."""
if state in ("boot", "modem"):
# Bootloader nemluvi nasim protokolem a openhop_modem nemluvi vubec;
# ptat se jich je jen ztrata casu (a u boot i riziko, ze to vypada
# jako zaseknuta deska).
return (sn, f"{board}/{state}", "-")
busy = port_busy(port)
if busy:
return (sn, f"{board}/obsazeny", f"drzi pid {busy} -- nesaham")
kind, ver = probe(port)
return (sn, f"{board}/{kind}", ver)
def _worker(i, sn, port, board, state, q):
try:
q.put((i,) + _probe_one(sn, port, board, state))
except Exception as e: # nikdy nenech potomka umrit potichu
q.put((i, sn, f"{board}/chyba", type(e).__name__))
def fingerprint():
"""Otisk cele sbernice. Paralelne -- porty jsou nezavisle a serazovat je za
sebe se necetlo: pet desek po ~9 s (settle + tri protokoly, u mlcicich desek
plny timeout) delalo pres dve minuty, coz je na kontrolu spoustenou PRED a PO
kazdym flashem moc. Poradi vysledku je dane vstupem, ne dobehem.
KAZDA DESKA VE VLASTNIM PROCESU, ne ve vlakne. Puvodni verze mela daemon
vlakna a tvrdy deadline, jenze `serial.Serial()` umi na nereagujici desce
viset v open(2) UVNITR C kodu, ktery NEPOUSTI GIL -- takze jedna zaseklá
deska zmrazila i vsechny ostatni probe vlakna a ta pak deadline nestihla.
Projev: 2. 9. 2026 hlasil x4 (zdravy KISS modem, sam o sobe 6,4 s)
"visi neodpovida v case" pri deadline 12 s, zatimco cely beh trval 42 s.
Diagnoza "deska neodpovida" na desce, ktera odpovida, je horsi nez zadna.
Proces se da terminate() i uprostred blokujiciho open(2), takze deadline
plati doopravdy a zbytek flotily se otiskne v normalnim case.
"visi" u T1000-E NENI diagnoza desky. Obe karty (B3F160.., B612AE..) visi
v serial.Serial() open(2) i pres 60 s, kazda samostatne ve vlastnim procesu
(zmereno 2. 9. 2026) -- pyserial se z nich otisk proste nedozvi a zvysovani
deadlinu s tim nic neudela. Deska pritom muze byt uplne v poradku; na
T1000-E se pta textova konzole primo, ne tenhle nastroj."""
boards = usb_boards()
rows = [None] * len(boards)
if not boards:
return []
ctx = multiprocessing.get_context("fork") # fork: potomek zdedi uz nactene moduly
q = ctx.Queue()
procs = []
for i, (sn, port, b, st) in enumerate(boards):
p = ctx.Process(target=_worker, args=(i, sn, port, b, st, q), daemon=True)
p.start()
procs.append(p)
deadline = time.time() + PROBE_DEADLINE
got = 0
while got < len(boards) and time.time() < deadline:
try:
i, sn, kind, ver = q.get(timeout=max(0.05, deadline - time.time()))
except Exception:
break
rows[i] = (sn, kind, ver)
got += 1
for p in procs:
if p.is_alive():
p.terminate() # utne i blokujici open(2)
for p in procs:
p.join(timeout=1.0)
# SIGKILL na to, co terminate() neslozilo. main() konci `os._exit`, ktery
# obchazi atexit handler multiprocessingu -- prezivsi potomek by tedy zustal
# bezet A DRZET SERIOVY PORT, takze dalsi beh (flash_node.sh pousti probe
# tretkrat za flash) by tu desku ohlasil jako `obsazeny drzi pid <n>`:
# nastroj obvinujici vlastni pozustatky.
for p in procs:
if p.is_alive():
p.kill()
for p in procs:
p.join(timeout=0.5)
for i, (sn, _, board, _) in enumerate(boards):
if rows[i] is None:
rows[i] = (sn, f"{board}/visi", "neodpovida v case")
return [r for r in rows if r]
def _parse_pairs(path):
"""[(serial, (kind, verze))] z otisku. Verze muze obsahovat mezery (starsi
KISS build vraci "Seeed Xiao-nrf52"), takze split(None, 2) -- split() na tri
pole by zbytek utnul a porovnani by hlasilo ZMENU tam, kde se nic nezmenilo.
Radek s PRAZDNOU verzi se NEZAHAZUJE. Driv to filtroval `len(p) >= 3`, takze
deska, u ktere probe verzi nevyplnil, z predchoziho otisku zmizela a pak se
ohlasila jako "ZMIZELA z USB" -- falesny poplach o desce, ktera tam celou dobu
byla.
"""
out = []
for line in open(path):
if not line.strip():
continue
p = line.split(None, 2)
if len(p) < 2:
continue
out.append((p[0], (p[1], p[2].strip() if len(p) > 2 else "")))
return out
def _parse(path):
return [(sn, k, v) for sn, (k, v) in _parse_pairs(path)]
def fmt(rows):
return "\n".join(f"{sn} {kind} {str(ver).strip()}" for sn, kind, ver in rows)
def main():
ap = argparse.ArgumentParser()
ap.add_argument("--all", action="store_true")
ap.add_argument("--compare", help="soubor s predchozim otiskem")
ap.add_argument("--now", help="soubor s AKTUALNIM otiskem (jinak se sbernice"
" otiskne znovu)")
ap.add_argument("--expect-changed", help="seriak, ktery se zmenit MA")
a = ap.parse_args()
# --now existuje proto, aby volajici, ktery uz otisk ma, nemusel platit dalsi
# probe (az PROBE_DEADLINE) -- a hlavne aby verdikt o zmenach a jeho vlastni
# kontrola verze vychazely z TEHOZ vzorku sbernice, ne ze dvou ruznych.
rows = _parse(a.now) if a.now else fingerprint()
now = {sn: (k, v) for sn, k, v in rows}
if not a.compare:
print(fmt(rows))
return 0
prev = dict(_parse_pairs(a.compare))
bad = False
for sn in sorted(set(prev) | set(now)):
was, is_ = prev.get(sn), now.get(sn)
tag = ""
if was != is_:
# Poradi je zamerne: deska, ktera ZMIZELA, neni uspech ani kdyz je to
# cil. Po flashi se to na tehle lavici stava bezne a hlaska "zmeneno
# (cil)" by to zakryla -- pritom se z desky nedá precist, co na ni je,
# takze flash NENI overeny. Chce to replug a spustit znovu.
if is_ is None:
tag = " <- ZMIZELA z USB (po flashi bezne) -- replug a spust znovu"
bad = True
elif was is None:
tag = " <- NOVA deska na sbernici"
elif (a.expect_changed
and sn.endswith(a.expect_changed.upper())
and len([x for x in set(prev) | set(now)
if x.endswith(a.expect_changed.upper())]) == 1):
tag = " <- zmeneno (cil)"
else:
tag = " <- !!! ZMENENO, PRESTOZE TO NEBYL CIL !!!"
bad = True
print(f" {sn} {was[0] if was else '-':10s} {was[1] if was else '-':22s}"
f" -> {is_[0] if is_ else '-':10s} {is_[1] if is_ else '-':22s}{tag}")
if a.expect_changed:
want = a.expect_changed.upper()
hits = [x for x in sorted(set(prev) | set(now)) if x.endswith(want)]
if len(hits) > 1:
# Kratky suffix umi sednout na vic seriaku; driv se vzal jeden podle
# poradi ve slovniku, takze "zmeneno (cil)" mohlo omluvit ZMENU NA JINE
# DESCE.
print(f"\n{a.expect_changed} sedi na {len(hits)} desky ({', '.join(hits)})"
f" -- upresni seriove cislo, jinak nejde rict, ktera se zmenit mela.")
bad = True
elif not hits:
# Driv: cil chybel v obou otiscich -> smycka ho nikdy nenavstivila,
# `bad` zustalo False a beh skoncil "ok, zmenil se jen cil". Otisk,
# ve kterem cil nikdy nikdo nevidel, neni uspech.
print(f"\nCIL {a.expect_changed} NENI V ZADNEM z otisku -- neni z ceho"
f" rict, ze se zmenil. Sedi to seriove cislo?")
bad = True
elif prev.get(hits[0]) == now.get(hits[0]):
print(f"\nCIL {a.expect_changed} SE NEZMENIL -- flash se neaplikoval,"
f" i kdyby nastroj hlasil uspech.")
bad = True
print("\nVERDIKT:", "PROBLEM (viz vys)" if bad else "ok, zmenil se jen cil")
return 1 if bad else 0
if __name__ == "__main__":
rc = main()
# os._exit misto sys.exit: vlakno, ktere visi v serial.Serial() open(2),
# drzi otevreny file descriptor a interpret na nej pri uklidu ceka -- otisk
# se vypsal za par sekund, ale proces dobihal jeste ~30 s (a pod `timeout`
# se tvaril jako zaseknuty). Vysledek uz je venku, uklizet nemame co.
sys.stdout.flush()
sys.stderr.flush()
os._exit(rc)
+10
View File
@@ -1,3 +1,4 @@
# SPDX-License-Identifier: MIT
# CUSTOM (TeTeHacko): real version and build timestamp for the `ver` command.
#
# WIRE THIS INTO EVERY ENV WE FLASH. Without it the node reports the fallback
@@ -18,6 +19,15 @@
# Import("env") has to come first, hence the file-wide ruff exemption.
# ruff: noqa: F821, E402
# mypy: disable-error-code="name-defined"
if __name__ == "__main__": # run by hand (--help): the header above, nothing else
with open(__file__) as _f:
for _ln in _f:
if not _ln.startswith("#"):
break
if "SPDX-License-Identifier" not in _ln:
print(_ln[2:].rstrip() if _ln.startswith("# ") else "")
raise SystemExit(0)
Import("env")
import re
import subprocess
+260
View File
@@ -0,0 +1,260 @@
#!/usr/bin/python
# SPDX-License-Identifier: MIT
"""Záloha companionu (L1, karta) přes companion protokol PŘED flashem.
tools/companion_backup.py /dev/serial/by-id/usb-...L1... L1-pre-flash
tools/companion_backup.py <port> <jméno> --diff ~/.local/share/meshcore-backups/<starší>.json
tools/companion_backup.py <BLE MAC> <jméno> # místo portu MAC = přes BLE (bond nutný)
Uloží self_info (jméno, rádio, poloha, path hash…), device query, custom vars,
kontakty a kanály do ~/.local/share/meshcore-backups/<jméno>-<datum>.json (0600 —
jsou v tom klíče kanálů). Na stdout nic tajného, jen souhrn; `--diff` porovná se
starší zálohou (po flashi), klíče kanálů porovnává jen jako shodu.
Solo navíc vystavuje nastavení přes companion CLI (`keys`, `get`, `set`;
ui-core/SettingsCli.h): záloha je uloží všechna do sekce `cli` a `--restore`
je vrátí. Live Share cíl/zapnutí/scope (`share.to`, `share.on`, `share.scope`)
umí CLI až od solo-tth s tímhle doplňkem — 16. 10. 2026 po v2.0 skončil Live
Share na kanálu Public a nebylo jak to zjistit. Co CLI nezná (bot, část UI),
musí po flashi zkontrolovat člověk na zařízení.
Hodiny flash nepřežijí (L1 22. 10. 2026 po v2.0.1 o 10 h pozadu), proto
`--diff` (= běh po flashi) a samostatné `--sync-time` nastaví čas hostu
(CMD_SET_DEVICE_TIME — lokální příkaz po USB, nic nevysílá). Firmware čas
dozadu odmítne; uzel napřed se jen ohlásí.
tools/companion_backup.py <port> L1-post --restore <záloha>.json # jen ukáže
tools/companion_backup.py <port> L1-post --restore <záloha>.json --apply # zapíše
`--restore` Live Share nikdy NEZAPNE (to je vysílání do meshe) — jen vypne,
když bylo v záloze vypnuté; zapnout ho je na člověku. Privátní klíč přes USB náš firmware nevydá
(`private_key_export_disabled`), záloha identity je ve vaultu (keys.yml).
Spouští se interpretem meshcli (#!/usr/bin/python), tam je knihovna meshcore.
Knihovna shazuje DTR a L1 bez DTR na USB mlčí ⇒ _dtr_on() + cx_dly=1,5 s.
Když je k L1 připojený telefon přes BLE, USB mlčí — vypni na telefonu BT.
"""
import argparse
import asyncio
import datetime as dt
import json
import os
import re
import sys
import time
if {"-h", "--help"} & set(sys.argv[1:]):
print(__doc__.strip())
sys.exit(0)
from meshcore import EventType, MeshCore # noqa: E402
DIR = os.path.expanduser("~/.local/share/meshcore-backups")
def plain(x):
if isinstance(x, (bytes, bytearray)):
return x.hex()
if isinstance(x, dict):
return {str(k): plain(v) for k, v in x.items()}
if isinstance(x, (list, tuple)):
return [plain(v) for v in x]
return x
def _dtr_on():
"""Knihovna meshcore po otevření portu SHAZUJE DTR (serial_cx.connection_made:
`dtr = False`, kvůli deskám, které DTR resetuje). Solo DualSerialInterface ale
bez DTR na USB neposlouchá — odtud „No response … serial companion?“ u
meshcli na L1. Proto DTR po otevření zase nahodit."""
from meshcore import serial_cx
proto = serial_cx.SerialConnection.MCSerialClientProtocol
orig = proto.connection_made
def connection_made(self, transport):
orig(self, transport)
if getattr(transport, "serial", None):
transport.serial.dtr = True
proto.connection_made = connection_made
async def connect(port):
# a BLE MAC instead of a port: a companion that is not on USB here (the
# probe card sits on another host, reachable over BLE only)
ble = re.fullmatch(r"([0-9A-Fa-f]{2}:){5}[0-9A-Fa-f]{2}", port) is not None
if not ble:
_dtr_on()
for attempt in range(4):
try:
if ble:
mc = await MeshCore.create_ble(port, default_timeout=8)
else:
mc = await MeshCore.create_serial(port, 115200, default_timeout=8, cx_dly=1.5)
if mc and mc.self_info:
return mc
if mc:
await mc.disconnect()
except (OSError, asyncio.TimeoutError, ConnectionError) as e:
print(f"pokus {attempt + 1}: {e}", file=sys.stderr)
await asyncio.sleep(2 + attempt * 2)
sys.exit("companion neodpovídá (připojený telefon přes BLE? po flashi chvíli počkej)")
async def cli(mc, cmd):
ev = await mc.commands.run_cli_command(cmd)
return ev.payload.get("text", "").strip() if ev.type == EventType.CLI_REPLY else None
async def cli_settings(mc):
"""Všechny klíče z `keys` (po stránkách) a jejich hodnoty z `get`; None, když
firmware Solo CLI nemá (upstream companion: „Unknown command“)."""
keys, page = [], 1
while page < 20:
r = await cli(mc, "keys" if page == 1 else f"keys {page}")
if not r or r.startswith(("Unknown", "Error", "No more")):
break
more = "(more: keys" in r
keys += r.split(" (more:")[0].split()
if not more:
break
page += 1
if not keys:
return None
out = {}
for k in keys:
r = await cli(mc, f"get {k}")
out[k] = r[2:] if r and r.startswith("> ") else r
return out
RESTORE_FIRST = ["share.to", "share.scope"] # cíl dřív než cokoli, co by vysílalo
async def restore(mc, saved, apply):
cur = await cli_settings(mc) or {}
order = [k for k in RESTORE_FIRST if k in saved] + [k for k in saved if k not in RESTORE_FIRST]
plan = []
for k in order:
v = saved[k]
if v is None or cur.get(k) == v or k not in cur:
continue
if k == "share.on" and v == "on":
plan.append((k, v, "PŘESKOČENO — zapnutí Live Share vysílá, zapni ho na zařízení"))
continue
plan.append((k, v, (await cli(mc, f"set {k} {v}")) if apply else "(--apply zapíše)"))
return plan
async def node_offset(mc):
ev = await mc.commands.get_time()
return ev.payload["time"] - int(time.time()) if ev.type == EventType.CURRENT_TIME else None
async def sync_clock(mc):
before = await node_offset(mc)
ev = await mc.commands.set_time(int(time.time()))
return {"before_s": before, "set": ev.type == EventType.OK, "after_s": await node_offset(mc)}
async def backup(port, restore_from=None, apply=False, sync=False):
mc = await connect(port)
out = {"taken_at": dt.datetime.now().astimezone().isoformat(timespec="seconds"), "port": port,
"self_info": plain(mc.self_info)}
ev = await mc.commands.send_device_query()
out["device"] = plain(ev.payload) if ev.type != EventType.ERROR else None
ev = await mc.commands.get_custom_vars()
out["custom_vars"] = plain(ev.payload) if ev.type != EventType.ERROR else None
ev = await mc.commands.get_contacts()
out["contacts"] = plain(ev.payload) if ev.type != EventType.ERROR else None
chans = []
for i in range(40):
ev = await mc.commands.get_channel(i)
if ev.type == EventType.ERROR:
break
chans.append(plain(ev.payload))
out["channels"] = chans
out["cli"] = await cli_settings(mc)
plan = await restore(mc, restore_from, apply) if restore_from else None
if plan and apply:
out["cli"] = await cli_settings(mc)
out["clock"] = await sync_clock(mc) if sync else {"before_s": await node_offset(mc)}
await mc.disconnect()
return out, plan
def summary(b):
si = b["self_info"]
used = [c for c in b["channels"] if c.get("channel_name")]
return (f"{si.get('name')} pubkey {str(si.get('public_key'))[:8]} · {si.get('radio_freq')}/{si.get('radio_bw')}/"
f"SF{si.get('radio_sf')}/CR{si.get('radio_cr')} · fw {(b.get('device') or {}).get('ver')} · "
f"{len(b.get('contacts') or {})} kontaktů · kanály: "
+ ", ".join(f"{c.get('channel_idx')}={c.get('channel_name')}" for c in used))
def diff(old, new):
keys = sorted(set(old["self_info"]) | set(new["self_info"]))
d = [f"self_info.{k}: {old['self_info'].get(k)} → {new['self_info'].get(k)}"
for k in keys if old["self_info"].get(k) != new["self_info"].get(k)]
if old.get("custom_vars") != new.get("custom_vars"):
d.append(f"custom_vars: {old.get('custom_vars')} → {new.get('custom_vars')}")
oc = {c["channel_idx"]: c for c in old["channels"]}
for c in new["channels"]:
o = oc.get(c["channel_idx"], {})
if o.get("channel_name") != c.get("channel_name") or o.get("channel_secret") != c.get("channel_secret"):
d.append(f"kanál {c['channel_idx']}: {o.get('channel_name')} → {c.get('channel_name')}"
+ (" (jiný klíč)" if o.get("channel_secret") != c.get("channel_secret") else ""))
oc, nc = old.get("cli") or {}, new.get("cli") or {}
for k in sorted(set(oc) | set(nc)):
if oc.get(k) != nc.get(k):
d.append(f"cli {k}: {oc.get(k)} → {nc.get(k)}")
ok, nk = set(old.get("contacts") or {}), set(new.get("contacts") or {})
if ok != nk:
d.append(f"kontakty: −{len(ok - nk)} +{len(nk - ok)}")
return d
def main():
ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
ap.add_argument("port", help="/dev/serial/by-id/... nebo BLE MAC")
ap.add_argument("name", help="jméno zálohy, např. L1-pre-flash")
ap.add_argument("--diff", metavar="JSON", help="porovnat se starší zálohou")
ap.add_argument("--restore", metavar="JSON", help="vrátit nastavení z CLI sekce zálohy (bez --apply jen ukáže)")
ap.add_argument("--apply", action="store_true", help="s --restore opravdu zapsat")
ap.add_argument("--sync-time", action="store_true", help="nastavit čas hostu (s --diff automaticky)")
a = ap.parse_args()
saved = None
if a.restore:
with open(os.path.expanduser(a.restore)) as f:
saved = json.load(f).get("cli")
if not saved:
sys.exit(f"{a.restore}: záloha nemá sekci cli (starší skript nebo firmware bez Solo CLI)")
b, plan = asyncio.run(backup(a.port, saved, a.apply, a.sync_time or bool(a.diff)))
os.makedirs(DIR, mode=0o700, exist_ok=True)
path = os.path.join(DIR, f"{a.name}-{dt.datetime.now().astimezone().date()}.json")
fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
with os.fdopen(fd, "w") as f:
json.dump(b, f, ensure_ascii=False, indent=1)
print(f"záloha: {path}\n{summary(b)}")
if b["cli"] is not None:
sh = {k: v for k, v in b["cli"].items() if k.startswith("share.")}
print(f"CLI: {len(b['cli'])} klíčů; Live Share: " + ", ".join(f"{k}={v}" for k, v in sh.items()))
else:
print("CLI: firmware Solo CLI nemá — Solo prefs zkontroluj na zařízení")
c = b["clock"]
if "set" not in c:
print(f"hodiny: odchylka {c['before_s']:+} s" if c["before_s"] is not None else "hodiny: nepřečteny")
elif c["set"]:
print(f"hodiny: odchylka {c['before_s']:+} s → srovnáno ({c['after_s']:+} s)")
else:
print(f"hodiny: odchylka {c['before_s']:+} s → firmware nastavení odmítl (čas dozadu?)")
if plan is not None:
print("\nobnova z " + a.restore + ":\n" + ("\n".join(f"- set {k} {v} → {r}" for k, v, r in plan)
if plan else "- nic, vše sedí"))
if a.diff:
with open(os.path.expanduser(a.diff)) as f:
d = diff(json.load(f), b)
print("\nrozdíly proti " + a.diff + ":\n" + ("\n".join("- " + x for x in d) if d else "- žádné"))
if __name__ == "__main__":
main()
+32
View File
@@ -0,0 +1,32 @@
; SPDX-License-Identifier: MIT
; Config of the MeshCore tools -- copy to ~/.config/meshcore-tools/config.ini
; (or point $MESHCORE_TOOLS_CONFIG at it) and describe YOUR boards.
; Format and the shell interface: tools/mctools_config.py --help.
; No secrets here: admin passwords stay in platformio.local.ini.
; A bench board on USB: tools take `b1` (or `1`) instead of the serial number.
[board.b1]
serial = 0123456789ABCDEF
mac = AA:BB:CC:DD:EE:01
aliases = 1
role = bench
; A board that keeps an identity you do not want overwritten by accident:
; flash_node.sh refuses it unless told to.
[board.home-card]
serial = FEDCBA9876543210
mac = AA:BB:CC:DD:EE:02
role = probe
protect = keeps its identity and a client database
; A radio that runs other firmware (e.g. a KISS modem of an observer): console
; tools refuse to open its port at all.
[board.modem]
serial = 00112233445566AA
role = bench
refuse = observer radio, not a MeshCore console
; A deployed node, reached over BLE only (no USB serial).
[board.hill-rpt]
mac = AA:BB:CC:DD:EE:10
role = live
+484
View File
@@ -0,0 +1,484 @@
#!/usr/bin/env bash
# SPDX-License-Identifier: MIT
# Flash any board of the fleet -- pick the route from what the board is doing,
# and prove where the image landed.
#
# tools/flash_node.sh <env> [target] [--force-protected]
#
# target USB serial (full or unique suffix), a BLE MAC, or a board name/alias
# from the local config (tools/mctools_config.py).
# Omit only when exactly one board of the fleet is plugged in.
#
# WHY A DISPATCHER. Which route works depends on the board AND on what it is
# doing right now. The rules are written out in .claude/skills/flash-node
# and AGENTS.md -- prose, i.e. the kind of thing that gets skipped mid-task. On
# 2026-09-01 three of them were skipped in one session: `pio -t upload` went to a
# board already in DFU (it touches unconditionally, kicking it back out), a
# hand-rolled nrfutil went to a board in the application (it does NOT touch, so
# nothing was listening), and a failed upload was retried instead of asking for a
# replug -- which is how an image ended up on a board nobody named. The rules
# therefore live here, where the board's state is actually known:
#
# board state route
# ------ ---------------- ------------------------------------------------
# xiao application pio -t upload (env has upload_protocol=nrfutil,
# so PlatformIO touches; ~35 s, no buttons)
# xiao bootloader + disk hand off to xiao_uf2_flash.sh
# xiao bootloader, no hand-rolled nrfutil (does not touch; the board is
# disk (serial-only) already where it needs to be)
# t1000e application with `dfu uf2` on the console -> wait for the port to
# a text console rename -> hand-rolled nrfutil on the CDC port
# t1000e bootloader hand-rolled nrfutil straight away
# wio-l1 application 1200-baud touch -> UF2 drive "TRACKER L1"
# sensecap anywhere not over USB: BLE OTA, tools/ble_dfu.py
#
# CDC is preferred over the UF2 drive wherever both work: mounting the drive
# needs root, and `sudo` over SSH without a terminal has nobody to ask for a
# password. Writing to a CDC port works as the ordinary user.
#
# Whatever the route: the whole bus is fingerprinted before and after, the target
# must come back with the new version READ OFF THE BOARD, and every other board
# must be untouched. "Device programmed" is not evidence -- both flashes that went
# wrong that day printed it.
set -uo pipefail
case "${1:-}" in -h | --help)
sed -n '3,/^[^#]/{/^#/s/^# \{0,1\}//p}' "$0"
exit 0
;;
esac
HERE="$(cd "$(dirname "$0")" && pwd)"
ROOT="$(cd "$HERE/.." && pwd)"
die() {
echo "CHYBA: $*" >&2
exit 1
}
# JEN JEDEN FLASH NAJEDNOU. Dva soubezne behy si lezou do cesty na sdilenych
# zdrojich -- jeden BLE adapter, jedna USB sbernice, jeden .pio/build adresar.
# 2. 9. 2026 se kvuli tomu spustily TRI instance zaraz (spousteny na pozadi, bez
# kontroly, jestli predchozi dobehla): kazda si zvlast retryovala BLE connect,
# takze se karta porad dokola pripojovala a odpojovala a zaplavila plochu
# notifikacemi. Nebyla to chyba retry logiky, ale toho, ze bezely tri.
exec 9>"${TMPDIR:-/tmp}/.meshcore-flash-node.lock"
if ! flock -n 9; then
die "uz bezi jiny flash (zamek ${TMPDIR:-/tmp}/.meshcore-flash-node.lock).
Pockej, az dobehne -- soubezne flashovani si leze do cesty na BLE i na USB."
fi
# Desky, na ktere se podle AGENTS.md nesaha bez vyslovneho zadani. Drzi identitu,
# historii nebo produkcni roli, a prepsat je omylem je draha chyba.
# Ktere to jsou, rika lokalni config (pole `protect`, tools/mctools_config.py).
cfg() { python3 "$HERE/mctools_config.py" "$@" 2>/dev/null; }
PROTECTED="$(cfg list --has protect --field serial || true)"
# Cil se da zadat i jako BLE MAC, takze gate musi znat OBOJI. Do 2. 9. 2026 se
# kontrola delala az po dispatchi a obe BLE cesty (`flash_over_ble` a vetev pro
# MAC) z ni utekly `exit`em driv, nez na ni dosla rada -- chranenou domaci
# T1000-E slo pres BLE prepsat bez --force-protected. Ta karta uz o identitu
# jednou nenavratne prisla.
is_protected() {
local t="$1" sn mac
for sn in $PROTECTED; do
case "$t" in *"$sn"*) return 0 ;; esac
mac="$(ble_mac_for "$sn")"
[ -n "$mac" ] && [ "$(printf %s "$t" | tr a-f A-F)" = "$mac" ] && return 0
done
return 1
}
guard_protected() {
is_protected "$1" || return 0
[ "$FORCE" = "1" ] || die "$1 je CHRANENA deska (AGENTS.md: bez vyslovneho
zadani na ni nesahat). Kdyz to fakt chces: --force-protected"
}
# BLE adresy desek, ktere nemaji textovou konzoli. Companion build se do
# bootloaderu neda poslat prikazem `dfu` (zadna konzole neni), takze jediny zpusob
# je buttonless DFU pres BLE. Kdyz je pak deska ZAROVEN na USB, samotny prenos jde
# po USB: ~20 s misto 3-15 min po BLE (podle vyjednaneho MTU).
ble_mac_for() {
cfg mac "$1" || true # pole `mac` v lokalnim configu
}
# Deska, ktera po flashi "spadla z USB", NENI mrtva -- 2. 9. 2026 x1 i x4 v tom
# stavu normalne advertovaly na BLE. Softwarovy replug pritom neni z ceho udelat:
# vsechny desky visi primo na root hubu (xhci), a ten neumi prepinat napajeni
# portu, takze ani uhubctl by nepomohl. BLE OTA je proto jedina cesta, jak takovou
# desku doflashovat BEZ RUKOU -- a nepotrebuje USB touch, takze ji ani nema jak
# shodit znovu.
#
# Pozor na dock-quiet: deska, ktera JE na USB, drzi DTR a proto neadvertuje
# (potvrzeno tyz den na x2). BLE zachrana tedy funguje prave pro ty desky, ktere
# z USB vypadly -- coz je presne kdyz je potreba.
# Vraci: 0 = MAC videna, 1 = scan bezel a MAC tam nebyla, 2 = ADAPTER NEVIDEL NIC.
# Ten treti stav je potreba rozlisit, protoze scanner na tehle pracovni stanici je
# HLUCHY (MediaTek; `Discovering: yes` a presto nulovy vystup -- viz pamet
# "BLE jen z desktop"). Bez toho rozliseni skript hlasil "deska neadvertuje" i
# tehdy, kdyz neslysi adapter, tedy obvinoval desku z vady hostitele.
ble_reachable() {
local mac="$1" out
out="$(timeout 20 bash -c "bluetoothctl --timeout 12 scan on 2>/dev/null" || true)"
printf %s "$out" | grep -q "$mac" && return 0
printf %s "$out" | grep -qE "^\s*\[NEW\] Device |Device [0-9A-F]{2}:" || return 2
return 1
}
flash_over_ble() {
local mac="$1"
echo "== cesta: BLE OTA na $mac (bez USB, tedy bez rizika replugu)"
"$PIO" run -e "$ENV_NAME" >/dev/null 2>&1 || die "build selhal"
bluetoothctl disconnect "$mac" >/dev/null 2>&1 || true
sleep 2
python3 "$HERE/ble_dfu.py" ".pio/build/$ENV_NAME/firmware.zip" "$mac"
}
ENV_NAME=""
TARGET=""
FORCE=0
PASSTHRU=()
for arg in "$@"; do
case "$arg" in
--force-protected) FORCE=1 ;;
# Vse ostatni s -- se predava ble_flash_node.sh (--require-silence, --via,
# --stop-service, --check-only); tady by to nemelo co delat.
--*) PASSTHRU+=("$arg") ;;
*) if [ -z "$ENV_NAME" ]; then ENV_NAME="$arg"; else TARGET="$arg"; fi ;;
esac
done
[ -n "$ENV_NAME" ] || {
echo "usage: $(basename "$0") <env> [serial|board|mac] [--force-protected]" >&2
exit 1
}
# Nastroje a pracovni adresar PRED jakoukoli cestou. Do 2. 9. 2026 se PIO
# prirazovalo AZ ZA vetvi pro BLE MAC, ktera ho pouzivala -- se `set -u` to
# znamenalo "PIO: unbound variable" a cela dokumentovana cesta na stozar/vzdálené stanoviště
# byla mrtva. `cd "$ROOT"` bylo taky pozdeji, takze build i relativni cesta do
# .pio/build mirily do cwd volajiciho.
PIO="$HOME/.platformio/penv/bin/pio"
[ -x "$PIO" ] || PIO="$(command -v pio)" || die "pio nenalezeno"
NRF="$HOME/.platformio/packages/tool-adafruit-nrfutil"
cd "$ROOT" || die "nelze do $ROOT"
# Jmeno nebo alias desky z lokalniho configu -> seriove cislo. Serial, jeho
# unikatni suffix i BLE MAC projdou beze zmeny.
case "$TARGET" in
"" | *:*:*:*:*:*) ;;
*) SN="$(cfg serial "$TARGET")" && TARGET="$SN" ;;
esac
# Cil zadany jako BLE MAC = deska na USB vubec neni (stozar, vzdálené stanoviště). Predava se
# ble_flash_node.sh, ktery kolem prenosu dela sest veci, jez tady chybely:
# odmitnuti spinaveho stromu, prefs PRED i PO (prefs v InternalFS prebijeji build
# flagy a flash je nepresipe), --require-silence u uzlu s odpojenou antenou,
# uvolneni linku v BlueZ, overeni verze proti obrazu a vraceni sluzby. Presne
# u mastovych/chatovych uzlu, kam tahle vetev miri, je ticho ochrana PA.
case "$TARGET" in
*:*:*:*:*:*)
guard_protected "$TARGET"
BFN="$HERE/ble_flash_node.sh"
[ -x "$BFN" ] || die "$BFN nenalezen"
echo "== cil je BLE MAC $TARGET -- deska neni na USB, predavam ble_flash_node.sh"
echo " (pokud ma uzel odpojenou antenu, pridej --require-silence)"
exec "$BFN" --env "$ENV_NAME" --mac "$TARGET" "${PASSTHRU[@]}"
;;
esac
# Spinavy strom da verzi s '+', a na uzlu pak nepoznas, co na nem je (AGENTS.md).
if [ -n "$(git status --porcelain 2>/dev/null)" ]; then
echo "VAROVANI: strom neni cisty -- obraz dostane verzi s '+'." >&2
fi
echo "== env: $ENV_NAME${TARGET:+ cil: $TARGET}"
echo "== otisk desek PRED flashem"
BEFORE="$("$HERE/board_probe.py" --all)" || die "otisk se nezdaril"
echo "$BEFORE" | sed 's/^/ /'
if [ -n "$TARGET" ]; then
hits="$(echo "$BEFORE" | grep -c -- "$TARGET" || true)"
if [ "$hits" = "0" ]; then
# Neni na USB. Drive to znamenalo "rekni si o replug"; kdyz ale deska
# advertuje, da se doflashovat pres BLE a ruce nejsou potreba.
guard_protected "$TARGET"
MAC="$(ble_mac_for "$TARGET")"
if [ -n "$MAC" ]; then
echo "== $TARGET neni na USB; zkousim, jestli je na BLE ($MAC)"
ble_reachable "$MAC"
BR=$?
if [ "$BR" = "0" ]; then
flash_over_ble "$MAC"
exit $?
fi
[ "$BR" = "2" ] && die "$TARGET neni na USB a BLE scan na tomhle hostu NEVIDEL
ANI JEDNO zarizeni -- to neni vypoved o desce, ale o adapteru. Na tehle
pracovni stanici je scanner hluchy (MediaTek): $(bluetoothctl) hlasi
Discovering: yes a presto nic. Bud replug po USB, nebo BLE cestu spust
z hostu, ktery ji slysi, nebo pres ble_flash_node.sh --via."
die "$TARGET neni na USB ani neadvertuje na BLE -- replug.
POZOR, nez z toho udelas diagnozu: BLE zachrana funguje jen tehdy, kdyz
ten build BLE vubec MA. USB-only companion (env *_companion_radio_usb,
napr. Xiao_x4_cmp_usb) ho nema, takze tam neadvertuje ani zdrava deska --
overeno 2. 9. 2026 na x2, ktera tehdy jela USB build. Dnesni Xiao_x2_cmp
je naopak BLE companion: na USB mlci a advertuje (11. 10. 2026). BLE MAC
v tabulce vyse muze byt z doby, kdy na desce jel jiny build."
fi
die "cil $TARGET neni na sbernici a neznam k nemu BLE adresu."
fi
[ "$hits" = "1" ] || die "cil $TARGET je na sbernici ${hits}x -- upresni seriove cislo"
else
n="$(echo "$BEFORE" | grep -c . || true)"
[ "$n" = "1" ] || die "na sbernici je $n desek -- rekni ktera: $(basename "$0") $ENV_NAME <serial|board>"
TARGET="$(echo "$BEFORE" | awk '{print $1}')"
fi
guard_protected "$TARGET"
FULL="$(echo "$BEFORE" | awk -v t="$TARGET" '$1 ~ t {print $2}')"
BOARD="${FULL%%/*}"
STATE="${FULL##*/}"
# shellcheck disable=SC2010 # by-id names are [A-Za-z0-9_:.-]; $TARGET is a regex
PORT="/dev/serial/by-id/$(ls /dev/serial/by-id/ | grep -- "$TARGET" | head -1)"
echo "== cil: $BOARD, stav: $STATE"
# Stav, ktery NENI zjisteny protokol, znamena "nevim, co na desce bezi" -- a do
# `xiao/*` propadal na `pio -t upload`, tedy 1200baudovy touch naslepo. U stavu
# `obsazeny` je to nejhorsi: board_probe.py se portu, ktery drzi nekdo jiny,
# schvalne NESAHA, protoze 2. 9. 2026 dotek portu, ktery drzel openHop, oznacil
# link za degradovany a vypnul radio natrvalo do repeater.db. Ta pojistka byla
# v probe a do dispatcheru se nepropsala.
case "$STATE" in
obsazeny)
die "port desky $TARGET drzi jiny proces ($(echo "$BEFORE" | grep -- "$TARGET" | cut -d' ' -f3-)).
Nesaham na nej: dotek zive linky umi protistrane vypnout radio natrvalo.
Zastav toho, kdo port drzi, a spust znovu."
;;
visi | nic | nedostupny | chyba)
die "stav desky $TARGET se nepodarilo zjistit (probe hlasi '$STATE'), takze
nevim, kterou cestou flashovat -- a hadat znamena touch naslepo.
U T1000-E je 'visi' bezne (pyserial ji neotiskne):
dostan ji do bootloaderu rucne (dlouhy stisk do 8 s od startu) a spust
znovu, pak to pujde vetvi t1000e/boot."
;;
esac
# OCEKAVANA VERZE. Bez ni umi otisk rict jen "neco se zmenilo", coz je slabe:
# 2. 9. 2026 pio dvakrat ohlasilo SUCCESS a na desce zustal STARY firmware
# (bootloader nestihl novy obraz aktivovat, protoze deska spadla z USB), a
# jindy naopak flash "selhal" a firmware se pritom nalil. Jedine, cemu se da
# verit, je verze PRECTENA Z DESKY -- a porovnat se musi proti tomu, co je
# v obrazu, ne proti predchozimu stavu.
"$PIO" run -e "$ENV_NAME" >/dev/null 2>&1 || die "build selhal"
WANT_VER="$(strings ".pio/build/$ENV_NAME/firmware.elf" 2>/dev/null |
grep -oE "v[0-9]+\.[0-9]+\.[0-9]+-tth[0-9a-f]+\+?" | head -1)"
[ -n "$WANT_VER" ] || die "obraz nema stampovanou verzi -- po flashi by neslo
overit, co na desce doopravdy je. Zapoj do envu: extra_scripts = \${stamped.extra_scripts}"
echo "== ocekavana verze: $WANT_VER"
has_uf2_drive() {
local d s blk
for d in /sys/bus/usb/devices/*/; do
s="$(cat "$d/serial" 2>/dev/null)" || continue
case "$s" in *"$TARGET"*) ;; *) continue ;; esac
blk="$(ls -d "$d"*/host*/target*/*/block/* 2>/dev/null | head -1)" || true
[ -n "$blk" ] && return 0
done
return 1
}
# nrfutil umi skoncit tracebackem a PRESTO vratit 0 -- videno 1. 9. 2026 na
# "No data received on serial port". Cte se tedy i vystup, ne jen navratovy kod.
run_nrfutil() {
local port="$1" out
# ZADNY dalsi `pio run`: build je jednou nahore, u cteni WANT_VER. Stamping meni
# FIRMWARE_BUILD_DATE pri kazdem behu, takze kazde volani znamenalo PLNY rebuild
# (10-30 s) -- a hlavne se pak flashoval jiny artefakt, nez ze ktereho se
# WANT_VER precetla, cimz ta kontrola prestavala overovat odeslany obraz.
out="$(PYTHONPATH="$NRF/site-packages" "$HOME/.platformio/penv/bin/python" \
"$NRF/adafruit-nrfutil.py" dfu serial \
-pkg ".pio/build/$ENV_NAME/firmware.zip" -p "$port" -b 115200 --singlebank 2>&1)" ||
{
echo "$out" | tail -4
return 1
}
echo "$out" | tail -3
case "$out" in *NordicSemiException* | *"Not able to proceed"* | *Traceback*) return 1 ;; esac
return 0
}
# T1000-E: aplikace s textovou konzoli se do bootloaderu posle sama prikazem
# `dfu uf2`. Port se pritom PREJMENUJE z "...T1000-E-BOOT..." na "...T1000-E..."
# (ano, "-BOOT" ma aplikace) a pyserial hodi OSError: [Errno 5] -- to je reboot,
# ne chyba.
t1000e_to_bootloader() {
echo "== posilam 'dfu uf2' na konzoli, deska se rebootne do bootloaderu"
python3 - "$PORT" <<'PY' || true
import serial, sys, time
try:
s = serial.Serial(sys.argv[1], 115200, timeout=0)
s.dtr = True; s.rts = True
time.sleep(1.5)
s.write(b"dfu uf2\r\n"); s.flush()
time.sleep(2)
s.close()
except Exception as e:
print(f" ({type(e).__name__} pri odesilani -- deska se rebootuje)")
PY
for _ in $(seq 30); do
local p
# shellcheck disable=SC2010 # by-id names are [A-Za-z0-9_:.-]; $TARGET is a regex
p="$(ls /dev/serial/by-id/ 2>/dev/null | grep -- "$TARGET" | grep -v -- "-BOOT" | head -1)"
[ -n "$p" ] && {
PORT="/dev/serial/by-id/$p"
echo " bootloader port: $PORT"
return 0
}
sleep 1
done
return 1
}
RC=0
case "$BOARD/$STATE" in
xiao/boot)
if has_uf2_drive; then
echo "== cesta: UF2 disk -> predavam xiao_uf2_flash.sh"
"$PIO" run -e "$ENV_NAME" -t create_uf2 >/dev/null 2>&1 || die "create_uf2 selhal"
# NE `exec`: tim by se predalo rizeni a preskocila zaverecna kontrola, ze
# se nezmenila zadna JINA deska -- tedy presne ta pojistka, kvuli ktere
# tenhle skript vznikl. xiao_uf2_flash.sh si overi svuj cil, my overime zbytek.
"$HERE/xiao_uf2_flash.sh" ".pio/build/$ENV_NAME/firmware.uf2" "$TARGET" || RC=$?
# `else` tady CHYBELO, takze po uspesnem UF2 flashi beh propadl do nrfutil na
# $PORT zachyceny PRED flashem -- ten uz neexistuje, protoze se deska
# rebootla do aplikace. Kazdy uspesny UF2 flash se tim ohlasil jako selhany,
# vcetne rady "dvojklikni RESET a spust znovu" pro flash, ktery prosel.
else
echo "== cesta: rucni nrfutil (bootloader bez UF2 disku = serial-only rezim)"
if ! run_nrfutil "$PORT"; then
# Videno 1. 9. 2026 na x2: bootloader vystavuje CDC (USB tridy 02+0a, zadne
# mass storage), ale na DFU protokol neodpovida -- nrfutil skonci na "No
# data received", se `--singlebank` i bez nej. Deska neni mrtva a replug
# s tim nehne, protoze v bootloaderu zustane; chce to DVOJKLIK na RESET,
# kterym se bootloader prepne do UF2 rezimu a VYSTAVI DISK. Pak uz tenhle
# skript sam zvoli druhou cestu (xiao_uf2_flash.sh).
echo >&2
echo "Bootloader neodpovida na serial DFU, a UF2 disk nevystavuje." >&2
echo "DVOJKLIKNI na male tlacitko RESET -- tim se prepne do UF2 rezimu" >&2
echo "a objevi se disk. Pak spust tenhle skript znovu, uz pujde diskem." >&2
RC=1
fi
fi
;;
xiao/*)
echo "== cesta: pio -t upload (deska je v APLIKACI, touch si udela sam)"
"$PIO" run -e "$ENV_NAME" -t upload --upload-port "$PORT" || RC=$?
;;
t1000e/boot)
echo "== cesta: rucni nrfutil (T1000-E uz je v bootloaderu)"
run_nrfutil "$PORT" || RC=1
;;
t1000e/text)
t1000e_to_bootloader || die "deska se do 30 s neprepnula do bootloaderu"
run_nrfutil "$PORT" || RC=1
;;
t1000e/*)
# Companion build nema textovou konzoli, takze `dfu uf2` nema kam poslat.
# Buttonless DFU pres BLE ho tam dostane -- a protoze deska JE na USB,
# samotny prenos pak jde po kabelu (~20 s misto minut po BLE).
MAC="$(ble_mac_for "$TARGET")"
[ -n "$MAC" ] || die "T1000-E ve stavu '$STATE' nema textovou konzoli a k seriaku
$TARGET neznam BLE adresu. Doplň pole mac do configu ($(cfg path || echo "$HOME/.config/meshcore-tools/config.ini")), nebo desku dostan
do bootloaderu rucne (dlouhy stisk do 8 s od startu)."
echo "== cesta: BLE buttonless -> bootloader, pak flash po USB"
echo " BLE $MAC (jen prepnuti; prenos pojede po kabelu)"
"$PIO" run -e "$ENV_NAME" >/dev/null 2>&1 || die "build selhal"
# Pripojeny BLE klient by uzel drzel a buttonless zapis by nemel kam --
# zastavit sluzbu NESTACI, spojeni drzi BlueZ (skill flash-node).
bluetoothctl disconnect "$MAC" >/dev/null 2>&1 || true
sleep 2
if ! python3 "$HERE/ble_dfu.py" ".pio/build/$ENV_NAME/firmware.zip" "$MAC" phase1; then
die "buttonless pres BLE se nepovedl. BLE DFU je flaky a jeden pokus o connect
nestaci -- ale NESPOUSTEJ to opakovane, RESET po kazdem padu umi desku
uštvat doopravdy (skill flash-node)."
fi
# Bootloader se na USB hlasi BEZ "-BOOT" v nazvu portu -- ano, obracene.
echo "== cekam na bootloader port"
BOOTPORT=""
for _ in $(seq 30); do
# shellcheck disable=SC2010 # by-id names are [A-Za-z0-9_:.-]; $TARGET is a regex
p="$(ls /dev/serial/by-id/ 2>/dev/null | grep -- "$TARGET" | grep -v -- "-BOOT" | head -1)"
[ -n "$p" ] && {
BOOTPORT="/dev/serial/by-id/$p"
break
}
sleep 1
done
[ -n "$BOOTPORT" ] || die "deska se do 30 s neobjevila v bootloaderu na USB"
echo " bootloader port: $BOOTPORT"
run_nrfutil "$BOOTPORT" || RC=1
;;
wio-l1/*)
echo "== cesta: Wio L1 -> predavam MeshCore-solo/flash-l1.sh (touch + disk TRACKER L1)"
L1="$HOME/projects/MeshCore-solo/flash-l1.sh"
[ -x "$L1" ] || die "$L1 nenalezen"
"$PIO" run -e "$ENV_NAME" -t create_uf2 >/dev/null 2>&1 || die "create_uf2 selhal"
"$L1" "$ROOT/.pio/build/$ENV_NAME/firmware.uf2" || RC=$?
;;
*)
die "kombinaci '$BOARD/$STATE' neumim. Deska neodpovida zadnemu protokolu --
vytahni ji z USB, zapoj zpatky a spust znovu."
;;
esac
if [ "$RC" != "0" ]; then
echo >&2
echo "FLASH SELHAL. NEOPAKUJ ho -- jeden 1200baudovy touch na power session." >&2
echo "Vytahni desku z USB, zapoj zpatky, a spust tenhle skript znovu." >&2
echo >&2
echo "Kontroluji, jestli to nezapsalo jinam:" >&2
"$HERE/board_probe.py" --all --compare <(echo "$BEFORE") >&2
exit 1
fi
echo "== otisk desek PO flashi (necham CDC nabehnout)"
sleep 8
AFTER="$("$HERE/board_probe.py" --all)"
# JEDEN otisk pro obe kontrole. Driv se sbernice otiskovala dvakrat za sebou
# (kazdy az PROBE_DEADLINE dlouhy) a verdikt o zmenach se pocital z jineho
# vzorku, nez overeni verze.
#
# A `|| true` tady BYT NESMI. Do 2. 9. 2026 tam bylo, takze verdikt "zmenila se
# i jina deska" se jen vypsal a skript skoncil nulou -- tedy presne ten nalez,
# pro ktery tenhle nastroj vznikl (obraz mel jit na x4 a pristal na x2), se dal
# prehlednout a kazdy volajici, ktery se ridi exit kodem, videl uspech.
if ! "$HERE/board_probe.py" --all --compare <(echo "$BEFORE") \
--expect-changed "$TARGET" --now <(echo "$AFTER"); then
echo >&2
die "otisk sbernice nesouhlasi (viz vys). Bud se zmenila i JINA deska, nebo se
cil nezmenil -- obojim smerem to znamena, ze obraz sel jinam, nez mel."
fi
GOT_VER="$(echo "$AFTER" | awk -v t="$TARGET" '$1 ~ t {print $3}')"
# Rozlisuj NEOVERITELNE od OVERENE SPATNE. board_probe umi vratit stavovy text
# misto verze (napr. T1000-E, kterou pyserial neotiskne), a
# ten se drive porovnal s WANT_VER a vypsal "FLASH SE NEAPLIKOVAL" po flashi,
# ktery klidne prosel. Dokumentovana cesta `flash_node.sh t1000e_repeater B3F160`
# tak koncila chybou vzdycky.
case "$GOT_VER" in
"" | "-" | neodpovida | drzi | nenalezen)
echo >&2
echo "NEOVERENO: flash probehl bez chyby, ale verzi z $TARGET nejde precist" >&2
echo "(probe hlasi '$STATE'). NEZNAMENA to, ze flash selhal -- u T1000-E je to" >&2
echo "bezny stav. Over rucne z konzole: 'ver' ma dat $WANT_VER." >&2
exit 2
;;
esac
if [ "$GOT_VER" != "$WANT_VER" ]; then
echo >&2
die "FLASH SE NEAPLIKOVAL. Deska hlasi '$GOT_VER', obraz ma '$WANT_VER'.
Nastroj pred tim mohl hlasit uspech -- 'Device programmed' i 'SUCCESS'
umi vypsat i beh, po kterem na desce zustal stary firmware (bootloader
nestihl novy obraz aktivovat). Spust znovu; pokud to vytrva, chce to
replug."
fi
echo "== OVERENO NA DESCE: $TARGET bezi $GOT_VER"
Executable
+26
View File
@@ -0,0 +1,26 @@
#!/usr/bin/env python3
# SPDX-License-Identifier: MIT
"""Board names -> USB serial numbers, for the Python tools.
A thin view of the local config (tools/mctools_config.py,
~/.config/meshcore-tools/config.ini): the tools refer to boards by name, and
`/dev/serial/by-id` is matched on the serial number -- a ttyACM number
changes with every replug and would point a console at a DIFFERENT board.
There used to be a table here, and a copy of it in five other places (the
shell flashers, the sniffer, the console and a hook). One board reflashed,
the copies drifted, and a stale entry aimed a console at the wrong board.
Now there is one file, outside the repo.
"""
from mctools_config import boards, serial_for # noqa: F401 (re-exported)
# name -> serial, only boards that have one (a BLE-only node has none)
FLEET = {n: b["serial"] for n, b in boards().items() if b.get("serial")}
# the same keyed by each alias too (mesh_sniffer takes `--board 0`)
FLEET_BARE = dict(FLEET)
for _b in boards().values():
for _a in (x.strip() for x in _b.get("aliases", "").split(",")):
if _a and _b.get("serial"):
FLEET_BARE[_a] = _b["serial"]
+569
View File
@@ -0,0 +1,569 @@
#!/usr/bin/env python3
# SPDX-License-Identifier: MIT
"""Regression smoke test for the bench fleet -- run it after every firmware change.
tools/fleet_test.py [--boards 0,1,2,4] [--rounds 1] [--json out.json]
Grew out of a one-off hw_check.py written to tell a dead radio from a dead IRQ
line. The lesson that made it worth keeping: **a node's own counters cannot
certify the node**. `sent` only says the firmware believes it transmitted, which
is exactly what a dead DIO1 line breaks -- bench-board reported `sent 0` for a week
while a second board heard every frame it sent. So every RF claim here is made by
a DIFFERENT board than the one under test.
What it does, in order:
1. identity version/build per board; flags unstamped ("v1.16.0" with no -tth,
identical in every build ever made) and dirty ("+") images, and
boards that are not on the same build as the rest.
2. config freq/bw/sf/cr must agree across the fleet, names must be unique.
Without this the matrix below measures nothing -- two boards on
different spreading factors simply cannot hear each other, which
looks exactly like broken hardware.
3. matrix N x N. Each board sends a ZERO-HOP advert in turn; every other
board must count it. Zero-hop is deliberate: nobody rebroadcasts
it, so "B heard A" cannot be satisfied by C's relay of A -- and
it means the test never has to touch `repeat` prefs.
4. hygiene tx_timeout / tx_start_fail / recv_errors must not move during the
run, on any board.
5. commands console builds only: the command surface answers (informational,
plus a hard fail on the handful every repeater build must have).
Nothing here writes prefs, changes radio settings or reboots anything.
Handles both build flavours on the bench: the text console (repeater/analyzer)
and the binary companion protocol (companion_radio, which has no text console).
Detection is automatic.
TRAP: do not leave a BLE client connected to a board under test. The USB and BLE
consoles share one command[160] buffer (simple_repeater/main.cpp), so two live
consoles interleave characters into one line and the node ends up executing
garbage. An earlier A/B run was invalidated exactly that way.
"""
import argparse
import glob
import json
import os
import re
import struct
import subprocess
import sys
import time
from datetime import datetime, timezone
import serial
HERE = os.path.dirname(os.path.abspath(__file__))
FLASH_SH = os.path.join(HERE, "xiao_uf2_flash.sh")
# Companion protocol (examples/companion_radio/MyMesh.cpp)
CMD_APP_START, CMD_SEND_SELF_ADVERT = 1, 7
CMD_DEVICE_QUERY, CMD_GET_STATS = 22, 56
STATS_TYPE_PACKETS = 2
RESP_SELF_INFO, RESP_DEVICE_INFO, RESP_STATS = 5, 13, 24
def fleet_table():
"""Fleet number -> USB serial, read out of xiao_uf2_flash.sh.
Parsed rather than duplicated on purpose: two copies of this table would
drift, and mixing up which board is which is the single most expensive
mistake on this bench (a flash went to x4 while the log said x3).
"""
try:
src = open(FLASH_SH).read()
except OSError as e:
sys.exit(f"nelze precist {FLASH_SH}: {e}")
tbl = dict(re.findall(r"^\s*([0-9])\)\s*TARGET=([0-9A-F]{16})\s*;;", src, re.M))
if not tbl:
sys.exit(f"v {FLASH_SH} nenalezena tabulka desek -- zmenil se format?")
return tbl
def discover(wanted):
"""[(fleet_no, serial, port)] for XIAO boards actually on USB.
Always through /dev/serial/by-id and matched on the SERIAL NUMBER: ttyACM*
renumbers on every replug, so a positional guess talks to another board.
"""
tbl = fleet_table()
found, modems = [], []
# Hledaji se OBA product stringy, ale znamenaji ruzne desky:
#
# usb-Seeed_Studio_XIAO_nRF52840_<sn> MeshCore build (PID 8044)
# usb-Seeed_XIAO-Wio-SX1262_<sn> openhop_modem firmware (PID 0044)
#
# Prejmenovani dela openhop_modem, ne bootloader -- je to hloupe SX1262 PHY
# pro openHop demona, takze na MeshCore konzoli ani companion protokol
# neodpovi a zadnou UF2 mechaniku nevystavi (openHop config:
# radio_type: pymc_usb).
#
# Hlasi se zvlast, protoze obe chybne odpovedi na tohle stoji cas: pri globu
# jen na "XIAO_nRF52840" se 1. 9. 2026 matice smrskla na jednu desku bez
# vysvetleni, a pri globu na oboji to vypadalo jako dve zaseknute desky
# (nasledoval replug a pokus o nrfutil, oboje zbytecne -- deska byla v poradku).
for port in sorted(glob.glob("/dev/serial/by-id/*XIAO-Wio-SX1262*")):
m = re.search(r"_([0-9A-F]{16})-if00", port)
if m:
sn = m.group(1)
modems.append((next((n for n, s in tbl.items() if s == sn), "?"), sn))
if modems:
for no, sn in modems:
print(f" x{no} ({sn}): openhop_modem firmware, ne MeshCore uzel -- vynechavam")
for port in sorted(glob.glob("/dev/serial/by-id/*XIAO_nRF52840*")):
m = re.search(r"_([0-9A-F]{16})-if00", port)
if not m:
continue
sn = m.group(1)
no = next((n for n, s in tbl.items() if s == sn), "?")
if wanted and no not in wanted:
continue
found.append((no, sn, port))
return found
# ---------------------------------------------------------------- transports
class Node:
"""Common bits. Ports are opened once and held: reopening costs ~1.3 s of
settle time per command (CDC on nRF52 is deaf until DTR is raised), which
turns an N x N matrix into minutes of dead waiting."""
def __init__(self, no, sn, port):
self.no, self.sn, self.port = no, sn, port
self.name = f"x{no}"
# serial_for_url: a /dev path, or socket://host:port for a board on
# another host (--remote; DTR/RTS are then held by the far end).
self.s = serial.serial_for_url(port, 115200, timeout=0)
self.s.dtr = True
self.s.rts = True
time.sleep(1.3)
self.s.reset_input_buffer()
self.info = {}
def close(self):
try:
self.s.close()
except Exception:
pass
class ConsoleNode(Node):
"""Repeater / analyzer build: line-oriented text console."""
kind = "console"
def cmd(self, c, timeout=3.0, quiet=0.25):
"""Send and read until the reply has stopped arriving.
Idle-based rather than a fixed sleep: paged analyzer replies (rxlog) are
kilobytes and a fixed wait either truncates them or wastes seconds on
every one-line answer.
"""
self.s.reset_input_buffer()
self.s.write((c + "\r\n").encode())
buf, deadline, last = b"", time.time() + timeout, None
while time.time() < deadline:
chunk = self.s.read(8192)
if chunk:
buf += chunk
last = time.time()
elif last and time.time() - last > quiet:
break
else:
time.sleep(0.02)
return buf.decode(errors="replace")
def stats(self):
m = re.search(r"\{.*\}", self.cmd("stats-packets"))
return json.loads(m.group(0)) if m else {}
def radio_stats(self):
m = re.search(r"\{.*\}", self.cmd("stats-radio"))
return json.loads(m.group(0)) if m else {}
def identify(self):
ver = self.cmd("ver")
m = re.search(r"->\s*(\S+)\s*\(Build:\s*([^)]*)\)", ver)
self.info["version"] = m.group(1) if m else "?"
self.info["build"] = m.group(2).strip() if m else "?"
r = re.search(r"->\s*>?\s*([\d.]+),([\d.]+),(\d+),(\d+)", self.cmd("get radio"))
self.info["radio"] = (f"{float(r.group(1)):.3f}/{float(r.group(2))}/"
f"{r.group(3)}/{r.group(4)}") if r else "?"
n = re.search(r"->\s*>?\s*(.+)", self.cmd("get name"))
self.info["node"] = n.group(1).strip() if n else "?"
def advert(self):
return "OK" in self.cmd("advert.zerohop", timeout=4.0)
class CompanionNode(Node):
"""companion_radio build: binary frames, no text console at all.
Framing is '<' + uint16 LE length + payload outbound, '>' + length + payload
inbound (src/helpers/ArduinoSerialInterface.cpp).
"""
kind = "companion"
def send(self, payload):
self.s.write(b"<" + struct.pack("<H", len(payload)) + bytes(payload))
self.s.flush()
def recv(self, want, timeout=2.5):
"""Wait for a frame with response code `want`, skipping push frames.
A companion node emits unsolicited pushes (new message waiting, and so
on), so 'the next frame' is not necessarily the answer to the question.
"""
buf, deadline = b"", time.time() + timeout
while time.time() < deadline:
buf += self.s.read(4096) or b""
while True:
i = buf.find(b">")
if i < 0 or len(buf) < i + 3:
break
ln = struct.unpack("<H", buf[i + 1:i + 3])[0]
if len(buf) < i + 3 + ln:
break
frame, buf = buf[i + 3:i + 3 + ln], buf[i + 3 + ln:]
if frame and frame[0] == want:
return frame
time.sleep(0.02)
return None
def handshake(self):
# RESP_CODE_DEVICE_INFO: code, ver_code, max_contacts/2, max_channels,
# ble_pin[4], build_date[12], manufacturer[40],
# firmware_version[20], client_repeat, path_hash_mode
self.send(bytes([CMD_DEVICE_QUERY, 10]))
d = self.recv(RESP_DEVICE_INFO)
if d and len(d) >= 80:
self.info["build"] = d[8:20].split(b"\0")[0].decode(errors="replace")
self.info["version"] = d[60:80].split(b"\0")[0].decode(errors="replace")
# RESP_CODE_SELF_INFO: code, adv_type, tx_power, max_tx_power,
# pub_key[32], lat[4], lon[4], multi_acks,
# loc_policy, telemetry, manual_contacts,
# freq[4], bw[4], sf, cr, name[...]
self.send(bytes([CMD_APP_START, 1, 0, 0, 0, 0, 0, 0]) + b"fleet")
s = self.recv(RESP_SELF_INFO)
if s and len(s) >= 58:
freq, bw = struct.unpack("<II", s[48:56])
self.info["radio"] = f"{freq/1000:.3f}/{bw/1000}/{s[56]}/{s[57]}"
self.info["node"] = s[58:].decode(errors="replace").strip()
return bool(s)
def identify(self):
if not self.handshake():
self.info.setdefault("version", "?")
def stats(self):
self.send(bytes([CMD_GET_STATS, STATS_TYPE_PACKETS]))
f = self.recv(RESP_STATS)
if not f or len(f) < 30 or f[1] != STATS_TYPE_PACKETS:
return {}
v = struct.unpack("<7I", f[2:30])
return dict(zip(("recv", "sent", "flood_tx", "direct_tx",
"flood_rx", "direct_rx", "recv_errors"), v))
def radio_stats(self):
return {}
def advert(self):
self.send(bytes([CMD_SEND_SELF_ADVERT, 0])) # 0 = zero hop
return True
def open_node(no, sn, port):
"""Console or companion? Ask, do not assume.
A companion build ignores stray text and a console build ignores stray
frames, so probing either way is harmless.
"""
n = ConsoleNode(no, sn, port)
if "->" in n.cmd("ver", timeout=2.0):
return n
n.close()
c = CompanionNode(no, sn, port)
if c.handshake():
return c
c.close()
return None
# -------------------------------------------------------------------- checks
class Report:
def __init__(self):
self.rows = []
def add(self, section, name, ok, detail):
self.rows.append((section, name, bool(ok), detail))
mark = "OK " if ok else "FAIL"
print(f" [{mark}] {name}: {detail}", flush=True)
def note(self, text):
print(f" {text}", flush=True)
@property
def failed(self):
return [r for r in self.rows if not r[2]]
def check_identity(nodes, rep):
print("\n== 1. identita a verze", flush=True)
for n in nodes:
v, b = n.info.get("version", "?"), n.info.get("build", "?")
rep.note(f"x{n.no} {n.info.get('node','?'):<14} {v} ({b}) [{n.kind}]")
vers = {n.info.get("version", "?") for n in nodes}
stale = [n for n in nodes if not re.search(r"-tth[0-9a-f]+", n.info.get("version", ""))]
dirty = [n for n in nodes if n.info.get("version", "").endswith("+")]
rep.add("identity", "vsechny obrazy jsou stampovane", not stale,
"ok" if not stale else
f"bez -tth<sha>: {[n.name for n in stale]} -- env nema ${{stamped.extra_scripts}}, "
"verze je literal shodny ve vsech buildech")
rep.add("identity", "zadny obraz z spinaveho stromu", not dirty,
"ok" if not dirty else f"konci na '+': {[n.name for n in dirty]}")
# Deliberately a note, not a check. The bench legitimately runs several envs
# at once (repeater, bot, companion), so "all on one version" is not a
# property this fleet has -- asserting it would cry wolf on every run and
# train you to ignore the summary. What matters is that you can SEE what is
# where, and the two things above, which are rule violations in any env.
if len(vers) > 1:
by_ver = {}
for n in nodes:
by_ver.setdefault(n.info.get("version", "?"), []).append(n.name)
rep.note("ruzne buildy na lavici: "
+ " | ".join(f"{v}: {' '.join(b)}" for v, b in sorted(by_ver.items())))
def check_config(nodes, rep):
print("\n== 2. konfigurace radia", flush=True)
radios = {}
for n in nodes:
radios.setdefault(n.info.get("radio", "?"), []).append(n.name)
rep.add("config", "shodne parametry radia", len(radios) == 1,
" | ".join(f"{r}: {v}" for r, v in radios.items()))
names = [n.info.get("node", "?") for n in nodes]
dupes = {x for x in names if names.count(x) > 1}
rep.add("config", "jmena uzlu jsou unikatni", not dupes,
"ok" if not dupes else f"duplicity: {sorted(dupes)}")
return len(radios) == 1
def check_matrix(nodes, rep, rounds):
print(f"\n== 3. krizova matice ({len(nodes)} desek, {rounds}x)", flush=True)
if len(nodes) < 2:
rep.add("matrix", "matice potrebuje aspon 2 desky", False,
f"pripojena je {len(nodes)}")
return {}
heard = {t.name: {r.name: 0 for r in nodes if r is not t} for t in nodes}
rssi = {t.name: {} for t in nodes}
for rnd in range(rounds):
for tx in nodes:
others = [n for n in nodes if n is not tx]
before = {n.name: n.stats() for n in nodes}
tx.advert()
time.sleep(3.0)
after = {n.name: n.stats() for n in nodes}
d_sent = after[tx.name].get("sent", 0) - before[tx.name].get("sent", 0)
d_to = after[tx.name].get("tx_timeout", 0) - before[tx.name].get("tx_timeout", 0)
got = []
for rx in others:
d = after[rx.name].get("recv", 0) - before[rx.name].get("recv", 0)
if d >= 1:
heard[tx.name][rx.name] += 1
rs = rx.radio_stats()
if rs:
rssi[tx.name][rx.name] = (rs.get("last_rssi"), rs.get("last_snr"))
got.append(f"{rx.name}{'+' if d >= 1 else '-'}")
rep.note(f"kolo {rnd+1}: {tx.name} vysila -> sent +{d_sent} "
f"timeout +{d_to} | slyseli: {' '.join(got)}")
for tx in nodes:
misses = [r for r, c in heard[tx.name].items() if c < rounds]
rep.add("matrix", f"{tx.name} slyseli vsichni ({rounds}/{rounds})", not misses,
"ok" if not misses else
f"neslyseli/ne vzdy: {', '.join(f'{r} {heard[tx.name][r]}/{rounds}' for r in misses)}")
for tx in nodes:
for rx, v in rssi[tx.name].items():
if v[0] is not None:
rep.note(f"{tx.name} -> {rx}: RSSI {v[0]} dBm, SNR {v[1]} dB")
return heard
def check_hygiene(nodes, base, rep):
print("\n== 4. countery chyb behem behu", flush=True)
for n in nodes:
a, b = n.stats(), base[n.name]
bad = {k: a.get(k, 0) - b.get(k, 0)
for k in ("tx_timeout", "tx_start_fail", "recv_errors")
if a.get(k, 0) - b.get(k, 0) > 0}
rep.add("hygiene", f"{n.name} bez chybovych counteru", not bad,
"ok" if not bad else str(bad))
# Rok, pod kterym je jasne, ze hodinam nikdo cas nenastavil: VolatileRTCClock
# startuje v kvetnu 2024 a jinak jen tika z millis().
CLOCK_FLOOR = 1735689600 # 2025-01-01 UTC
def check_clock(nodes, rep):
print("\n== 6. hodiny desek", flush=True)
for n in nodes:
if n.kind != "console":
rep.note(f"{n.name}: companion build, `clock` neexistuje -- preskoceno")
continue
out = n.cmd("clock")
m = re.search(r"epoch\s+(\d+)", out)
if m:
node_epoch = int(m.group(1))
else:
m = re.search(r"\b(\d{1,2}):(\d{2})\s*-\s*(\d{1,2})/(\d{1,2})/(\d{4})", out)
if not m:
rep.add("clock", f"{n.name} odpovida na clock", False, out.strip()[:60])
continue
hh, mm, day, mon, year = (int(g) for g in m.groups())
try:
node_epoch = int(datetime(year, mon, day, hh, mm,
tzinfo=timezone.utc).timestamp())
except ValueError:
rep.add("clock", f"{n.name} odpovida na clock", False, out.strip()[:60])
continue
skew = int(time.time()) - node_epoch
# Deska, ktere nikdo cas nenastavil, je vada konfigurace, ne vada desky --
# ale prave proto se to musi hlasit. Na x3 to uniklo 811 dni a na teto
# lavici to 7. 8. 2026 platilo pro KAZDOU desku. Spatny cas neni kosmetika:
# RTC stampuje kazdy vyslany advert a prijemce stary timestamp zahodi jako
# replay. Srovnat: `tools/ble_cli.py <MAC> "time {epoch}"` nebo pres USB.
rep.add("clock", f"{n.name} ma nastavene hodiny", node_epoch > CLOCK_FLOOR,
f"{datetime.fromtimestamp(node_epoch, timezone.utc).isoformat()}"
f" (skew {skew:+d} s = {skew / 86400:.1f} dni)")
# Commands every repeater/analyzer build must answer. `dfu` is deliberately NOT
# probed -- it reboots into the bootloader.
MUST_HAVE = ["ver", "advert.zerohop", "stats-packets", "blink", "txpwr"]
OPTIONAL = ["nodes", "rxlog 999999", "pktlog 999999", "bot", "dio1", "bleconn"]
def check_commands(nodes, rep):
print("\n== 5. povrch prikazu (jen console buildy)", flush=True)
for n in nodes:
if n.kind != "console":
rep.note(f"{n.name}: companion build, textova konzole neexistuje -- preskoceno")
continue
missing = [c for c in MUST_HAVE if "Unknown command" in n.cmd(c)]
rep.add("commands", f"{n.name} ma zakladni prikazy", not missing,
"ok" if not missing else f"chybi: {missing}")
have = [c.split()[0] for c in OPTIONAL if "Unknown command" not in n.cmd(c)]
rep.note(f"{n.name} volitelne: {' '.join(have) if have else '(zadne)'}")
def main():
ap = argparse.ArgumentParser()
ap.add_argument("--boards", help="cisla desek, napr. 0,1,2,4 (vychozi: vse na USB)")
ap.add_argument("--rounds", type=int, default=1, help="kol matice (vychozi 1)")
ap.add_argument("--json", help="ulozit vysledek jako JSON")
ap.add_argument("--remote", action="append", default=[], metavar="N=URL",
help="deska na jinem hostu, napr. 1=socket://127.0.0.1:7001 "
"(TCP<->serial proxy na tom hostu + ssh -L); opakovatelne")
a = ap.parse_args()
wanted = set(a.boards.split(",")) if a.boards else None
found = discover(wanted)
tbl = fleet_table()
for r in a.remote:
no, _, url = r.partition("=")
if not url:
sys.exit(f"--remote {r}: cekam N=URL")
found.append((no, tbl.get(no, "?"), url))
if not found:
sys.exit("na USB nenalezena zadna XIAO deska")
print(f"== nalezeno {len(found)} desek", flush=True)
nodes = []
for no, sn, port in found:
n = open_node(no, sn, port)
if n is None:
# "Neodpovida" je spatna diagnoza, kdyz na desce bezi neco, co ani
# odpovidat nema. 1. 9. 2026 to stalo hodinu a tri zbytecne replugy:
# na x2 skoncil omylem KISS modem (nema textovou konzoli ANI companion
# protokol) a hlaska vypadala jako zaseknuta deska. Doptame se tedy
# jeste KISS ramcem, at je videt, CO tam bezi.
what = "neodpovida ani konzoli, ani companion protokolu"
try:
out = subprocess.run(
[os.path.join(HERE, "board_probe.py"), "--all"],
capture_output=True, text=True, timeout=90).stdout
# Stav, ktery probe NEZJISTIL, se nesmi vydavat za zjistenou
# identitu firmwaru. `visi` znamena, ze deska visela v open(2),
# `obsazeny` ze port drzi nekdo jiny (casto tenhle beh sam),
# `chyba` ze probe spadl -- z zadneho z nich neplyne "neni to
# MeshCore uzel". Takhle to hlasilo presne tu diagnozu, kterou
# nastroj nemel cim podepřít.
for line in out.splitlines():
f = line.split(None, 2)
if len(f) < 2 or f[0] != sn:
continue
kind = f[1].split("/")[-1]
ver = f[2].strip() if len(f) > 2 else ""
if kind in ("nic", "nedostupny", "modem", "boot"):
what = f"{f[1]} {ver} -- neni to MeshCore uzel, vynechavam"
elif kind in ("visi", "obsazeny", "chyba"):
what = (f"{f[1]} {ver} -- stav se NEPODARILO zjistit,"
f" vynechavam (o firmwaru to nic nerika)")
else:
what = f"{f[1]} {ver} -- jiny protokol, vynechavam"
except Exception:
pass
print(f" x{no} ({sn}): {what}", flush=True)
continue
n.identify()
nodes.append(n)
if not nodes:
sys.exit("zadna deska neodpovedela")
rep = Report()
try:
check_identity(nodes, rep)
same_radio = check_config(nodes, rep)
if not same_radio:
rep.note("POZOR: desky nejsou na stejnem radiu, matice nize je tim padem "
"test konfigurace, ne hardwaru")
base = {n.name: n.stats() for n in nodes}
check_matrix(nodes, rep, a.rounds)
check_hygiene(nodes, base, rep)
check_commands(nodes, rep)
check_clock(nodes, rep)
finally:
for n in nodes:
n.close()
print("\n===== SOUHRN =====")
for _sec, name, ok, _detail in rep.rows:
print(f" {'OK ' if ok else 'FAIL'} {name}")
n_bad = len(rep.failed)
print(f"\n{len(rep.rows) - n_bad}/{len(rep.rows)} proslo")
if a.json:
with open(a.json, "w") as f:
json.dump({"boards": [{"no": n.no, "sn": n.sn, "kind": n.kind, **n.info}
for n in nodes],
"checks": [{"section": s, "name": nm, "ok": ok, "detail": d}
for s, nm, ok, d in rep.rows]}, f, indent=2)
print(f"JSON: {a.json}")
return 1 if n_bad else 0
# The guard is not decoration: this module TRANSMITS. check_matrix() and the
# `advert.zerohop` probe in check_commands() key the radio on every console board
# found on USB, whatever band each one is tuned to. Without the guard, so much as
# `import fleet_test` to reuse discover() ran the whole suite -- which on
# 7. 8. 2026 put two zero-hop adverts on 869.432 out of a bench board configured
# for the live CZ mesh, before the importing script's own first line had run.
if __name__ == "__main__":
sys.exit(main())
+119
View File
@@ -0,0 +1,119 @@
#!/usr/bin/env python3
# SPDX-License-Identifier: MIT
"""Smoke test of a FIRMWARE room server (simple_room_server) over the air.
Two MeshCore companions log in as guests; each posts once and the room must
push that post to the OTHER one (signed message from the room, author prefix
in the signature), never back to its author. That is the room's whole job --
login, store, push -- end to end, on real radios.
tools/fw_room_smoke.py --room <pubkey64> --password <guest pw> \\
--a 127.0.0.1:47001 --b 127.0.0.1:47003
--a/--b are companions reachable as meshcore TCP (a companion on USB elsewhere
can be exposed with a TCP<->serial bridge; the frames are the same). The room
is added to both as a contact with a flood path, so no advert is needed.
Run it on the bench preset only (all three on 866.5): it transmits logins and
posts. Exit 0 = every step passed.
Not the openHop room (tth-room): that one has its own bench,
openhop-repeater/tools/bench/room_delivery.py.
"""
import argparse
import asyncio
import sys
import time
if __name__ == "__main__" and any(a in ("-h", "--help") for a in sys.argv[1:]):
print(__doc__)
sys.exit(0)
from meshcore import EventType, MeshCore # noqa: E402
ROOM_TYPE = 3
def room_contact(pubkey, name="room-under-test"):
return {
"public_key": pubkey, "type": ROOM_TYPE, "flags": 0,
"out_path_len": -1, "out_path": "", "out_path_hash_mode": 0,
"adv_name": name, "last_advert": 0, "adv_lat": 0.0, "adv_lon": 0.0,
}
async def connect(hostport):
host, port = hostport.rsplit(":", 1)
mc = await MeshCore.create_tcp(host, int(port))
return mc
async def wait_push(mc, room_prefix, needle, timeout):
"""Wait for a message from the room whose text contains `needle`."""
deadline = time.monotonic() + timeout
while time.monotonic() < deadline:
ev = await mc.dispatcher.wait_for_event(EventType.CONTACT_MSG_RECV,
timeout=max(0.1, deadline - time.monotonic()))
if ev is None:
break
p = ev.payload
if p.get("pubkey_prefix", "").lower() == room_prefix and needle in p.get("text", ""):
return p
return None
async def main():
ap = argparse.ArgumentParser(description="firmware room server smoke test")
ap.add_argument("--room", required=True, help="room server public key (64 hex)")
ap.add_argument("--password", required=True, help="guest password")
ap.add_argument("--a", required=True, help="companion A host:port")
ap.add_argument("--b", required=True, help="companion B host:port")
ap.add_argument("--push-timeout", type=float, default=120)
args = ap.parse_args()
room = args.room.lower()
prefix = room[:12]
ok = True
a, b = await connect(args.a), await connect(args.b)
names = {id(a): a.self_info.get("name"), id(b): b.self_info.get("name")}
for mc in (a, b):
await mc.commands.add_contact(room_contact(room))
await mc.ensure_contacts()
await mc.start_auto_message_fetching()
for mc in (a, b):
t0 = time.monotonic()
ev = await mc.commands.send_login_sync(room, args.password, min_timeout=20)
good = ev is not None and ev.type == EventType.LOGIN_SUCCESS
print(f"login {names[id(mc)]}: {'OK' if good else 'FAIL'} ({time.monotonic() - t0:.1f} s)")
ok &= good
if not good:
break
if ok:
for src, dst in ((a, b), (b, a)):
tag = f"smoke-{int(time.time())}-{names[id(src)]}"
res = await src.commands.send_msg_with_retry(room, tag, max_attempts=3)
sent = res is not None and res.type != EventType.ERROR
print(f"post by {names[id(src)]}: {'acked' if sent else 'NOT acked'}")
t0 = time.monotonic()
got = await wait_push(dst, prefix, tag, args.push_timeout)
if got:
print(f"push to {names[id(dst)]}: OK after {time.monotonic() - t0:.1f} s "
f"(author sig {got.get('signature')}, path_len {got.get('path_len')})")
else:
print(f"push to {names[id(dst)]}: FAIL (nothing in {args.push_timeout:.0f} s)")
echo = await wait_push(src, prefix, tag, 5)
if echo:
print(f"author {names[id(src)]} got its own post back: FAIL")
ok &= sent and got is not None and echo is None
for mc in (a, b):
await mc.disconnect()
print("RESULT:", "PASS" if ok else "FAIL")
return 0 if ok else 1
if __name__ == "__main__":
sys.exit(asyncio.run(main()))
+177
View File
@@ -0,0 +1,177 @@
#!/usr/bin/env python3
# SPDX-License-Identifier: MIT
"""Vygeneruje identitu uzlu s NEKOLIZNIM path hashem.
Proc to nejde nechat na nahode
-------------------------------
Path hash je prosty prefix verejneho klice (`Identity.h:20`) a jeho sirku urcuje
ODESILATEL paketu, ne forwarder -- `Mesh.cpp:346` pripoji `packet->getPathHashSize()`
bajtu, takze do jednobajtoveho paketu pripise jeden bajt i repeater nastaveny na dva.
Kandidatem na hop je proto VZDY cela populace repeateru, ne jen ti nastaveni na tutez
sirku. Zmereno na CZ meshi 5. 8. 2026 (669 repeateru):
1 bajt -> 620 repeateru sedi na sdilenem prefixu (253 z 256 hodnot obsazeno)
2 bajty -> 6 (obsazenost 1,25 %)
3 bajty -> 0
Jednobajtova unikatnost je tedy neziskatelna (pigeonhole: 669 > 256), zato dvoubajtova
je skoro zadarmo. Kolize neni kosmetika: `isHashMatch` porovna prave tyhle bajty, takze
na kolidujici hop reaguje VIC repeateru -- rozbiji to routovani i atribuci v analyzeru.
Pouziti
-------
tools/gen_node_id.py # 2B prefix volny proti CoreScope
tools/gen_node_id.py --bytes 3 # prisnejsi
tools/gen_node_id.py --first-byte 5f # k tomu konkretni prvni bajt
tools/gen_node_id.py --known klice.txt # offline, misto CoreScope
Nahrani do uzlu (klic je 64 B = seed32 || pubkey32, viz PRV_KEY_SIZE v MeshCore.h):
meshcore-cli -a <adresa> set private_key <128 hex znaku>
"""
import argparse
import hashlib
import json
import os
import secrets
import sys
import urllib.request
from cryptography.hazmat.primitives import serialization as ser
from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
def keypair(seed: bytes):
"""Vrati (pub32, prv64) ve formatu, ktery ceka MeshCore.
POZOR: prv NENI seed||pub (konvence libsodium), ale **clampnuty SHA-512(seed)**
-- viz lib/ed25519/keypair.c:
sha512(seed, 32, private_key);
private_key[0] &= 248; private_key[31] &= 63; private_key[31] |= 64;
ge_scalarmult_base(&A, private_key);
`set prv.key` jinak odpovi "Error, bad key", protoze validatePrivateKey()
si pubkey odvodi pres ed25519_derive_pub() z prvnich 32 bajtu jako ze skalaru.
Pub pocitame pres standardni Ed25519 ze seedu -- RFC 8032 dela presne tohle.
"""
h = bytearray(hashlib.sha512(seed).digest())
h[0] &= 248
h[31] &= 63
h[31] |= 64
pub = Ed25519PrivateKey.from_private_bytes(seed).public_key().public_bytes(
ser.Encoding.Raw, ser.PublicFormat.Raw)
return pub, bytes(h)
# Verejny komunitni analyzer: vidi cely mesh (50 observeru), ne jen to, co slysi
# nase dve. Kolize se musi hledat proti nejuplnejsi populaci, jakou sezeneme.
DEFAULT_SRC = "https://analyzer.meshcore.cz/api/analytics/hash-sizes"
def load_known(src):
"""Vrati (vsechny_pubkey, pubkey_repeateru) jako lowercase hex."""
if src.startswith("http"):
with urllib.request.urlopen(src, timeout=20) as r:
d = json.load(r)
# Zdroje se lisi tvarem a API se meni pod rukama (23. 8. 2026 zmizel
# "multiByteCapability" z CoreScope): zkus zname obalky, pak fallback
# na prvni list dictu v odpovedi. Klic pubkeye taky pluje.
nodes = None
for k in ("multiByteCapability", "nodes", "data"):
if isinstance(d, dict) and isinstance(d.get(k), list):
nodes = d[k]
break
if nodes is None:
if isinstance(d, list):
nodes = d
else:
nodes = next((v for v in d.values() if isinstance(v, list)), None)
if not nodes:
sys.exit(f"zdroj {src} nevratil zadny seznam uzlu")
def pk(n):
return (n.get("pubkey") or n.get("public_key") or n.get("publicKey") or "").lower()
rep_types = {"repeater", 2, "2"}
return ([pk(n) for n in nodes if pk(n)],
[pk(n) for n in nodes if pk(n) and (
n.get("role") in rep_types or n.get("type") in rep_types
or n.get("node_type") in rep_types)])
keys = [ln.strip().lower() for ln in open(src) if ln.strip()]
return keys, keys
def main():
ap = argparse.ArgumentParser()
ap.add_argument("--bytes", type=int, default=2,
help="kolik bajtu prefixu musi byt volnych (default 2)")
ap.add_argument("--first-byte", metavar="HEX",
help="vynutit konkretni prvni bajt, napr. 5f")
ap.add_argument("--known", default=DEFAULT_SRC,
help="zdroj znamych klicu: URL CoreScope nebo soubor")
ap.add_argument("--max-tries", type=int, default=5_000_000)
ap.add_argument("--derive", metavar="HEX128",
help="jen odvodit pubkey z existujiciho 64B prv.key a skoncit. "
"PAST: prv[32:64] NENI pubkey (je to druha pulka SHA-512) "
"-- pub = ge_scalarmult_base(prv[0:32]). Chce PyNaCl.")
ap.add_argument("--out", metavar="SOUBOR",
help="kam zapsat privatni klic (0600). Bez toho se NEVYPISUJE "
"-- klic nema co delat v scrollbacku terminalu.")
a = ap.parse_args()
if a.derive:
import nacl.bindings as nb # jen tady, jinak staci `cryptography`
prv = bytes.fromhex(a.derive.strip())
if len(prv) != 64:
sys.exit(f"prv.key ma mit 64 bajtu (128 hex), ma {len(prv)}")
print(nb.crypto_scalarmult_ed25519_base_noclamp(prv[:32]).hex())
return
try:
allk, repk = load_known(a.known)
except Exception as e:
sys.exit(f"nelze nacist zname klice z {a.known}: {e}")
n = a.bytes * 2
taken_all = {k[:n] for k in allk}
bucket1 = {}
for k in repk:
bucket1[k[:2]] = bucket1.get(k[:2], 0) + 1
print(f"znamych uzlu {len(allk)} (z toho repeateru {len(repk)}); "
f"obsazenych {a.bytes}B prefixu: {len(taken_all)}", file=sys.stderr)
want = a.first_byte.lower() if a.first_byte else None
if want and len(want) != 2:
sys.exit("--first-byte chce prave dva hex znaky")
if want in ("00", "ff"):
sys.exit("00 a ff nejsou volne, ale ZAKAZANE -- Identity.cpp:56 odmita "
"klic s pub[0] == 0x00 nebo 0xFF jako neplatny")
for i in range(a.max_tries):
seed = secrets.token_bytes(32)
pub, prv64 = keypair(seed)
h = pub.hex()
if h[:2] in ("00", "ff"): # firmware by takovy klic odmitl
continue
if want and h[:2] != want:
continue
if h[:n] in taken_all:
continue
crowd = bucket1.get(h[:2], 0)
print(f"nalezeno po {i + 1} pokusech", file=sys.stderr)
print(f"pub_key {h}")
print(f"path hash 1B={h[:2]} 2B={h[:4]} 3B={h[:6]}")
print(f"prvni bajt {h[:2]} sdili {crowd} repeateru"
+ (" <-- unikatni i na 1 bajt!" if crowd == 0 else ""))
if a.out:
fd = os.open(a.out, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
with os.fdopen(fd, "w") as f:
f.write(prv64.hex() + "\n")
print(f"\nprivatni klic zapsan do {a.out} (0600). Nahrani do uzlu:")
print(f" repeater po seriove konzoli: set prv.key $(cat {a.out})")
print(f" companion pres meshcore-cli: set private_key $(cat {a.out})")
else:
print("\n(privatni klic se nevypisuje; pouzij --out SOUBOR)")
return
sys.exit("nenalezeno, zvys --max-tries nebo uvolni podminky")
if __name__ == "__main__":
main()
+173
View File
@@ -0,0 +1,173 @@
#!/usr/bin/env python3
# SPDX-License-Identifier: MIT
"""Local config of the MeshCore tools: which boards and nodes you have.
The tools in this directory carry no board serial, MAC or host of anyone's
bench. They take them from ONE file beside the repo:
~/.config/meshcore-tools/config.ini (or $MESHCORE_TOOLS_CONFIG)
Copy tools/config.example.ini there and describe your boards. Without the
file every tool still works with full serial numbers, MACs and port paths --
only names like `b1` need it. No secrets go in here: admin passwords stay in
platformio.local.ini.
From Python:
from mctools_config import serial_for, mac_for, boards
serial_for("b1") # -> "0123456789ABCDEF", or the input unchanged
From shell (the same answers, one per line, exit 1 when there is none):
tools/mctools_config.py path
tools/mctools_config.py serial b1 # alias, number or serial
tools/mctools_config.py mac b1 # BLE MAC of that board
tools/mctools_config.py get b1 protect # any field of the board
tools/mctools_config.py list [--role bench] [--has protect] [--field serial]
tools/mctools_config.py name 0123456789ABCDEF # board name for a serial or MAC
Board section, every field optional:
[board.b1]
serial = 0123456789ABCDEF ; USB serial number (/dev/serial/by-id)
mac = AA:BB:CC:DD:EE:01 ; BLE MAC of the application
aliases = 1 ; other names that mean this board
role = bench ; bench | live | probe -- tools and hooks decide by it
protect = keeps an identity ; flashing tools refuse it unless told to
refuse = an observer radio ; console tools refuse to open it at all
host = lab-pc ; where it is plugged in (informative)
"""
from __future__ import annotations
import argparse
import configparser
import os
import re
import shlex
import sys
from pathlib import Path
ENV = "MESHCORE_TOOLS_CONFIG"
DEFAULT = Path.home() / ".config/meshcore-tools/config.ini"
EXAMPLE = Path(__file__).resolve().parent / "config.example.ini"
FIELDS = ("serial", "mac", "aliases", "role", "protect", "refuse", "host")
def path() -> Path:
return Path(os.environ.get(ENV) or DEFAULT)
def boards() -> dict[str, dict[str, str]]:
"""{name: {field: value}} from the config; empty without a config."""
cp = configparser.ConfigParser(interpolation=None, inline_comment_prefixes=(";", "#"))
cp.read(path())
out = {}
for sec in cp.sections():
if sec.startswith("board."):
out[sec[6:]] = {k: v.strip() for k, v in cp[sec].items()}
return out
def find(key: str) -> tuple[str, dict[str, str]] | None:
"""The board a name, alias, serial number or MAC belongs to."""
k = key.strip()
for name, b in boards().items():
aliases = [a.strip() for a in b.get("aliases", "").split(",") if a.strip()]
if k == name or k in aliases:
return name, b
if b.get("serial") and k.upper() == b["serial"].upper():
return name, b
if b.get("mac") and k.upper() == b["mac"].upper():
return name, b
return None
def serial_for(key: str) -> str:
"""USB serial of a board name/alias, or the input unchanged (a serial or a
port path passes straight through)."""
hit = find(key)
return hit[1].get("serial", key) if hit else key
def mac_for(key: str) -> str | None:
hit = find(key)
return hit[1].get("mac") if hit else None
def field(key: str, name: str) -> str | None:
hit = find(key)
return hit[1].get(name) if hit else None
def by_role(role: str | None = None) -> dict[str, dict[str, str]]:
return {n: b for n, b in boards().items() if role is None or b.get("role") == role}
def unknown_alias_hint(key: str) -> str:
return f"{key!r} is no board in {path()} (template: {EXAMPLE})"
def main() -> int:
ap = argparse.ArgumentParser(
description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter
)
sub = ap.add_subparsers(dest="cmd", required=True)
sub.add_parser("path", help="the config file in use")
sub.add_parser("hook-vars", help="shell assignments LIVE_IDS / BENCH_IDS (regexes) for a guard hook")
for c in ("serial", "mac", "name"):
sub.add_parser(c).add_argument("key")
g = sub.add_parser("get")
g.add_argument("key")
g.add_argument("field", choices=FIELDS)
lst = sub.add_parser("list")
lst.add_argument("--role")
lst.add_argument("--has", choices=FIELDS, help="only boards that set this field")
lst.add_argument("--field", choices=FIELDS, help="print only this field (skip boards without it)")
a = ap.parse_args()
if a.cmd == "path":
print(path())
return 0 if path().exists() else 1
if a.cmd == "hook-vars":
# live: MACs and names; bench: serials, MACs and names as whole words
def ere(text: str) -> str: # POSIX ERE (grep -E), not Python re
return re.sub(r"([.^$*+?()\[\]{}|\\])", r"\\\1", text)
def ids(role: str) -> str:
out = []
for n, b in by_role(role).items():
out += [ere(b[k]) for k in ("serial", "mac") if b.get(k)]
out.append(f"(^| ){ere(n)}( |$)")
return "|".join(out)
print(f"LIVE_IDS={shlex.quote(ids('live'))}")
print(f"BENCH_IDS={shlex.quote(ids('bench'))}")
return 0
if a.cmd == "list":
for n, b in by_role(a.role).items():
if a.has and not b.get(a.has):
continue
if a.field:
if b.get(a.field):
print(b[a.field])
else:
print(n)
return 0
hit = find(a.key)
if a.cmd == "serial":
val = hit[1].get("serial") if hit else None
elif a.cmd == "mac":
val = hit[1].get("mac") if hit else None
elif a.cmd == "name":
val = hit[0] if hit else None
else:
val = hit[1].get(a.field) if hit else None
if not val:
return 1
print(val)
return 0
if __name__ == "__main__":
sys.exit(main())
+445
View File
@@ -0,0 +1,445 @@
#!/usr/bin/env python3
# SPDX-License-Identifier: MIT
"""Passive MeshCore sniffer -- every frame the radio hears, decoded on the host.
tools/mesh_sniffer.py --board 0 --preset cz [--jsonl cap.jsonl] [--pcap cap.pcap]
[--psk <hex>] [--seconds 600]
Needs a board running the openHop modem firmware (openhop-dev/openhop_modem) and
`pip install openhop-core` -- the Python reimplementation of the MeshCore stack.
The board is a dumb SX1262 PHY: it hands up EVERY frame that passes CRC, tagged
with RSSI/SNR, and all decoding happens here.
Why this exists, when we already have a node + BLE bridge feeding the analyzer:
* A companion node only ever surfaces what ITS firmware decided to process --
its own channels and DMs, adverts, packets addressed to it. Foreign-PSK
channel traffic and DIRECT packets for other destinations are dropped before
the companion protocol ever sees them. The modem has no such opinion, so
"SDR sees twice what the observer decodes" (docs, measured) becomes a
testable claim instead of a mystery: the modem's own rx_count is printed
next to the number of frames we managed to parse.
* No BLE anywhere on the path -- no dock-quiet interaction, no BlueZ holding
the link, no MC_BLE_OFF_INTERVAL windows costing 42 % of the capture.
RECEIVE ONLY, by construction. There is no call to radio.send() in this file and
no dispatcher/handler is registered, so nothing can answer, ACK or forward. That
matters on 869.432: an unannounced node that starts answering confuses routing.
The modem is left with tx_power at its floor as a second line of defence.
Two traps that shaped the code, both worth keeping in mind if you extend it:
* openhop_core's own Dispatcher runs a PacketFilter that swallows byte-identical
frames for 30 s. That is right for a repeater and wrong for a sniffer -- two
neighbours relaying the same flood is exactly the observation we are after.
So this script parses packets itself instead of going through the dispatcher,
and counts duplicates instead of hiding them.
* USBLoRaRadio's rx_callback is handed only the payload; RSSI/SNR live in
radio.last_rssi/last_snr, which the NEXT packet overwrites before a queued
callback runs. So we override _dispatch_frame and take the metadata straight
out of the CMD_RX_PACKET frame, where it is atomic with the bytes.
"""
from __future__ import annotations
import argparse
import glob
import hashlib
import hmac
import json
import os
import socket
import struct
import sys
import threading
import time
from collections import Counter
try:
from openhop_core.hardware.usb_radio import CMD_RX_PACKET, USBLoRaRadio
from openhop_core.protocol import decode_appdata, parse_advert_payload
from openhop_core.protocol.packet import Packet
except ImportError:
# --help má jít i bez závislostí: aspoň hlavička (plné volby až s openhop-core).
if {"-h", "--help"} & set(sys.argv[1:]):
print(__doc__.strip())
sys.exit(0)
sys.exit(
"chybi openhop-core: python3 -m venv .venv && .venv/bin/pip install openhop-core pyserial"
)
# Fleet shorthand, same numbering as tools/xiao_uf2_flash.sh. Keyed on serial
# number because the by-id NAME changes with the firmware: the modem build
# renames the port from usb-Seeed_Studio_XIAO_nRF52840_<sn> to
# usb-Seeed_XIAO-Wio-SX1262_<sn>, so anything matching on the name breaks the
# moment the board becomes a modem.
# Tabulka žije v fleet.py, ať se pátá kopie nerozejde s deskami.
sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
from fleet import FLEET_BARE as FLEET
# freq_hz, bandwidth_hz, sf, cr -- mirrored from platformio.ini / .local.ini so a
# capture cannot silently run on the wrong parameters. Two boards on different
# spreading factors simply cannot hear each other.
PRESETS = {
"cz": (869_432_000, 62_500, 7, 5), # live CZ mesh, [cz_radio]
"bench": (866_500_000, 62_500, 8, 5), # test band, [test_radio] + committed defaults
"prod": (869_618_000, 62_500, 8, 5), # committed platformio.ini default
}
ROUTE_TYPES = {0: "TRANSPORT_FLOOD", 1: "FLOOD", 2: "DIRECT", 3: "TRANSPORT_DIRECT"}
PAYLOAD_TYPES = {
0x00: "REQ",
0x01: "RESPONSE",
0x02: "TXT_MSG",
0x03: "ACK",
0x04: "ADVERT",
0x05: "GRP_TXT",
0x06: "GRP_DATA",
0x07: "ANON_REQ",
0x08: "PATH",
0x09: "TRACE",
0x0A: "MULTIPART",
0x0B: "CONTROL",
0x0F: "RAW_CUSTOM",
}
ADVERT_ROLES = {0x01: "chat", 0x02: "repeater", 0x03: "room", 0x04: "sensor"}
LINKTYPE_USER0 = 147 # what openhop_core's own wireshark example uses
def resolve_port(board: str, port: str | None) -> str:
"""Map a fleet number or serial number to a /dev/serial/by-id path."""
if port:
return port
serial_no = FLEET.get(board, board)
matches = [p for p in glob.glob("/dev/serial/by-id/*") if serial_no in p]
if not matches:
sys.exit(f"zadny port pro sn {serial_no} -- pripojena deska? (ls /dev/serial/by-id/)")
if len(matches) > 1:
sys.exit(f"vic portu pro sn {serial_no}: {matches}")
return matches[0]
class SnifferRadio(USBLoRaRadio):
"""USBLoRaRadio that hands RX frames straight to a callback, metadata included.
See the module docstring: the stock rx_callback loses the RSSI/SNR pairing
under load, and it is scheduled onto an asyncio loop we do not want to run.
"""
def __init__(self, *args, on_frame=None, **kwargs):
super().__init__(*args, **kwargs)
self._on_frame = on_frame
def _dispatch_frame(self, cmd: int, payload: bytes):
if cmd == CMD_RX_PACKET and len(payload) >= 6:
# Keep the driver's own bookkeeping up to date -- get_status() is our
# honest denominator -- but do NOT delegate to super() here: with no
# rx_callback set it logs "RX packet but no callback registered" for
# every single frame, which is noise in a capture.
rssi, snr_x10, signal_rssi = struct.unpack("<hhh", payload[0:6])
self.last_rssi, self.last_snr = rssi, snr_x10 / 10.0
self.last_signal_rssi = signal_rssi
self._rx_count += 1
if self._on_frame:
self._on_frame(payload[6:], rssi, snr_x10 / 10.0, signal_rssi)
return
super()._dispatch_frame(cmd, payload)
class PcapWriter:
"""Minimal pcap writer/streamer. Payload is the raw MeshCore frame.
LINKTYPE_USER0 means Wireshark shows the bytes but does not dissect them --
good enough for eyeballing lengths and repeats, and the decoded fields are in
the JSONL anyway. A Lua dissector for USER0 would be the next step.
"""
def __init__(self, path: str | None, udp: str | None):
self.fh = None
self.sock = None
self.dest = None
header = struct.pack("<IHHiIII", 0xA1B2C3D4, 2, 4, 0, 0, 65535, LINKTYPE_USER0)
if path:
self.fh = open(path, "wb")
self.fh.write(header)
if udp:
host, _, port = udp.partition(":")
self.dest = (host, int(port or 5555))
self.sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
self.sock.sendto(header, self.dest)
def write(self, data: bytes, ts: float):
if not (self.fh or self.sock):
return
rec = struct.pack("<IIII", int(ts), int((ts % 1) * 1e6), len(data), len(data)) + data
if self.fh:
self.fh.write(rec)
self.fh.flush()
if self.sock and self.dest:
self.sock.sendto(rec, self.dest)
def close(self):
if self.fh:
self.fh.close()
if self.sock:
self.sock.close()
def channel_keys(psk_hex: str) -> tuple[int, bytes]:
"""(channel hash, 32B secret) from a hex PSK, matching the firmware.
The firmware hashes only the first 16 bytes when the second 16 are zero, so a
128-bit key written out as 32 hex bytes still derives the right hash.
"""
secret = bytes.fromhex(psk_hex)
if len(secret) >= 32 and secret[16:32] == b"\x00" * 16:
hashed = secret[:16]
else:
hashed = secret[:32]
master = hashlib.sha256(hashed).digest()
secret32 = (secret + b"\x00" * 32)[:32]
return master[0], secret32
def try_decrypt_channel(payload: bytes, keys: dict[int, list[bytes]]) -> dict | None:
"""MeshCore group text: hash(1) | mac(2) | AES-128-ECB ciphertext."""
if len(payload) < 4:
return None
chan_hash, mac, ciphertext = payload[0], payload[1:3], payload[3:]
for secret32 in keys.get(chan_hash, []):
if hmac.new(secret32, ciphertext, hashlib.sha256).digest()[:2] != mac:
continue # 1-byte hash collides; the HMAC is the real test
from Crypto.Cipher import AES # pycryptodome, pulled in by openhop-core
padded = ciphertext + b"\x00" * (-len(ciphertext) % 16)
plain = AES.new(secret32[:16], AES.MODE_ECB).decrypt(padded)[: len(ciphertext)]
if len(plain) < 5:
return None
return {
"timestamp": int.from_bytes(plain[:4], "little"),
"flags": plain[4],
"text": plain[5:].decode("utf-8", errors="replace").rstrip("\x00"),
}
return None
def decode(data: bytes, keys: dict[int, list[bytes]]) -> dict:
"""Parse one raw frame into a flat dict. Never raises."""
out: dict = {"len": len(data), "raw": data.hex()}
pkt = Packet()
try:
pkt.read_from(data)
except Exception as exc: # truncated, bad version, bogus path_len
out["error"] = str(exc)
return out
hash_size = pkt.get_path_hash_size()
hash_count = pkt.get_path_hash_count()
payload_type = pkt.get_payload_type()
path = bytes(pkt.path)
out.update(
{
"route": ROUTE_TYPES.get(pkt.get_route_type(), "?"),
"type": PAYLOAD_TYPES.get(payload_type, f"0x{payload_type:02X}"),
"ver": pkt.get_payload_ver(),
# Hash width is chosen by the SENDER and carried in bits 6-7 of
# path_len, so a 2B/3B-path-hash node decodes here without a rebuild.
"hash_size": hash_size,
"hops": hash_count,
"path": ":".join(
path[i : i + hash_size].hex() for i in range(0, hash_size * hash_count, hash_size)
),
}
)
if pkt.has_transport_codes():
out["transport_codes"] = list(pkt.transport_codes)
payload = bytes(pkt.payload)
name = out["type"]
try:
if name == "ADVERT":
adv = parse_advert_payload(payload)
app = decode_appdata(adv["appdata"]) if adv["appdata"] else {}
out["advert"] = {
"pubkey": adv["pubkey"],
"path_hash": adv["pubkey"][: hash_size * 2],
"timestamp": adv["timestamp"],
"name": app.get("node_name"),
"role": ADVERT_ROLES.get(app.get("flags", 0) & 0x0F),
"lat": app.get("latitude"),
"lon": app.get("longitude"),
}
elif name in ("GRP_TXT", "GRP_DATA"):
out["channel_hash"] = f"{payload[0]:02x}"
decrypted = try_decrypt_channel(payload, keys)
if decrypted:
out["channel_msg"] = decrypted
elif name == "ACK":
out["ack_crc"] = payload[:4].hex()
elif name in ("TXT_MSG", "RESPONSE", "REQ"):
# dest hash | src hash | mac | ciphertext, hashes as wide as the sender chose
out["dest"] = payload[:hash_size].hex()
out["src"] = payload[hash_size : hash_size * 2].hex()
elif name == "PATH":
out["dest"] = payload[:hash_size].hex()
elif name == "TRACE":
tag, auth, flags = struct.unpack("<IIB", payload[:9])
out["trace"] = {"tag": f"{tag:08x}", "auth": f"{auth:08x}", "flags": flags}
elif name == "ANON_REQ":
out["dest"] = payload[:hash_size].hex()
out["src_pubkey"] = payload[hash_size : hash_size + 32].hex()
except Exception as exc:
out["decode_error"] = f"{name}: {exc}"
return out
def format_line(rec: dict) -> str:
"""One packet, one terminal line, most-identifying field last."""
head = (
f"{time.strftime('%H:%M:%S', time.localtime(rec['ts']))} "
f"{rec['rssi']:>4}dBm {rec['snr']:>5.1f}dB {rec['len']:>3}B "
f"{rec.get('route', '?'):<15} {rec.get('type', '?'):<9} "
f"{rec.get('hops', 0)}hop/{rec.get('hash_size', 0)}B"
)
if rec.get("dup"):
head += f" dup#{rec['dup']}"
if "error" in rec:
return f"{head} UNPARSED: {rec['error']} {rec['raw'][:48]}"
tail = []
if rec.get("path"):
tail.append(f"path={rec['path']}")
adv = rec.get("advert")
if adv:
tail.append(f"{adv.get('role') or 'node'} {adv.get('name') or '?'} [{adv['path_hash']}]")
if adv.get("lat"):
tail.append(f"{adv['lat']:.4f},{adv['lon']:.4f}")
if rec.get("channel_hash"):
tail.append(f"chan={rec['channel_hash']}")
if rec.get("channel_msg"):
tail.append(f"msg={rec['channel_msg']['text']!r}")
for key in ("dest", "src", "ack_crc"):
if rec.get(key):
tail.append(f"{key}={rec[key]}")
if rec.get("trace"):
tail.append(f"trace tag={rec['trace']['tag']}")
return f"{head} " + " ".join(tail)
def main() -> int:
ap = argparse.ArgumentParser(description=(__doc__ or "").split("\n")[0])
ap.add_argument("--board", default="0", help="fleet number or serial number (default 0)")
ap.add_argument("--port", help="explicit /dev/serial/by-id path, overrides --board")
ap.add_argument("--preset", choices=sorted(PRESETS), default="cz")
ap.add_argument("--freq", type=float, help="MHz, overrides preset")
ap.add_argument("--bw", type=float, help="kHz, overrides preset")
ap.add_argument("--sf", type=int, help="overrides preset")
ap.add_argument("--cr", type=int, help="overrides preset")
ap.add_argument("--psk", action="append", default=[], help="channel PSK hex, repeatable")
ap.add_argument("--jsonl", help="append decoded packets here, one JSON per line")
ap.add_argument("--pcap", help="write raw frames as pcap (LINKTYPE_USER0)")
ap.add_argument("--wireshark", help="also stream pcap over UDP, host:port")
ap.add_argument("--seconds", type=float, help="stop after N seconds")
ap.add_argument("--status-interval", type=float, default=60.0, help="0 disables")
ap.add_argument("--quiet", action="store_true", help="no per-packet stdout")
args = ap.parse_args()
freq, bw, sf, cr = PRESETS[args.preset]
if args.freq:
freq = int(args.freq * 1e6)
if args.bw:
bw = int(args.bw * 1000)
sf, cr = args.sf or sf, args.cr or cr
port = resolve_port(args.board, args.port)
keys: dict[int, list[bytes]] = {}
for psk in args.psk:
chan_hash, secret32 = channel_keys(psk)
keys.setdefault(chan_hash, []).append(secret32)
stats: Counter[str] = Counter()
seen: dict[str, int] = {}
lock = threading.Lock()
jsonl = open(args.jsonl, "a") if args.jsonl else None
pcap = PcapWriter(args.pcap, args.wireshark)
def on_frame(data: bytes, rssi: int, snr: float, signal_rssi: int):
ts = time.time()
with lock:
stats["heard"] += 1
rec = decode(data, keys)
rec.update({"ts": ts, "rssi": rssi, "snr": snr, "signal_rssi": signal_rssi})
digest = hashlib.sha256(data).hexdigest()[:16]
seen[digest] = seen.get(digest, 0) + 1
if seen[digest] > 1:
rec["dup"] = seen[digest]
stats["dup"] += 1
stats["parsed" if "error" not in rec else "unparsed"] += 1
stats[f"type:{rec.get('type', 'BAD')}"] += 1
pcap.write(data, ts)
if jsonl:
jsonl.write(json.dumps(rec, default=str) + "\n")
jsonl.flush()
if not args.quiet:
print(format_line(rec), flush=True)
print(
f"== port {os.path.basename(port)}\n"
f"== {freq / 1e6:.3f} MHz BW {bw / 1000:g} kHz SF{sf} CR{cr}"
f" ({args.preset}){' +' + str(len(args.psk)) + ' PSK' if args.psk else ''}",
flush=True,
)
radio = SnifferRadio(
port=port,
frequency=freq,
bandwidth=bw,
spreading_factor=sf,
coding_rate=cr,
tx_power=2, # receive-only tool; keep the floor as a second safety net
lbt_enabled=False,
on_frame=on_frame,
)
if not radio.begin():
sys.exit(f"modem na {port} neodpovedel -- bezi na desce openHop modem firmware?")
print("== RX only, nic nevysilam. Ctrl-C ukonci a vypise souhrn.\n", flush=True)
t0 = time.time()
next_status = t0 + args.status_interval if args.status_interval else None
try:
while True:
time.sleep(0.25)
now = time.time()
if args.seconds and now - t0 >= args.seconds:
break
if next_status and now >= next_status:
next_status = now + args.status_interval
# The modem's own counter is the honest denominator: it counted a
# CRC-clean frame even when nothing here could parse it.
modem = radio.get_status()
with lock:
print(
f"-- {now - t0:6.0f}s modem rx={modem.get('rx_count')} "
f"crc_err={modem.get('crc_errors')} heard={stats['heard']} "
f"parsed={stats['parsed']} unparsed={stats['unparsed']} "
f"dup={stats['dup']}",
flush=True,
)
except KeyboardInterrupt:
pass
finally:
radio.cleanup()
pcap.close()
if jsonl:
jsonl.close()
elapsed = time.time() - t0
print(f"\n== {elapsed:.0f}s, {stats['heard']} frames heard, {stats['dup']} duplicates")
print(f"== parsed {stats['parsed']}, unparsed {stats['unparsed']}")
for key, count in sorted(stats.items()):
if key.startswith("type:"):
print(f" {key[5:]:<10} {count}")
return 0
if __name__ == "__main__":
sys.exit(main())
+461
View File
@@ -0,0 +1,461 @@
#!/usr/bin/env python3
# SPDX-License-Identifier: MIT
"""A/B current measurement on a bench node, via the UC96 meter's own exporter.
tools/power_ab.py --serial 0123456789ABCDEF --minutes 30 \
--cell "baseline=" --cell "ps=powersaving on" --cell "duty=gps duty"
Why the exporter and not the meter: `uc96-exporter.service` owns the BLE link to
the UC96. A second central connecting to it takes the link away and the service
reconnect-loops, so this reads http://localhost:9877/metrics instead. Same data,
no contention. (It also lands in Mimir via alloy, so a run stays inspectable
afterwards -- but the exporter is scraped live, which is tighter for timing.)
**The instantaneous current field is useless here.** The UC96 reports current in
10 mA steps (`meter_current_amps` 0.02 for a node drawing anywhere from 15 to
24 mA), and the deltas worth chasing on a repeater are 1-4 mA. The accumulating
`meter_capacity_ah` counter has 1 mAh resolution, so this integrates that over a
window instead: avg mA = 60 * delta_mAh / minutes. The +-1 mAh quantisation is
printed with every cell as an explicit error bar -- at 20 minutes that is
+-3 mA, which would swallow the whole effect, so short windows are a trap and
the tool says so rather than letting you read noise as a result.
Two estimators are reported per cell, because the endpoint one alone wastes the
window: `fit` is a least-squares slope through the whole sampled staircase, and
it beats the endpoint difference by using WHEN each 1 mAh step landed instead of
only how many landed. Its residual spread is printed too -- a cell that drifted
(traffic burst, charging, a hand near the antenna) shows up there rather than
quietly biasing the number. When the two estimators disagree by more than the
error bar, do not average them: the cell was not stationary, so re-run it.
Airtime counters are recorded per cell as CONTEXT, not as the claim: a cell that
happened to relay a flood burns more than an idle one, and without that column a
polluted cell looks like a real regression.
"""
import argparse
import glob
import json
import re
import sys
import time
import urllib.request
import serial
EXPORTER = "http://localhost:9877/metrics"
SETTLE_DEFAULT = 60
def meter_sample(url, meter=None):
"""One reading of the exporter: (capacity_mAh, volts, amps, unix_ts)."""
with urllib.request.urlopen(url, timeout=10) as r:
body = r.read().decode()
out = {}
for name in ("meter_capacity_ah", "meter_voltage_volts", "meter_current_amps",
"meter_last_seen_timestamp_seconds", "meter_up"):
for line in body.splitlines():
if not line.startswith(name + "{"):
continue
if meter and f'meter="{meter}"' not in line:
continue
out[name] = float(line.rsplit(" ", 1)[1])
break
missing = [k for k in ("meter_capacity_ah", "meter_up") if k not in out]
if missing:
raise SystemExit(f"exporter neposkytl {missing} (jiny meter? --meter <mac bez dvojtecek>)")
if out["meter_up"] != 1.0:
raise SystemExit("meter_up=0 -- exporter nema spojeni s meraakem, meritko by lhalo")
# Frames must be arriving, not just the link be up: a stale series is a
# straight line, and a straight line reads like a perfectly stable load.
age = time.time() - out.get("meter_last_seen_timestamp_seconds", 0.0)
if age > 30:
raise SystemExit(f"posledni ramec pred {age:.0f} s -- serie je zamrzla, ne stabilni")
return (out["meter_capacity_ah"] * 1000.0, out.get("meter_voltage_volts", 0.0),
out.get("meter_current_amps", 0.0), out.get("meter_last_seen_timestamp_seconds", 0.0))
def fit_slope_ma(series):
"""Least-squares mA through (seconds, mAh) samples: (mA, residual, std err).
The counter is a 1 mAh staircase, so the slope carries the timing of every
step, not just the count at the ends. Residuals are returned in mAh: on a
stationary cell they stay under ~0.6 (half a step); much more than that means
the load moved during the window and the average is hiding something.
CAVEAT on the standard error: it assumes independent residuals, and a
quantised staircase violates that (consecutive samples sit on the same step),
so it reads optimistic. It is still the right order of magnitude, and it is
the honest one to compare deltas against -- unlike the endpoint quantisation,
which the fit is specifically there to beat. Run one cell twice to get the
empirical repeatability; that number outranks this estimate.
"""
n = len(series)
if n < 4:
return None, None, None
tx = sum(t for t, _ in series) / n
ty = sum(c for _, c in series) / n
sxx = sum((t - tx) ** 2 for t, _ in series)
if sxx == 0:
return None, None, None
sxy = sum((t - tx) * (c - ty) for t, c in series)
slope = sxy / sxx # mAh per second
sse = sum((c - (ty + slope * (t - tx))) ** 2 for t, c in series)
resid = (sse / n) ** 0.5
se = ((sse / (n - 2)) / sxx) ** 0.5 # mAh/s
return slope * 3600.0, resid, se * 3600.0
class Console:
"""Text console of a repeater/analyzer build over USB CDC.
dtr/rts + the settle delay are not optional: nRF52 TinyUSB keeps the CDC
mute until DTR is asserted, and a board opened without it looks dead.
"""
LOST = "<console lost>"
def __init__(self, port_glob):
self.port_glob = port_glob
self.s = None
self._open()
def _open(self):
path = glob.glob(self.port_glob)
if not path:
raise SystemExit(f"port {self.port_glob} nenalezen")
self.s = serial.Serial(path[0], 115200, timeout=0)
self.s.dtr = True
self.s.rts = True
time.sleep(1.3)
self.s.reset_input_buffer()
def reopen(self, wait=90.0):
"""Wait for the board to come back on USB and re-open it.
These boards drop off USB on their own (documented flakiness) and return
seconds to minutes later. Losing the console mid-run must not force a
rerun of an hour-long matrix.
"""
try:
if self.s:
self.s.close()
except Exception:
pass
self.s = None
t0 = time.time()
while time.time() - t0 < wait:
if glob.glob(self.port_glob):
try:
self._open()
return True
except (OSError, serial.SerialException, SystemExit):
pass
time.sleep(3)
return False
def cmd(self, c, timeout=4.0, quiet=0.3):
"""Send a command. On a console drop, re-open once and retry.
Returns LOST if the console could not be recovered. Callers that are
APPLYING a cell setting must treat that as a failed cell — measuring a
treatment that was never applied is worse than no measurement, and it
happened: `gps off` was lost on the wire, the run carried on, and two
cells silently measured `gps on` again.
"""
try:
return self._cmd(c, timeout, quiet)
except (OSError, serial.SerialException):
pass
if self.reopen():
try:
return self._cmd(c, timeout, quiet)
except (OSError, serial.SerialException):
pass
return self.LOST
def _cmd(self, c, timeout, quiet):
if self.s is None:
raise serial.SerialException("console not open")
self.s.write((c + "\r").encode())
buf, last, t0 = b"", time.time(), time.time()
while time.time() - t0 < timeout:
d = self.s.read(256)
if d:
buf += d
last = time.time()
elif buf and time.time() - last > quiet:
break
else:
time.sleep(0.02)
txt = buf.decode(errors="replace")
# echo of the command comes back first; keep the answer only
lines = [ln.strip() for ln in txt.replace("\r", "\n").split("\n") if ln.strip()]
lines = [ln for ln in lines if ln != c]
return " | ".join(ln.lstrip("> ").strip() for ln in lines)
def air(self):
m = re.search(r'"tx_air_secs":(\d+).*?"rx_air_secs":(\d+)', self.cmd("stats-radio"))
return (int(m.group(1)), int(m.group(2))) if m else (None, None)
def close(self):
try:
if self.s:
self.s.close()
except Exception:
pass
# What a cell's setting command must end up reporting, so "applied" is verified
# on the node rather than assumed from a write that returned no error. Key is the
# command prefix, value is (query, expected substring in the answer).
VERIFY = {
"gps off": ("gps", "off"),
"gps on": ("gps", "on,"),
"gps duty": ("gps", "duty"),
"powersaving on": ("powersaving", "on"),
"powersaving off": ("powersaving", "off"),
"ble on": ("ble", "on"),
"ble off": ("ble", "off"),
}
# Queried at the start of every cell: the record of what the node actually was,
# and the raw material for VERIFY above.
STATE_QUERIES = ("powersaving", "gps", "ble", "get repeat")
def port_glob_for(serial_no):
g = glob.glob(f"/dev/serial/by-id/*{serial_no}*")
if not g:
raise SystemExit(f"port pro seriak {serial_no} nenalezen v /dev/serial/by-id/")
return f"/dev/serial/by-id/*{serial_no}*"
def main():
ap = argparse.ArgumentParser(description="A/B mereni proudu pres UC96 exporter")
ap.add_argument("--serial", help="seriove cislo desky (matchuje se v /dev/serial/by-id/)")
ap.add_argument("--port", help="misto --serial: pevna cesta k portu")
ap.add_argument("--cell", action="append", default=[], metavar="NAME=CMD[;CMD]",
help="jedna bunka: jmeno a prikazy, ktere ji nastavi (prazdne = jen mer)")
ap.add_argument("--minutes", type=float, default=30.0, help="delka okna bunky (vychozi 30)")
ap.add_argument("--settle", type=float, default=SETTLE_DEFAULT,
help="prodleva po aplikaci prikazu pred zacatkem okna (s, vychozi 60)")
ap.add_argument("--poll", type=float, default=10.0,
help="jak casto vzorkovat citac kapacity v okne (s, vychozi 10)")
ap.add_argument("--meter", help="MAC merace bez dvojtecek, kdyz exporter vidi vic meraku")
ap.add_argument("--url", default=EXPORTER)
ap.add_argument("--json", help="ulozit vysledek jako JSON")
args = ap.parse_args()
if not args.cell:
raise SystemExit("aspon jedna --cell")
err_ma = 60.0 / args.minutes # +-1 mAh quantisation over the window
print(f"okno {args.minutes:g} min => kvantizace merice je +-{err_ma:.2f} mA na bunku")
if err_ma > 1.5:
print(" POZOR: to je vic, nez kolik ceka vetsina uspor. Delsi --minutes, nebo "
"cti vysledek jako 'nezmereno'.")
con = None
if args.serial or args.port:
con = Console(args.port or port_glob_for(args.serial))
print(f"deska: {con.cmd('ver')} / {con.cmd('get name')}")
results = []
try:
for spec in args.cell:
name, _, cmds = spec.partition("=")
name = name.strip() or "cell"
cmds = [c.strip() for c in cmds.split(";") if c.strip()]
print(f"\n=== bunka {name}")
applied = True
for c in cmds:
if not con:
raise SystemExit("bunka ma prikazy, ale neni zadana deska (--serial)")
reply = con.cmd(c)
print(f" {c} -> {reply}")
if reply == Console.LOST or "Unknown command" in reply or "rror" in reply:
applied = False
if cmds:
print(f" usazovani {args.settle:g} s")
time.sleep(args.settle)
state = {}
tx0 = rx0 = None
if con:
for q in STATE_QUERIES:
state[q] = con.cmd(q)
tx0, rx0 = con.air()
# Verify on the node that the setting took, then refuse to measure a
# treatment that is not actually in place. The alternative -- what
# this tool did before -- is a plausible-looking number for a state
# the node was never in.
for c in cmds:
for prefix, (query, expect) in VERIFY.items():
if c.startswith(prefix):
answer = state.get(query, "")
if expect not in answer:
print(f" NEOVERENO: po '{c}' hlasi '{query}' -> "
f"'{answer}' (cekano '{expect}')")
applied = False
if not applied:
print(" CHYBA: zasah se neaplikoval/neoveril -- bunka se NEMERI "
"(merit neaplikovany zasah je horsi nez nemerit)")
results.append({"cell": name, "cmds": cmds, "avg_ma": None, "fit_ma": None,
"resid_mah": None, "se_ma": None, "delta_mah": None,
"minutes": 0.0, "err_ma": err_ma, "volts": None,
"state": state, "tx_air_delta": None, "rx_air_delta": None,
"samples": 0, "invalid": "neaplikovano"})
continue
cap0, v0, _, _ = meter_sample(args.url, args.meter)
t0 = time.time()
print(f" start: cap={cap0:.0f} mAh, U={v0:.2f} V, stav={state}")
series = [(0.0, cap0)]
deadline = t0 + args.minutes * 60
# Heartbeat once a minute. Without it a healthy cell and a hung
# process look identical for ten minutes at a stretch -- which is
# exactly how a good run got killed two minutes before it finished.
next_beat = t0 + 60
while time.time() < deadline:
time.sleep(min(args.poll, max(0.0, deadline - time.time())))
cap, v1, i1, _ = meter_sample(args.url, args.meter)
now = time.time()
series.append((now - t0, cap))
if now >= next_beat:
next_beat += 60
el = (now - t0) / 60.0
print(f" ... {el:.0f}/{args.minutes:g} min, +{cap-cap0:.0f} mAh, "
f"zatim {(cap-cap0)/((now-t0)/3600.0):.1f} mA", flush=True)
cap1, v1, i1, _ = meter_sample(args.url, args.meter)
series.append((time.time() - t0, cap1))
dt_h = (time.time() - t0) / 3600.0
tx1, rx1 = con.air() if con else (None, None)
dcap = cap1 - cap0
fit_ma = resid = se_ma = None
if dcap < 0:
print(" CHYBA: citac kapacity klesl (reset merice) -- bunka je neplatna")
avg = None
elif dcap == 0:
# An instrument reporting a perfectly flat counter is not
# measuring a small load, it is not measuring. Reporting
# "0.00 +-0.00 mA" as a result once sent a whole session chasing
# the wrong thing: the same board read 22 mA on another meter
# while this one sat at zero for 15 minutes. Refuse the cell.
print(f" CHYBA: citac kapacity se za {dt_h*60:.0f} min NEHNUL "
f"(instant {i1*1000:.0f} mA). Merak tuhle zatez nemeri -- "
f"nula NENI vysledek. Zkus jiny merak nebo vetsi zatez.")
avg = None
else:
avg = dcap / dt_h
fit_ma, resid, se_ma = fit_slope_ma(series)
print(f" konec: cap={cap1:.0f} mAh, delta={dcap:.0f} mAh za {dt_h*60:.1f} min, "
f"{len(series)} vzorku")
print(f" ==> endpoint {avg:.2f} +-{err_ma:.2f} mA | fit {fit_ma:.2f} "
f"+-{se_ma:.2f} mA (rezidua {resid:.2f} mAh) @ {v1:.2f} V "
f"(instant {i1*1000:.0f} mA, 10mA krok)")
if abs(fit_ma - avg) > err_ma:
print(" POZOR: estimatory se rozchazi vic nez chyba -- bunka nebyla "
"stacionarni, zopakuj ji")
# stats-radio can fail to parse on either end (busy console); keep the
# cell valid and just report the airtime column as unknown.
d_tx = tx1 - tx0 if (tx0 is not None and tx1 is not None) else None
d_rx = rx1 - rx0 if (rx0 is not None and rx1 is not None) else None
if d_tx is not None:
print(f" airtime v okne: tx +{d_tx} s, rx +{d_rx} s")
results.append({"cell": name, "cmds": cmds, "avg_ma": avg, "fit_ma": fit_ma,
"resid_mah": resid, "se_ma": se_ma, "delta_mah": dcap,
"minutes": dt_h * 60, "err_ma": err_ma, "volts": v1,
"state": state, "tx_air_delta": d_tx, "rx_air_delta": d_rx,
"samples": len(series)})
finally:
if con:
con.close()
summarize(results)
if args.json:
with open(args.json, "w") as f:
json.dump(results, f, indent=2)
print(f"\nJSON -> {args.json}")
return 0
def summarize(results):
"""Print the summary. Separate from main() so a finished run's JSON can be
re-analysed (and the analysis tested) without touching hardware."""
print("\n===== SOUHRN ===== (fit je presnejsi estimator, endpoint v zavorce)")
valid = [r for r in results if r["fit_ma"] is not None]
base = valid[0] if valid else None
# Spread across repeats of the same cell is repeatability ONLY if the rig is
# stationary. It is not, when something drifts underneath (a charging cell
# tapering: `gps on` cells went 107 -> 92 -> 88 -> 84 mA across one hour).
# Using that spread as a noise floor then buries the very effect being
# measured -- it flagged a real 46 mA GPS delta as "v sumu".
floor = None
groups = {}
for r in valid:
groups.setdefault(tuple(r["cmds"]), []).append(r["fit_ma"])
for cmds, vals in groups.items():
if len(vals) > 1:
spread = max(vals) - min(vals)
trend = abs(vals[-1] - vals[0])
drifting = trend > 0.6 * spread # monotone-ish: most of the spread is trend
label = "drift, NE sum" if drifting else "opakovatelnost"
print(f" {label} ({'+'.join(cmds) or 'bez prikazu'}): rozptyl {spread:.2f} mA "
f"pres {len(vals)} bunky (kraje se lisi o {trend:.2f})")
if not drifting:
floor = spread if floor is None else max(floor, spread)
# Alternating designs (A B A B ...) are the answer to a drifting rig, so
# analyse them as such: each B against the MEAN OF ITS TWO NEIGHBOURING A
# cells, which cancels a linear trend. This is the number to quote.
sigs = [tuple(r["cmds"]) for r in valid]
distinct = list(dict.fromkeys(sigs))
if len(distinct) == 2 and len(valid) >= 3:
a_sig, b_sig = distinct
deltas = []
for i, r in enumerate(valid):
if tuple(r["cmds"]) != b_sig:
continue
before = next((v["fit_ma"] for v in reversed(valid[:i])
if tuple(v["cmds"]) == a_sig), None)
after = next((v["fit_ma"] for v in valid[i + 1:]
if tuple(v["cmds"]) == a_sig), None)
flank = [x for x in (before, after) if x is not None]
if flank:
deltas.append(sum(flank) / len(flank) - r["fit_ma"])
if deltas:
mean = sum(deltas) / len(deltas)
print(f"\n PAROVY ODHAD ({'+'.join(a_sig) or 'bez prikazu'} minus "
f"{'+'.join(b_sig) or 'bez prikazu'}): {mean:.2f} mA "
f"(z {len(deltas)} paru, rozptyl {min(deltas):.2f}-{max(deltas):.2f}) "
f"-- drift vykracen, tohle je cislo k citovani")
for r in valid:
d = ""
if base and r is not base:
diff = r["fit_ma"] - base["fit_ma"]
# Significance against the measured repeatability when we have it,
# otherwise against twice the fit's own standard error.
lim = floor if floor is not None else 2 * (r["se_ma"] or 0)
sig = "" if abs(diff) > lim else " (v sumu!)"
d = f" delta vs {base['cell']}: {diff:+.2f} mA{sig}"
print(f" {r['cell']:12s} {r['fit_ma']:6.2f} +-{r['se_ma']:.2f} mA "
f"(endpoint {r['avg_ma']:.2f} +-{r['err_ma']:.2f}){d}")
for r in results:
if r["fit_ma"] is None:
print(f" {r['cell']:12s} neplatna ({r.get('invalid', 'merak nemeril')})")
if __name__ == "__main__":
# Re-analyse a finished run: power_ab.py --reanalyse run.json
if len(sys.argv) == 3 and sys.argv[1] == "--reanalyse":
with open(sys.argv[2]) as f:
summarize(json.load(f))
sys.exit(0)
sys.exit(main())
+85
View File
@@ -0,0 +1,85 @@
#!/usr/bin/env python3
# SPDX-License-Identifier: MIT
"""TRACE po pevné cestě na zvoleném presetu přes USB companion — měření přímého hopu.
Companion přepne rádio na preset, pošle N× TRACE po cestě (2B hashe) a vypíše
SNR, které na trase připsal každý hop, a SNR, se kterým odpověď slyšel on sám.
Slouží k měření spoje mezi dvěma repeatery, které jsou mezitím přes `tempradio`
na stejném presetu (sám je nepřelaďuje).
preset_trace.py /dev/serial/by-id/... 869.525 62.5 12 8 --path 025c,5f14,025c -n 8
preset_trace.py /dev/serial/by-id/... 866.5 62.5 8 5 --tx 2 --restore # zpět, bez TRACE
Nastavení rádia companion ukládá do prefs — po měření ho vrať (--restore).
Výstup: jedna JSON řádka na pokus (ok/timeout, hopy se SNR, rtt).
"""
import argparse
import asyncio
import json
import random
import time
def parse():
ap = argparse.ArgumentParser(description=__doc__,
formatter_class=argparse.RawDescriptionHelpFormatter)
ap.add_argument("port", help="sériový port companionu (/dev/serial/by-id/...)")
ap.add_argument("freq", type=float, help="MHz")
ap.add_argument("bw", type=float, help="kHz")
ap.add_argument("sf", type=int)
ap.add_argument("cr", type=int, help="5..8 (4/5..4/8)")
ap.add_argument("--tx", type=int, default=22, help="TX výkon dBm (default 22)")
ap.add_argument("--path", default="025c,5f14,025c", help="hopy TRACE, 2B hex, čárkou")
ap.add_argument("-n", type=int, default=8, help="počet TRACE (default 8)")
ap.add_argument("--gap", type=float, default=3.0, help="pauza mezi pokusy, s")
ap.add_argument("--timeout", type=float, default=0,
help="čekání na odpověď, s (0 = odhad firmwaru + 50 %%)")
ap.add_argument("--restore", action="store_true", help="jen nastavit rádio, žádný TRACE")
return ap.parse_args()
async def main(a):
from meshcore import EventType, MeshCore
mc = await MeshCore.create_serial(a.port, 115200)
if mc is None:
raise SystemExit("companion neodpovídá")
r = await mc.commands.set_radio(a.freq, a.bw, a.sf, a.cr)
if r.type == EventType.ERROR:
raise SystemExit("set_radio: %s" % r.payload)
r = await mc.commands.set_tx_power(a.tx)
if r.type == EventType.ERROR: # build caps TX (MAX_LORA_TX_POWER): keep its current power
print(json.dumps({"warn": "set_tx_power %d refused" % a.tx}), flush=True)
await mc.commands.send_appstart()
si = mc.self_info
print(json.dumps({"radio": [si.get("radio_freq"), si.get("radio_bw"), si.get("radio_sf"),
si.get("radio_cr")], "tx": si.get("tx_power")}), flush=True)
if a.restore:
await mc.disconnect()
return
for i in range(a.n):
tag = random.randint(1, 0xFFFFFFFF)
t0 = time.monotonic()
sent = await mc.commands.send_trace(auth_code=0, tag=tag, flags=1, path=a.path)
if sent.type == EventType.ERROR:
print(json.dumps({"i": i, "error": str(sent.payload)}), flush=True)
await asyncio.sleep(a.gap)
continue
est = (sent.payload or {}).get("suggested_timeout", 0) / 1000
wait = a.timeout or max(10.0, est * 1.5)
ev = await mc.wait_for_event(EventType.TRACE_DATA, attribute_filters={"tag": tag},
timeout=wait)
rec = {"i": i, "t": time.strftime("%H:%M:%S"), "wait": round(wait, 1)}
if ev is None:
rec["ok"] = False
else:
rec.update(ok=True, rtt=round(time.monotonic() - t0, 1),
hops=[[h.get("hash", "me"), h["snr"]] for h in ev.payload.get("path", [])])
print(json.dumps(rec), flush=True)
await asyncio.sleep(a.gap)
await mc.disconnect()
if __name__ == "__main__":
asyncio.run(main(parse()))
+129
View File
@@ -0,0 +1,129 @@
#!/usr/bin/env python3
# SPDX-License-Identifier: MIT
"""Watch a RADIO_DIAG node on its USB console until its receiver goes deaf.
usage: radio_stall_watch.py [--stall-min N] [--log FILE] <serial-port>
Born 31. 10. 2026: bench-sensor stopped receiving (recv frozen, noise_floor
-120, last_rssi 0) and a reboot revived it. A reboot fixes nothing, it only
destroys the evidence -- so this sits on the console and waits for the next one:
* every line the node prints (MESH_DEBUG) goes to the log with a UTC stamp
* every 60 s: `radiostat` + `stats-packets`
* no packet read for --stall-min minutes (default 15; the live CZ mesh
normally delivers a flood every 30-60 s) = STALL:
- three `radiostat` snapshots, 10 s apart (is anything still moving?)
- then the recovery ladder, gentlest first, one step at a time:
clrirq -> rx -> standby -> agc. After each step it waits 3 min for a
packet; the FIRST step that brings recv back names the broken layer
(lost DIO1 edge / RX not re-armed / chip out of RX / AGC-analog).
- if nothing helps, it says so and leaves the node deaf for a human.
It does not reboot the node, ever.
Needs firmware built with -D RADIO_DIAG (radiostat/radiokick). Holds the port
open for as long as it runs, so the node's BLE (dock-quiet) and other console
users are off meanwhile. Nothing is transmitted.
"""
import re
import sys
import time
if {"-h", "--help"} & set(sys.argv[1:]):
print(__doc__.strip())
sys.exit(0)
import serial # noqa: E402
LADDER = ["clrirq", "rx", "standby", "agc"]
RX_RE = re.compile(r"\brx=(\d+)/(\d+)s")
def utc():
return time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
class Node:
def __init__(self, port, log):
self.s = serial.Serial(port, 115200, timeout=0.2)
self.log = log
self.buf = b""
def write_log(self, line):
self.log.write(f"{utc()} {line}\n")
self.log.flush()
def pump(self, secs):
"""Log everything the node prints for `secs`; return the lines."""
out, end = [], time.time() + secs
while time.time() < end:
self.buf += self.s.read(4096)
while b"\n" in self.buf:
raw, self.buf = self.buf.split(b"\n", 1)
line = raw.decode(errors="replace").rstrip("\r")
if line:
self.write_log(line)
out.append(line)
return out
def cmd(self, c):
self.write_log(f">>> {c}")
self.s.write((c + "\r").encode())
for line in self.pump(1.0):
if line.startswith(c) and "->" in line:
return line.split("->", 1)[1].strip()
return ""
def rx_age(self):
m = RX_RE.search(self.cmd("radiostat"))
return (int(m.group(1)), int(m.group(2))) if m else (None, None)
def main(port, stall_s, logpath):
with open(logpath, "a") as log:
n = Node(port, log)
n.write_log(f"=== watch start, stall after {stall_s} s, port {port}")
n.cmd("ver")
while True:
n.pump(59)
n.cmd("stats-packets")
rx, age = n.rx_age()
if age is None or age < stall_s:
continue
n.write_log(f"!!! STALL: no packet read for {age} s (rx={rx})")
for _ in range(3):
n.cmd("radiostat")
n.pump(10)
for step in LADDER:
n.cmd(f"radiokick {step}")
end = time.time() + 180
while time.time() < end:
n.pump(30)
rx2, _ = n.rx_age()
if rx2 is not None and rx2 > rx:
n.write_log(f"!!! RECOVERED by '{step}' (rx {rx} -> {rx2})")
break
else:
n.write_log(f"... '{step}' did not bring RX back")
continue
break
else:
n.write_log("!!! NOTHING on the ladder revived RX -- left deaf for inspection")
n.pump(10**9)
stall_min, logfile = 15, "radio_stall_watch.log"
it = iter(sys.argv[1:])
args = []
for a in it:
if a == "--stall-min":
stall_min = int(next(it))
elif a == "--log":
logfile = next(it)
elif a.startswith("--"):
sys.exit(__doc__.strip().splitlines()[2])
else:
args.append(a)
if len(args) != 1:
sys.exit(__doc__.strip().splitlines()[2])
main(args[0], stall_min * 60, logfile)
+116
View File
@@ -0,0 +1,116 @@
#!/usr/bin/env python3
# SPDX-License-Identifier: MIT
"""Textova konzole uzlu na USB -- posli prikazy, vypis odpovedi.
tools/serial_cli.py x4 ver
tools/serial_cli.py x4 "get freq" "get name" "get batt.icon"
tools/serial_cli.py /dev/serial/by-id/usb-Seeed_Studio_XIAO_... ver
tools/serial_cli.py --list
USB protejsek `ble_cli.py`. Vzniklo 21. 9. 2026: `board_probe.py` umi jen
otisk (posle `ver` a skonci), `fleet_test.py` konzoli pouziva, ale jen na svuj
scenar -- a na kazdy dotaz typu "co ma ta deska ve `get freq`" se pokazde psal
jednorazovy skript znovu.
Parametry portu jsou prevzate z `board_probe.py::_open()` vcetne dvou veci,
ktere vypadaji jako zbytecnost a nejsou:
* DTR+RTS nahoru a 0,9 s cekani -- bez toho deska jeste neni pripravena
a prvni prikaz spolkne.
* prazdne CRLF pred prvnim prikazem -- prvni radek po otevreni portu se
casto ztrati uplne.
PAST (z hlavicky fleet_test.py): nenechavej pripojeneho BLE klienta na desce,
se kterou tady mluvis. USB a BLE konzole sdileji jeden buffer command[160]
(simple_repeater/main.cpp), takze dve zive konzole si michaji znaky do jedne
radky a uzel pak vykona nesmysl.
Companion buildy textovou konzoli NEMAJI a na vsechno tady odpovi tichem --
neni to zaseklá deska. Co na ktere desce bezi rekne `board_probe.py --all`.
"""
import argparse
import glob
import os
import sys
import time
# FLEET ani otevírání portu se tu NEDUPLIKUJE -- viz fleet.py (tabulka) a
# board_probe.py::_open (sekvence dtr/rts + settle + prime, kterou by druhá
# kopie dřív nebo později rozešla). AGENTS.md: "nevymýšlej kolo".
sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
from board_probe import _open as open_port
from fleet import FLEET, serial_for
from mctools_config import field, unknown_alias_hint
def ports():
return sorted(glob.glob("/dev/serial/by-id/*"))
def resolve(target):
"""Jmeno z flotily, holé seriove cislo, nebo rovnou cesta k portu."""
if target.startswith("/"):
return target
sn = serial_for(target)
why = field(sn, "refuse")
if why:
sys.exit(f"{target}: odmitnuto -- {why}")
hits = [p for p in ports() if sn in p]
if not hits:
hint = f"; {unknown_alias_hint(target)}" if sn == target else ""
sys.exit(f"port pro {target!r} (sn {sn}) nenalezen -- viz --list{hint}")
if len(hits) > 1:
sys.exit(f"{target!r} odpovida vic portum: {hits}")
return hits[0]
def drain(s, window):
buf, t = b"", time.time()
while time.time() - t < window:
d = s.read(8192)
if d:
buf += d
else:
time.sleep(0.02)
return buf
def main():
ap = argparse.ArgumentParser(description=__doc__,
formatter_class=argparse.RawDescriptionHelpFormatter)
ap.add_argument("board", nargs="?", help="jmeno desky z configu (tools/mctools_config.py), seriove cislo, nebo cesta k portu")
ap.add_argument("cmd", nargs="*", help="prikazy konzole")
ap.add_argument("--list", action="store_true", help="vypis porty a konci")
ap.add_argument("--wait", type=float, default=1.5,
help="kolik sekund cekat na odpoved (default 1.5; `nodes` a "
"`rxlog` na plnem uzlu chtou vic)")
ap.add_argument("--raw", action="store_true", help="bez hlavicek, jen odpovedi")
args = ap.parse_args()
if args.list:
for p in ports():
tag = next((n for n, sn in FLEET.items() if sn in p), "")
print(f"{tag:4} {p}")
return
if not args.board or not args.cmd:
ap.error("chybi deska nebo prikaz (viz --list)")
port = resolve(args.board)
s = open_port(port) # dtr/rts + 0,9 s settle + reset_input_buffer
try:
s.write(b"\r\n")
time.sleep(0.4)
s.reset_input_buffer()
for c in args.cmd:
s.write(c.encode() + b"\r\n")
out = drain(s, args.wait).decode(errors="replace").strip()
if args.raw:
print(out)
else:
print(f"[{args.board}] {c}\n{out}\n")
finally:
s.close()
main()
+86
View File
@@ -0,0 +1,86 @@
#!/usr/bin/env python3
# SPDX-License-Identifier: MIT
"""Bridge a bench XIAO's USB console to a localhost TCP port.
tools/serial_tcp_proxy.py <usb-serial|board> <tcp-port>
Holds the console open with DTR/RTS up (as fleet_test.py does) and serves it
on 127.0.0.1:<tcp-port>, one client at a time, so a board on another host
joins a test run here through an SSH tunnel:
ssh -L 7001:127.0.0.1:7001 lab-pc \\
'python3 MeshCore/tools/serial_tcp_proxy.py b1 7001'
tools/fleet_test.py --boards 4 --remote 1=socket://127.0.0.1:7001
Localhost only. Matches the board by its USB serial number, never ttyACM*;
a board name/alias is looked up in the local config (tools/mctools_config.py)
of the host it runs on. Refuses a board whose config entry sets `refuse`
(e.g. the radio of an observer, which runs other firmware).
"""
import glob
import socket
import sys
import threading
from mctools_config import field, serial_for
def serve(ser, srv: socket.socket) -> None:
while True:
conn, _ = srv.accept()
conn.settimeout(0.05)
alive = [True]
def to_client() -> None:
while alive[0]:
try:
data = ser.read(4096)
if data:
conn.sendall(data)
except OSError:
alive[0] = False
t = threading.Thread(target=to_client, daemon=True)
t.start()
while alive[0]:
try:
data = conn.recv(4096)
if not data:
break
ser.write(data)
except socket.timeout:
continue
except OSError:
break
alive[0] = False
t.join(1)
conn.close()
def main() -> None:
if len(sys.argv) != 3 or sys.argv[1] in ("-h", "--help"):
print(__doc__)
sys.exit(0)
sn, tport = serial_for(sys.argv[1]), int(sys.argv[2])
why = field(sn, "refuse")
if why:
sys.exit(f"refused: {why}")
ports = [p for p in glob.glob("/dev/serial/by-id/*Seeed_Studio_XIAO*") if sn in p]
if not ports:
sys.exit(f"{sn}: no MeshCore XIAO port")
import serial # after --help: the help works without pyserial
ser = serial.Serial(ports[0], 115200, timeout=0.05)
ser.dtr = True
ser.rts = True
srv = socket.socket()
srv.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
srv.bind(("127.0.0.1", tport))
srv.listen(1)
print(f"{ports[0]} <-> 127.0.0.1:{tport}", flush=True)
serve(ser, srv)
if __name__ == "__main__":
main()
+75
View File
@@ -0,0 +1,75 @@
#!/usr/bin/env bash
# SPDX-License-Identifier: MIT
# Flash a XIAO nRF52840 with a text console (repeater, room server, sensor)
# over USB serial DFU -- no UF2 drive, no mount, no root, no 1200-baud touch.
#
# tools/xiao_serial_dfu.sh <firmware.zip> <usb-serial> <board>
#
# firmware.zip the DFU package (.pio/build/<env>/firmware.zip, or a release
# asset *.zip)
# usb-serial the board's USB serial number (matched in /dev/serial/by-id)
# board its name for serial_cli.py (local config, tools/mctools_config.py)
#
# NRF=<dir> directory holding tool-adafruit-nrfutil
# (default ~/.platformio/packages)
# PY=<python> interpreter (default python3)
# CLI=<path> serial_cli.py (default: next to this script)
#
# Sends `dfu serial` on the console, waits for the bootloader port
# (XIAO_nRF52840_Sense_<sn>) and runs adafruit-nrfutil on it; a board already
# in the bootloader is flashed as it is. Reports success only when the app is
# back on USB -- check `ver` yourself. Companion builds have no console: use
# `pio run -e <env> -t upload` there (touch). Refuses a board whose config
# entry has `refuse` set (e.g. the radio of an observer). Runs on any host that
# has the board on USB and a checkout of this repo -- no PlatformIO project
# build needed there, only the nrfutil package.
set -euo pipefail
case "${1:-}" in -h | --help | "")
sed -n '3,/^[^#]/{/^#/s/^# \{0,1\}//p}' "$0"
exit 0
;;
esac
[ $# -eq 3 ] || {
echo "usage: $0 <firmware.zip> <usb-serial> <board>" >&2
exit 2
}
ZIP=$1 SN=$2 BOARD=$3
WHY="$(python3 "$(dirname "$0")/mctools_config.py" get "$SN" refuse 2>/dev/null || true)"
[ -z "$WHY" ] || {
echo "refused: $WHY" >&2
exit 1
}
[ -f "$ZIP" ] || {
echo "$ZIP: no such file" >&2
exit 1
}
NRF=${NRF:-$HOME/.platformio/packages}
PY=${PY:-python3}
CLI=${CLI:-$(dirname "$(readlink -f "$0")")/serial_cli.py}
port() { compgen -G "/dev/serial/by-id/*$1$SN*" | head -1; }
if [ -n "$(port Seeed_Studio_XIAO_nRF52840_)" ]; then
timeout 20 "$PY" "$CLI" "$BOARD" "dfu serial" >/dev/null 2>&1 || true
fi
B=""
for _ in $(seq 1 25); do
B=$(port XIAO_nRF52840_Sense_ || true)
[ -n "$B" ] && break
sleep 1
done
[ -n "$B" ] || {
echo "$BOARD: bootloader port did not appear" >&2
exit 1
}
PYTHONPATH="$NRF/tool-adafruit-nrfutil/site-packages" timeout 120 "$PY" \
"$NRF/tool-adafruit-nrfutil/adafruit-nrfutil.py" dfu serial -pkg "$ZIP" \
-p "$B" -b 115200 --singlebank 2>&1 | tail -1
for _ in $(seq 1 30); do
if [ -n "$(port Seeed_Studio_XIAO_nRF52840_)" ]; then
echo "$BOARD: app back on USB"
exit 0
fi
sleep 2
done
echo "$BOARD: app did not come back on USB" >&2
exit 1
+314
View File
@@ -0,0 +1,314 @@
#!/usr/bin/env bash
# SPDX-License-Identifier: MIT
# Flash a XIAO nRF52840 through its UF2 drive -- to a named board, and verified.
#
# tools/xiao_uf2_flash.sh <firmware.uf2> [target]
#
# target USB serial (full or unique suffix), or a board name/alias from the
# local config (tools/mctools_config.py).
# Omit only when exactly one board is plugged in.
#
# XIAO_UF2_WAIT=300 seconds to wait for UF2 mode (default 90). Worth raising
# when the board has to be double-tapped by hand.
#
# Get the board into UF2 mode with 'dfu' on its console (deterministic), or by
# double-tapping its small RESET button.
#
# What it refuses to do, because each of these has actually gone wrong here:
# - flash an image older than the build that produced it (pio run and
# pio run -t create_uf2 refresh different artifacts; x3 silently ended up
# two commits behind the rest of the fleet that way)
# - guess which board to write to when several are in UF2 mode (every drive
# is labelled XIAO-SENSE, in plug order, so the label proves nothing)
# - write to a board other than the one you named
# - report success without reading the version back off the board (the first
# version of this script printed x4's port after flashing x3)
#
# NEVER uses the 1200-baud touch: it only requests the bootloader's SERIAL_ONLY
# mode, so no drive ever appears, and a second touch in one power session wedges
# the board out of USB and BLE with no self-recovery.
set -uo pipefail
case "${1:-}" in -h | --help)
sed -n '3,/^[^#]/{/^#/s/^# \{0,1\}//p}' "$0"
exit 0
;;
esac
die() {
echo "CHYBA: $*" >&2
exit 1
}
UF2="${1:-}"
TARGET="${2:-}"
[ -n "$UF2" ] && [ -f "$UF2" ] || {
echo "usage: $(basename "$0") <firmware.uf2> [serial|board]" >&2
exit 1
}
# Board names/aliases come from the local config (tools/mctools_config.py);
# a serial or its unique suffix passes through.
if [ -n "$TARGET" ] && SN="$(python3 "$(dirname "$0")/mctools_config.py" serial "$TARGET" 2>/dev/null)"; then
TARGET="$SN"
fi
# A .hex or .zip dropped on a UF2 drive is silently ignored by the bootloader and
# looks like a successful flash, so check the container before trusting it.
# UF2 blocks start with the magic 0x0A324655 ("UF2\n").
head -c4 "$UF2" | grep -q 'UF2' || die "$UF2 neni UF2 obraz (chybi magic 'UF2\\n')"
echo "== image: $UF2 ($(stat -c%s "$UF2") B)"
ELF="$(dirname "$UF2")/firmware.elf"
if [ -f "$ELF" ] && [ "$ELF" -nt "$UF2" ]; then
die "$(basename "$UF2") je STARSI nez firmware.elf -- nalil bys stary obraz.
Sprav: pio run -e <env> && pio run -e <env> -t create_uf2"
fi
# Read the version out of the UF2 PAYLOAD, not the raw file. A UF2 is 512-byte
# blocks of 32 B header + 256 B data, so any string in the image can be cut in
# half by a block boundary -- and then a plain grep over the file finds nothing
# and this script refuses a perfectly good build. That is not hypothetical: it
# happened to SenseCap_mast_rpt on 15. 8. 2026 (the version was in the ELF the
# whole time), and it cost a hand-copied flash and a board that had to be
# replugged. Stitching the payload back together makes the check depend on the
# image rather than on where the linker happened to put the string.
WANT_VER="$(
python3 - "$UF2" <<'PY' 2>/dev/null || true
import re, sys
raw = open(sys.argv[1], "rb").read()
payload = b"".join(raw[i+32:i+288] for i in range(0, len(raw), 512))
m = re.search(rb"v[0-9]+\.[0-9]+\.[0-9]+-tth[0-9a-f]+\+?", payload)
if m: print(m.group(0).decode())
PY
)"
if [ -z "$WANT_VER" ]; then
die "obraz nema verzi od tools/build_version.py -- po flashi by neslo overit,
co na desce doopravdy je. Zapoj do envu: extra_scripts = \${stamped.extra_scripts}"
fi
echo "== verze v obrazu: $WANT_VER"
[ -n "$TARGET" ] && echo "== cil: $TARGET"
# Resolve UF2 drives THROUGH SYSFS, never by label: every XIAO drive is called
# XIAO-SENSE (then XIAO-SENSE1, ...) assigned in plug order, so with several
# boards on the bus the label says nothing about which board you are writing to.
find_uf2_boards() {
local d s blk
for d in /sys/bus/usb/devices/*/; do
s="$(cat "$d/serial" 2>/dev/null)" || continue
[ "$(cat "$d/idVendor" 2>/dev/null)" = "2886" ] || continue
blk="$(ls -d "$d"*/host*/target*/*/block/* 2>/dev/null | head -1)" || true
[ -n "$blk" ] && echo "$s /dev/$(basename "$blk")"
done
}
# Companion builds have no text console, so no `dfu` command: those boards can
# only be double-tapped by hand, and 90 s turned out to be shorter than the round
# trip of asking someone to do it. Overridable rather than just longer, so an
# unattended flash still fails fast.
WAIT="${XIAO_UF2_WAIT:-90}"
echo -n "== cekam na UF2 rezim, ${WAIT}s (\"dfu\" na konzoli, nebo dvojklik RESET) "
SERIAL=""
DISK=""
for _ in $(seq 1 "$WAIT"); do
mapfile -t found < <(find_uf2_boards)
if [ -n "$TARGET" ]; then # keep only the board asked for
mapfile -t found < <(printf '%s\n' "${found[@]:-}" | grep -F "$TARGET" || true)
fi
if [ "${#found[@]}" -gt 1 ]; then
echo
{
echo "${#found[@]} desek v UF2 rezimu -- nevim, ktera je ta tva:"
printf ' %s\n' "${found[@]}"
echo "Zadej cil: $(basename "$0") $UF2 <serial|board>"
} >&2
exit 1
fi
if [ "${#found[@]}" -eq 1 ] && [ -n "${found[0]}" ]; then
SERIAL="${found[0]%% *}"
DISK="${found[0]##* }"
break
fi
echo -n "."
sleep 1
done
echo
[ -n "$DISK" ] || die "do ${WAIT} s se v UF2 rezimu neobjevila${TARGET:+ deska $TARGET}"
echo "== deska: $SERIAL disk: $DISK"
# Mount with retries: the drive appears a moment before the desktop automounter
# gets to it, and udisksctl can lose that race, so a single attempt fails on a
# board that is perfectly fine. Observed on the very first `dfu`-driven flash.
MNT=""
for _ in $(seq 1 12); do
MNT="$(lsblk -no MOUNTPOINT "$DISK" | head -1)"
[ -n "$MNT" ] && break
udisksctl mount -b "$DISK" >/dev/null 2>&1 || true
sleep 1
done
[ -n "$MNT" ] || die "disk $DISK se nepodarilo namountovat ani na 12 pokusu
Zkus rucne: udisksctl mount -b $DISK"
echo "== mount: $MNT -- kopiruju"
# The board resets itself the moment it has all the blocks, so cp/sync failing
# at the very end is normal, not an error.
cp "$UF2" "$MNT/" 2>/dev/null || true
sync 2>/dev/null || true
echo -n "== cekam, az disk zmizi (= bootloader obraz prevzal) "
GONE=0
for _ in $(seq 1 30); do
find_uf2_boards | grep -q "^$SERIAL " || {
GONE=1
break
}
echo -n "."
sleep 1
done
echo
[ "$GONE" -eq 1 ] || die "disk nezmizel -- flash nejspis neprobehl"
# Wait for THIS board, matched on its serial. "Some XIAO came back on USB" is
# worthless with four of them plugged in.
echo -n "== cekam na navrat desky $SERIAL "
PORT=""
for _ in $(seq 1 45); do
for d in /sys/bus/usb/devices/*/; do
[ "$(cat "$d/serial" 2>/dev/null)" = "$SERIAL" ] || continue
[ "$(cat "$d/idProduct" 2>/dev/null)" = "8044" ] || continue
PORT="$(ls /dev/serial/by-id/*"$SERIAL"*-if00 2>/dev/null | head -1)" || true
done
[ -n "$PORT" ] && break
echo -n "."
sleep 1
done
echo
[ -n "$PORT" ] || die "$SERIAL se do 45 s neohlasila jako aplikace"
# The actual proof: ask the board what it is running. Anything less and a flash
# that quietly did nothing still reports success.
#
# The same trip also SETS THE CLOCK, because this is the one moment when a host
# is provably talking to the board. Every clock in this firmware is volatile
# unless the board has GPS or an I2C RTC: `VolatileRTCClock` starts in May 2024
# and only ticks from millis(). A node with a wrong clock is not a cosmetic
# problem -- the RTC stamps every advert it transmits, and receivers drop a stale
# timestamp as a replay. Measured 7. 8. 2026: bench-board had been running 811 days
# behind since deployment, and bench board x1 was 812 days behind, both simply
# because nobody ever typed `time <epoch>`.
GOT="$(
python3 - "$PORT" <<'PY' 2>/dev/null || true
import re, struct, sys, time
try:
import serial
except ImportError:
sys.exit(0)
# Retry: the port enumerates a second or two before the firmware is answering on
# it, so a single attempt calls a perfectly good flash "unverified" -- which is
# worse than no check, because it teaches you to ignore the tool.
for attempt in range(5):
try:
s = serial.Serial(sys.argv[1], 115200, timeout=1); s.dtr = True; s.rts = True
time.sleep(2.5); s.reset_input_buffer()
# Throwaway newline first. The board's own line buffer can still hold a
# fragment from before the reset, and whatever is sent next gets appended
# to it -- so the first real command comes back "Unknown command" and the
# flash is declared unverified even though it landed. Cost this exactly
# one wrong conclusion about x4.
s.write(b"\r\n"); s.flush(); time.sleep(0.5); s.reset_input_buffer()
s.write(b"ver\r\n"); s.flush(); time.sleep(2.0)
out = s.read(s.in_waiting or 1).decode("utf-8", "replace")
m = re.search(r"v[0-9]+\.[0-9]+\.[0-9]+-tth[0-9a-f]+\+?", out)
if m:
print("VER\t" + m.group(0))
# Set the clock, then read it back. The read-back is what decides:
# `time` answers "(ERR: clock cannot go backwards)" when the board is
# already right -- which happens once the build epoch seeds the RTC,
# and is SUCCESS, not failure. Never trust the setter's own reply.
s.reset_input_buffer()
s.write(("time %d\r\n" % int(time.time())).encode()); s.flush()
time.sleep(1.5); s.reset_input_buffer()
s.write(b"clock\r\n"); s.flush(); time.sleep(1.5)
got = s.read(s.in_waiting or 1).decode("utf-8", "replace")
c = re.search(r"\d{1,2}:\d{2} - \d{1,2}/\d{1,2}/\d{4} UTC(?: \(epoch \d+\))?", got)
print("CLOCK\t" + (c.group(0) if c else "?"))
s.close(); break
# No text console means this is a companion_radio build, which has no
# `ver` command at all -- ask in its own language rather than calling a
# perfectly good flash unverified (it did exactly that on x2).
# CMD_DEVICE_QUERY(22) -> RESP_CODE_DEVICE_INFO(13); firmware_version is
# the 20-byte field at offset 60. Framing: '<' + uint16 LE len + payload
# outbound, '>' + len + payload back.
s.reset_input_buffer()
s.write(b"<" + struct.pack("<H", 2) + bytes([22, 10])); s.flush()
time.sleep(1.0)
buf = s.read(s.in_waiting or 1)
# The port stays OPEN here on purpose. It used to be closed on this line,
# before the reply was even parsed -- which was harmless while the only
# thing left to do was print, and became a PortNotOpenError the moment
# the clock was set afterwards (caught by the outer handler, so it looked
# like four silent retries printing VER over and over). Closed on both
# exits below instead.
i = buf.find(b">")
if i >= 0 and len(buf) >= i + 3:
ln = struct.unpack("<H", buf[i+1:i+3])[0]
f = buf[i+3:i+3+ln]
if len(f) >= 80 and f[0] == 13:
v = f[60:80].split(b"\0")[0].decode("utf-8", "replace")
if v:
print("VER\t" + v)
# Companion builds have no `time` command at all -- the app
# sets the clock with CMD_SET_DEVICE_TIME(6). Same guard as
# the console (`secs >= curr`), so an ERR frame here is not a
# failure either; CMD_GET_DEVICE_TIME(5) -> RESP(9) decides.
now = int(time.time())
s.reset_input_buffer()
fr = bytes([6]) + struct.pack("<I", now)
s.write(b"<" + struct.pack("<H", len(fr)) + fr); s.flush()
time.sleep(1.0); s.reset_input_buffer()
s.write(b"<" + struct.pack("<H", 1) + bytes([5])); s.flush()
time.sleep(1.0)
rb = s.read(s.in_waiting or 1)
shown = "?"
j = rb.find(b">")
if j >= 0 and len(rb) >= j + 3:
rl = struct.unpack("<H", rb[j+1:j+3])[0]
rf = rb[j+3:j+3+rl]
if len(rf) >= 5 and rf[0] == 9:
t = struct.unpack("<I", rf[1:5])[0]
shown = time.strftime("%H:%M - %-d/%-m/%Y UTC",
time.gmtime(t)) + " (epoch %d)" % t
print("CLOCK\t" + shown)
s.close(); break
s.close() # neither dialect answered -- close before the retry reopens
except Exception:
pass
time.sleep(3)
PY
)"
GOT_VER="$(printf '%s\n' "$GOT" | sed -n 's/^VER\t//p' | head -1)"
GOT_CLOCK="$(printf '%s\n' "$GOT" | sed -n 's/^CLOCK\t//p' | head -1)"
if [ -z "$GOT_VER" ]; then
echo "!! deska neodpovedela ani konzoli, ani companion protokolu -- flash NEOVERENY (drzi konzoli BLE klient?)" >&2
exit 2
fi
if [ "$GOT_VER" != "$WANT_VER" ]; then
die "deska hlasi $GOT_VER, ale v obrazu bylo $WANT_VER -- flash NEPROSEL"
fi
echo "== OK: $SERIAL bezi $GOT_VER ($PORT)"
# Warn rather than fail: a wrong clock does not mean the flash was bad, and this
# script's contract is "the image landed". But it must not pass silently -- an
# unset clock is exactly what went unnoticed on x3 for 811 days.
# Only the year is checked, because that is what a volatile RTC gets wrong: it
# comes up in 2024 and stays there. (Around midnight on 31 December this warns
# for one minute on a board that is actually right. Non-fatal, once a year.)
case "$GOT_CLOCK" in
"") echo "!! hodiny se necetly zpatky -- nastav je rucne: time \$(date +%s)" >&2 ;;
"?") echo "!! hodiny neodpovedely ve znamem formatu -- zkontroluj 'clock' rucne" >&2 ;;
*"/$(date -u +%Y)"*)
echo "== hodiny: $GOT_CLOCK"
;;
*) echo "!! hodiny hlasi $GOT_CLOCK -- nesedi rok, nastav je rucne: time \$(date +%s)" >&2 ;;
esac