@rygine/omnilogic-local-sdk 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+All notable changes to this project are recorded here, and versions follow
+[Semantic Versioning](https://semver.org/).
+
+## 0.0.1
+
+Initial release.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ry Racherbaumer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,149 @@
+# OmniLogicLocal SDK
+
+TypeScript SDK for local control of Hayward OmniLogic pool controllers. No
+internet or cloud login required.
+
+> [!IMPORTANT]
+>
+> This SDK is currently in beta. It may contain bugs or change based on
+> feedback.
+
+## Features
+
+- Access to the controller config, system info, and equipment telemetry
+- Typed parameters and results for all 237 firmware-verified commands
+- Built-in caching and throttling to prevent controller overload
+- Equipment control through an API built on top of the command interface
+
+> [!NOTE]
+>
+> Not all commands have been verified against real hardware. Some commands seem
+> to be unusable, require certain setups and equipment, or may put your system
+> in an undesirable state. The equipment control API has been tested against
+> real hardware, has safeguards in place, and is the best way to access your
+> equipment. Unverified hardware of a kind it already covers, such as other
+> lights, relays, heaters and chlorinators, may work through it too. Anything it
+> does not cover, such as auxiliary pumps or Sense and Dispense, is reached with
+> `command()`: those commands should work, but have not been confirmed.
+
+## Requirements
+
+- Node.js >= 24
+- Network access to the OmniLogic controller on port 10444
+
+## Installation
+
+```bash
+yarn add @rygine/omnilogic-local-sdk
+# or
+npm install @rygine/omnilogic-local-sdk
+```
+
+## Usage
+
+```typescript
+import { OmniLogic } from "@rygine/omnilogic-local-sdk";
+
+const omni = new OmniLogic({ host: "192.168.1.100" });
+
+// fetch the latest controller config and telemetry
+await omni.refresh();
+
+// access controller config and telemetry
+console.log("Backyard name:", omni.config.backyard.name);
+console.log("Air temp:", omni.telemetry.backyard.airTemp);
+
+// send a raw command with typed parameters
+const poolTemp = await omni.command("GetUIPoolTempCmd", { poolId: 1 });
+console.log("Pool temp:", poolTemp.temp);
+
+// or use the equipment API
+console.log("Filter speed:", omni.backyard.pool?.filter?.speed);
+console.log("Filter status:", omni.backyard.pool?.filter?.status);
+```
+
+## Supported hardware
+
+The equipment API has been verified on this hardware:
+
+- Hayward OmniPL, MSP firmware R0502000
+- Pool and spa sharing one filter pump, heater and chlorinator
+- Hayward TriStar VS 950 Omni filter pump
+- Hayward Smart Heater (gas)
+- Salt chlorinator with a TCELLS340 cell
+- Universal ColorLogic (UCL) lights, with or without OmniDirect
+- High voltage relays
+- Air temperature, water temperature and flow sensors
+
+The controller runs other equipment the SDK supports but has not yet verified on
+hardware:
+
+- Salt chlorinator cells
+  - T-Cell-3
+  - T-Cell-5
+  - T-Cell-9
+  - T-Cell-15
+  - T-Cell-LS
+  - TCELLS315
+  - TCELLS325
+- AQR940/AQR925 Aqua Rite chlorine generator, with an HLAQRPCB communication
+  board
+- Feeders and dispensers
+  - HL-CHEM4-CHLOR liquid chlorine feeder
+  - CL200 chlorine tablet feeder
+  - HL-CHEM4-ACID liquid acid feeder
+  - AQL-CHEM2 CO2 dispenser
+- HL-CHEM Sense and Dispense ORP and pH sensing kit
+- Pumps
+  - TriStar VS 900 Omni
+  - Super Pump VS 700 Omni
+  - MaxFlo VS 500 Omni
+  - EcoStar
+  - Single speed and two speed filter pumps
+  - Cleaner, water feature and accessory pumps
+- Heat pump, solar, electric and geothermal heaters, and chillers
+- Lights
+  - ColorLogic 2.5 (CL2.5)
+  - ColorLogic 4.0 (CL4.0)
+  - Universal ColorLogic in Pentair SAM mode
+  - WaterBowl
+  - Pentair Color LED (P-COLOR)
+  - Jandy Color LED (Z-Color)
+  - Incandescent
+  - LTSUY11300 Smart Power Transformer
+- Valve actuators
+  - GVA-24 valve actuator
+  - V&A-xx valve and actuator
+  - Pentair/Compool and Jandy valve actuators
+- Relays and expansion
+  - Low voltage relays
+  - HLRELAYBANK additional relay pack
+  - HLRELAY single high voltage relay kit
+  - HLH485RELAY Smart Relay
+  - HLEXPAND Expansion Panel
+  - HLIOEXPAND Input/Output Expander Board
+- Sensors and inputs
+  - GLX-FLO flow switch
+  - 2PC temperature sensor
+  - Solar sensor
+  - External input interlocks
+
+Hardware the equipment API does not cover is controlled with `command()`, for
+example an auxiliary pump:
+
+```typescript
+import { timerParams } from "@rygine/omnilogic-local-sdk";
+
+// turn on an auxiliary pump
+await omni.command("SetUIEquipmentCmd", {
+  poolId: 1,
+  equipmentId: 12,
+  isOn: 1,
+  ...timerParams(),
+});
+```
+
+## Disclaimer
+
+This software is not produced, endorsed, or supported by Hayward Industries,
+Inc. "Hayward" and "OmniLogic" are trademarks of their respective owners.