feat: over-the-air firmware updates

README.md

@@ -14,6 +14,7 @@
 - 🧠 **Native MCP server** — read telemetry and control hardware from an AI assistant, on devices you are not physically next to. Owner-gated and off by default; see [AI assistants (MCP)](#ai-assistants-mcp).
 - 👥 **Multi-user** — owner / admin / member roles, email invites, and social sign-in (Google, GitHub).
 - 📝 **Audit log** — every privileged action recorded and paginated in the UI.
+- 🔧 **Over-the-air updates** — compile with your own toolchain, upload the image, assign it to a board; it pulls the update on its next check.
 
 ## Quick start
 
@@ -36,6 +37,18 @@
      -H "Authorization: Bearer $NODRIX_TOKEN"
    ```
 
+## Updating hardware over the air
+
+Compile with the toolchain you already use, upload the image, and any board in the project can take it on its next check — no USB, no cable, no physical access.
+
+1. **Version the sketch.** `Nodrix.setFirmwareVersion("1.2.0")` — the board reports this back, and it is how nodrix knows the update landed. Needs the [Nodrix library](https://github.com/decoded-cipher/nodrix-sdk) at 0.2.0 or newer.
+2. **Compile.** Arduino IDE: **Sketch → Export Compiled Binary**, then take `<sketch>.ino.bin` from `build/<board>/`. `arduino-cli compile --output-dir build` and PlatformIO's `.pio/build/<env>/firmware.bin` work the same way. Upload the app image, not `.ino.merged.bin` or `.ino.bootloader.bin` — nodrix rejects those, since a board flashed with one over the air would not boot.
+3. **Upload** it on **Devices → Firmware** with the same version string, then **assign** it to a board on **Devices**.
+
+A board on the control socket is told immediately; one on HTTP finds it at its next check or on reboot. The board reports the new version when it comes back up, which is what marks the update done. If it keeps pulling the image without ever reporting the new version — nearly always the version in the sketch not matching the one on the upload — nodrix stops offering it after a few attempts and says so, instead of leaving the board reinstalling forever. Assigning the firmware again clears that and retries.
+
+The first flash of a board is still over USB, with the Arduino IDE or `esptool`, and it needs a partition scheme with OTA slots (the ESP32 default has them). Every image you ship over the air has to include the nodrix SDK, or the board will have no way to receive the next one.
+
 ## AI assistants (MCP)
 
 nodrix ships a native [Model Context Protocol](https://modelcontextprotocol.io) server, so an assistant can read a project's telemetry and — once you allow it — act on the hardware. Because devices report to your deployment rather than to your laptop, the board does not need to be plugged into the machine running the assistant; it can be in another building.

deploy/wrangler.toml

@@ -1,7 +1,8 @@
-# nodrix deploy carrier. The Deploy to Cloudflare button clones only this
-# subdir; the build command pulls the real source from upstream over it. Don't
-# edit by hand — manage the deployment from the Cloudflare dashboard. Keep the
-# bindings in sync with the repo-root wrangler.toml.
+# nodrix deploy carrier. The Deploy to Cloudflare button clones only this subdir;
+# the build command pulls the real source from upstream over it and rebuilds the
+# deployment's wrangler.toml from this file, keeping only its Worker name,
+# account, routes, resource IDs and vars. Everything else here reaches every
+# existing deployment on its next build — keep it in sync with the root config.
 name = "nodrix"
 main = "worker/src/index.ts"
 compatibility_date = "2025-05-01"

package.json

@@ -1,7 +1,7 @@
 {
   "name": "nodrix",
   "private": true,
-  "version": "1.0.1",
+  "version": "1.1.0",
   "type": "module",
   "workspaces": [
     "worker",

scripts/build-from-upstream.sh

@@ -9,9 +9,11 @@
 # source of truth — meaning code changes in upstream never reach them. With
 # this script, every deploy:
 #
-#   1. Preserves the user's wrangler.toml (which has their resource IDs,
-#      filled by the Deploy button on day 1 and never changed since).
-#   2. Replaces every other file with the upstream source's contents.
+#   1. Replaces every file with the upstream source's contents.
+#   2. Rebuilds wrangler.toml from upstream's carrier template, keeping only the
+#      deployment's identity (Worker name, account, routes, resource IDs, vars).
+#      Keeping the whole file instead froze the topology at day 1, so a binding
+#      or flag added upstream never reached anyone who had already deployed.
 #   3. Runs upstream's build pipeline.
 #
 # Result: the user's clone is functionally a config carrier. Code = upstream.
@@ -31,6 +33,7 @@ UPSTREAM_REPO="${NODRIX_UPSTREAM_REPO:-decoded-cipher/nodrix}"
 DEPLOY_CHANNEL="${NODRIX_DEPLOY_CHANNEL:-release}"
 UPSTREAM_DIR="/tmp/nodrix-upstream"
 WRANGLER_BACKUP="/tmp/nodrix-wrangler.toml"
+WRANGLER_MERGED="/tmp/nodrix-wrangler.merged.toml"
 
 if [ -z "${WORKERS_CI_COMMIT_SHA:-}" ]; then
   echo "[build-from-upstream] not in Workers Builds CI — running local build chain"
@@ -43,7 +46,7 @@ fi
 
 echo "[build-from-upstream] CI build — pulling upstream ${UPSTREAM_REPO} (${DEPLOY_CHANNEL} channel)"
 
-# 1. Preserve user's wrangler.toml.
+# 1. Save the deployment's wrangler.toml; step 4 merges it back.
 if [ ! -f wrangler.toml ]; then
   echo "[build-from-upstream] no wrangler.toml in cwd — refusing to proceed" >&2
   exit 1
@@ -114,8 +117,17 @@ for dir in web worker scripts; do
     done
 done
 
-# 4. Restore user's wrangler.toml in case upstream had its own (which it does).
-cp "${WRANGLER_BACKUP}" wrangler.toml
+# 4. Rebuild wrangler.toml. This script comes from master but the clone is the
+#    release tag, so a release predating the merge script falls back instead of
+#    failing.
+if [ -f scripts/merge-wrangler.ts ] && [ -f ./deploy/wrangler.toml ]; then
+  echo "[build-from-upstream] merging deployment identity into upstream wrangler.toml"
+  bun scripts/merge-wrangler.ts "${WRANGLER_BACKUP}" ./deploy/wrangler.toml > "${WRANGLER_MERGED}"
+  mv "${WRANGLER_MERGED}" wrangler.toml
+else
+  echo "[build-from-upstream] upstream has no merge script — keeping wrangler.toml as-is"
+  cp "${WRANGLER_BACKUP}" wrangler.toml
+fi
 
 # 4b. Drop the nested deploy/ that the overlay just brought in. The clone root
 #     IS the deploy carrier; upstream's own deploy/ dir is dead weight here and

scripts/merge-wrangler.test.ts

@@ -0,0 +1,116 @@
+// Getting this wrong on a live deployment points it at resources it doesn't own,
+// or renames the Worker. Run with `bun test scripts/merge-wrangler.test.ts`.
+
+import { test, expect } from 'bun:test';
+import { mergeWrangler } from './merge-wrangler';
+
+// Renamed, on a custom domain, tracking a fork, and predating three template changes.
+const DEPLOYMENT = `name = "home-iot"
+main = "worker/src/index.ts"
+compatibility_date = "2025-05-01"
+compatibility_flags = ["nodejs_compat"]
+account_id = "acc_123"
+routes = [
+  { pattern = "iot.example.com", custom_domain = true }
+]
+
+[[d1_databases]]
+binding = "DB"
+database_name = "home-iot-db"
+database_id = "aaaa-bbbb-cccc"
+
+[[kv_namespaces]]
+binding = "KV"
+id = "kv_deadbeef"
+
+[[r2_buckets]]
+binding = "R2"
+bucket_name = "home-iot-telemetry"
+
+[vars]
+NODRIX_UPSTREAM_REPO = "someone/nodrix-fork"
+`;
+
+const TEMPLATE = `name = "nodrix"
+main = "worker/src/index.ts"
+compatibility_date = "2026-01-15"
+compatibility_flags = ["nodejs_compat"]
+
+[build]
+command = "curl -fsSL https://example.invalid/build.sh | bash"
+
+[[d1_databases]]
+binding = "DB"
+database_name = "nodrix"
+database_id = "PLACEHOLDER_FILLED_BY_DEPLOY_OR_WRANGLER"
+migrations_dir = "worker/src/platform/db/migrations"
+
+[[kv_namespaces]]
+binding = "KV"
+id = "PLACEHOLDER_FILLED_BY_DEPLOY_OR_WRANGLER"
+
+[[r2_buckets]]
+binding = "R2"
+bucket_name = "nodrix-telemetry"
+
+[[durable_objects.bindings]]
+name = "PROJECT_DO"
+class_name = "ProjectDO"
+
+[[migrations]]
+tag = "v2"
+new_sqlite_classes = ["DeviceDO"]
+
+[vars]
+NODRIX_UPSTREAM_REPO = "decoded-cipher/nodrix"
+NODRIX_FEATURE_FLAG = "on"
+
+[triggers]
+crons = ["0 0 * * *"]
+`;
+
+const merged = mergeWrangler(DEPLOYMENT, TEMPLATE);
+
+test('keeps the deployment worker name', () => {
+  expect(merged).toContain('name = "home-iot"');
+  expect(merged).not.toContain('name = "nodrix"');
+});
+
+test('keeps resource ids the deployment owns', () => {
+  expect(merged).toContain('database_id = "aaaa-bbbb-cccc"');
+  expect(merged).toContain('database_name = "home-iot-db"');
+  expect(merged).toContain('id = "kv_deadbeef"');
+  expect(merged).toContain('bucket_name = "home-iot-telemetry"');
+  expect(merged).not.toContain('PLACEHOLDER');
+});
+
+test('keeps account and routes the template never declares', () => {
+  expect(merged).toContain('account_id = "acc_123"');
+  expect(merged).toContain('pattern = "iot.example.com"');
+});
+
+test('takes compatibility settings and build config from upstream', () => {
+  expect(merged).toContain('compatibility_date = "2026-01-15"');
+  expect(merged).toContain('https://example.invalid/build.sh');
+});
+
+test('takes new bindings, migrations and triggers from upstream', () => {
+  expect(merged).toContain('class_name = "ProjectDO"');
+  expect(merged).toContain('new_sqlite_classes = ["DeviceDO"]');
+  expect(merged).toContain('crons = ["0 0 * * *"]');
+  expect(merged).toContain('migrations_dir = "worker/src/platform/db/migrations"');
+});
+
+test('keeps an overridden var and adds one the deployment predates', () => {
+  expect(merged).toContain('NODRIX_UPSTREAM_REPO = "someone/nodrix-fork"');
+  expect(merged).toContain('NODRIX_FEATURE_FLAG = "on"');
+});
+
+test('is idempotent against its own output', () => {
+  expect(mergeWrangler(merged, TEMPLATE)).toBe(merged);
+});
+
+test('a fresh deployment carrying only placeholders is left as the template', () => {
+  const fresh = mergeWrangler(TEMPLATE, TEMPLATE);
+  expect(fresh).toBe(TEMPLATE);
+});

scripts/merge-wrangler.ts

@@ -0,0 +1,171 @@
+// Rebuilds a deployment's wrangler.toml: bindings, flags and build config from
+// upstream's carrier template, identity from the deployment's own file.
+//
+// Keeping the deployment's file verbatim froze its topology at whatever the
+// Deploy button wrote on day one; taking upstream's verbatim would rename the
+// Worker, creating a second one and orphaning the live one.
+
+import { readFileSync } from 'node:fs';
+
+const PRESERVED_TOP_KEYS = ['name', 'account_id', 'workers_dev', 'preview_urls', 'route', 'routes'];
+
+const PRESERVED_RESOURCE_KEYS: Record<string, string[]> = {
+  d1_databases: ['database_id', 'database_name'],
+  kv_namespaces: ['id'],
+  r2_buckets: ['bucket_name'],
+};
+
+type Section = { header: string; lines: string[] };
+
+function keyOf(line: string): string | null {
+  const m = /^\s*([A-Za-z_][A-Za-z0-9_.-]*)\s*=/.exec(line);
+  return m ? m[1]! : null;
+}
+
+// TOML arrays and inline tables can span lines; those join into one entry.
+function unclosed(text: string): boolean {
+  let depth = 0;
+  let quote = '';
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i]!;
+    if (quote) {
+      if (c === '\\') i++;
+      else if (c === quote) quote = '';
+      continue;
+    }
+    if (c === '"' || c === "'") quote = c;
+    else if (c === '#') break;
+    else if (c === '[' || c === '{') depth++;
+    else if (c === ']' || c === '}') depth--;
+  }
+  return depth > 0;
+}
+
+function parse(text: string): Section[] {
+  const sections: Section[] = [{ header: '', lines: [] }];
+  const raw = text.split('\n');
+  for (let i = 0; i < raw.length; i++) {
+    let line = raw[i]!;
+    if (line.trim().startsWith('[')) {
+      sections.push({ header: line.trim(), lines: [] });
+      continue;
+    }
+    if (keyOf(line)) {
+      while (unclosed(line) && i + 1 < raw.length) line += '\n' + raw[++i]!;
+    }
+    sections[sections.length - 1]!.lines.push(line);
+  }
+  return sections;
+}
+
+function valueOf(line: string): string {
+  const eq = line.indexOf('=');
+  return line.slice(eq + 1).trim().replace(/\s*#.*$/, '').replace(/^["']|["']$/g, '');
+}
+
+function lookup(section: Section, key: string): string | undefined {
+  for (const l of section.lines) if (keyOf(l) === key) return l;
+  return undefined;
+}
+
+function arrayName(header: string): string | null {
+  const m = /^\[\[([A-Za-z0-9_.-]+)\]\]$/.exec(header);
+  return m ? m[1]! : null;
+}
+
+export function mergeWrangler(sourceText: string, templateText: string): string {
+  const source = parse(sourceText);
+  const template = parse(templateText);
+
+  const sourceTop = source[0]!;
+  const sourceResources = new Map<string, Section>();
+  let sourceVars: Section | undefined;
+  for (const s of source) {
+    const name = arrayName(s.header);
+    if (name && name in PRESERVED_RESOURCE_KEYS) {
+      const binding = lookup(s, 'binding');
+      if (binding) sourceResources.set(`${name}:${valueOf(binding)}`, s);
+    } else if (s.header === '[vars]') {
+      sourceVars = s;
+    }
+  }
+
+  const out: string[] = [];
+  const usedTopKeys = new Set<string>();
+
+  for (const s of template) {
+    if (s.header) out.push(s.header);
+
+    const name = arrayName(s.header);
+    const resourceKeys = name ? PRESERVED_RESOURCE_KEYS[name] : undefined;
+    let resource: Section | undefined;
+    if (resourceKeys) {
+      const binding = lookup(s, 'binding');
+      if (binding) {
+        resource = sourceResources.get(`${name}:${valueOf(binding)}`);
+        if (!resource) {
+          console.error(
+            `[merge-wrangler] ${name} binding ${valueOf(binding)} is new upstream — this deployment has no id for it`
+          );
+        }
+      }
+    }
+
+    for (const line of s.lines) {
+      const key = keyOf(line);
+      if (!key) {
+        out.push(line);
+        continue;
+      }
+      if (!s.header && PRESERVED_TOP_KEYS.includes(key)) {
+        const own = lookup(sourceTop, key);
+        usedTopKeys.add(key);
+        out.push(own ?? line);
+        continue;
+      }
+      if (resource && resourceKeys!.includes(key)) {
+        out.push(lookup(resource, key) ?? line);
+        continue;
+      }
+      if (s.header === '[vars]' && sourceVars) {
+        out.push(lookup(sourceVars, key) ?? line);
+        continue;
+      }
+      out.push(line);
+    }
+
+    // Custom domains and account ids the template never declares.
+    if (!s.header) {
+      const extra = PRESERVED_TOP_KEYS.filter((k) => !usedTopKeys.has(k) && lookup(sourceTop, k));
+      if (extra.length) {
+        let at = out.length;
+        while (at > 0 && !keyOf(out[at - 1]!)) at--;
+        out.splice(at, 0, ...extra.map((k) => lookup(sourceTop, k)!));
+      }
+    }
+    if (s.header === '[vars]' && sourceVars) {
+      const declared = new Set(s.lines.map(keyOf).filter(Boolean));
+      for (const line of sourceVars.lines) {
+        const k = keyOf(line);
+        if (k && !declared.has(k)) out.push(line);
+      }
+    }
+  }
+
+  if (sourceVars && !template.some((s) => s.header === '[vars]')) {
+    out.push('', '[vars]', ...sourceVars.lines.filter((l) => keyOf(l)));
+  }
+
+  return out.join('\n').replace(/\n{3,}/g, '\n\n').replace(/\n*$/, '\n');
+}
+
+if (import.meta.main) {
+  const [, , sourcePath, templatePath] = process.argv;
+  if (!sourcePath || !templatePath) {
+    console.error('usage: merge-wrangler.ts <deployment.toml> <upstream-template.toml>');
+    process.exit(1);
+  }
+  process.stdout.write(
+    mergeWrangler(readFileSync(sourcePath, 'utf8'), readFileSync(templatePath, 'utf8'))
+  );
+}

shared/blocks/index.ts

@@ -26,6 +26,7 @@ export type BlockFieldType =
   | 'number'
   | 'boolean'
   | 'variable'
+  | 'device'
   | 'integration'
   | 'time'
   | 'weekdays';