Make T114 screen detection the default firmware and picker choice

This commit is contained in:
mikecarper committed 2026-10-18 16:20:27 -07:00
1 parent 864d0cacff
commit 1ce3f0cdd7
22 files changed
+1686 -124

No files matched your search

+144 -15
View File
@@ -252,7 +252,27 @@
return release.published_at || release.created_at || "";
}
function selectReleaseSet(releases) {
function isT114PreviewTag(tag) {
return /^heltec-t114-v\d+(?:\.\d+){2,3}\.preview[1-9]\d*$/.test(tag || "");
}
function controlsForRelease(controlData, tag) {
if (!controlData) return null;
if ((controlData.releaseTag || controlData.familyTag) === tag) return controlData;
return (Array.isArray(controlData.supplementalReleases) ? controlData.supplementalReleases : [])
.find(function (entry) { return entry && entry.releaseTag === tag; }) || null;
}
function t114PreviewControls(controlData, tag) {
const entry = controlsForRelease(controlData, tag);
if (!isT114PreviewTag(tag) || !entry || !/^[0-9a-f]{40}$/.test(entry.source || "")) return null;
const family = tag.slice("heltec-t114-".length);
const hash = String(entry.familyTag || "").slice(family.length + 1);
return entry.familyTag === family + "-" + hash && /^[0-9a-f]{8,40}$/.test(hash) &&
entry.source.startsWith(hash) && entry.profiles ? entry : null;
}
function selectReleaseSet(releases, controlData) {
const publicReleases = (Array.isArray(releases) ? releases : []).filter(
function (release) {
return release && !release.draft && typeof release.tag_name === "string";
@@ -263,10 +283,14 @@
}).sort(function (a, b) {
return releaseDate(b).localeCompare(releaseDate(a));
});
const main = mainReleases[0];
const supplements = publicReleases.filter(function (release) {
return Boolean(t114PreviewControls(controlData, release.tag_name));
}).sort(function (a, b) { return releaseDate(b).localeCompare(releaseDate(a)); });
const main = mainReleases[0] || supplements[0];
if (!main) return null;
const familyTag = main.tag_name;
const mainSupplement = t114PreviewControls(controlData, main.tag_name);
const familyTag = mainSupplement ? mainSupplement.familyTag : main.tag_name;
const acceptedTags = new Set(RELEASE_PAGE_PREFIXES.map(function (prefix) {
return prefix + familyTag;
}));
@@ -276,7 +300,7 @@
const chunkTag = new RegExp("^(?:" + chunkGroups.map(escapeRegExp).join("|") +
")-(?:[2-9]|[1-9][0-9]+)-" + escapeRegExp(familyTag) + "$");
const familyReleases = publicReleases.filter(function (release) {
return acceptedTags.has(release.tag_name) || chunkTag.test(release.tag_name);
return acceptedTags.has(release.tag_name) || chunkTag.test(release.tag_name) || supplements.includes(release);
}).sort(function (a, b) {
return releaseDate(b).localeCompare(releaseDate(a));
});
@@ -287,6 +311,10 @@
url: isSafeGithubUrl(main.html_url) ? main.html_url : "",
prerelease: Boolean(main.prerelease),
releases: familyReleases,
supplementalReleases: supplements.map(function (release) {
const entry = t114PreviewControls(controlData, release.tag_name);
return { releaseTag: release.tag_name, familyTag: entry.familyTag, source: entry.source };
}),
};
}
@@ -309,6 +337,12 @@
? release.html_url
: "",
publishedAt: releaseDate(release),
familyTag: ((releaseSet.supplementalReleases || []).find(function (entry) {
return entry.releaseTag === release.tag_name;
}) || {}).familyTag || releaseSet.familyTag,
t114Preview: (releaseSet.supplementalReleases || []).some(function (entry) {
return entry.releaseTag === release.tag_name;
}),
});
}
);
@@ -686,6 +720,57 @@
}));
}
function t114AutoDisplayProfile(profile) {
const controls = profile && profile.controls;
return Boolean(controls && controls.platform === "NRF52_PLATFORM" &&
controls.display === true && controls.displayAuto === true && controls.displayController === "st7789" &&
/^[0-9a-f]{40}$/.test(controls.displaySource || "") &&
/^heltec_t114_/i.test(profile.target || "") &&
Array.isArray(profile.files) && profile.files.length > 0 && profile.files.every(function (file) {
const hash = String(file.name || "").match(/-([0-9a-f]{8,40})\.(?:hex|uf2|zip)$/i);
return hash && controls.displaySource.startsWith(hash[1].toLowerCase());
}));
}
function t114HeadlessModemProfile(profile) {
return Boolean(profile && profile.role === "kiss" && profile.controls &&
profile.controls.platform === "NRF52_PLATFORM" && profile.controls.display === false &&
/^[0-9a-f]{40}$/.test(profile.controlsSource || "") && profile.files.length > 0 &&
profile.files.every(function (file) {
const hash = file.name.match(/-([0-9a-f]{8,40})\.(?:hex|uf2|zip)$/i);
return hash && profile.controlsSource.startsWith(hash[1].toLowerCase());
}));
}
function omitT114DisplayDuplicates(profiles) {
const families = new Map();
function role(profile) { return profile.role || parseTargetProfile(profile.target).role; }
function family(profile) { return profile.releaseFamily || profile.files[0].familyTag || ""; }
function qualified(profile) {
return /^heltec_t114_/i.test(profile.target || "") && !/_without_display_/i.test(profile.target) &&
(t114AutoDisplayProfile(profile) || t114HeadlessModemProfile(profile));
}
(profiles || []).forEach(function (profile) {
if (!qualified(profile)) return;
const key = role(profile);
const previous = families.get(key);
const date = String(profile.files[0].publishedAt || "");
const previousDate = previous && String(previous.files[0].publishedAt || "");
if (!previous || date > previousDate ||
(date === previousDate && profile.t114Preview && !previous.t114Preview)) {
families.set(key, profile);
}
});
return (profiles || []).filter(function (profile) {
if (!/^heltec_t114_/i.test(profile.target || "")) return true;
const replacement = families.get(role(profile));
// Recommend the newest qualified family for this role, including its
// real sensor/OTA choices. Historical screen-assumed and headless
// policies stay in raw rows, never renamed into a new OTA identity.
return !replacement || qualified(profile) && family(profile) === family(replacement);
});
}
function hardwareChoiceLabel(field, value, profiles, family) {
const matches = (profiles || []).filter(function (profile) {
return profile[field] === value;
@@ -696,6 +781,8 @@
})) {
return "Station G3 ESP32 (automatic slot detection)";
}
if (String(value).toLowerCase() === "heltec_t114" && matches.length > 0 &&
matches.every(t114AutoDisplayProfile)) return "Heltec T114 (automatic screen detection)";
return field === "hardware" && family
? humanizeHardwareVariant(value, family) : humanizeHardware(value);
}
@@ -971,25 +1058,27 @@
}
function buildCatalog(releases, controlData) {
const releaseSet = selectReleaseSet(releases);
const releaseSet = selectReleaseSet(releases, controlData);
if (!releaseSet) {
return { releaseSet: null, rows: [], profiles: [] };
}
const rows = flattenReleaseAssets(releaseSet);
const firmwareRows = rows.map(function (row) {
return parseFirmwareAsset(row, releaseSet.familyTag);
return parseFirmwareAsset(row, row.familyTag);
}).filter(Boolean);
const grouped = new Map();
firmwareRows.forEach(function (file) {
let profile = grouped.get(file.target);
const key = file.familyTag + ":" + file.target;
let profile = grouped.get(key);
if (!profile) {
profile = Object.assign(parseTargetProfile(file.target), {
files: [],
otaPackaged: false,
releaseFamily: releaseSet.familyTag,
releaseFamily: file.familyTag,
t114Preview: file.t114Preview,
});
grouped.set(file.target, profile);
grouped.set(key, profile);
}
profile.files.push(file);
profile.otaPackaged = profile.otaPackaged || file.otaPackaged;
@@ -1004,8 +1093,25 @@
profile.files.sort(function (a, b) {
return a.name.localeCompare(b.name);
});
if (profile.t114Preview) {
const metadata = controlsForRelease(controlData, profile.files[0].releaseTag);
profile.controls = metadata && metadata.profiles[profile.target];
profile.controlsSource = metadata && metadata.source;
if (profile.controls) applyReleaseRuntimeCapabilities(profile, profile.controls);
}
return profile;
}).filter(function (profile) {
if (profile.t114Preview) {
const metadata = controlsForRelease(controlData, profile.files[0].releaseTag);
const hashesMatch = metadata && profile.files.every(function (file) {
const hash = file.name.match(/-([0-9a-f]{8,40})\.(?:hex|uf2|zip)$/i);
return hash && metadata.source.startsWith(hash[1].toLowerCase());
});
if (!hashesMatch || String(profile.hardware).toLowerCase() !== "heltec_t114" ||
!profile.controls || profile.controls.platform !== "NRF52_PLATFORM" ||
!(t114AutoDisplayProfile(profile) && profile.controls.displaySource === metadata.source ||
profile.role === "kiss" && profile.controls.display === false)) return false;
}
return !isHiddenLegacyProfile(profile);
});
const profiles = omitLegacyObserverCompatibilityProfiles(
@@ -1029,12 +1135,14 @@
return profile.hardware;
})));
profiles.forEach(function (profile) {
if (controlData && controlData.familyTag === releaseSet.familyTag &&
controlData.profiles && controlData.profiles[profile.target]) {
profile.controls = controlData.profiles[profile.target];
const metadata = profile.t114Preview ? controlsForRelease(controlData, profile.files[0].releaseTag) : controlData;
if (metadata && metadata.familyTag === profile.releaseFamily &&
metadata.profiles && metadata.profiles[profile.target]) {
profile.controls = metadata.profiles[profile.target];
profile.controlsSource = metadata.source;
applyReleaseRuntimeCapabilities(profile, profile.controls);
profile.migrationPackage = migrationPackageForProfile(
profile, controlData.partitionMigrations
profile, metadata.partitionMigrations
);
profile.migrationAsset = migrationAssetForProfile(profile, rows);
if (isFullCompanion(profile) && profile.controls.mqtt &&
@@ -1078,10 +1186,14 @@
return {
releaseSet: releaseSet,
rows: firmwareRows,
rows: firmwareRows.filter(function (file) {
return !file.t114Preview || profiles.some(function (profile) {
return profile.t114Preview && profile.files.includes(file);
});
}),
// Recommendation filters retain original files and target identities in
// the raw catalog, including when a qualified successor replaces them.
profiles: omitReplacedQspiProfiles(omitStationG3SlotDuplicates(profiles)),
profiles: omitT114DisplayDuplicates(omitReplacedQspiProfiles(omitStationG3SlotDuplicates(profiles))),
};
}
@@ -1394,6 +1506,17 @@
FACET_FIELDS.forEach(function (field) {
requested[field] = params.get(field) || "";
});
if (!profiles.some(function (profile) {
return String(profile.hardware).toLowerCase() === "heltec_t114_without_display" &&
(!requested.role || profile.role === requested.role);
}) && profiles.some(function (profile) {
return String(profile.hardware).toLowerCase() === "heltec_t114" && t114AutoDisplayProfile(profile) &&
(!requested.role || profile.role === requested.role);
})) {
["hardware", "hardwareFamily"].forEach(function (field) {
if (String(requested[field]).toLowerCase() === "heltec_t114_without_display") requested[field] = "Heltec_t114";
});
}
if (!profiles.some(function (profile) {
return profile.hardware === "Station_G3_ESP32_r2" &&
(!requested.role || profile.role === requested.role);
@@ -1632,6 +1755,10 @@
const target = profile.target;
const info = profile.controls || {};
const notes = [];
if (t114AutoDisplayProfile(profile)) {
notes.push("One T114 image detects the supported ST7789 screen at startup and also runs without a screen.");
notes.push("Switching from an older without_display image requires a local USB update; do not use a different target's LoRa OTA package. Keep your existing identity and settings; no erase is required.");
}
if (identity.hardware === "Station_G3_ESP32" && stationG3SharedSlotProfile(profile)) {
notes.push("Automatically selects physical radio slot 1 or 2. Use this same image for either slot.");
}
@@ -2756,6 +2883,8 @@
omitLegacyObserverCompatibilityProfiles:
omitLegacyObserverCompatibilityProfiles,
omitStationG3SlotDuplicates: omitStationG3SlotDuplicates,
t114AutoDisplayProfile: t114AutoDisplayProfile,
omitT114DisplayDuplicates: omitT114DisplayDuplicates,
omitTransportsReplacedByDualCdcFull:
omitTransportsReplacedByFull,
omitNrf52TransportsReplacedByFull:
+5
View File
@@ -147,6 +147,11 @@
## What the choices mean
New **Heltec T114** images detect the optional screen automatically, so the
same firmware works with or without it. Choose the board and firmware role;
there is no screen option for an automatic-detection image. See the
[T114 update guide](heltec_t114.md) when moving from an older screenless target.
Pick the choices in any order. The controls stay limited to compatible
firmware combinations that were actually built in the current release set.
The result count stays visible while you scroll through the filters on a phone.
+4
View File
@@ -14,6 +14,10 @@ not require rebuilding it. USB remains the normal way to update the Companion
itself. WiFi/Bluetooth updates are optional, and Full does not install LoRa
MOTA packages on itself.
New **Heltec T114** Full images automatically detect the optional screen and
also run without it. Choose **Heltec T114** in the firmware picker for either
board configuration; see the [T114 update guide](heltec_t114.md).
The Wireless Paper Full memory-sharing update keeps 350 contacts and 256
queued messages normally. During an mOTA session, 128 message slots are
available while the other half holds its workspace. If more than 128 unread
+37
View File
@@ -0,0 +1,37 @@
<!-- meshcore-hosted-doc-link:start -->
<p class="meshcore-hosted-doc-link"><a href="https://mikecarper.github.io/MeshCore/heltec_t114/">View this page on MeshCore Docs</a>.</p>
<!-- meshcore-hosted-doc-link:end -->
# Heltec T114 screen detection
Choose **Heltec T114** and your firmware role in the [firmware picker](firmware_picker.md).
New T114 images with automatic screen detection work on boards with or without
the optional stock 1.14-inch screen. There is no separate screen selection.
For Companion, use the Full image for USB and Bluetooth support together.
The KISS modem role remains headless.
At startup, the firmware checks whether the screen responds before starting
the display. The backlight stays off during the check. If no screen responds,
the display stays powered off and the node continues without a screen.
The selected role's supported connections and radio functions continue to work
normally.
A detected screen uses the existing display settings and button wake behavior.
Detection does not reset saved screen timeouts, power-saving preferences,
identity, or radio settings. To add or remove the screen, power the board off
first, then restart it after changing the hardware.
## Updating an older T114
Use USB when moving from an older `Heltec_t114_without_display` firmware target
to the canonical `Heltec_t114` target. The old and new target names have
different LoRa update identities; a package built for one is not an update for
the other. Follow the normal update procedure and preserve your settings;
screen detection does not require a factory reset or a new bootloader.
Previously published firmware remains unchanged. The picker identifies
automatic detection from the selected release's verified firmware metadata;
an old display-enabled image does not gain detection from its filename.
See the [implementation and validation record](test-results/heltec_t114_display_detection.md)
for the startup checks and hardware-testing boundary.
@@ -0,0 +1,56 @@
<!-- meshcore-hosted-doc-link:start -->
<p class="meshcore-hosted-doc-link"><a href="https://mikecarper.github.io/MeshCore/test-results/heltec_t114_display_detection/">View this page on MeshCore Docs</a>.</p>
<!-- meshcore-hosted-doc-link:end -->
# Heltec T114 automatic screen detection
The canonical T114 firmware now includes the optional ST7789 screen driver and
checks for the stock screen at boot. Screenless boards use the same firmware.
Legacy `without_display` build names remain compatibility aliases; automatic
release selection uses the canonical targets.
## Hardware basis
Heltec's [stock panel specification](https://resource.heltec.cn/download/Mesh_Node_T114/1.14inch%20LH114T-IF03%20VER%20C.pdf)
identifies the controller as ST7789V2 and describes SDA as an SPI input/output
pin. The existing T114 wiring supports register reads over this shared data
line; a separate MISO wire is unnecessary.
The [Sitronix controller specification](https://files.waveshare.com/wiki/common/ST7789V2.pdf)
documents the read-ID command and serial turnaround on pages 58–64 and 167,
and reset recovery on pages 48–49. Its ID bytes are programmable, so detection
does not require a single guessed factory ID.
## Expected behavior
- The backlight stays off during a bounded boot probe, before framebuffer
allocation and display SPI startup.
- Consistent ID responses with both data-line pull directions distinguish a
responding panel from floating, stuck, or unstable inputs.
- An absent panel or failed display initialization leaves display power off.
Later drawing and wake requests cannot start an absent panel.
- Companion button events remain safe without a display. Notification
acknowledgement, buzzer toggling and early-boot CLI rescue remain available;
visual navigation is skipped when there is no display.
- A detected panel retains normal rendering, sleep, wake, and display settings.
- Detection is specific to the T114 automatic-display recipe. Other boards
using the shared ST7789 driver retain their existing behavior.
- Picker consolidation requires evidence from the exact published application.
Historical releases retain their original screen behavior and update IDs.
## Validation
| Check | Result |
| --- | --- |
| Native probe, GPIO, headless and wake regressions | PASS, 4 methods with ASan/UBSan; late-turnaround, reset-delay and floating-line negative controls |
| Resolved recipe and compatibility-alias checks | PASS, 5 methods; actual PlatformIO configuration also confirms all 5 legacy aliases match their canonical targets |
| Companion headless buttons and related navigation, reader, pairing, startup and deadline suites | PASS, 55 methods, including native headless fault regression and 4 input/reader configurations |
| Picker and release-selection regressions | PASS, 78 Python methods and 3 Node suites; old assets, scoped previews, newest-role defaults and unavailable legacy choices covered |
| T114 firmware and package checks | Pending |
| Hosted documentation links | PASS, 7 methods |
| Physical T114 with and without a screen | Not performed |
Native tests simulate controller replies and GPIO state; they do not establish
physical detection reliability. Before calling the hardware qualified, test
cold USB and battery boots with a stock screen and with no screen, then verify
screen sleep/wake, Bluetooth/USB connections, and normal radio receive/transmit.