nodejs-poolcontroller 8.1.2 → 8.4.0

package/.eslintrc.json

@@ -1,36 +1,36 @@
-{
-    "env": {
-        "es2021": true,
-        "node": true
-    },
-    "extends": [
-        "eslint:recommended",
-        "plugin:@typescript-eslint/recommended"
-    ],
-    "parser": "@typescript-eslint/parser",
-    "parserOptions": {
-        "ecmaVersion": "latest",
-        "sourceType": "module"
-    },
-    "plugins": [
-        "@typescript-eslint"
-    ],
-    "rules": {
-        "indent": [
-            "error",
-            "tab"
-        ],
-        "linebreak-style": [
-            "error",
-            "windows"
-        ],
-        "quotes": [
-            "error",
-            "single"
-        ],
-        "semi": [
-            "error",
-            "always"
-        ]
-    }
-}
+{
+    "env": {
+        "es2021": true,
+        "node": true
+    },
+    "extends": [
+        "eslint:recommended",
+        "plugin:@typescript-eslint/recommended"
+    ],
+    "parser": "@typescript-eslint/parser",
+    "parserOptions": {
+        "ecmaVersion": "latest",
+        "sourceType": "module"
+    },
+    "plugins": [
+        "@typescript-eslint"
+    ],
+    "rules": {
+        "indent": [
+            "error",
+            "tab"
+        ],
+        "linebreak-style": [
+            "error",
+            "windows"
+        ],
+        "quotes": [
+            "error",
+            "single"
+        ],
+        "semi": [
+            "error",
+            "always"
+        ]
+    }
+}

package/.github/ISSUE_TEMPLATE/1-bug-report.yml

@@ -1,84 +1,84 @@
-name: "\U0001F41B Bug report"
-description: Create a report to help us improve
-title: '[BUG] '
-body:
-  - type: markdown
-    attributes:
-      value: |
-        Thank you for reporting an issue.  Most issues can be more readily resolved by attaching a Packet Capture.  Follow the instructions to complete a [packet capture](https://github.com/tagyoureit/nodejs-poolController/wiki/How-to-capture-all-packets-for-issue-resolution) and attach the resulting zip/log files.
-
-        If you require more general support please file an start a discussion on our discussion board https://github.com/tagyoureit/nodejs-poolController/discussions
-
-        Having trouble installing? Be sure to check out the wiki! https://github.com/tagyoureit/nodejs-poolController/wiki
-
-        Please fill in as much of the form below as you're able.
-  - type: input
-    attributes:
-      label: nodejs-poolController Version/commit
-      description: can be viewed under dashPanel.  Hamburger menu => System.
-    validations:
-      required: true
-  - type: input
-    attributes:
-      label: nodejs-poolController-dashPanel Version/commit
-      description: if applicable
-  - type: input
-    attributes:
-      label: relayEquipmentManager Version/commit 
-      description: if applicable
-  - type: input
-    attributes:
-      label: Node Version
-      description: Output of `node -v`
-  - type: input
-    attributes:
-      label: Platform
-      description: |
-        UNIX: output of `uname -a`
-        Windows: output of `"$([Environment]::OSVersion | ForEach-Object VersionString) $(if ([Environment]::Is64BitOperatingSystem) { "x64" } else { "x86" })"` in PowerShell console
-  - type: input
-    attributes:
-      label: RS485 Adapter
-      description: Elfin? JBTek?
-  - type: checkboxes
-    attributes:
-      label: Are you using Docker?
-      options:
-        - label: Yes.
-  - type: input
-    attributes:
-      label: OCP
-      description: Outdoor Control Panel.  Eg EasyTouch2 8P, Intellicenter i5PS, none.
-      placeholder: None / Nixie (standalone setup)
-  - type: input
-    attributes:
-      label: Pump(s)
-      description: Please list all pumps.  EG Intelliflo 2 VST, Intelliflo VS
-      placeholder: Intelliflo VS
-  - type: input
-    attributes:
-      label: Chlorinator(s)
-      description: Please list all chlorinators.  EG Intellichlor IC-40, Aquarite, None
-      placeholder: None
-  - type: textarea
-    attributes:
-      label: What steps will reproduce the bug?
-      description: Enter details about your bug, preferably a simple code snippet that can be run using `node` directly without installing third-party dependencies.
-    validations:
-      required: true
-  - type: textarea
-    attributes:
-      label: What happens?
-      description: If possible please provide textual output instead of screenshots.
-    validations:
-      required: true
-  - type: textarea
-    attributes:
-      label: What should have happened?
-      description: If possible please provide textual output instead of screenshots.
-    validations:
-      required: true
-  - type: textarea
-    attributes:
-      label: Additional information
-      description: Tell us anything else you think we should know.
+name: "\U0001F41B Bug report"
+description: Create a report to help us improve
+title: '[BUG] '
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thank you for reporting an issue.  Most issues can be more readily resolved by attaching a Packet Capture.  Follow the instructions to complete a [packet capture](https://github.com/tagyoureit/nodejs-poolController/wiki/How-to-capture-all-packets-for-issue-resolution) and attach the resulting zip/log files.
+
+        If you require more general support please file an start a discussion on our discussion board https://github.com/tagyoureit/nodejs-poolController/discussions
+
+        Having trouble installing? Be sure to check out the wiki! https://github.com/tagyoureit/nodejs-poolController/wiki
+
+        Please fill in as much of the form below as you're able.
+  - type: input
+    attributes:
+      label: nodejs-poolController Version/commit
+      description: can be viewed under dashPanel.  Hamburger menu => System.
+    validations:
+      required: true
+  - type: input
+    attributes:
+      label: nodejs-poolController-dashPanel Version/commit
+      description: if applicable
+  - type: input
+    attributes:
+      label: relayEquipmentManager Version/commit 
+      description: if applicable
+  - type: input
+    attributes:
+      label: Node Version
+      description: Output of `node -v`
+  - type: input
+    attributes:
+      label: Platform
+      description: |
+        UNIX: output of `uname -a`
+        Windows: output of `"$([Environment]::OSVersion | ForEach-Object VersionString) $(if ([Environment]::Is64BitOperatingSystem) { "x64" } else { "x86" })"` in PowerShell console
+  - type: input
+    attributes:
+      label: RS485 Adapter
+      description: Elfin? JBTek?
+  - type: checkboxes
+    attributes:
+      label: Are you using Docker?
+      options:
+        - label: Yes.
+  - type: input
+    attributes:
+      label: OCP
+      description: Outdoor Control Panel.  Eg EasyTouch2 8P, Intellicenter i5PS, none.
+      placeholder: None / Nixie (standalone setup)
+  - type: input
+    attributes:
+      label: Pump(s)
+      description: Please list all pumps.  EG Intelliflo 2 VST, Intelliflo VS
+      placeholder: Intelliflo VS
+  - type: input
+    attributes:
+      label: Chlorinator(s)
+      description: Please list all chlorinators.  EG Intellichlor IC-40, Aquarite, None
+      placeholder: None
+  - type: textarea
+    attributes:
+      label: What steps will reproduce the bug?
+      description: Enter details about your bug, preferably a simple code snippet that can be run using `node` directly without installing third-party dependencies.
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: What happens?
+      description: If possible please provide textual output instead of screenshots.
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: What should have happened?
+      description: If possible please provide textual output instead of screenshots.
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Additional information
+      description: Tell us anything else you think we should know.

package/.github/ISSUE_TEMPLATE/2-docs.md

@@ -1,12 +1,12 @@
----
-name: 📚 Documentation
-about: Report an issue related to documentation
----
-
-## 📚 Documentation
-
-(A clear and concise description of how the docs could be better, with links if possible)
-
-### Have you read the [Contributing Guidelines on docs](https://github.com/serialport/node-serialport/blob/master/CONTRIBUTING.md#writing-documentation)?
-
-(Write your answer here.)
+---
+name: 📚 Documentation
+about: Report an issue related to documentation
+---
+
+## 📚 Documentation
+
+(A clear and concise description of how the docs could be better, with links if possible)
+
+### Have you read the [Contributing Guidelines on docs](https://github.com/serialport/node-serialport/blob/master/CONTRIBUTING.md#writing-documentation)?
+
+(Write your answer here.)

package/.github/ISSUE_TEMPLATE/3-proposal.md

@@ -1,28 +1,28 @@
----
-name: 💥 Proposal / Feature
-about: Propose a non-trivial change or new feature for SerialPort
----
-
-## 💥 Proposal
-
-### What feature you'd like to see
-
-(A clear and concise description of what the proposal is.)
-
-## Motivation
-
-(Please outline the motivation for the proposal. It's interesting knowing what people are working on and also could help community members make suggestions for work-arounds until the feature is built)
-
-## Pitch
-
-(Please explain why this feature should be implemented and how it would be used.)
-
-<!--
-  What happens if you skip this step?
-
-  Someone will read your feature proposal and maybe will be able to help you,
-  but it’s unlikely that it will get much attention from the team. Eventually,
-  the issue will likely get closed in favor of issues that have better explanations
-
-  Thanks for helping us help you!
--->
+---
+name: 💥 Proposal / Feature
+about: Propose a non-trivial change or new feature for SerialPort
+---
+
+## 💥 Proposal
+
+### What feature you'd like to see
+
+(A clear and concise description of what the proposal is.)
+
+## Motivation
+
+(Please outline the motivation for the proposal. It's interesting knowing what people are working on and also could help community members make suggestions for work-arounds until the feature is built)
+
+## Pitch
+
+(Please explain why this feature should be implemented and how it would be used.)
+
+<!--
+  What happens if you skip this step?
+
+  Someone will read your feature proposal and maybe will be able to help you,
+  but it’s unlikely that it will get much attention from the team. Eventually,
+  the issue will likely get closed in favor of issues that have better explanations
+
+  Thanks for helping us help you!
+-->

package/.github/ISSUE_TEMPLATE/config.yml

@@ -1,8 +1,8 @@
-blank_issues_enabled: false
-contact_links:
-  - name: ⁉️ Need help with nodejs-poolController?
-    url: https://github.com/tagyoureit/nodejs-poolController/discussions
-    about: Please start a discussion before opening a bug.
-  - name: Gitter
-    url: https://gitter.im/nodejs-poolController/Lobby
-    about: Legacy Gitter discussion forums
+blank_issues_enabled: false
+contact_links:
+  - name: ⁉️ Need help with nodejs-poolController?
+    url: https://github.com/tagyoureit/nodejs-poolController/discussions
+    about: Please start a discussion before opening a bug.
+  - name: Gitter
+    url: https://gitter.im/nodejs-poolController/Lobby
+    about: Legacy Gitter discussion forums

package/.github/copilot-instructions.md

@@ -0,0 +1,63 @@
+# Copilot Project Instructions
+
+Purpose: Help AI agents contribute effectively to nodejs-poolController (njsPC) with minimal ramp-up.
+
+## 1. Core Domain & Architecture
+- Goal: Bridge Pentair / compatible pool automation equipment (RS-485 / ScreenLogic) to REST, WebSockets, MQTT, InfluxDB, Rules, and REM (Relay Equipment Manager) interfaces.
+- Startup sequence (see `app.ts`): config.init -> logger.init -> sys.init -> state.init -> webApp.init -> conn.initAsync (RS485 / network) -> sys.start -> webApp.initAutoBackup -> sl.openAsync (ScreenLogic).
+- Major layers:
+  1. `config/Config.ts`: Loads/merges `defaultConfig.json` + `config.json`, watches disk, applies env overrides (POOL_*). Always mutate via `config.setSection()` / `config.updateAsync()`.
+  2. `controller/`:
+     - `comms/Comms.ts` (RS485 transport) + `comms/messages/*` (protocol encode/decode) feeding message objects to system/state.
+     - `Equipment.ts` (`sys`): Aggregates boards, pumps, heaters, bodies, chemistry, schedules.
+     - `boards/*Board.ts` selected by `BoardFactory.fromControllerType()` (ControllerType enum) to encapsulate model-specific logic.
+     - `State.ts`: Higher-level computed/state cache (emits events to interfaces & persistence).
+  3. `web/Server.ts`: Orchestrates multiple server/interface types (http/https/http2, mdns, ssdp, mqtt, influx, rule, rem). Each concrete server extends a ProtoServer pattern (see file) and exposes `emitToClients` / `emitToChannel`.
+  4. `logger/Logger.ts`: Winston wrapper with packet & ScreenLogic capture, optional replay capture mode (`log.app.captureForReplay`).
+- Data Flow: Raw bytes -> `Comms` -> `Messages` decode -> equipment/state mutation -> events -> `webApp.emitToChannel()` -> clients (dashPanel, bindings, MQTT, etc.).
+
+## 2. Key Conventions & Patterns
+- Prefer calling exported singletons (`config`, `logger`, `sys`, `state`, `webApp`, `conn`) — they are initialized once in `app.ts`.
+- Extend support for a new controller board: create `controller/boards/NewBoard.ts` implementing expected interface and add to `BoardFactory` switch.
+- Adding an external interface: implement a server class similar to existing ones in `web/Server.ts` and register in `initInterfaces()` via `type` value in `web.interfaces` section of config.
+- Configuration writes are async & debounced by a semaphore (`_isLoading`). Avoid rapid consecutive writes — batch changes before `setSection`.
+- Logging packets: push through `logger.packet(msg)`; only log when `log.packet.enabled` or capture mode active. Don't bypass logger for protocol-level diagnostics.
+- Use `utils.uuid()` for persistent IDs stored back into config (`web.servers.*` / `web.interfaces.*`).
+
+## 3. Build & Run Workflow
+- Scripts (`package.json`): `npm start` = build (tsc) + run `dist/app.js`; `npm run start:cached` skips build (use only after prior successful build); `npm run build` or `watch` for development.
+- Always rebuild after pulling if Typescript sources changed (common; master is live development).
+- Minimum Node >=16 (see `engines`).
+- Typical dev loop: edit TS -> `npm run build` (or `watch` in one terminal) -> `npm run start:cached` in another.
+
+## 4. Safe Change Guidelines (Project Specific)
+- Never directly edit `config.json` structure assumptions without updating `defaultConfig.json` and migration logic if needed.
+- When adding message types: place in proper `controller/comms/messages/{config|status}` folder; ensure decode populates strongly typed object consumed by equipment/state.
+- Emitting to clients: prefer channel scoping with `webApp.emitToChannel(channel, evt, payload)` over broad `emitToClients` to reduce noise.
+- Shutdown paths must await: see `stopAsync()` ordering in `app.ts`; replicate that order if introducing new long-lived resources.
+- Packet capture integration: if adding new traffic sources, feed capture arrays so `logger.stopCaptureForReplayAsync()` includes them in backups.
+
+## 5. Extending / Examples
+- Add new board: create file, implement constructor(system), override protocol handlers, add case in `BoardFactory`.
+- Add new interface type: define class (e.g., `FooInterfaceServer`) patterned after `MqttInterfaceServer`; map `type: 'foo'` in config to new class in `initInterfaces` switch.
+- Add env override: update `Config.getEnvVariables()` with POOL_* variable mapping.
+
+## 6. Debugging Tips
+- Packet issues: enable `log.packet.logToConsole` & set `log.app.level` to `debug` or `silly` in `config.json` (or via capture mode) then rebuild & restart.
+- Config reload: editing `config.json` on disk triggers fs watch; logger reinitializes log settings automatically.
+- Network discovery problems: inspect `mdns` / `ssdp` sections in `web.servers` config; ensure correct interface binding (`ip` / `0.0.0.0`).
+
+## 7. Common Pitfalls
+- Forgetting to rebuild after TS edits (leads to running stale `dist`).
+- Mutating returned config objects directly after `getSection` (they are deep-cloned; you must re-set via `setSection`).
+- Adding interface without persisting UUID: ensure `utils.uuid()` assigned when undefined.
+- Logging floods: avoid tight loops writing directly to console; use logger buffering (`packet` flush timer) pattern.
+
+## 8. Contribution Checklist (Agent Focused)
+1. Identify layer (comms / equipment / state / interface / config / logging) impacted.
+2. Update or add unit-like logic in correct module; keep cross-layer boundaries (no UI assumptions in lower layers).
+3. Use existing singletons; avoid new global state without need.
+4. Validate build (`npm run build`) before proposing changes.
+5. Provide brief rationale in PR tying change to equipment behavior or integration capability.
+
+Feedback welcome: clarify any unclear pattern or request examples to extend this guide.

package/.github/workflows/ghcr-publish.yml

@@ -0,0 +1,67 @@
+name: Publish Docker Image - GHCR
+
+on:
+  push:
+    branches:
+      - master
+    tags:
+      - 'v*.*.*'
+  workflow_dispatch:
+
+jobs:
+  build-and-push:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Docker meta
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: |
+            ghcr.io/${{ github.repository_owner }}/njspc
+          tags: |
+            type=ref,event=branch
+            type=ref,event=pr
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=semver,pattern={{major}}
+            type=sha
+            type=raw,value=latest,enable={{is_default_branch}}
+          labels: |
+            org.opencontainers.image.source=${{ github.repository }}
+            org.opencontainers.image.revision=${{ github.sha }}
+            org.opencontainers.image.title=njspc
+            org.opencontainers.image.description=Pentair pool controller bridge (GHCR image)
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Login to GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build and push
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          push: true
+          platforms: linux/amd64,linux/arm64,linux/arm/v7
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+      - name: Echo published tags
+        run: |
+          echo "Published: ${{ steps.meta.outputs.tags }}"