feat(peripheral-demo): add Edge App for peripheral integration

.prettierignore

@@ -3,6 +3,7 @@ edge-apps/.bun-create/
 edge-apps/cap-alerting/
 edge-apps/clock/
 edge-apps/edge-apps-library/
+edge-apps/peripheral-integration-demo/
 edge-apps/grafana/
 edge-apps/powerbi-legacy/
 edge-apps/powerbi-legacy/**

edge-apps/edge-apps-library/package.json

@@ -78,7 +78,8 @@
     "offline-geocode-city": "^1.0.2",
     "panic-overlay": "^1.0.51",
     "sharp": "^0.34.5",
-    "tailwindcss": "^4.2.1"
+    "tailwindcss": "^4.2.1",
+    "ulid": "^3.0.2"
   },
   "peerDependencies": {
     "@playwright/test": "^1.58.0"
@@ -94,6 +95,7 @@
     "@types/jsdom": "^28.0.0",
     "@types/node": "^25.4.0",
     "@types/sharp": "^0.32.0",
+    "@types/ws": "^8.18.1",
     "bun-types": "^1.3.10",
     "eslint": "^10.0.3",
     "jiti": "^2.6.1",
@@ -102,6 +104,7 @@
     "typescript": "^5.9.3",
     "typescript-eslint": "^8.57.0",
     "vite": "^7.3.1",
+    "ws": "^8.19.0",
     "yaml": "^2.8.2"
   }
 }

edge-apps/edge-apps-library/src/index.ts

@@ -9,3 +9,6 @@ export * from './components/index.js'
 
 // Types
 export * from './types/index.js'
+
+// Peripheral integration
+export * from './peripherals/index.js'

edge-apps/edge-apps-library/src/peripherals/index.ts

@@ -0,0 +1,125 @@
+import { ulid } from 'ulid'
+
+import type { PeripheralStateMessage } from '../types/index.js'
+
+// WebSocket address of the hardware integration service on the Screenly player.
+// Port 9010 is a fixed port defined in the player firmware for Edge App connections.
+const PERIPHERAL_WS_URL = 'ws://127.0.0.1:9010'
+
+const ETB = '\x17'
+
+/**
+ * Serializes `payload` as JSON, appends the ETB delimiter, and sends it over
+ * the WebSocket connection to the hardware integration service.
+ * Throws if the connection is not open or if the underlying send fails.
+ */
+function sendMessage(ws: WebSocket, payload: unknown): void {
+  if (ws.readyState !== WebSocket.OPEN) {
+    throw new Error('Cannot send message: WebSocket is not open')
+  }
+  try {
+    ws.send(JSON.stringify(payload) + ETB)
+  } catch (err) {
+    throw new Error('Failed to send message', { cause: err })
+  }
+}
+
+export interface PeripheralClient {
+  register: (edgeAppId: string) => void
+  watchState: (callback: (msg: PeripheralStateMessage) => void) => void
+}
+
+// eslint-disable-next-line max-lines-per-function
+export function createPeripheralClient(): PeripheralClient {
+  let ws: WebSocket | null = null
+  const subscribers: Array<(msg: PeripheralStateMessage) => void> = []
+  const readings: Record<string, unknown> = {}
+
+  /**
+   * Packages the latest cached sensor readings into a wire message and
+   * dispatches it to every callback registered via watchState().
+   */
+  function notifySubscribers() {
+    const msg: PeripheralStateMessage = {
+      request: {
+        id: ulid(),
+        edge_app_source_state: {
+          states: Object.values(
+            readings,
+          ) as PeripheralStateMessage['request']['edge_app_source_state']['states'],
+        },
+      },
+    }
+    subscribers.forEach((cb) => cb(msg))
+  }
+
+  function connect() {
+    ws = new WebSocket(PERIPHERAL_WS_URL)
+
+    ws.onmessage = async (e: MessageEvent) => {
+      let text: string
+      if (e.data instanceof Blob) {
+        text = await e.data.text()
+      } else {
+        text = e.data as string
+      }
+
+      text = text.replace(ETB, '')
+      let msg: Record<string, unknown>
+      try {
+        msg = JSON.parse(text) as Record<string, unknown>
+      } catch (err) {
+        console.warn('Failed to parse peripheral message', err)
+        return
+      }
+
+      const request = msg.request as Record<string, unknown> | undefined
+      if (request?.edge_app_source_state) {
+        const state = request.edge_app_source_state as {
+          states: Array<{ name: string }>
+        }
+        state.states.forEach((s) => {
+          readings[s.name] = s
+        })
+        notifySubscribers()
+        sendMessage(ws!, {
+          response: { request_id: request.id, ok: 'edge_app_source_state' },
+        })
+        return
+      }
+    }
+
+    ws.onerror = () => console.warn('Peripheral WebSocket error')
+    ws.onclose = () => {
+      setTimeout(connect, 2000)
+    }
+  }
+
+  return {
+    register(edgeAppId: string) {
+      if (!ws) connect()
+      const sendRegistration = () => {
+        sendMessage(ws!, {
+          request: {
+            id: ulid(),
+            edge_app_registration: {
+              id: edgeAppId,
+              secret: '',
+              requested_source_channels: [],
+            },
+          },
+        })
+      }
+      if (ws!.readyState === WebSocket.OPEN) {
+        sendRegistration()
+      } else {
+        ws!.addEventListener('open', sendRegistration, { once: true })
+      }
+    },
+
+    watchState(callback: (msg: PeripheralStateMessage) => void) {
+      if (!ws) connect()
+      subscribers.push(callback)
+    },
+  }
+}

edge-apps/edge-apps-library/src/types/index.ts

@@ -49,6 +49,34 @@ export interface ScreenlySettings extends Record<string, unknown> {
   sentry_dsn?: string
 }
 
+/**
+ * A single peripheral channel reading as delivered by the hardware integration service.
+ * The sensor-specific value is carried under its wire key (e.g. ambient_temperature, humidity).
+ */
+export interface PeripheralState {
+  /** Channel name as configured on the player (e.g. "my_living_room_temp") */
+  name: string
+  /** Unix epoch timestamp in milliseconds */
+  timestamp: number
+  /** Physical unit (e.g. "°C", "%", "hPa") — omitted when not applicable */
+  unit?: string
+  /** Sensor-specific value field (e.g. ambient_temperature, humidity, byte_array) */
+  [wireKey: string]: unknown
+}
+
+/**
+ * Full wire message delivered by the hardware integration service.
+ * Matches the `edge_app_source_state` push event shape from the hardware integration service.
+ */
+export interface PeripheralStateMessage {
+  request: {
+    id: string
+    edge_app_source_state: {
+      states: PeripheralState[]
+    }
+  }
+}
+
 /**
  * The global screenly object provided by screenly.js
  */