[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6,"_7":8,"_9":10},"actionData","errors","root",{"_154":155,"_156":157},"routes/_app.x.$handle.$name",{"_95":94,"_32":45,"_104":85,"_27":99,"_13":14,"_105":-5,"_11":106,"_107":108,"_109":110,"_111":112,"_113":114,"_20":-5,"_115":-5,"_116":-5,"_117":25,"_118":119,"_120":25,"_121":-5,"_122":-5,"_123":124},"routes/_app.x.$handle.$name.branch.$branch.version.$version.diff",{"_11":12,"_13":14,"_15":16,"_17":-5,"_18":-5},"project",{"_43":44,"_32":45,"_38":46,"_47":-5,"_48":25,"_49":50,"_51":50,"_52":53,"_54":-5,"_18":55,"_56":-5,"_57":25,"_58":-5,"_59":-5,"_60":61,"_62":63,"_64":-5,"_65":-5,"_66":-5,"_67":-5,"_68":69,"_70":69,"_71":72,"_73":72,"_74":72,"_75":69,"_76":69,"_77":78,"_79":80,"_81":82,"_83":25},"version",3,"changes",[19],"aiChatInfo","userId",{"_20":21,"_22":23,"_24":25,"_26":25,"_27":28,"_29":28},"file",{"_30":31,"_32":28,"_33":37,"_35":36,"_38":39,"_40":14,"_41":42,"_24":25},"previous",{"_30":31,"_32":28,"_33":34,"_35":36},"deleted",false,"deletedHere","path","main.ts","latestPath","fileId","f0dcdcd0-a2df-11f1-8a32-1607ee4eb77e","name","fileType","script","content","/**\n * TRMNL Device Liveness Monitor — Val Town CRON val\n * ---------------------------------------------------------------------------\n * Replaces the daily Cowork scheduled task. Detection latency drops from up to\n * ~24 hours to ~15-35 minutes, it costs nothing (96 runs/day against Val Town's\n * 100,000/day free allowance), and the API key lives in an environment variable\n * instead of a task prompt that gets fed into model context on every run.\n *\n * SETUP\n * 1. Create a new val, type = Cron, schedule = every 15 minutes.\n * (15 min is the Val Town FREE-plan minimum. Pro allows 1 min.)\n * 2. Paste this file in.\n * 3. In the val's sidebar, add two environment variables:\n * TRMNL_API_KEY = \n * TRMNL_DEVICES = :,:\n * TRMNL_API_KEY is never printed by this code, never emailed, and does not\n * appear in the source. Val Town's docs: others can see that a variable is\n * used, but not its value.\n * 4. Privacy: private vals require Val Town Pro, so on the free plan this val\n * is PUBLIC and its source is world-readable. That is why device ids and\n * labels live in TRMNL_DEVICES rather than in the code — published source\n * should not describe which rooms of your home have a screen in them, or\n * what hours they are idle. There is no HTTP endpoint to call regardless.\n *\n * WHY THERE IS NO HTTP ENDPOINT HERE\n * Val Town HTTP endpoints are reachable by anyone who knows the URL in EVERY\n * privacy mode — private only hides the code. An HTTP route returning device\n * status would leak a presence signal for the monitored location, and securing\n * it would require a shared token that the caller has to store, which is the\n * exact problem this design exists to avoid. Cron needs no inbound request.\n *\n * ALERT POLICY — this is the part that makes a 15-minute check tolerable.\n * Running 96 times a day must NOT mean 96 emails a day. Email is sent only on\n * a STATE CHANGE (ok -> problem, problem -> ok), plus one re-nag every 24h\n * while a problem persists. State is kept in val-scoped blob storage.\n *\n * WHAT IS VERIFIED vs ASSUMED (read before trusting the sleep logic)\n * VERIFIED against a live HTTP 200 response:\n * - the device array sits under a \"data\" key\n * - devices report sleep_start_time / sleep_end_time as integers\n * - the Device schema contains NO timezone field of any kind\n * ASSUMED, because TRMNL documents neither:\n * - that sleep_start_time / sleep_end_time are MINUTES PAST MIDNIGHT\n * - that they are expressed in the ACCOUNT's timezone (there is no other\n * candidate — the device object carries no timezone)\n * Because both are assumptions, the sleep window can only ever SUPPRESS an\n * alert for a bounded period. See SLEEP_GRACE_HOURS: a device that goes quiet\n * and stays quiet past the longest possible sleep window still alerts. If the\n * assumptions are wrong, the failure mode is a late alert, never a silent one.\n */\n\nimport { email } from \"https://esm.town/v/std/email\";\nimport { blob } from \"https://esm.town/v/std/blob/main.ts\";\n\n// ---------------------------------------------------------------- config ----\n\n/** Timezone the sleep window is interpreted in. Must match the TRMNL account\n * timezone shown at trmnl.com/account, because the device object carries no\n * timezone of its own. Override with the TRMNL_TZ environment variable. */\nconst TZ = Deno.env.get(\"TRMNL_TZ\") ?? \"America/Denver\";\n\n/** Minutes since last ping before a device counts as dead.\n * TRMNL devices commonly refresh every 5 min, so 20 = four missed cycles. */\nconst STALE_MIN = 20;\n\n/** Extra hours beyond the sleep window before a sleeping device alerts anyway.\n * This is the safety net over the two unverified sleep assumptions above. */\nconst SLEEP_GRACE_HOURS = 2;\n\nconst BATTERY_WARN_PCT = 20;\nconst RSSI_WARN_DBM = -75;\n\n/** Re-send a reminder this often while a problem is unresolved. */\nconst RENAG_HOURS = 24;\n\n/** Device ids and labels come from the TRMNL_DEVICES environment variable,\n * formatted \":,:\". Kept out of the source because a\n * free-plan val is public. */\nfunction parseDevices(raw: string): Record {\n const out: Record = {};\n for (const pair of raw.split(\",\").map((x) => x.trim()).filter(Boolean)) {\n const i = pair.indexOf(\":\");\n if (i > 0) out[pair.slice(0, i).trim()] = pair.slice(i + 1).trim();\n }\n return out;\n}\n\nconst STATE_KEY = \"trmnl_liveness_state_v1\";\n\n// ----------------------------------------------------------------- utils ----\n\n/** Minutes past midnight, in TZ. Handles DST because Intl does. */\nfunction minutesOfDayInTz(d: Date, tz: string): number {\n const parts = new Intl.DateTimeFormat(\"en-US\", {\n timeZone: tz,\n hour: \"2-digit\",\n minute: \"2-digit\",\n hour12: false,\n }).formatToParts(d);\n const h = Number(parts.find((p) => p.type === \"hour\")?.value ?? \"0\") % 24;\n const m = Number(parts.find((p) => p.type === \"minute\")?.value ?? \"0\");\n return h * 60 + m;\n}\n\n/** Sleep windows wrap midnight when start > end (e.g. 1320..240). */\nfunction inWindow(start: number, end: number, now: number): boolean {\n return start <= end\n ? (now >= start && now < end)\n : (now >= start || now < end);\n}\n\nfunction windowLengthMin(start: number, end: number): number {\n return start <= end ? end - start : 1440 - start + end;\n}\n\nfunction fmtAge(min: number): string {\n if (min < 60) return `${Math.round(min)}m`;\n const h = Math.floor(min / 60);\n return `${h}h ${Math.round(min - h * 60)}m`;\n}\n\n// ------------------------------------------------------------------ main ----\n\nexport async function trmnlLiveness(_interval: { lastRunAt?: Date }) {\n const now = new Date();\n const problems: string[] = [];\n const notes: string[] = [];\n\n const EXPECTED = parseDevices(Deno.env.get(\"TRMNL_DEVICES\") ?? \"\");\n if (Object.keys(EXPECTED).length === 0) {\n problems.push(\n \"TRMNL_DEVICES is not set on this val, so there is nothing to check. \" +\n 'Set it to \":,:\" in the Environment Variables sidebar.',\n );\n return await settle(now, problems, notes, \"unconfigured\");\n }\n\n const KEY = Deno.env.get(\"TRMNL_API_KEY\");\n if (!KEY) {\n // Deliberately a problem, not a silent no-op: a monitor that quietly does\n // nothing is worse than no monitor, because it looks like coverage.\n problems.push(\n \"TRMNL_API_KEY is not set on this val, so no device check ran at all. \" +\n \"Add it in the val's Environment Variables sidebar.\",\n );\n return await settle(now, problems, notes, \"unconfigured\");\n }\n\n // ---- fetch -------------------------------------------------------------\n let payload: any;\n try {\n const res = await fetch(\"https://trmnl.com/api/devices\", {\n headers: { Authorization: `Bearer ${KEY}` },\n signal: AbortSignal.timeout(20_000),\n });\n if (res.status === 401 || res.status === 403) {\n problems.push(\n `TRMNL API rejected the key (HTTP ${res.status}). If the key was ` +\n `recently regenerated, update TRMNL_API_KEY on this val.`,\n );\n return await settle(now, problems, notes, \"auth\");\n }\n if (!res.ok) {\n problems.push(`TRMNL API returned HTTP ${res.status}.`);\n return await settle(now, problems, notes, `http_${res.status}`);\n }\n payload = await res.json();\n } catch (e) {\n // A network blip should not page you. Record it and let the NEXT run decide;\n // a real outage will still be there in 15 minutes.\n notes.push(`Transient fetch error: ${String(e).slice(0, 200)}`);\n return await settle(now, [], notes, \"fetch_error\", /*transient*/ true);\n }\n\n // Shape was verified as { data: [...] } on 2026-08-28, but stay tolerant.\n const devices: any[] = Array.isArray(payload)\n ? payload\n : Array.isArray(payload?.data)\n ? payload.data\n : [];\n if (!Array.isArray(payload) && !Array.isArray(payload?.data)) {\n notes.push(\n \"Response shape differed from the documented { data: [...] } — \" +\n `top-level keys were: ${\n Object.keys(payload ?? {}).join(\", \") || \"(none)\"\n }`,\n );\n }\n\n const nowMin = minutesOfDayInTz(now, TZ);\n\n for (const [id, label] of Object.entries(EXPECTED)) {\n const d = devices.find((x) => String(x?.id) === id);\n if (!d) {\n problems.push(`${label}: device id ${id} was missing from the response.`);\n continue;\n }\n\n const pingRaw = d.hardware_last_ping_at ?? null;\n if (!pingRaw) {\n problems.push(\n `${label}: hardware_last_ping_at is null — never checked in.`,\n );\n continue;\n }\n\n const ageMin = (now.getTime() - new Date(pingRaw).getTime()) / 60000;\n\n if (ageMin > STALE_MIN) {\n const asleep = d.sleep_mode_enabled === true &&\n Number.isFinite(d.sleep_start_time) &&\n Number.isFinite(d.sleep_end_time) &&\n inWindow(d.sleep_start_time, d.sleep_end_time, nowMin);\n\n const graceMin =\n windowLengthMin(d.sleep_start_time ?? 0, d.sleep_end_time ?? 0) +\n SLEEP_GRACE_HOURS * 60;\n\n if (asleep && ageMin <= graceMin) {\n notes.push(\n `${label}: quiet for ${fmtAge(ageMin)}, but inside its configured ` +\n `sleep window — treated as expected, not flagged. (Sleep-window ` +\n `interpretation is an assumption; see the header.)`,\n );\n } else {\n problems.push(\n `${label}: last ping ${fmtAge(ageMin)} ago` +\n (asleep\n ? ` — this EXCEEDS its sleep window plus ${SLEEP_GRACE_HOURS}h of grace, ` +\n `so it is not just asleep.`\n : `.`) +\n ` Its screen is frozen on a stale quote right now and looks completely normal.`,\n );\n }\n }\n\n if (\n typeof d.percent_charged === \"number\" &&\n d.percent_charged < BATTERY_WARN_PCT\n ) {\n problems.push(`${label}: battery at ${d.percent_charged}%.`);\n }\n if (typeof d.rssi === \"number\" && d.rssi < RSSI_WARN_DBM) {\n problems.push(\n `${label}: Wi-Fi RSSI ${d.rssi} dBm (weaker than ${RSSI_WARN_DBM}) — ` +\n `marginal signal, a known precursor to dropouts on this setup.`,\n );\n }\n }\n\n return await settle(now, problems, notes, \"checked\");\n}\n\n// --------------------------------------------------- state + notification ----\n\nasync function settle(\n now: Date,\n problems: string[],\n notes: string[],\n kind: string,\n transient = false,\n) {\n const status = problems.length ? \"bad\" : \"ok\";\n const prev = (await blob.getJSON(STATE_KEY).catch(() => null)) as any ?? {\n status: \"ok\",\n since: now.toISOString(),\n lastEmailAt: null,\n kind: \"init\",\n };\n\n // A transient fetch error never changes state and never emails. If the\n // problem is real it will still be here on the next run, 15 minutes later.\n if (transient) {\n await blob.setJSON(STATE_KEY, {\n ...prev,\n lastNote: notes.join(\" | \"),\n lastSeenAt: now.toISOString(),\n });\n return { status: prev.status, emailed: false, transient: true, notes };\n }\n\n const changed = status !== prev.status;\n const lastEmail = prev.lastEmailAt ? new Date(prev.lastEmailAt).getTime() : 0;\n const dueRenag = status === \"bad\" &&\n now.getTime() - lastEmail > RENAG_HOURS * 3600_000;\n\n // FIRST RUN EVER: send one confirmation even if everything is fine. Without\n // this the val is silent on a healthy system, which is indistinguishable from\n // a val that is not running at all — and an unverifiable monitor is the exact\n // failure this whole exercise exists to fix.\n const firstRun = prev.kind === \"init\";\n if (firstRun && status === \"ok\") {\n await email({\n subject: \"TRMNL monitor is live\",\n text: [\n \"The Val Town device liveness monitor ran for the first time and both\",\n \"devices are checking in normally.\",\n \"\",\n ...notes.map((n) => ` - ${n}`),\n \"\",\n \"From here it stays quiet. You will only hear from it when something\",\n \"changes: a device stops checking in, comes back, battery drops below\",\n `${BATTERY_WARN_PCT}%, or Wi-Fi RSSI drops below ${RSSI_WARN_DBM} dBm.`,\n `While a problem is unresolved it re-sends every ${RENAG_HOURS}h.`,\n \"\",\n `Checked ${now.toISOString()}. Runs every 15 minutes.`,\n ].join(\"\\n\"),\n });\n await blob.setJSON(STATE_KEY, {\n status,\n since: now.toISOString(),\n lastEmailAt: now.toISOString(),\n lastSeenAt: now.toISOString(),\n kind,\n lastProblems: [],\n });\n return { status, emailed: true, firstRun: true, notes };\n }\n\n let emailed = false;\n if (changed || dueRenag) {\n const downFor = status === \"bad\" && !changed\n ? ` (unresolved for ${\n fmtAge((now.getTime() - new Date(prev.since).getTime()) / 60000)\n })`\n : \"\";\n\n const subject = status === \"bad\"\n ? `TRMNL: device problem${downFor}`\n : `TRMNL: back to normal`;\n\n const body = [\n status === \"bad\"\n ? \"PROBLEM\"\n : \"RESOLVED — all devices are checking in again.\",\n \"\",\n ...problems.map((p) => ` • ${p}`),\n problems.length ? \"\" : null,\n status === \"bad\" ? \"What to try, in order:\" : null,\n status === \"bad\"\n ? \" 1. Tap the middle of the touch bar (it may just be asleep — free to try).\"\n : null,\n status === \"bad\"\n ? \" 2. Soft reset: invert the dock, circular motion near the bottom-left of the back.\"\n : null,\n status === \"bad\"\n ? \" 3. Charge it: dock on the centre of the TRMNL logo.\"\n : null,\n status === \"bad\"\n ? \" 4. Check the dock pins / try the other dock orientation.\"\n : null,\n status === \"bad\"\n ? \" 5. Re-pair Wi-Fi: hold BOTH ends of the touch bar until the screen blinks, then hold the middle.\"\n : null,\n status === \"bad\"\n ? \" If this device drops repeatedly, pair it to 2.4 GHz rather than 5 GHz.\"\n : null,\n status === \"bad\" ? \"\" : null,\n notes.length ? \"Notes:\" : null,\n ...notes.map((n) => ` - ${n}`),\n \"\",\n `Checked ${now.toISOString()} — TRMNL Device Liveness (Val Town cron, every 15 min).`,\n `Full runbook: section 17 of \"TRMNL Quote Display - System Log and Maintenance Guide.md\".`,\n ].filter((l) => l !== null).join(\"\\n\");\n\n await email({ subject, text: body });\n emailed = true;\n }\n\n await blob.setJSON(STATE_KEY, {\n status,\n since: changed ? now.toISOString() : prev.since,\n lastEmailAt: emailed ? now.toISOString() : prev.lastEmailAt,\n lastSeenAt: now.toISOString(),\n kind,\n lastProblems: problems,\n });\n\n return { status, emailed, problems, notes };\n}","interval","createdAt",["D",1787922345267],"branchVersion","branchId","89a1c79c-a287-4436-ba23-147afbd718e8","id","1773c256-a0c3-4081-8f85-d76d74386ee4","trmnldevicemonitor",["D",1787921812710],"deletedAt","legacyEnvVars","privacy","public","httpPrivacy","description","Cron: TRMNL device liveness, emails on state change","imageUrl","a5b8c2ff-3219-464a-b112-3d77ca9951e8","pinnedFileId","pinPreview","pinMigrated","screenshotVersion","likeCount",0,"orgId","019ef991-b184-72ce-82ef-299400125b59","tursoName","tursoHostname","tursoMeasuredAt","pinned","userPerm","r","valPerm","blobPerm","rw","emailPerm","sqlitePerm","projectPerm","telemetryPerm","user",{"_95":94,"_103":99},"org",{"_95":94,"_96":97,"_98":99,"_18":55,"_100":101,"_102":25},"branch",{"_13":84,"_32":85,"_43":42,"_86":44,"_87":-5,"_88":-5,"_89":-5,"_90":-5,"_91":-5,"_92":45,"_93":94},"isOwned",11,"main","projectId","forkedBranchId","forkedBranchVersion","forkedProjectPrivacy","forkedProjectId","forkedProjectOrgId","projectName","userHandle","buddyd","handle","displayName","Buddy Dillenberg","avatar","","tier","free","canRestrictVals","profileImageUrl","branchName","adoptOrgId",{"_43":44,"_32":45,"_38":150,"_47":-5,"_48":25,"_49":50,"_51":50,"_52":53,"_54":-5,"_18":55,"_56":-5,"_57":25,"_58":-5,"_59":-5,"_60":61,"_62":63,"_64":-5,"_65":-5,"_66":-5,"_67":-5,"_68":69,"_70":69,"_71":72,"_73":72,"_74":72,"_75":69,"_76":69,"_77":151,"_79":152,"_81":153,"_83":25},"tree",[145],"files",[145],"counts",{"_133":61,"_134":135,"_136":61,"_137":138,"_139":140},"contents",[125],"upstreamProject","upstreamBranch","emptyEnvVars","flags",[],"hasHttpFiles","grants","orgs","customDomains",{},{"_43":126,"_32":28,"_30":31,"_127":-5,"_41":42,"_40":14,"_128":25,"_38":129,"_13":130,"_33":37,"_35":36,"_24":25,"_131":-5,"_27":132},"08350dc9-234d-4881-a592-ff7fb4e80fd5","parentId","latest",["D",1787922345267],2,"label",[28],"pulls","branches",1,"forks","envVars",{"_141":143,"_144":61},"connections",{"_141":61,"_142":61},"count","unfilledCount",4,"emptyCount",{"_43":126,"_32":28,"_30":31,"_127":-5,"_41":42,"_40":14,"_128":25,"_38":146,"_13":130,"_33":37,"_35":36,"_24":25,"_131":-5,"_147":148,"_27":149},["D",1787922345267],"children",[],[28],["D",1787921812710],{"_95":94,"_103":99},{"_95":94,"_96":97,"_98":99,"_18":55,"_100":101,"_102":25},{"_13":84,"_32":85,"_43":42,"_86":44,"_87":-5,"_88":-5,"_89":-5,"_90":-5,"_91":-5,"_92":45,"_93":94},"ctx",{"_77":-5,"_122":187,"_188":189,"_190":191,"_192":25,"_193":25,"_194":25,"_195":196,"_197":-5,"_198":-7,"_199":-7,"_200":61,"_201":25,"_202":25,"_203":-5,"_204":25,"_205":25,"_206":25,"_207":-5},"ENV",{"_158":159,"_160":161,"_162":85,"_163":164,"_165":166,"_167":168,"_169":170,"_171":172,"_173":174,"_175":176,"_177":178,"_179":180,"_181":182,"_183":184,"_185":186},"REACT_APP_SENTRY_DSN","https://586020d86f05489db63a554690acf1e9@o1398359.ingest.sentry.io/6724499","RENDER_GIT_COMMIT","e87eb04e707cf64e7e532c8e8ec395f209e17f15","RENDER_GIT_BRANCH","POSTHOG_API_TOKEN","phc_nmoyuAkStEZuUp69rYlg1DZgrIt19Gx0Y4Hwf8tGgJP","POSTHOG_API_HOST","https://wart.val.town","WEB_API_TEMPLATE","https://{val}.web.val.run","APP_URL","https://www.val.town","MODULE_URL","https://esm.town","VANITY_WEB_API_TEMPLATE","https://{label}.val.run/","DENOLS_URL","https://lsp.val.town","NODE_ENV","production","CLOUDFLARE_TURNSTILE_SITE_KEY","0x4AAAAAACtaIZJH7s9rBMZ6","GOOGLE_CLIENT_ID","875989696899-jtsqkhlbdv5jrlsk8631p7ipjg3c6o62.apps.googleusercontent.com","STRIPE_PUBLISHABLE_KEY","pk_live_51N2zvWEpZTTLipIkVEwXrUG9AT0yeOOEYxszarZT1jpsZV58Ly6wlg3SltZpHN26CUalOBmUSY7adQRQiSkCZz2500qSXNkf8Y","API_URL","https://api.val.town",[],"preferencesKeybindings","default","preferencesTheme","light","preferencesFixers","preferencesCopilot","preferencesSelectionAi","preferencesCloseBrackets",true,"preferencesChatPanelState","preferencesDprint","preferencesDenofmt","notificationCount","flagDenols","isBusinessOrgMember","businessOrgHandle","isBusinessOrgAdmin","isHigherTownieTier","navCollapsed","currentOrgId"]

Diff · v3