Cury scripts: production-ready structure, docs, and manifest/index sync

CHANGELOG.md

@@ -13,6 +13,9 @@ All notable changes to this project will be documented in this file.
 - Add dev branch to CI/CD pull_request trigger
 - Mark SDS011 examples as under development
 - Mark all the_pill examples as under development
+- Expand `cury/` README files with per-script use cases and user personas
+- Standardize JSDoc metadata headers for all `cury/**/*.shelly.js` scripts (`@title`, `@description`, `@status`, `@link`)
+- Reorganize `cury/` examples into `light-language/`, `button-control/`, and `legacy/` folders with README files and duplicate analysis notes
 - Add `switch-input/rgbw-remote-controll.shelly.js` and register it in the manifest/index
 - Restructure loose HTTP integration scripts into per-script folders with matching README files
 - Fix incomplete Prometheus move (update manifest, @link, README, delete old file)

SHELLY_MJS.md

@@ -123,10 +123,30 @@ blu-assistant/print-label-online.shelly.js: BLU device label printer
 ===
 Scans for Shelly BLU devices and sends device info to an online label printer.
 
+cury/button-control/cury-btn-listener.shelly.js: Cury Button Listener
+===
+Listens for BLU button events and controls the paired Cury animation script.
+
+cury/button-control/cury-btn-test.shelly.js: Cury Button Test Scanner
+===
+Scans BTHome BLE advertisements, logs nearby devices, and prints decoded events for the target BLU button.
+
 cury/cury-light-language-2.shelly.js: Cury Light Language v2
 ===
 Expressive light patterns for Shelly Cury UI and ambient LEDs with 9 communication states.
 
+cury/legacy/cury-mini.shelly.js: Cury Mini Legacy
+===
+Compact legacy Cury light-language implementation with built-in state logic, timing patterns, and periodic hardware checks.
+
+cury/light-language/cury-light-language-2.shelly.js: Cury Light Language v2
+===
+Expressive light patterns for Shelly Cury UI and ambient LEDs with 9 communication states.
+
+cury/light-language/cury-light-language-v2.shelly.js: Cury Intensity Crossfade and Ambient Fade
+===
+Runs a 6-step Cury animation loop with crossfading UI intensity and ambient color flash/fade transitions.
+
 howto/input-event.shelly.js: Example - Input events
 ===
 Example showing how to work with Input component's events.
@@ -396,13 +416,13 @@ the_pill/MODBUS/Deye/the_pill_mbsa_deye_vc.shelly.js: Deye SG02LP1 MODBUS-RTU +
 ===
 MODBUS-RTU reader for Deye SG02LP1 solar inverter with Virtual Component updates. Reads parameters over UART (RS485) and pushes values to user-defined virtual number components.
 
-the_pill/UART/uart_test.shelly.js: UART test
+the_pill/MODBUS/JK200-MBS/the_pill_mbsa_jk200.shelly.js: JK200 BMS MODBUS-RTU Reader
 ===
-Simple UART loopback test that sends periodic messages and prints received data.
+MODBUS-RTU reader for Jikong JK-PB series BMS over RS485.
 
-the_pill/ys_irtm/ysirtm.shelly.js: YS-IRTM infrared UART library
+the_pill/UART/uart_test.shelly.js: UART test
 ===
-UART protocol implementation for YS-IRTM to send and receive NEC IR codes.
+Simple UART loopback test that sends periodic messages and prints received data.
 
 the_pill/ys_irtm/btn2ir.shelly.js: YS-IRTM button-to-IR example
 ===
@@ -424,6 +444,10 @@ the_pill/ys_irtm/tv_ir.shelly.js: YS-IRTM TV remote codes
 ===
 Preconfigured NEC IR codes for common TV brands using YS-IRTM.
 
+the_pill/ys_irtm/ysirtm.shelly.js: YS-IRTM infrared UART library
+===
+UART protocol implementation for YS-IRTM to send and receive NEC IR codes.
+
 weather-env/cover-control-weather.shelly.js: Control a Shelly 2.5 (Gen1) depending on current cloud conditions
 ===
 The script, when run, will fetch via REST api from a weather service the current conditions for a location check if

cury/README.md

@@ -1,9 +1,31 @@
-# Cury
+# Cury Examples
 
-Expressive light patterns for Shelly Cury UI and ambient LEDs.
+Cury-specific scripts are grouped by purpose to make selection and testing easier.
 
-Use these scripts to create visual feedback and status communication through light patterns on Shelly Cury devices. The light language system supports 9 distinct states for different device conditions.
+## Folder Layout
 
-## Scripts
+- `light-language/` - UI/ambient animation engines
+- `button-control/` - BLE button listener and test utilities
+- `legacy/` - Compact or older variants kept for reference
 
-- `cury-light-language-2.shelly.js`
+## Use Case and Persona by Folder
+
+- `light-language/`
+  - Use case: Build branded LED behavior for product states (boot, ready, active, warning, error, night).
+  - User persona: UX/product engineer prototyping device feedback language.
+- `button-control/`
+  - Use case: Control Cury animation scripts from a BLU button and validate BLE event payloads.
+  - User persona: Field integrator or installer pairing physical controls with scripted behavior.
+- `legacy/`
+  - Use case: Keep a compact fallback script for quick deployment or regression comparison.
+  - User persona: Support engineer troubleshooting behavior differences across script revisions.
+
+## Duplicate and Variant Analysis
+
+- `button-control/cury-btn-listener.shelly.js` and `button-control/cury-btn-listener 1.shelly.js` are near-duplicates.
+  - Both map BLU button actions to animation control.
+  - `cury-btn-listener 1.shelly.js` adds BLE scanner options (`addr` filter + `active: false`) and extra comments.
+- `light-language/cury-light-language-2.shelly.js` and `light-language/cury-light-language-v2.shelly.js` are different implementations, not duplicates.
+  - `-2` is a state-machine light language with 9 states.
+  - `-v2` is a step-based crossfade animation loop.
+- `legacy/cury-mini.shelly.js` is a compact/legacy-style variant close in behavior to `cury-light-language-2.shelly.js`, but includes extra condensed logic and hardware polling.

cury/button-control/README.md

@@ -0,0 +1,19 @@
+# Cury Button Control
+
+BLE button listeners and validation helpers.
+
+## Files
+
+- `cury-btn-listener.shelly.js`
+  - Use case: Primary BLU button integration to start/stop animation and cycle colors.
+  - User persona: Smart-home installer deploying a single reliable control script.
+- `cury-btn-listener 1.shelly.js`
+  - Use case: Same control flow as primary listener, but optimized BLE subscription (`addr` filter, passive scan).
+  - User persona: Performance-focused developer reducing BLE processing noise in dense RF environments.
+- `cury-btn-test.shelly.js`
+  - Use case: Discovery and validation of BTHome button events before production mapping.
+  - User persona: QA/test engineer verifying button packet content and debouncing behavior.
+
+## Duplicate Note
+
+`cury-btn-listener.shelly.js` and `cury-btn-listener 1.shelly.js` are functionally similar; keep one active for production usage.

cury/button-control/cury-btn-listener.shelly.js

@@ -0,0 +1,55 @@
+/**
+ * @title Cury Button Listener
+ * @description Listens for BLU button events and controls the paired Cury animation script.
+ * @status production
+ * @link https://github.com/ALLTERCO/shelly-script-examples/blob/main/cury/button-control/cury-btn-listener.shelly.js
+ */
+
+var ANIM_ID  = 1;
+var BLU_ADDR = "bc:02:6e:c3:a3:0e";
+var lastPid  = -1;
+
+function bthomeParseByte(svc, objId) {
+  var i = 1;
+  while (i + 1 < svc.length) {
+    if (svc.charCodeAt(i) === objId) return svc.charCodeAt(i + 1);
+    i += 2;
+  }
+  return -1;
+}
+
+function onTap() {
+  print("[Cury] BTN: next color");
+  Shelly.call("Script.Eval", { id: ANIM_ID, code: "nextColor();" });
+}
+
+function onDoubleTap() {
+  print("[Cury] BTN: stop animation");
+  Shelly.call("Script.Stop",    { id: ANIM_ID });
+  Shelly.call("Cury.Set",       { id: 0, slot: "right", on: false });
+  Shelly.call("Cury.Set",       { id: 0, slot: "left",  on: false });
+  Shelly.call("Cury.SetConfig", { id: 0, config: {
+    ambient: { enable: false, brightness: 0 },
+    ui:      { mode: "level", brightness: 100 }
+  }});
+}
+
+function onLongPress() {
+  print("[Cury] BTN: start animation");
+  Shelly.call("Script.Start", { id: ANIM_ID });
+}
+
+BLE.Scanner.Subscribe(function(ev, res) {
+  if (ev !== BLE.Scanner.SCAN_RESULT) return;
+  if (!res || res.addr !== BLU_ADDR) return;
+  var svc = res.service_data && res.service_data["fcd2"];
+  if (!svc) return;
+  var pid = bthomeParseByte(svc, 0x00);
+  var btn = bthomeParseByte(svc, 0x3A);
+  if (pid >= 0 && pid === lastPid) return;
+  lastPid = pid;
+  if (btn <= 0) return;
+  if (btn === 1) { onTap();       return; }
+  if (btn === 2) { onDoubleTap(); return; }
+  if (btn === 4) { onLongPress(); return; }
+});

cury/button-control/cury-btn-test.shelly.js

@@ -0,0 +1,50 @@
+/**
+ * @title Cury Button Test Scanner
+ * @description Scans BTHome BLE advertisements, logs nearby devices, and prints decoded events for the target BLU button.
+ * @status production
+ * @link https://github.com/ALLTERCO/shelly-script-examples/blob/main/cury/button-control/cury-btn-test.shelly.js
+ */
+
+// MAC must be lowercase to match res.addr from BLE scanner.
+
+var BLU_ADDR = "bc:02:6e:c3:a3:0e";  // lowercase!
+var lastPid = -1;
+
+function parseByte(svc, objId) {
+  var i = 1; // skip device info byte at pos 0
+  while (i + 1 < svc.length) {
+    if (svc.charCodeAt(i) === objId) return svc.charCodeAt(i + 1);
+    i += 2;
+  }
+  return -1;
+}
+
+BLE.Scanner.Subscribe(function(ev, res) {
+  if (ev !== BLE.Scanner.SCAN_RESULT) return;
+  if (!res || !res.addr) return;
+
+  var svc = res.service_data && res.service_data["fcd2"];
+  if (!svc) return; // not a BTHome device
+
+  // Print ALL BTHome devices seen (to discover what's in range)
+  if (res.addr !== BLU_ADDR) {
+    print("[SCAN] BTHome device: " + res.addr);
+    return;
+  }
+
+  // Our target button
+  var pid = parseByte(svc, 0x00);
+  var btn = parseByte(svc, 0x3A);
+
+  if (pid === lastPid) return;
+  lastPid = pid;
+
+  print("[BTN] pid=" + pid + " btn=" + btn);
+
+  if (btn === 1) print("[BTN] SINGLE PRESS");
+  if (btn === 2) print("[BTN] DOUBLE PRESS");
+  if (btn === 3) print("[BTN] TRIPLE PRESS");
+  if (btn === 4) print("[BTN] LONG PRESS");
+});
+
+print("[BTN] Listening... target=" + BLU_ADDR);

cury/legacy/README.md

@@ -0,0 +1,13 @@
+# Cury Legacy
+
+Legacy or compact scripts retained for reference.
+
+## Files
+
+- `cury-mini.shelly.js`
+  - Use case: Single-file compact fallback when memory/readability tradeoffs are acceptable.
+  - User persona: Maintenance engineer needing a concise script for quick rollback or constrained deployments.
+
+## Note
+
+Prefer scripts in `../light-language/` + `../button-control/` for clearer maintenance.