docs(iATS): Expand automatic-transfer-switch script descriptions with full paragraphs and direct links#205
Closed
orlin369 wants to merge 66 commits into
Closed
docs(iATS): Expand automatic-transfer-switch script descriptions with full paragraphs and direct links#205orlin369 wants to merge 66 commits into
orlin369 wants to merge 66 commits into
Conversation
…scripts - button-event-source.shelly.js: routes physical button "one"/"two" events; button ONE triggers wifi-provisioning via Script.Eval - wifi-provisioning.shelly.js: BLE scans for devices matching TARGET_MODEL_IDS (array of Gen3/Gen4 model IDs) and provisions them as WiFi STA clients with retry queue; includes full Gen3/Gen4 model ID reference in comments - README.md: updated with section 4 documenting the two-script pair, updated TOC, added troubleshooting entries for the new scripts Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Add aicb2sp.shelly.js: polls voltage, current, power, energy, frequency, power factor, temperature; exposes switchOn/switchOff - Add AICB2SP and GACIA vendor READMEs with register map and wiring - Update MODBUS root README index with GACIA/ entry - Update CHANGELOG Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Add sen0492.shelly.js: console reader, polls distance and status - Add sen0492_vc.shelly.js: console + Virtual Component (number:200) - Add SEN0492 and DFRobot vendor READMEs with full register map, cable colours, and wiring table - Update MODBUS root README index with DFRobot/ entry - Promote both scripts to production - Update CHANGELOG Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Add screenshot.png showing Distance VC (188 mm) grouped under DFRobot SEN0492 in the Shelly UI - Add Screenshot section to README with caption Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Add titles/descriptions for 10 previously undocumented scripts (BLU Assistant, MODBUS integrations). Enhance sync-manifest-md.py to auto-extract metadata from source files when --extract-metadata flag is used and entry has TODO placeholders. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Rename Davis screenshot to screenshot.png and add ## Screenshot section to Davis README - Add rs485-diagram.png/svg to the_pill/MODBUS and reference it in README - Add missing_screenshots.md listing all examples that still need UI screenshots Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Add Fronius grid flow integration with virtual component handles - Add under-development multi-channel Fronius dashboard variant - Update changelog for the Fronius script changes Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
into dev # Conflicts: # the_pill/MODBUS/DFRobot/README.md # the_pill/MODBUS/DFRobot/SEN0492/README.md # the_pill/MODBUS/DFRobot/SEN0492/sen0492.shelly.js # the_pill/MODBUS/DFRobot/SEN0492/sen0492_vc.shelly.js # the_pill/MODBUS/GACIA/AICB2SP/README.md # the_pill/MODBUS/GACIA/AICB2SP/aicb2sp.shelly.js # the_pill/MODBUS/GACIA/README.md
- add static-config EcoFlow STREAM Ultra load-balancing scripts - add parent and device README files with usage and screenshot - record the new HTTP integration in the changelog Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- remove repeated RS485 pinout text from DFRobot and GACIA docs - remove redundant Davis screenshot block - trim duplicate entries from the MODBUS root README Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- restructure Tasmota HTTP integrations into collection and device folders - standardize the Mitsubishi Heavy AC Shelly script and anonymize endpoint placeholders - add parent and device README files plus screenshot references Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Mark EcoFlow STREAM Ultra VC load balancing as production - Mark Mitsubishi Heavy Tasmota IR bridge as production - Update related READMEs, manifest, and generated MJS index Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Adds modbus_register_scan.shelly.js: a generic single-register FC03/FC04 walker for The Pill that assumes slave address, baud rate, and UART mode are already known. Designed to run a full discovery pass and print all readable addresses in the configured range, with OK/exception/timeout counts in the final summary. Extracted from the V-TAC-specific vtac_modbus_scan so it can be reused for any MODBUS-RTU device. Updates utils/README.md to document the new script alongside modbus_scan.shelly.js and clarifies when to use each utility (bus discovery vs. register-space walking). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Adds documentation and reverse-engineering notes for the V-TAC VT-66036103 hybrid solar inverter, which exposes RS485 but ships with no public register map. - README.md: context, persona, file index, and RS485 wiring diagram for The Pill - label.md: physical label data and official/mirror document links for VT-66036103 - registers.md: all FC03 holding and FC04 input register addresses discovered by live scanning on the actual inverter, with raw values at capture time - register-proposals.md: inferred naming, scaling, grouping, and confidence levels for discovered registers based on cross-referencing published electrical specs with the INVT single-phase hybrid family (V-TAC identifies INVT as the OEM brand) Six high-confidence live-telemetry registers identified so far: 5776 pv1_voltage 0.1 V 5778 pv2_voltage 0.1 V 5784 input_voltage 0.1 V 5786 output_voltage 0.1 V 5790 power 0.01 W 5792 frequency 0.01 Hz Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Four scripts for reading and monitoring the V-TAC VT-66036103 inverter via RS485/MODBUS-RTU from The Pill, all targeting slave ID 1, 9600 8N1: vtac_six_register_example.shelly.js Compact console reader for the six strongest live-telemetry candidates: PV1/PV2 voltage, input/output voltage, power, and frequency. Polls every 15s. vtac_six_register_example_vc.shelly.js Virtual Components variant of the above. Auto-creates a group:200 and six Number VCs (number:200-205) with appropriate icons, units, and range limits. Updates VCs every 15s alongside console output. vtac_baseline_watch.shelly.js Polls all ~100 currently known readable holding and input registers every 15s and reports only registers that deviate from their captured baseline values. Used to detect which registers move with live inverter state (PV, load, grid). Register blocks encoded as compact strings to keep heap usage manageable. vtac_inferred_reader.shelly.js Console reader for the 23 highest-confidence inferred holding registers from the proposal map, covering battery limits, PV ratings, AC ratings, grid code thresholds, and frequency trip points. Prints scaled values every 15s. All four are marked @status under development; none go into the manifest yet. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Collected vendor and mirror documents for the two main V-TAC hybrid inverter models in this family (VT-66036103 is the 3.6 kW unit on the bench; VT-6607103 is the 5 kW sibling sharing the same MODBUS interface): - vt-6607103.pdf: instruction manual for VT-6607103 (5 kW) - vt66036103.pdf: instruction manual for VT-66036103 (3.6 kW) - VT-6607103_Single-phase_hybrid_inverter_5kW.pdf: downloaded from V-TAC exports portal; confirms RS485, baud rate options (2400/4800/9600), and default slave address 1 — but contains no MODBUS register map - VT-66036103_manualslib_download.html: ManualsLib mirror page for VT-66036103 kept as an offline reference Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
MODBUS/README.md: adds V-TAC/ entry to the device directory listing and updates the utils/ description to mention register-space discovery alongside bus-level scanning. CHANGELOG.md: records all V-TAC work done on this branch — vtac_modbus_scan iterations, baseline watcher, inferred reader, six-register example, VC variant, register-proposals.md, power-scale correction (0.1→0.01 W), and the promotion of vtac_modbus_scan logic to the generic utils scanner. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Adds screenshot.png showing vtac_six_register_example_vc.shelly.js running live on The Pill: six Virtual Components (PV1/PV2 voltage, input/output voltage, power, frequency) with real inverter values in the Shelly app. Updates README.md to match the project example style: - Adds ## Screenshot section with image and live-value description - Fixes label.MD reference to label.md (case) - Removes "under-development" qualifiers from file descriptions Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Brings in V-TAC VT-66036103 hybrid inverter work: - Generic MODBUS register-space scanner (utils/modbus_register_scan.shelly.js) - V-TAC scripts: six-register example, VC variant, baseline watcher, inferred reader - Discovered register data, inferred register map, device documentation - Datasheets for VT-66036103 and VT-6607103 - Screenshot of live Virtual Components in Shelly app Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Extend min from 125 to 0 and max from 500 to 600 so setValue does not silently clamp when the inverter reports 0 V (off or below MPPT threshold), which previously made PV1 and PV2 CVs appear frozen. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Add Marstek VenusE console and Virtual Component readers - Document register map, RJ45 pinout, validation notes, and screenshots - Move V-TAC VT6607103 work into its own device folder Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Mark the three Marstek VenusE read-only MODBUS scripts as production - Regenerate examples manifest and SHELLY_MJS index - Update VenusE documentation and changelog
Implements the main controller for an Intelligent Automatic Transfer Switch (iATS) running on Shelly Pro 2 / Pro 2PM / Plus 2PM / 2PM Gen3/Gen4 devices. Key design decisions: - Inputs (SW1/SW2) are detached from outputs on boot to prevent the Shelly firmware from directly toggling the contactors; the script is the sole owner of switch:0 (K2 backup) and switch:1 (K1 grid). - Startup is aborted if detach + verification fails (configurable via START_IF_DETACH_VERIFICATION_FAILS). - Both outputs are opened before selecting a new source; a configurable TRANSFER_DELAY_MS gap prevents brief parallel-contactor overlap. - A debounce timer (DEBOUNCE_MS) prevents rapid re-evaluation on input chatter. - Manual override is received from the Sensor Add-on helper script via KVS key "iats.manual_control"; a stale-sequence watchdog reverts to AUTO after MANUAL_CONTROL_MAX_STALE_POLLS missed updates. Truth table: SW2 SW1 | O2 O1 | State 0 0 | 0 0 | OFF 0 1 | 1 0 | GRID 1 0 | 0 1 | BACKUP 1 1 | 1 0 | GRID priority Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Companion script for the iATS controller that runs on the Shelly Pro Sensor Add-on to let an operator override source selection via two digital inputs. Input mapping: - DIN0 (input:100): LOW = AUTO, HIGH = MANUAL - DIN1 (input:101): LOW = GRID, HIGH = PV/backup The script publishes mode/target/sequence to KVS key "iats.manual_control" at a configurable PUBLISH_MS interval. It does NOT touch switch outputs; iats_grid_backup_controller.shelly.js remains the only owner of the contactors and validates source availability before acting on manual requests. An incrementing sequence number lets the controller detect stale KVS values (no publish heartbeat) and fall back to AUTO+OFF automatically. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Adds the iATS (Intelligent Automatic Transfer Switch) Shelly script pair: - iats_grid_backup_controller: two-channel grid/backup contactor controller with input detachment, transfer delay, debounce, and KVS-based manual override - iats_sensor_addon_manual_control: Sensor Add-on helper that publishes AUTO/MANUAL + GRID/PV selection to KVS for the controller to consume Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
One-shot Shelly script that provisions nine virtual Number components (IDs 220–228) and groups them under a "Victron Energy" group (ID 219). Run it once on the target device; it is safe to re-run (Virtual.Add silently skips already-existing IDs). Components created: 220 – Battery SOC (%, 0–100, step 0.01) 221 – Battery Power (W, ±100000, step 1) 222 – Total Grid Power (W, ±100000, step 1) 223 – Grid Voltage L1 (V, 0–1000, step 0.1) 224 – Current L1 (A, ±10000, step 0.01) 225 – AC Frequency (Hz, 0–100, step 0.01) 226 – PV1 Power (W, 0–100000, step 1) 227 – PV1 Voltage (V, 0–1000, step 0.1) 228 – Total Power (W, 0–100000, step 1) Each component is configured with a progressbar UI hint so that the Shelly app renders it as a live gauge. After provisioning the group, the script calls die() to free memory; it is not meant to run permanently. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Exports a Node-RED tab "Victron → Shelly Virtual" that continuously reads live telemetry from a Victron system via node-red-contrib-victron and forwards each value to the corresponding Shelly virtual Number component via HTTP POST to Number.Set. Data sources and targets: Battery SOC (battery/2 /Soc) → VC 220 Battery Power (battery/2 /Dc/0/Power) → VC 221 Total Grid Power (vebus/276 /Ac/ActiveIn/L1/P) → VC 222 Grid Voltage L1 (vebus/276 /Ac/ActiveIn/L1/V) → VC 223 Current L1 (vebus/276 /Ac/ActiveIn/L1/I) → VC 224 AC Frequency (vebus/276 /Ac/ActiveIn/L1/F) → VC 225 PV1 Power (solarcharger/279 /Yield/Power) → VC 226 PV1 Voltage (solarcharger/279 /Dc/0/Voltage)→ VC 227 Active Input (vebus/276 /Ac/ActiveIn/ActiveInput) → VC 228 All nodes use rateLimit=0.2 s with a 2000 ms debounce and 2 decimal rounding. The HTTP node targets the Shelly at 10.101.7.56; update the URL to match the target device address before importing. Requires: @victronenergy/node-red-contrib-victron 1.6.64+ Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Adds the Victron Energy → Shelly virtual components integration: - victron-virtual-components-setup.shelly.js: one-shot provisioning script that creates and configures Number virtual components 220–228 and groups them under "Victron Energy" (group 219) - victron-to-shelly-virtual.nodered.json: Node-RED flow that bridges live Victron telemetry (battery, VE.Bus, MPPT) to those virtual components via Number.Set HTTP RPC calls Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Empty sentinel file that signals to Codex/AI tooling that this repository has been indexed and is ready for AI-assisted code navigation. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Adds the empty .codex sentinel file for AI tooling integration. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Brings three scripts into line with the repository convention of /** @title @description @status @link */ headers used across all other power-energy scripts. - iats_grid_backup_controller.shelly.js: replaced bare /* */ block - iats_sensor_addon_manual_control.shelly.js: replaced bare /* */ block - victron-virtual-components-setup.shelly.js: added missing header Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Adds standard JSDoc headers (@title, @description, @status, @link) to the iATS controller, iATS Sensor Add-on helper, and Victron VC setup scripts. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Documents the iATS two-script architecture: controller device wiring, I/O mapping, truth table, safety behaviour (detach, open-before-close, debounce, transfer guard, stale-override watchdog), control modes, KVS interface between the two scripts, all configuration constants, and installation steps. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Adds README.md to power-energy/automatic-transfer-switch covering wiring, I/O mapping, truth table, safety behaviour, control modes, KVS interface, configuration reference, and installation steps. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Rewrites the minimal script list into a proper index with descriptions sourced from each script's @title/@description header. Adds the three new entries introduced on dev (victron-virtual-components-setup, victron-to-shelly-virtual Node-RED flow, automatic-transfer-switch subdirectory) and links every entry to its file or folder. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Updates power-energy/README.md to a full linked inventory covering all nine scripts, the Node-RED flow, and the automatic-transfer-switch subdirectory with one-line descriptions. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Brings in all changes from dev: - iATS automatic transfer switch scripts (controller + Sensor Add-on helper) - Victron virtual components setup script and Node-RED bridge flow - .codex marker file - JSDoc headers for iATS and Victron VC setup scripts - README for automatic-transfer-switch - Updated power-energy README with full linked inventory Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Replaces the Files table with a Scripts section containing a descriptive paragraph and direct GitHub link for each JS file, making the README self-contained for readers arriving from the repository browser. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Adds per-script paragraphs with GitHub links to the automatic-transfer-switch README. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Creates .claude/commands/ with four project-local slash commands that wrap the tools/ scripts: /upload (put_script.py), /check-manifest (check-manifest-integrity.py), /sync-manifest (sync-manifest-md.py), and /gen-index (sync-manifest-json.py). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What changed
The
power-energy/automatic-transfer-switch/README.mdScripts section has been rewrittenfrom a compact two-row table into per-script prose with absolute GitHub links.
Previously, each script got a one-line description in a table.
Now each script gets a dedicated subsection that explains:
Direct links to each
.jsfile on GitHub are included so readers canopen the source without cloning the repository.
Why this matters — for installers, electricians, and sales
Shelly installers / electricians commissioning a grid–backup site
Before wiring anything you need to know which script owns which terminal.
The expanded descriptions make it immediately clear that
iats_grid_backup_controller.shelly.jsis the sole owner of the contactoroutputs (
switch:0 / switch:1) and that it detaches the physical inputsfrom the outputs on boot — so the Shelly firmware cannot bypass the script
and accidentally close both contactors simultaneously.
PV / solar-backup installers
The Sensor Add-on companion script description now explicitly states that
it never touches switch:0 or switch:1 — it only publishes an override
request to KVS. The controller validates source availability before any
contactor moves. This matters when the backup source is a PV inverter that
can disappear mid-transfer.
Technical sales
The supported-devices list (Shelly Pro 2, Pro 2PM, Plus 2PM, 2PM Gen3/Gen4)
is unchanged and visible at a glance. The script links give a customer or
prospect a direct path from the README to the source code during a demo or
evaluation.
Related upstream context
The last three PRs merged into ALLTERCO/shelly-script-examples
(#201 – #203) promoted the Marstek VenusE RS485/MODBUS-RTU integration to
production. This PR targets the iATS (power-energy) track and does not
overlap with that work.
Type of change
Checklist
mainbranch of the upstream repo.jsfiles