@trillboards/edge-sdk 0.2.2 → 0.2.3

package/deploy/helm/trillboards-edge/values.yaml

@@ -0,0 +1,95 @@
+# Default values for trillboards-edge Helm chart
+
+# Image configuration
+image:
+  repository: trillboards/edge-sdk
+  tag: "latest"
+  pullPolicy: Always
+
+# Available tags: latest (CPU), cuda (NVIDIA GPU), openvino (Intel GPU)
+# Override per-node using nodeSelector + separate releases if heterogeneous fleet
+
+# Trillboards API configuration
+api:
+  baseUrl: "https://api.trillboards.com"
+
+# Device token — create a Kubernetes secret:
+#   kubectl create secret generic trillboards-edge --from-literal=device-token=YOUR_TOKEN
+deviceToken:
+  existingSecret: "trillboards-edge"
+  secretKey: "device-token"
+
+# Sensing configuration
+sensing:
+  camera:
+    enabled: true
+  audio:
+    enabled: true
+  kiosk:
+    enabled: false
+    url: "https://screen.trillboards.com"
+  executionProvider: "cpu"  # cpu, openvino, directml, cuda
+  logLevel: "info"
+
+# Resource limits
+resources:
+  requests:
+    cpu: "250m"
+    memory: "256Mi"
+  limits:
+    cpu: "1000m"
+    memory: "1Gi"
+
+# GPU resources (for CUDA/OpenVINO images)
+gpu:
+  enabled: false
+  # nvidia.com/gpu: 1
+
+# Status server
+statusServer:
+  port: 9090
+
+# Prometheus scraping
+prometheus:
+  enabled: true
+  port: 9090
+  path: "/metrics"
+
+# Health probes
+probes:
+  liveness:
+    initialDelaySeconds: 30
+    periodSeconds: 30
+  readiness:
+    initialDelaySeconds: 10
+    periodSeconds: 10
+
+# Model storage — hostPath for persistent models across restarts
+models:
+  hostPath: "/opt/trillboards/models"
+
+# Data storage — hostPath for signal buffer, device identity, etc.
+data:
+  hostPath: "/opt/trillboards/data"
+
+# Node scheduling
+nodeSelector:
+  trillboards.com/edge-device: "true"
+
+tolerations:
+  - key: "edge"
+    operator: "Exists"
+    effect: "NoSchedule"
+
+affinity: {}
+
+# DaemonSet update strategy
+updateStrategy:
+  type: RollingUpdate
+  rollingUpdate:
+    maxUnavailable: 1
+
+# Security context
+securityContext:
+  privileged: false
+  readOnlyRootFilesystem: false

package/deploy/k8s/daemonset.yaml

@@ -0,0 +1,144 @@
+# Trillboards Edge SDK — Kubernetes DaemonSet
+# Deploys one edge agent per node for fleet-wide audience sensing
+#
+# Usage:
+#   kubectl create secret generic trillboards-edge \
+#     --from-literal=device-token=YOUR_TOKEN
+#   kubectl apply -f daemonset.yaml
+#
+# For GPU nodes, use the CUDA image and add NVIDIA tolerations.
+
+apiVersion: apps/v1
+kind: DaemonSet
+metadata:
+  name: trillboards-edge-agent
+  namespace: default
+  labels:
+    app: trillboards-edge
+    component: agent
+spec:
+  selector:
+    matchLabels:
+      app: trillboards-edge
+  updateStrategy:
+    type: RollingUpdate
+    rollingUpdate:
+      maxUnavailable: 1
+  template:
+    metadata:
+      labels:
+        app: trillboards-edge
+        component: agent
+      annotations:
+        prometheus.io/scrape: "true"
+        prometheus.io/port: "9090"
+        prometheus.io/path: "/metrics"
+    spec:
+      terminationGracePeriodSeconds: 30
+      containers:
+        - name: edge-agent
+          image: trillboards/edge-sdk:latest
+          imagePullPolicy: Always
+          ports:
+            - name: status
+              containerPort: 9090
+              protocol: TCP
+          env:
+            - name: DEVICE_TOKEN
+              valueFrom:
+                secretKeyRef:
+                  name: trillboards-edge
+                  key: device-token
+            - name: SCREEN_ID
+              valueFrom:
+                fieldRef:
+                  fieldPath: spec.nodeName
+            - name: API_BASE_URL
+              value: "https://api.trillboards.com"
+            - name: CAMERA_ENABLED
+              value: "true"
+            - name: AUDIO_ENABLED
+              value: "true"
+            - name: KIOSK_ENABLED
+              value: "false"
+            - name: EXECUTION_PROVIDER
+              value: "cpu"
+            - name: LOG_LEVEL
+              value: "info"
+            - name: NODE_NAME
+              valueFrom:
+                fieldRef:
+                  fieldPath: spec.nodeName
+          resources:
+            requests:
+              cpu: "250m"
+              memory: "256Mi"
+            limits:
+              cpu: "1000m"
+              memory: "1Gi"
+          livenessProbe:
+            httpGet:
+              path: /health
+              port: status
+            initialDelaySeconds: 30
+            periodSeconds: 30
+            timeoutSeconds: 5
+            failureThreshold: 3
+          readinessProbe:
+            httpGet:
+              path: /health
+              port: status
+            initialDelaySeconds: 10
+            periodSeconds: 10
+            timeoutSeconds: 3
+            failureThreshold: 2
+          volumeMounts:
+            - name: models
+              mountPath: /app/models
+            - name: data
+              mountPath: /app/data
+            # Mount camera device if available
+            - name: video-devices
+              mountPath: /dev
+              readOnly: true
+          securityContext:
+            privileged: false
+            readOnlyRootFilesystem: false
+      volumes:
+        - name: models
+          hostPath:
+            path: /opt/trillboards/models
+            type: DirectoryOrCreate
+        - name: data
+          hostPath:
+            path: /opt/trillboards/data
+            type: DirectoryOrCreate
+        - name: video-devices
+          hostPath:
+            path: /dev
+            type: Directory
+      # Schedule on edge nodes only
+      nodeSelector:
+        trillboards.com/edge-device: "true"
+      tolerations:
+        - key: "edge"
+          operator: "Exists"
+          effect: "NoSchedule"
+---
+# Service for status endpoint access
+apiVersion: v1
+kind: Service
+metadata:
+  name: trillboards-edge-status
+  namespace: default
+  labels:
+    app: trillboards-edge
+spec:
+  selector:
+    app: trillboards-edge
+  ports:
+    - name: status
+      port: 9090
+      targetPort: status
+      protocol: TCP
+  clusterIP: None  # Headless — each pod addressable individually

package/dist/CommandRouter.d.ts

@@ -0,0 +1,113 @@
+/**
+ * CommandRouter — Routes incoming `deviceCommand` socket events to
+ * the appropriate handler and reports results back to the caller.
+ *
+ * Supported commands:
+ *   config.push      — Hot-push sensing/VAS/full config
+ *   device.screenshot — Capture + upload a screenshot to S3
+ *   power.sleep      — DPMS display off
+ *   power.wake       — DPMS display on
+ *   kiosk.reload     — Reload kiosk browser
+ *   device.restart   — Restart the edge agent process
+ *   device.ping      — Heartbeat ping/pong
+ *   device.info      — Return host system information
+ */
+import { EventEmitter } from 'events';
+/**
+ * Capabilities injected by EdgeAgent when constructing the CommandRouter.
+ * Each function encapsulates a side-effect the router delegates to rather
+ * than performing directly — this keeps the router unit-testable.
+ */
+export interface CommandContext {
+    reloadKiosk: () => Promise<void>;
+    captureScreenshot: () => Promise<Buffer | null>;
+    getUploadUrl: (type: string) => Promise<string | null>;
+    uploadToS3: (url: string, data: Buffer, contentType: string) => Promise<boolean>;
+    setSleepMode: (sleep: boolean) => Promise<void>;
+    restartDevice: () => Promise<void>;
+    updateConfig: (configPatch: Record<string, unknown>) => Promise<void>;
+}
+/**
+ * Shape of the `deviceCommand` event payload received from the backend.
+ * Matches the server-side dispatcher: `{ commandId, command, payload, ... }`.
+ */
+export interface DeviceCommand {
+    commandId: string;
+    command: string;
+    payload?: Record<string, unknown>;
+    timestamp?: number;
+}
+/**
+ * Outcome of executing a single command — sent back to the server
+ * via `deviceCommandStatus`.
+ */
+export interface CommandResult {
+    commandId: string;
+    command: string;
+    status: 'completed' | 'failed' | 'unsupported';
+    result?: unknown;
+    error?: string;
+    durationMs: number;
+}
+export declare class CommandRouter extends EventEmitter {
+    private readonly context;
+    private readonly commandHistory;
+    private readonly maxHistory;
+    private readonly startedAt;
+    constructor(context: CommandContext, maxHistory?: number);
+    /**
+     * Route and execute an incoming device command.
+     * Returns the `CommandResult` which the caller should send back via socket.
+     *
+     * This method **never throws** — every failure path is captured in
+     * the result with `status: 'failed'` and a human-readable error message.
+     */
+    handleCommand(cmd: DeviceCommand): Promise<CommandResult>;
+    /**
+     * Return a shallow copy of the recent command history, newest-first.
+     */
+    getHistory(): CommandResult[];
+    private dispatch;
+    /**
+     * config.push — Update sensing/VAS config.
+     * Payload: `{ type: 'sensing' | 'vas' | 'full', config: {...} }`
+     */
+    private handleConfigPush;
+    /**
+     * device.screenshot — Capture kiosk screenshot, upload to S3.
+     * 1. captureScreenshot() -> Buffer | null
+     * 2. getUploadUrl('screenshot') -> presigned URL
+     * 3. uploadToS3(url, buffer, 'image/png')
+     */
+    private handleScreenshot;
+    /**
+     * power.sleep — Put the display to sleep via DPMS.
+     */
+    private handlePowerSleep;
+    /**
+     * power.wake — Wake the display from DPMS sleep.
+     */
+    private handlePowerWake;
+    /**
+     * kiosk.reload — Reload the kiosk browser page.
+     */
+    private handleKioskReload;
+    /**
+     * device.restart — Restart the edge agent process.
+     *
+     * Note: after calling `context.restartDevice()`, this process may terminate
+     * before the result can be sent. The caller should emit the ack/status
+     * *before* actually restarting if reliable delivery matters.
+     */
+    private handleDeviceRestart;
+    /**
+     * device.ping — Simple liveness check. Returns a pong with server timestamp.
+     */
+    private handleDevicePing;
+    /**
+     * device.info — Return system information useful for remote diagnostics.
+     */
+    private handleDeviceInfo;
+    private recordHistory;
+}
+//# sourceMappingURL=CommandRouter.d.ts.map

package/dist/CommandRouter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CommandRouter.d.ts","sourceRoot":"","sources":["../src/CommandRouter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AAKtC;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,WAAW,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACjC,iBAAiB,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAChD,YAAY,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACvD,UAAU,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACjF,YAAY,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAChD,aAAa,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,YAAY,EAAE,CAAC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACvE;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,WAAW,GAAG,QAAQ,GAAG,aAAa,CAAC;IAC/C,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;CACpB;AAiBD,qBAAa,aAAc,SAAQ,YAAY;IAC7C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiB;IACzC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAuB;IACtD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;gBAEvB,OAAO,EAAE,cAAc,EAAE,UAAU,SAAM;IASrD;;;;;;OAMG;IACG,aAAa,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC;IAuB/D;;OAEG;IACH,UAAU,IAAI,aAAa,EAAE;YAMf,QAAQ;IA+BtB;;;OAGG;YACW,gBAAgB;IAoC9B;;;;;OAKG;YACW,gBAAgB;IAwD9B;;OAEG;YACW,gBAAgB;IAqB9B;;OAEG;YACW,eAAe;IAqB7B;;OAEG;YACW,iBAAiB;IAqB/B;;;;;;OAMG;YACW,mBAAmB;IAqBjC;;OAEG;YACW,gBAAgB;IAU9B;;OAEG;YACW,gBAAgB;IAsC9B,OAAO,CAAC,aAAa;CAMtB"}