Logo for the website. A blue P-like symbol and a red K-like symbol. Pushkar Kurhekar
•
3 min read

Pulse Deck

Table of Contents

Overview

Pulse Deck is an Elgato Stream Deck plugin designed for real-time macOS system telemetry in a compact, graph-first visual format. It targets fast glanceability and stable low-overhead updates across multiple keys.

Metrics

  • CPU usage (%)
  • Memory usage (%)
  • Ping latency (ms; 1.1.1.1 with 8.8.8.8 fallback)
  • Battery level (%)
  • Uptime

Architecture

The plugin uses a small modular runtime:

  • Node plugin loop: handles Elgato Stream Deck events and metric polling.
  • Metric sampler: collects and caches data per active metric.
  • Renderer bridge: normalizes values/history, caches rendered images, and dispatches tile generation.
  • Python renderer: draws polished key images with value + sparkline graph using Pillow.

This split keeps rendering concerns separate from system sampling logic and makes updates easier to maintain.

Data Collection

CPU

CPU usage is computed from OS CPU tick deltas and aligned with Stats-style behavior:

usage = (systemDelta + userDelta) / totalTicks

Memory

Memory usage is based on parsed vm_stat output (instead of only freemem) using a Stats-aligned formula:

used = active + inactive + speculative + wired + compressed - purgeable - external

Ping

Ping runs on a configurable interval (default 30s) and supports fallback host probing. The interval is set through the Ping key property inspector.

Technology Stack

  • Runtime: Node.js 20
  • Rendering: Python 3 + Pillow
  • Platform SDK: Elgato Stream Deck SDK 2
  • Target OS: macOS

Local Setup

npm run prepare
npm run icons
npm test
npm run install:local

Restart Elgato Stream Deck after local installation.

Packaging

npm run package:plugin

Artifact output:

dist/com.pshkrh.pulse-deck-<version>.streamDeckPlugin

Repository Layout

  • com.pshkrh.pulse-deck.sdPlugin/manifest.json: Elgato Stream Deck metadata and actions
  • com.pshkrh.pulse-deck.sdPlugin/bin/plugin.js: event loop and action wiring
  • com.pshkrh.pulse-deck.sdPlugin/bin/lib/system/metrics.js: macOS metric sampling and normalization
  • com.pshkrh.pulse-deck.sdPlugin/bin/lib/render/icon-renderer.js: render orchestration and cache logic
  • com.pshkrh.pulse-deck.sdPlugin/bin/scripts/render_vital_tile.py: Python tile renderer
  • scripts/install-pulse-deck.sh: local install script
  • scripts/package-plugin.sh: release packaging script