This commit is contained in:
mikecarper committed 2026-10-26 22:20:09 +00:00
1 parent e8e3a1eaf3
commit d2052d7ca2
6 files changed
+199 -6

No files matched your search

+23
View File
@@ -822,8 +822,20 @@
releaseBoundControl(profile, "combinedCompanion"));
}
function unifiedV4DisplayProfile(profile) {
return Boolean(profile && profile.hardware === "heltec_v4" &&
profile.controls && profile.controls.platform === "ESP32_PLATFORM" &&
profile.controls.display === true && releaseBoundControl(profile, "unifiedV4Display"));
}
function consolidationSuccessor(profile, candidate) {
if (!profile || !candidate || profile.role !== candidate.role) return false;
if (/^heltec_v4(?:_3)?(?:_expansionkit)?(?:_tft)?$/.test(profile.hardware) &&
profile.hardware !== "heltec_v4" && unifiedV4DisplayProfile(candidate)) {
return candidate.feature === profile.feature && candidate.ota === profile.ota &&
(!profile.sensorProfile || profile.sensorProfile === candidate.sensorProfile) &&
(profile.role !== "companion" || isFullCompanion(candidate));
}
if (/^PicoW_companion_radio_(usb|ble|wifi)$/.test(profile.target)) {
return combinedPicoCompanion(candidate);
}
@@ -1725,6 +1737,10 @@
requested[field] = params.get(field) || "";
});
[
...["heltec_v4_3", "heltec_v4_tft", "heltec_v4_3_tft", "heltec_v4_expansionkit",
"heltec_v4_expansionkit_tft", "heltec_v4_3_expansionkit_tft"].map(function (hardware) {
return [hardware, "heltec_v4", unifiedV4DisplayProfile];
}),
["heltec_rc32_without_display", "heltec_rc32", function (profile) { return optionalAutoDisplayProfile(profile); }],
["heltec_v4_expansionkit", "heltec_v4", function (profile) { return ["repeater", "room"].includes(profile.role) && releaseBoundControl(profile, "oledExpansionCompatible"); }],
["heltec_v4_r8_tft_portrait", "heltec_v4_r8_tft", function (profile) { return ["repeater", "room"].includes(profile.role) && releaseBoundControl(profile, "displayRotation"); }],
@@ -2011,6 +2027,10 @@
if (combinedPicoCompanion(profile)) {
notes.push("This Companion image includes USB, Bluetooth LE and WiFi together. Separate transport firmware is unnecessary; this image does not add a wireless firmware updater.");
}
if (unifiedV4DisplayProfile(profile)) {
notes.push("One ordinary Heltec V4 image supports V4.2/V4.3 with OLED, the stock touch TFT kit, or no screen. The saved display.type setting selects auto, oled, tft or off; board reports the detected revision and active display. R8 uses its separate hardware image.");
notes.push("When changing from a legacy TFT or expansion-kit target, use a local USB installation or a supported WiFi application update. Their LoRa OTA target IDs remain distinct; never force a different target's LoRa OTA package.");
}
if (releaseBoundControl(profile, "oledExpansionCompatible")) {
notes.push("The same OLED firmware supports the base Heltec V4 and its OLED expansion kit. Existing expansion-kit OTA identities still require their exact historical update or a local USB migration.");
}
@@ -2375,6 +2395,9 @@
if (infrastructure && (info.updateMethods || []).includes("bluetooth")) section("Bluetooth firmware update", [
{ label: "Start DFU", commands: ["start ota"], text: "Use the exact board's application DFU ZIP with the matching Bluetooth-capable bootloader." },
]);
if (unifiedV4DisplayProfile(profile)) section("Display type", ["auto", "oled", "tft", "off"].map(function (type) {
return {label: type === "auto" ? "Automatic" : type === "off" ? "Screen off" : type.toUpperCase(), commands: ["set display.type " + type]};
}), "Saved choice applies immediately. Check with get display.type and board. Automatic mode continues without a screen if no supported display is detected.");
if ((full || releaseBoundControl(profile, "displayRotation")) && info.display) section("Display rotation", [0, 90, 180, 270].map(function (angle) {
return { label: angle === 0 ? "Board default" : angle + " degrees", commands: ["set display.rotation " + angle] };
}), "Use on supported displays; 0 restores the board default. Check with get display.rotation.");
+49
View File
@@ -2199,6 +2199,17 @@
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#select-the-original-heltec-v4-display" class="md-nav__link">
<span class="md-ellipsis">
Select the original Heltec V4 display
</span>
</a>
</li>
<li class="md-nav__item">
@@ -5362,6 +5373,17 @@
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#select-the-original-heltec-v4-display" class="md-nav__link">
<span class="md-ellipsis">
Select the original Heltec V4 display
</span>
</a>
</li>
<li class="md-nav__item">
@@ -8710,6 +8732,33 @@ USB, BLE, or TCP connection. Non-touchscreen, missing-display, and legacy UI
builds report <code>Error: touchscreen diagnostics unsupported</code>. No Indicator-only
build flag is needed.</p>
<hr />
<h2 id="select-the-original-heltec-v4-display">Select the original Heltec V4 display</h2>
<p>New unified original-V4 images support V4.2/V4.3 OLED, the original TFT
touchscreen expansion kit, and operation without a screen. This feature is
not present in the older 1.17.1.1 or 1.17.1.5 images. V4 R8 remains a separate
hardware target.</p>
<pre><code class="language-text">get display.type
set display.type auto
set display.type oled
set display.type tft
set display.type off
board
</code></pre>
<p>The default <code>auto</code> requires an OLED I2C response or a stable identity from the
stock TFT assembly's touch controller. No OLED response alone is not evidence
of a TFT. When neither responds, the node runs without a screen and <code>board</code>
reports <code>none detected</code>. Touch identification establishes the stock assembly,
not LCD health. A damaged or nonstandard panel can require an override.</p>
<p><code>oled</code> explicitly selects and checks the OLED driver. <code>tft</code> explicitly selects
the TFT driver and reports <code>TFT (forced)</code> rather than claiming detection.
<code>off</code> disables display initialization and reports <code>off</code>, distinct from
<code>none detected</code>. Selections apply immediately and survive reboot in the checked
<code>/display_type</code> file. A failed save leaves the live selection unchanged.</p>
<p><code>board</code> combines the detected radio front end with the live display status,
for example <code>Heltec V4.3 OLED</code>, <code>Heltec V4.2 TFT</code>, or <code>Heltec V4.3 off</code>.
The radio front end identifies the V4.2/V4.3 hardware generation; it is not a
read of a PCB revision register. Use <code>display.mode</code> below for normal screen
sleep/wake policy without changing the selected hardware driver.</p>
<h2 id="set-display-modes-and-timeouts">Set display modes and timeouts</h2>
<p>Companion message sound, vibration, LED, screen and GPIO rules have separate
CLI controls. See the <a href="../notifications/">notification builder and CLI reference</a>,
+7
View File
@@ -3036,6 +3036,13 @@ combined and single-transport names are explicit-build compatibility aliases.
SSD1306 Full Companion builds use <code>set display.rotation 90|180|270</code>; <code>0</code>
restores the board default, so a separate rotated release image is not
recommended.</p>
<p>Newly built ordinary Heltec V4 images combine V4.2/V4.3, OLED, the stock touch
TFT kit, and no screen in one image per role. A qualified image offers saved
<code>display.type auto|oled|tft|off</code> controls; selection applies immediately, and
<code>board</code> reports the detected revision and active display. R8 remains separate.
Older TFT/expansion-kit target names retain their distinct LoRa OTA identities;
use USB or supported WiFi updating when moving to the canonical image. Older
published downloads keep their original behavior. See <a href="../optional_screens/#heltec-v42-v43">optional screens</a>.</p>
<p>New display-capable RAK4631 and RAK3401 images with OLED controller detection
also offer saved <code>display.controller</code> choices: <code>auto</code>, <code>ssd1306</code> or <code>sh1106</code>.
This applies after restart and avoids a custom image when a panel needs an
+38 -5
View File
@@ -2381,6 +2381,17 @@
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#heltec-v42-v43" class="md-nav__link">
<span class="md-ellipsis">
Heltec V4.2 / V4.3
</span>
</a>
</li>
<li class="md-nav__item">
@@ -2438,7 +2449,9 @@
<p>Use the normal display-capable firmware for your exact board and role. When
automatic detection is included, that image starts the supported screen if
it responds, or continues headless if it is absent. There is no screen-presence
setting. Power the board off before attaching or removing an optional screen.</p>
setting on most boards. The unified ordinary Heltec V4 image also offers a
saved display override, described below. Power the board off before attaching
or removing an optional screen.</p>
<p>The <a href="../firmware_picker/">firmware picker</a> describes automatic screen detection
only when the selected application has been verified to contain it. Previously
published firmware retains its original behavior. These additions become
@@ -2511,10 +2524,30 @@ add detection to an older download.</p>
</tr>
</tbody>
</table>
<p>The older V4 TFT expansion configuration is also optional, but its current
recipe has no verified panel readback connection. Detection is not enabled for
that wiring. A touchscreen acknowledgement alone does not establish that the
LCD responds. The V4 R8 TFT and older V4 TFT pin mappings are distinct.</p>
<h2 id="heltec-v42-v43">Heltec V4.2 / V4.3</h2>
<p>New ordinary V4 images combine OLED, the original stock touch TFT expansion
kit, and operation without a screen in one image per role. The OLED probe uses
its own I2C bus; a verified CHSC6xxx touch-controller identity selects the stock
TFT assembly. This identifies the touchscreen assembly, not a working LCD.
With neither display detected, the firmware continues without a screen.</p>
<p><code>get display.type</code> reports the saved choice and active display. Use
<code>set display.type auto|oled|tft|off</code> to change it immediately and save the choice.
<code>auto</code> is the default. <code>off</code> explicitly disables rendering; it is distinct from
an absent or unrecognized screen. <code>board</code> reports the radio front-end revision
and active display, including the off/headless states. V4.2/V4.3 is inferred
from the detected radio front end, rather than reading a PCB revision code.</p>
<p>This change applies to newly built and qualified unified images. Existing
releases retain their compiled OLED/TFT behavior. The picker advertises the
combined image only when its application and source-bound metadata prove that
it includes the new driver. V4.3 OLED detection, live selection and reboot
persistence passed on the Mercerwood test board. Physical TFT detection and
display operation remain unqualified. See the <a href="../test-results/firmware_variant_consolidation/#unified-ordinary-v4-update-2026-10-26">validation record</a>.</p>
<p>The V4 R8 retains its separate hardware image because its memory configuration
and display wiring differ. Older TFT/expansion-kit target names remain explicit
compatibility builds with their original LoRa OTA identity. Moving to the
canonical ordinary V4 image requires a local USB installation or an updater
that accepts the matching application over WiFi. Do not force a different
LoRa OTA target ID. No settings erase is required for display selection.</p>
<p>RAK4631 and RAK3401 images with OLED controller detection support
<code>set display.controller auto</code>, <code>ssd1306</code> or <code>sh1106</code> in all display-enabled
roles. Keep <code>auto</code> for normal use; choose the panel's controller explicitly if
+1 -1
View File
@@ -1 +1 @@
{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"],"fields":{"title":{"boost":1000.0},"text":{"boost":1.0},"tags":{"boost":1000000.0}}},"docs":[{"location":"","title":"Home","text":"<p>View this page on MeshCore Docs.</p>"},{"location":"#meshcore-documentation","title":"MeshCore documentation","text":""},{"location":"#start-here","title":"Start here","text":"<p>Current stable release: 1.18.0.1 USA Cascade. Read what changed, which boards benefit and the known limitations in one place.</p> I want to... Start here See what is new or fixed 1.18.0.1 release notes Download firmware for my board Firmware picker Install an update Update guide Turn a feature on or off Feature controls by role Find a command CLI reference Troubleshoot a device FAQ"},{"location":"#detailed-guides","title":"Detailed guides","text":"<ul> <li> <p>SolarXiao Base/Advanced/MPPT detection and battery controls</p> </li> <li> <p>Feature switches by role and Full Companion features</p> </li> <li>Firmware update guide, easy LoRa OTA, and scripted LoRa OTA</li> <li>CLI commands, availability by build, and radio profiles</li> <li>Private fleet management: signed filtering and secondary-radio commands for a fleet or one node</li> <li>Room history, moderation, and information board: optional persistent chat and local Wi-Fi room access</li> <li>Companion protocol, packet format, and QR codes</li> </ul> <p>The navigation groups the remaining guides under Documentation, including board-specific updates, networking, power, and protocol references.</p>"},{"location":"#tools","title":"Tools","text":"<ul> <li>Firmware picker and USB web console</li> <li>Notification builder and temporary radio test builder</li> <li>Filter policy playground, telemetry decoder, and management report decoder</li> </ul>"},{"location":"#engineering-records","title":"Engineering records","text":"<ul> <li>Test Results - hardware and build evidence, with the tested versions</li> <li>Research - design notes, diagnostics, and historical update-chain studies</li> <li>Old Releases - historical release notes and supporting files</li> </ul> <p>Found a mistake or missing information? Edit the documentation.</p>"},{"location":"WiFi/","title":"WiFi","text":"<p>View this page on MeshCore Docs.</p>"},{"location":"WiFi/#wifi-and-mqtt-by-firmware-type","title":"WiFi and MQTT by Firmware Type","text":"<p>MeshCore itself does not require WiFi or the internet. LoRa packet exchange, repeating, room servers, companions, and sensors can all operate without either. WiFi is added by particular ESP32 firmware targets for one or more of these purposes:</p> <ul> <li>a TCP connection between a WiFi companion and a phone or computer;</li> <li>the WebConfig browser interface;</li> <li>MQTT uplinking from the radio to internet or LAN brokers;</li> <li>WiFi-assisted OTA services on builds that include them;</li> <li>ESP-NOW bridging, which uses the ESP32's 2.4 GHz radio but is not a connection to a WiFi access point.</li> </ul> <p>The firmware role and the build profile are separate choices. USB logging does not itself provide MQTT. MQTT-capable Full Companions include that feature without <code>mqtt</code> in their filename; check the artifact capability manifest. See feature switches by role for the different Companion and infrastructure controls and the USB web console.</p>"},{"location":"WiFi/#quick-reference","title":"Quick reference","text":"Firmware target or role Infrastructure WiFi MQTT What WiFi does <code>*_repeater</code> Build-dependent on ESP32 No FULL builds provide WebConfig, browser OTA, and the TCP 5001 LoRa-OTA seeder while WiFi is active <code>*_repeater_observer_mqtt</code> Yes Yes Uplinks heard and selected transmitted LoRa packets; repeating remains enabled by default <code>*_room_server</code> Build-dependent on ESP32 No FULL builds provide WebConfig, browser OTA, and the TCP 5001 LoRa-OTA seeder while WiFi is active <code>*_room_server_observer_mqtt</code> Yes Yes Runs the room server and uplinks radio traffic <code>*_companion_radio_wifi</code> Yes No Exposes the MeshCore companion protocol on TCP port 5000 <code>*_companion_radio_wifi_mqtt</code> Yes Yes Runs both the TCP companion interface and the MQTT uplink <code>*_companion_radio_full*</code> ESP32, subject to board/transport selection Where compiled on ESP32 Includes supported USB/wireless transports; configure MQTT through WebConfig Dedicated USB, BLE, or serial companion (not Full) No No Uses the transport named by the target instead <code>*_repeater_bridge_espnow</code> Build-dependent on ESP32 No Uses ESP-NOW for its bridge; <code>bridge.format wrapped|raw</code> selects legacy bridge framing or primary-ESP-NOW compatibility; a FULL build also exposes the TCP 5001 LoRa-OTA seeder whenever WiFi is usable RS232 bridge No No Bridges through a serial interface Ethernet repeater/room server No WiFi No Uses wired Ethernet for its role-specific network interface <code>*_sensor</code> Build-dependenLine truncated
{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"],"fields":{"title":{"boost":1000.0},"text":{"boost":1.0},"tags":{"boost":1000000.0}}},"docs":[{"location":"","title":"Home","text":"<p>View this page on MeshCore Docs.</p>"},{"location":"#meshcore-documentation","title":"MeshCore documentation","text":""},{"location":"#start-here","title":"Start here","text":"<p>Current stable release: 1.18.0.1 USA Cascade. Read what changed, which boards benefit and the known limitations in one place.</p> I want to... Start here See what is new or fixed 1.18.0.1 release notes Download firmware for my board Firmware picker Install an update Update guide Turn a feature on or off Feature controls by role Find a command CLI reference Troubleshoot a device FAQ"},{"location":"#detailed-guides","title":"Detailed guides","text":"<ul> <li> <p>SolarXiao Base/Advanced/MPPT detection and battery controls</p> </li> <li> <p>Feature switches by role and Full Companion features</p> </li> <li>Firmware update guide, easy LoRa OTA, and scripted LoRa OTA</li> <li>CLI commands, availability by build, and radio profiles</li> <li>Private fleet management: signed filtering and secondary-radio commands for a fleet or one node</li> <li>Room history, moderation, and information board: optional persistent chat and local Wi-Fi room access</li> <li>Companion protocol, packet format, and QR codes</li> </ul> <p>The navigation groups the remaining guides under Documentation, including board-specific updates, networking, power, and protocol references.</p>"},{"location":"#tools","title":"Tools","text":"<ul> <li>Firmware picker and USB web console</li> <li>Notification builder and temporary radio test builder</li> <li>Filter policy playground, telemetry decoder, and management report decoder</li> </ul>"},{"location":"#engineering-records","title":"Engineering records","text":"<ul> <li>Test Results - hardware and build evidence, with the tested versions</li> <li>Research - design notes, diagnostics, and historical update-chain studies</li> <li>Old Releases - historical release notes and supporting files</li> </ul> <p>Found a mistake or missing information? Edit the documentation.</p>"},{"location":"WiFi/","title":"WiFi","text":"<p>View this page on MeshCore Docs.</p>"},{"location":"WiFi/#wifi-and-mqtt-by-firmware-type","title":"WiFi and MQTT by Firmware Type","text":"<p>MeshCore itself does not require WiFi or the internet. LoRa packet exchange, repeating, room servers, companions, and sensors can all operate without either. WiFi is added by particular ESP32 firmware targets for one or more of these purposes:</p> <ul> <li>a TCP connection between a WiFi companion and a phone or computer;</li> <li>the WebConfig browser interface;</li> <li>MQTT uplinking from the radio to internet or LAN brokers;</li> <li>WiFi-assisted OTA services on builds that include them;</li> <li>ESP-NOW bridging, which uses the ESP32's 2.4 GHz radio but is not a connection to a WiFi access point.</li> </ul> <p>The firmware role and the build profile are separate choices. USB logging does not itself provide MQTT. MQTT-capable Full Companions include that feature without <code>mqtt</code> in their filename; check the artifact capability manifest. See feature switches by role for the different Companion and infrastructure controls and the USB web console.</p>"},{"location":"WiFi/#quick-reference","title":"Quick reference","text":"Firmware target or role Infrastructure WiFi MQTT What WiFi does <code>*_repeater</code> Build-dependent on ESP32 No FULL builds provide WebConfig, browser OTA, and the TCP 5001 LoRa-OTA seeder while WiFi is active <code>*_repeater_observer_mqtt</code> Yes Yes Uplinks heard and selected transmitted LoRa packets; repeating remains enabled by default <code>*_room_server</code> Build-dependent on ESP32 No FULL builds provide WebConfig, browser OTA, and the TCP 5001 LoRa-OTA seeder while WiFi is active <code>*_room_server_observer_mqtt</code> Yes Yes Runs the room server and uplinks radio traffic <code>*_companion_radio_wifi</code> Yes No Exposes the MeshCore companion protocol on TCP port 5000 <code>*_companion_radio_wifi_mqtt</code> Yes Yes Runs both the TCP companion interface and the MQTT uplink <code>*_companion_radio_full*</code> ESP32, subject to board/transport selection Where compiled on ESP32 Includes supported USB/wireless transports; configure MQTT through WebConfig Dedicated USB, BLE, or serial companion (not Full) No No Uses the transport named by the target instead <code>*_repeater_bridge_espnow</code> Build-dependent on ESP32 No Uses ESP-NOW for its bridge; <code>bridge.format wrapped|raw</code> selects legacy bridge framing or primary-ESP-NOW compatibility; a FULL build also exposes the TCP 5001 LoRa-OTA seeder whenever WiFi is usable RS232 bridge No No Bridges through a serial interface Ethernet repeater/room server No WiFi No Uses wired Ethernet for its role-specific network interface <code>*_sensor</code> Build-dependenLine truncated
@@ -2414,6 +2414,17 @@
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#unified-ordinary-v4-update-2026-10-26" class="md-nav__link">
<span class="md-ellipsis">
Unified ordinary V4 update - 2026-10-26
</span>
</a>
</li>
</ul>
@@ -2596,6 +2607,76 @@ The packages were built locally; physical testing of these combinations remains
</ul>
<p>These checks are required before describing the hardware combinations as physically qualified.</p>
<p>The earlier <a href="../../optional_screens/#validation">optional-screen record</a> covers separate RC32 and Tracker smoke packages; those are not part of this ten-profile matrix.</p>
<h2 id="unified-ordinary-v4-update-2026-10-26">Unified ordinary V4 update - 2026-10-26</h2>
<p>New original-V4 builds combine OLED, the stock touch TFT kit and headless
operation. <code>display.type</code> defaults to <code>auto</code>; saved <code>oled</code>, <code>tft</code> and <code>off</code>
overrides apply immediately. <code>board</code> reports the radio front end's V4.2/V4.3
generation and live display selection. R8 retains its separate hardware image.</p>
<p>All five Full packages below passed serialized compilation, application size,
capability-marker and runtime RAM admission checks. Test version:
<code>v1.18.0.2-display-test-a87b2a33</code>, built from the working implementation based
on <code>a87b2a33a</code>. The application hashes distinguish these local test builds.</p>
<table>
<thead>
<tr>
<th>Target</th>
<th style="text-align: right;">Application bytes</th>
<th style="text-align: right;">RAM admission margin (bytes)</th>
<th>SHA-256 prefix</th>
</tr>
</thead>
<tbody>
<tr>
<td>V4 Full Companion</td>
<td style="text-align: right;">2,545,128</td>
<td style="text-align: right;">25,328</td>
<td><code>d90b050b9892</code></td>
</tr>
<tr>
<td>V4 Full Repeater</td>
<td style="text-align: right;">2,140,920</td>
<td style="text-align: right;">3,912</td>
<td><code>9e1bf8b7c31a</code></td>
</tr>
<tr>
<td>V4 Full Room Server</td>
<td style="text-align: right;">2,139,400</td>
<td style="text-align: right;">18,040</td>
<td><code>8d3cddf67659</code></td>
</tr>
<tr>
<td>V4 Full Sensor</td>
<td style="text-align: right;">1,524,472</td>
<td style="text-align: right;">123,112</td>
<td><code>6bd02f499a4a</code></td>
</tr>
<tr>
<td>Legacy TFT Repeater identity</td>
<td style="text-align: right;">1,784,936</td>
<td style="text-align: right;">50,936</td>
<td><code>7c47a7825100</code></td>
</tr>
</tbody>
</table>
<p>The ten focused detection/integration tests pass, including absent and invalid
panels, saved-setting recovery, live switching, clock wrap and headless
Companion notifications/battery checks. They also verify that display sleep
keeps the sensor power rail intact, sensors retain primary I2C, and TFT FSPI
cleanup cannot stop the radio's separate HSPI controller. Shared R8, T-Deck
and OLED regressions pass, as do build-profile and picker/provider checks.</p>
<p>The Mercerwood V4.3 OLED passed automatic detection, live off/auto/oled changes,
off and auto persistence across reboot, accurate <code>board</code> output and USB CLI
responses. Its original display power preferences were retained. Only the
active application was flashed; partitions and stored device data were kept.
The final image also passed a save/logging smoke check: no false missing-file
errors. Native USB needed one additional monitored RTS reset after esptool's
flash/reset handoff before the terminal responded; later application reboots
passed the persistence checks.</p>
<p>Physical TFT identity/readback, visible rendering and sleep/wake still require
the original stock kit. Screen-absent hardware and V4.2 hardware were covered
by software tests, not a physical run. These display checks do not qualify
maximum MQTT/TLS load, radio throughput or sleep current. Existing published
images and LoRa update identities were not changed.</p>