{"id":50120397,"url":"https://github.com/synryzen/nodespark-wisp","last_synced_at":"2026-05-23T18:34:32.442Z","repository":{"id":358069578,"uuid":"1239280026","full_name":"synryzen/nodespark-wisp","owner":"synryzen","description":"NodeSpark Wisp Raspberry Pi companion device for NodeSparkHub: display, voice, approvals, dashboards, QR, and physical workflow demos","archived":false,"fork":false,"pushed_at":"2026-05-15T14:31:56.000Z","size":596,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-15T16:30:56.286Z","etag":null,"topics":["iot","nodesparkhub","physical-computing","raspberry-pi","voice-assistant","workflow-automation"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/synryzen.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-15T00:07:26.000Z","updated_at":"2026-05-15T14:32:00.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/synryzen/nodespark-wisp","commit_stats":null,"previous_names":["synryzen/nodespark-wisp"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/synryzen/nodespark-wisp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/synryzen%2Fnodespark-wisp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/synryzen%2Fnodespark-wisp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/synryzen%2Fnodespark-wisp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/synryzen%2Fnodespark-wisp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/synryzen","download_url":"https://codeload.github.com/synryzen/nodespark-wisp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/synryzen%2Fnodespark-wisp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33408490,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-23T18:09:33.147Z","status":"ssl_error","status_checked_at":"2026-05-23T18:09:31.380Z","response_time":53,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["iot","nodesparkhub","physical-computing","raspberry-pi","voice-assistant","workflow-automation"],"created_at":"2026-05-23T18:34:31.144Z","updated_at":"2026-05-23T18:34:32.420Z","avatar_url":"https://github.com/synryzen.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# NodeSpark Wisp\n\nNodeSpark Wisp is a pocket-sized physical companion device for NodeSparkHub.\nIt gives NodeSparkHub a real physical presence: a tiny display, speaker,\nmicrophone, touch screen or button input, RGB/light feedback, and a workflow\nsurface that can show live results, request approvals, and display branded\ndashboard screens.\n\nIt is built to demonstrate what NodeSparkHub can do beyond an iPhone. With\nWisp, NodeSparkHub can connect software automation to something people can hold\nin their hand.\n\nRepository:\n\n```text\nhttps://github.com/synryzen/nodespark-wisp\n```\n\nWebsite:\n\n```text\nhttps://synryzen.github.io/nodespark-wisp/\n```\n\n![NodeSpark Wisp running on a PiSugar Whisplay HAT](docs/assets/wisp-whisplay-startup.jpg)\n\n## What It Is For\n\nNodeSpark Wisp is for showing, testing, and building physical workflow\nexperiences powered by NodeSparkHub.\n\nUse it to:\n\n- Demo NodeSparkHub at a desk, booth, store, classroom, or client meeting.\n- Trigger Hub workflows from a real button.\n- Navigate a touch-first ESP32-S3 Wisp interface.\n- Run a premium M5Stack Core2 Wisp with built-in touch, speaker, mic, haptics,\n  battery, IMU, RTC, and SD card support.\n- Send live workflow output from NodeSparkHub to a Raspberry Pi display.\n- Speak Hub responses through the device speaker.\n- Capture short voice commands and send them into Hub workflows.\n- Show branded cards, metrics, alerts, approvals, QR codes, and status screens.\n- Prove that NodeSparkHub can connect Mac, iPhone, APIs, schedules, automations,\n  and physical hardware into one workflow system.\n\nThe big idea: NodeSparkHub is not just an app screen. It can become a control\ncenter for real-world devices.\n\n## Subscription Requirement\n\nNodeSpark Wisp is designed for active NodeSparkHub subscribers. The hardware is\nnot split into separate locked feature tiers: display cards, voice, buttons,\napprovals, dashboards, QR screens, Bluetooth Mobile Bridge, and workflow actions\nare the full Wisp experience.\n\nAn active NodeSparkHub All Access subscription powers the Hub runtime behind\nthat experience: pairing, secure command routing, live device commands,\nworkflow execution, automation history, and iPhone Mobile Bridge forwarding.\nWithout All Access, builders can still install the software and bring up the\ndevice, but live Hub-to-Wisp operation requires the subscription.\n\n## How It Works With NodeSparkHub\n\nNodeSpark Wisp connects to the Hub server built into NodeSparkHub over HTTP.\nAfter pairing, it checks in with the Hub, appears in Hub Server device settings,\nand polls for commands from NodeSparkHub.\n\nThe device uses these Hub API flows:\n\n- `POST /pair`\n- `POST /devices/checkin`\n- `GET /workflows`\n- `POST /workflows/\u003cname\u003e/run`\n- `GET /runs/\u003cid\u003e/status`\n- `POST /wisp/assistant`\n- `POST /devices/\u003cdeviceId\u003e/commands`\n- `GET /devices/\u003cdeviceId\u003e/commands/poll`\n- `POST /devices/\u003cdeviceId\u003e/commands/\u003ccommandId\u003e/ack`\n\nNodeSparkHub can send commands to the Wisp from workflow templates, local demo\nscripts, or direct API calls. The Wisp acknowledges each command so Hub can know\nwhether it displayed, spoke, ran, approved, rejected, or failed the request.\n\n## NodeSparkHub Intelligence\n\nNodeSpark Wisp is designed to work with the NodeSparkHub Intelligence Center in\nNodeSparkHub 3.2 and newer. That means the device can be more than a remote\nworkflow button: it can act like a small AI assistant for the Hub.\n\nThe current app-side intelligence layer adds:\n\n- Wisp Assistant access to NodeSparkHub's default AI profile.\n- Local assistant memory for more helpful follow-up responses.\n- Auto Context so recent memory and workflow clues can be layered into AI\n  requests without changing workflow JSON.\n- Knowledge Vault controls for keeping useful setup notes, assistant answers,\n  and Wisp troubleshooting context reviewable.\n- Token compression so long device/workflow context can be sent more cleanly.\n- Prompt safety checks before Hub or device-originated AI requests are sent.\n- Smart model routing hints for extraction, classification, JSON, creative, and\n  general assistant tasks.\n- Proactive suggestions that guide users toward Hub pairing, Wisp setup,\n  workflow creation, and AI model readiness.\n- Voice Everywhere controls for natural commands across workflow running,\n  workflow creation, debugging, Hub status, Wisp help, and general AI questions.\n- Device Presence awareness so assistant replies can account for Raspberry Pi\n  Whisplay, ESP32-S3 Touch, M5Stack Core2, and iPhone Mobile Bridge contexts.\n- A Hub setting to turn Wisp Assistant access on or off without breaking normal\n  device pairing, command polling, workflow launches, or Bluetooth Mobile Bridge.\n\nIn NodeSparkHub, open:\n\n```text\nSettings -\u003e Intelligence\n```\n\nor:\n\n```text\nDashboard -\u003e Intelligence\n```\n\nIn NodeSpark on iPhone, open:\n\n```text\nSettings -\u003e Intelligence\n```\n\nThese settings upgrade the AI behavior around Wisp, Hub workflows, and iPhone\nbridge requests while preserving the existing device API contract.\n\n## What The Device Can Do\n\nCurrent Wisp capabilities:\n\n- Pair with NodeSparkHub using a one-time pairing code.\n- Appear inside NodeSparkHub's connected device list.\n- Check in automatically so Hub can show connection status.\n- Run on Raspberry Pi Zero 2 W with PiSugar Whisplay HAT.\n- Run on ESP32-S3 N16R8 with ILI9341 touch display, MAX98357 amp, and INMP441 mic.\n- Run on M5Stack Core2 using the built-in touch screen, speaker, microphone,\n  vibration motor, battery monitor, IMU, RTC, and SD slot.\n- Show the NodeSpark mascot as a startup logo.\n- Show animated listening, thinking, running, success, and error screens.\n- Show text messages from NodeSparkHub.\n- Show rich branded cards with icons, subtitles, accent colors, and progress.\n- Ask NodeSparkHub's default AI profile through the Wisp Assistant endpoint for\n  general questions, troubleshooting, brainstorming, and workflow help, with\n  workflow fallback when direct AI is not configured.\n- Use NodeSparkHub Intelligence memory, prompt safety, token compression, and\n  smart model routing when Wisp Assistant is enabled.\n- Show approval prompts where short press approves and hold rejects.\n- Show a notification center with recent Hub alerts.\n- Show compact dashboards with metrics and list items.\n- Show icon/graphics grids for visual demos.\n- Show QR/link screens for pairing, identity, Hub URLs, or workflow data.\n- Show device-health screens for Wi-Fi, Hub pairing, battery/temperature when\n  available, SD status, and audio readiness.\n- Select the active Hub workflow from NodeSparkHub and save it on the ESP32 Wisp.\n- Sync live NodeSparkHub workflows onto the Wisp so the device cycles real Hub\n  workflows instead of only static config favorites.\n- Speak Hub text and Wisp Assistant AI replies. Raspberry Pi Wisp can use local\n  `espeak-ng`; ESP32-S3 and Core2 can play Hub-generated PCM WAV speech clips\n  returned by NodeSparkHub's Wisp Assistant endpoint.\n- Play startup, listening, success, and error chimes when audio is available.\n- Adjust Whisplay speaker volume remotely from NodeSparkHub.\n- Use the NodeSparkHub Wisp Control Center for setup checks, demo profiles,\n  assistant voice tests, volume, brightness requests, mic view, SD/storage\n  checks, health dashboards, and reboot commands where supported by hardware.\n- Set the RGB LED color from Hub commands.\n- Run a selected Hub workflow from the physical button.\n- Run a selected Hub workflow from the ESP32-S3 touch UI.\n- Cycle favorite workflows with a short button press.\n- Record a short voice command with a button hold.\n- Transcribe with OpenAI, offline Vosk, or skip transcription for text-only use.\n- Send workflow payloads back to Hub with device identity and transcript text.\n- Run a full sales-showcase sequence from one Hub command.\n- Print local status including IP/Wi-Fi/battery/temperature when available.\n- Optionally advertise a Bluetooth LE Wisp Mobile Bridge for NodeSpark on iPhone.\n\n## Hardware Targets\n\nNodeSpark Wisp now has three hardware builds:\n\n- **Whisplay Wisp**: Raspberry Pi Zero 2 W + PiSugar Whisplay HAT.\n- **ESP32-S3 Wisp Touch**: ESP32-S3 N16R8 + 2.8-inch ILI9341 touch TFT +\n  MAX98357 I2S amp + INMP441 I2S mic.\n- **M5Stack Core2 Wisp**: M5Stack Core2 with built-in 2-inch touch screen,\n  speaker amp, microphone, vibration motor, battery, IMU, RTC, and SD slot.\n\nAll three builds pair with NodeSparkHub, appear in Hub Server device settings,\npoll Hub commands, and acknowledge command results.\n\n## Choose Your Wisp Build\n\nPick the build that matches the hardware in front of you:\n\n| Device | Best for | Start here |\n| --- | --- | --- |\n| Raspberry Pi Whisplay Wisp | The polished pocket demo with mascot startup, speaker, mic, button, battery, custom OS image, and reliable iPhone BLE bridge | [Raspberry Pi Whisplay Wisp](#raspberry-pi-whisplay-wisp) |\n| ESP32-S3 Wisp Touch | Lower-cost touch panels, breadboard prototypes, wall controls, and custom screen sizes | [ESP32-S3 Wisp Touch](#esp32-s3-wisp-touch) |\n| M5Stack Core2 Wisp | Easiest all-in-one touchscreen build with built-in speaker, mic, haptics, battery, IMU, RTC, SD slot, and iPhone BLE bridge | [M5Stack Core2 Wisp](#m5stack-core2-wisp) |\n\nShared features across the three builds:\n\n- NodeSparkHub pairing and connected-device status.\n- Hub command polling and command acknowledgements.\n- Rich cards, dashboard screens, approvals, notifications, QR/link screens,\n  workflow launch, Ask AI, and Wisp Assistant replies.\n- Bluetooth Mobile Bridge with NodeSpark iOS. Raspberry Pi and Core2 are the\n  recommended BLE demo devices; ESP32-S3 keeps BLE opt-in for stability.\n\n## Raspberry Pi Whisplay Wisp\n\n### Hardware Needed\n\nThis software targets the same hardware stack used by OpenClaw-style DIY\nassistants:\n\n- Raspberry Pi Zero 2 W\n- MicroSD card, 16 GB or larger recommended\n- PiSugar Whisplay HAT with:\n  - 1.69-inch LCD\n  - WM8960 speaker/microphone audio\n  - RGB LED\n  - onboard button\n- PiSugar battery pack compatible with the Whisplay HAT\n- Small speaker connected through the Whisplay/WM8960 audio path\n- USB power cable for charging/setup\n- Wi-Fi network reachable by the Mac running NodeSparkHub\n- Optional case/enclosure for demo-ready builds\n\nRecommended software/runtime:\n\n- Raspberry Pi OS Lite or Desktop, 64-bit recommended\n- Python 3.11 or newer\n- NodeSparkHub 3 or newer running on the Mac\n- Hub Server enabled in NodeSparkHub\n- Optional: OpenAI API key for cloud transcription\n- Optional: Vosk model for offline speech transcription\n- NodeSparkHub 3.2 or newer for Intelligence Center and Wisp Assistant\n- NodeSpark iOS 3.2 or newer for Wisp Mobile Bridge intelligence settings\n\nImportant: this project uses the same physical hardware style as OpenClaw, but\nit is NodeSparkHub companion software. OpenClaw is not required.\n\n### Custom Raspberry Pi OS Image\n\nThe Raspberry Pi build has a custom image recipe in [image/README.md](image/README.md).\nThe image installs NodeSpark Wisp, the boot service, Whisplay dependencies,\nBluetooth Mobile Bridge dependencies, and a first-boot helper that can read\n`nodespark-wisp.toml` from the boot partition.\n\nBuild the image from this repo on Linux or Docker:\n\n```bash\nbash scripts/build_pi_image.sh\n```\n\nAfter flashing, users set Wi-Fi and login details in Raspberry Pi Imager, boot\nwith the Whisplay HAT attached, then pair from NodeSparkHub.\n\n## ESP32-S3 Wisp Touch\n\n### Hardware Needed\n\nThe ESP32-S3 build is a lower-cost touch-first Wisp variant. It is great for\nlarger screens, handheld demo panels, wall controls, and future battery builds.\n\nParts:\n\n- ESP32-S3 Development Board N16R8 with USB-C\n- ILI9341 2.8-inch SPI TFT LCD Display Touch Panel, 240x320\n- MAX98357 I2S DAC Class D Amplifier Module\n- Small speaker for the MAX98357 output\n- INMP441 omnidirectional I2S MEMS microphone module\n- Jumper wires and a breadboard or soldered prototype board\n\nFirmware and wiring guide:\n\n```text\nfirmware/esp32-s3-wisp/README.md\n```\n\nBuild check from this repo:\n\n```bash\nbash scripts/build_esp32_s3.sh\n```\n\nThe ESP32-S3 firmware currently supports Wi-Fi Hub pairing, check-ins, Hub\ncommand polling, touch navigation, touchscreen approvals, local demo actions,\nworkflow triggering, direct `Ask AI` through NodeSparkHub, rich cards, dashboard\nitems, notifications, icon grids, QR/link screens, startup logo screens, device\nhealth checks, I2S chimes, INMP441 mic level testing, and the shared Wisp Mobile\nBridge BLE protocol when `WISP_ENABLE_BLE` is enabled. ESP32-S3 Bluetooth stays\nopt-in because some boards become unstable when BLE, Wi-Fi, HTTPS, I2S, and TFT\nUI are all active.\n\n## M5Stack Core2 Wisp\n\n### Hardware Needed\n\nThe M5Stack Core2 build is the easiest premium microcontroller Wisp because the\ninteractive hardware is already inside the unit.\n\nParts:\n\n- M5Stack Core2\n- USB-C cable\n- Optional microSD card, 16 GB or smaller recommended\n- Wi-Fi network reachable by NodeSparkHub, or an HTTPS/Cloudflare Hub URL\n\nFirmware guide:\n\n```text\nfirmware/m5stack-core2-wisp/README.md\n```\n\nBuild check from this repo:\n\n```bash\nbash scripts/build_m5stack_core2.sh\n```\n\nThe Core2 firmware supports the NodeSpark mascot startup screen, touch\nnavigation, virtual hardware buttons, Hub pairing, automatic check-ins, command\npolling, approvals, rich cards, Ask AI, workflow launch, speaker chimes, haptic\nfeedback, volume control, mic level visualization, battery/charging status, IMU\nreadings, SD card health logging, and Bluetooth Mobile Bridge for NodeSpark iOS.\n\n## Quick Install\n\n### Downloadable Raspberry Pi Image\n\nThe easiest path for customers is the custom NodeSpark Wisp Raspberry Pi OS\nimage. It is built from Raspberry Pi OS Lite with Wisp preinstalled and\nenabled as a boot service.\n\nImage build recipe:\n\n```text\nimage/README.md\n```\n\nBuild the image from this repo on Linux or Docker:\n\n```bash\nbash scripts/build_pi_image.sh\n```\n\nThen users can:\n\n1. Open Raspberry Pi Imager.\n2. Choose **Use custom** and select the NodeSpark Wisp `.img.xz`.\n3. Set Wi-Fi, username/password, locale, and SSH in Imager.\n4. Flash the microSD card.\n5. Optional: copy `nodespark-wisp.toml.example` to `nodespark-wisp.toml` on the\n   boot partition and set the Hub URL.\n6. Boot the Pi with the Whisplay HAT attached.\n7. Pair from NodeSparkHub.\n\nThe factory image does not include a shared default login password. That keeps\npublic downloads safer while still making the Wisp software start\nautomatically.\n\n### Manual Pi Install\n\nOn the Raspberry Pi:\n\n```bash\ngit clone https://github.com/synryzen/nodespark-wisp.git\ncd nodespark-wisp\nbash scripts/install_pi.sh\n```\n\nEdit the Hub URL and favorite workflows:\n\n```bash\nsudo nano /etc/nodespark-wisp/config.toml\n```\n\nIn NodeSparkHub on your Mac:\n\n1. Start NodeSparkHub.\n2. Start the Hub server.\n3. Open `Settings -\u003e Intelligence` and confirm `Wisp Assistant` is enabled.\n4. Open `Settings -\u003e Hub Server -\u003e Devices`.\n5. Generate a pairing code.\n\nThen pair the Pi:\n\n```bash\n/opt/nodespark-wisp/scripts/pair_device.sh 123456\n```\n\nStart the background service:\n\n```bash\nsudo systemctl enable --now nodespark-wisp\njournalctl -u nodespark-wisp -f\n```\n\nFor the full setup guide, see [docs/INSTALL.md](docs/INSTALL.md).\n\n## First Demo\n\nAfter the Wisp appears in NodeSparkHub's device list, copy its device ID and run\nthese from the Mac or from a terminal that can reach the Hub:\n\n```bash\ncurl http://127.0.0.1:8787/devices\n```\n\nShow a display message:\n\n```bash\nbash scripts/send_demo_command.sh \u003cdevice-id\u003e display \"A Stripe order arrived. NodeSparkHub routed it to this device.\"\n```\n\nMake the device speak:\n\n```bash\nbash scripts/send_demo_command.sh \u003cdevice-id\u003e speak \"NodeSparkHub just controlled a Raspberry Pi display from a workflow.\"\n```\n\nShow a rich card:\n\n```bash\nbash scripts/send_demo_command.sh \u003cdevice-id\u003e card \"The workflow finished and the physical device updated instantly.\"\n```\n\nRun the full showcase:\n\n```bash\nbash scripts/send_demo_command.sh \u003cdevice-id\u003e demo \"Physical workflows are live.\"\n```\n\nThat is the moment people understand it: NodeSparkHub can receive an event, run\nautomation logic, then command a real device as an output surface.\n\n## Hub-To-Device Commands\n\nSupported Wisp command types:\n\n- `display`: show a title/body text screen.\n- `card`: show a branded rich card with style, icon, subtitle, footer, and progress.\n- `approval`: show an approve/reject prompt; short press approves, hold rejects.\n- `notification` or `notify`: add an alert to the device notification stack.\n- `dashboard`: show a compact metric dashboard with list items.\n- `graphics` or `icons`: show a visual icon grid.\n- `speak`: speak text through the Wisp speaker.\n- `volume`: set Whisplay speaker volume with `percent`, `volume`, or `level`.\n- `led`: set the RGB LED color.\n- `ping`: show a live connectivity ping.\n- `logo`, `splash`, or `startup`: show the branded NodeSpark mascot screen.\n- `qr`: show custom QR data, or the pairing/device-identity QR screen.\n- `demo`: run the sales-showcase sequence.\n- `runWorkflow`: ask the device to start another Hub workflow.\n- `selectWorkflow`: change the selected favorite workflow.\n- `workflows`: show the currently synced Hub workflow list on the device.\n\nWisp-originated assistant requests use `POST /wisp/assistant` and return text\nplus optional speech audio when NodeSparkHub can synthesize a voice response.\n\nRun a full Mac-side smoke check before demos:\n\n```bash\nscripts/wisp_smoke_test.py\n```\n\nThat verifies Hub health, workflow listing, registered Wisp devices, and the\ndirect Wisp Assistant AI path. When a device is powered on and freshly checked\nin, queue the command suite:\n\n```bash\nscripts/wisp_smoke_test.py --send --all-wisp\n```\n\nOr target one known device:\n\n```bash\nscripts/wisp_smoke_test.py --send --device-id \u003cdevice-id\u003e\n```\n\nRaw rich-card example:\n\n```bash\ncurl -X POST \"http://127.0.0.1:8787/devices/\u003cdevice-id\u003e/commands\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"type\":\"card\",\"style\":\"ai\",\"icon\":\"ai\",\"title\":\"AI Result\",\"subtitle\":\"NodeSparkHub\",\"body\":\"The workflow finished and the physical device updated instantly.\",\"progress\":0.82,\"rgb\":[0,190,255]}'\n```\n\nApproval example:\n\n```bash\ncurl -X POST \"http://127.0.0.1:8787/devices/\u003cdevice-id\u003e/commands\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"type\":\"approval\",\"title\":\"Approval Needed\",\"body\":\"Approve the next workflow step?\",\"choices\":[\"Approve\",\"Reject\"],\"rgb\":[255,180,50]}'\n```\n\nDashboard example:\n\n```bash\ncurl -X POST \"http://127.0.0.1:8787/devices/\u003cdevice-id\u003e/commands\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"type\":\"dashboard\",\"title\":\"Workflow Monitor\",\"metricLabel\":\"Hub\",\"metricValue\":\"Live\",\"items\":[\"Server online\",\"Watchers active\",\"Device paired\"],\"rgb\":[45,160,255]}'\n```\n\n## Voice And Button Controls\n\nDefault button behavior:\n\n- Short press: cycle through favorite Hub workflows.\n- Hold: record a short voice command and run the selected workflow.\n- During approval: short press approves, hold rejects.\n\nThe simplest first voice test is text-only:\n\n```bash\n/opt/nodespark-wisp/.venv/bin/nodespark-wisp run --workflow \"Wisp Assistant\" --text \"hello from the pi\"\n```\n\nFor OpenAI transcription, set:\n\n```toml\n[audio]\ntranscription_provider = \"openai\"\nopenai_model = \"gpt-4o-mini-transcribe\"\n```\n\nThen export `OPENAI_API_KEY` for the service, or put it in the config file.\nFor a product build, prefer an environment variable or secret manager over\nstoring the key directly in TOML.\n\nFor offline transcription, install `vosk`, download a small model, and set:\n\n```toml\n[audio]\ntranscription_provider = \"vosk\"\nvosk_model_path = \"/opt/nodespark-wisp/models/vosk\"\n```\n\n## Wisp Mobile Bridge\n\nWisp Mobile Bridge is an optional Bluetooth LE mode for travel demos and\non-the-go control. It lets NodeSpark on iPhone connect directly to the Wisp,\nsend display/speech/dashboard commands, and forward Wisp events into\nNodeSparkHub when the iPhone has a Hub connection. Raspberry Pi Wisp and\nM5Stack Core2 can advertise this bridge directly; ESP32-S3 includes the same\nbridge behind `WISP_ENABLE_BLE` for boards that stay stable with BLE enabled.\n\nThe standard Wi-Fi/Hub connection remains the best full-time setup. Bluetooth\nbridge mode is for mobile use when the Wisp is near the iPhone.\n\nEnable it on Raspberry Pi Wisp:\n\n```bash\nsudo nano /etc/nodespark-wisp/config.toml\n```\n\nSet:\n\n```toml\n[bluetooth]\nenabled = true\ndevice_name = \"NodeSpark Wisp\"\n```\n\nRestart:\n\n```bash\nsudo systemctl restart nodespark-wisp\n```\n\nOn M5Stack Core2, BLE Mobile Bridge is enabled by default in\n`firmware/m5stack-core2-wisp/nodespark_wisp_core2/config.example.h` with\n`WISP_ENABLE_BLE 1`.\n\nOn ESP32-S3, set `WISP_ENABLE_BLE` to `1` in `config.h` only after the\ndisplay/touch/Wi-Fi/audio build is stable.\n\nIn NodeSpark on iPhone, open:\n\n```text\nSettings -\u003e Hub Pairing \u0026 Control -\u003e Wisp Mobile Bridge\n```\n\nThen scan, connect, and try Ping or Demo Card.\n\nBLE protocol:\n\n- Service: `4E530001-4E53-5749-5350-000000000001`\n- Command characteristic, write: `4E530002-4E53-5749-5350-000000000001`\n- Event characteristic, notify/read: `4E530003-4E53-5749-5350-000000000001`\n- State characteristic, notify/read: `4E530004-4E53-5749-5350-000000000001`\n\nCommands are compact JSON objects using the same command shapes as the Hub\ndevice command channel, such as `display`, `card`, `dashboard`, `speak`, `led`,\n`ping`, and `demo`.\n\nDevice-originated `assistant` and `runWorkflow` events include `text`, `body`,\n`detail`, `workflowName`, and device identity so NodeSpark iOS can forward them\nto NodeSparkHub over the user's current iPhone connection.\n\n## Startup Logo\n\nThe device uses the bundled NodeSpark mascot at startup. To swap in a different\nPNG later, copy it onto the Pi and set:\n\n```toml\n[display]\nstartup_logo_enabled = true\nstartup_logo_path = \"/home/pi/my-logo.png\"\n```\n\nLeave `startup_logo_path` blank to use the built-in mascot.\n\n## Status, QR, And Updates\n\nPrint device status:\n\n```bash\n/opt/nodespark-wisp/.venv/bin/nodespark-wisp status\n```\n\nShow the pairing QR on the LCD:\n\n```bash\n/opt/nodespark-wisp/.venv/bin/nodespark-wisp qr\n```\n\nRefresh the installed package/dependencies and restart the service:\n\n```bash\n/opt/nodespark-wisp/scripts/update_pi.sh\n```\n\nIf the Pi install is a Git checkout, the update command pulls first. If it was\ncopied with `install_pi.sh`, re-copy the folder from your Mac and run\n`update_pi.sh`.\n\n## Sales Demo Flow\n\n1. Start NodeSparkHub on the Mac and start the Hub server.\n2. Pair the Wisp device.\n3. Show the device appearing in connected devices.\n4. Run a workflow from the physical button.\n5. Send a Hub-to-device command that changes the screen and speaks.\n6. Open the Template Library and use one of the Wisp templates:\n   - `Wisp Device Showcase`\n   - `Wisp AI Voice Reply`\n   - `Physical Approval Ping`\n7. Explain the bigger idea: NodeSparkHub connects iPhone, Mac, bots, APIs,\n   schedules, and physical devices into one workflow system.\n\n## Workflow Payload\n\nButton-triggered runs send this payload to NodeSparkHub:\n\n```json\n{\n  \"source\": \"wisp\",\n  \"deviceId\": \"...\",\n  \"deviceName\": \"NodeSpark Wisp\",\n  \"text\": \"transcribed voice command\",\n  \"input\": \"transcribed voice command\",\n  \"utterance\": \"transcribed voice command\",\n  \"timestamp\": \"...\"\n}\n```\n\nIn your workflow nodes, use `{{input.text}}`, `{{input}}`, or payload fields\ndepending on the NodeSparkHub node.\n\n## Critical Notes\n\n- NodeSparkHub must be running and reachable on the same network unless you\n  expose the Hub another way.\n- Pairing creates the device token used for Hub check-ins and command polling.\n- Treat device tokens like credentials.\n- Keep the Hub server URL updated if the Mac IP address changes.\n- The Whisplay/WM8960 audio driver may require a reboot after installation.\n- Voice features are optional. Display, button, workflow, QR, and command\n  features work without cloud transcription.\n- The legacy `nodespark-whisplay` command is still available as a compatibility\n  alias, but new installs should use `nodespark-wisp`.\n\n## Whisplay Driver\n\nThe installer clones PiSugar's official Whisplay repo into `/opt/Whisplay`. If\naudio is not visible in `arecord -l` and `aplay -l`, install the WM8960 driver\nand reboot:\n\n```bash\nsudo bash /opt/Whisplay/Driver/install_wm8960_drive.sh\nsudo reboot\n```\n\n## Development From Your Mac\n\nYou can run the non-hardware parts locally:\n\n```bash\ncp config.example.toml config.toml\n# edit config.toml to point at your Hub\nbash scripts/run_dev.sh health\nbash scripts/run_dev.sh workflows\nbash scripts/run_dev.sh run --workflow \"Wisp Assistant\" --text \"test\"\n```\n\n## License\n\nMIT License. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsynryzen%2Fnodespark-wisp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsynryzen%2Fnodespark-wisp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsynryzen%2Fnodespark-wisp/lists"}