nodejs-poolcontroller 8.1.1 → 8.3.0

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 }}"

package/Changelog

@@ -1,5 +1,32 @@
 # Changelog
 
+## 8.3.0
+1. Configurable RS‑485 transmit pacing via new `controller.txDelays` for finer collision avoidance and throughput tuning.
+2. Startup & config resilience: empty or invalid `config.json` now auto‑recreated from defaults, corrupt originals backed up.
+3. Latitude / longitude environment overrides to eliminate early heliotrope warnings prior to UI configuration.
+4. Version check enhancements: git detection, safer redirects, throttled polling, warning suppression.
+5. Docker improvements: fixed Dockerfile and added docker‑compose example with named volumes & environment variable guidance.
+6. Add workflow to build and publish docker images to GitHub Container registry.
+7. Runtime requirements: elevated minimum Node.js version to 20+, safe dependency and security/patch updates.
+8. Documentation updates.
+
+## 8.1.2
+1. Regal Century pump support added.
+2. Enhanced error handling: replaced EquipmentNotFoundError with InvalidEquipmentIdError for improved clarity.
+3. Improved error handling in NixieBoard, NixieCircuitCommands, and NixieValveCommands.
+4. Refactored tolerance handling in TouchChemControllerCommands to ensure data integrity.
+5. Added new expansion board configuration for SunTouchBoard.
+
+## 8.1.1
+1. Enhanced REM server integration with packet capture functionality.
+2. Improved error handling in REMInterfaceServer methods.
+3. Refined chlorinator message processing logic in MessagesMock.
+4. Adjusted mock port checks across various components for consistency.
+5. Refined logic for Nixie schedules.
+6. Fixed documentation links for bindings integrations.
+7. Enhanced queueBodyHeatSettings to handle processing timeouts and improve error logging.
+8. Fixed typo in valveModes.
+
 ## 8.1.0
 1. Support for dual chlorinators with REM chem controllers.  It is now possible to have two separate chlorinators controlled in 'dynamic' mode by two separate REM chems.  Note: In order for REM chem to control each chlorinator, each needs to be on a dedicated RS-485 port (not shared with an OCP or any other chlorinator).
 

package/Dockerfile

@@ -1,19 +1,62 @@
-FROM node:18-alpine AS build
-RUN apk add --no-cache make gcc g++ python3 linux-headers udev tzdata
+### Build stage
+FROM node:20-alpine AS build
+LABEL maintainer="nodejs-poolController"
+LABEL org.opencontainers.image.title="nodejs-poolController"
+LABEL org.opencontainers.image.description="Bridge Pentair / compatible pool automation equipment to modern interfaces (REST, WebSockets, MQTT, Influx, Rules)."
+LABEL org.opencontainers.image.licenses="AGPL-3.0-only"
+LABEL org.opencontainers.image.source="https://github.com/tagyoureit/nodejs-poolController"
+
+# Install build toolchain only for native deps (serialport, etc.)
+RUN apk add --no-cache make gcc g++ python3 linux-headers udev tzdata git
+
 WORKDIR /app
+
+# Leverage Docker layer caching: copy only manifests first
 COPY package*.json ./
 COPY defaultConfig.json config.json
+
+# Install all deps (including dev) for build
 RUN npm ci
+
+# Copy source
 COPY . .
+
+# Build Typescript
 RUN npm run build
-RUN npm ci --omit=dev
 
-FROM node:18-alpine as prod
-RUN apk add git
-RUN mkdir /app && chown node:node /app
+# Remove dev dependencies while keeping a clean node_modules with prod deps only
+RUN npm prune --production
+
+### Runtime stage
+FROM node:20-alpine AS prod
+LABEL org.opencontainers.image.title="nodejs-poolController"
+LABEL org.opencontainers.image.description="Bridge Pentair / compatible pool automation equipment to modern interfaces (REST, WebSockets, MQTT, Influx, Rules)."
+LABEL org.opencontainers.image.licenses="AGPL-3.0-only"
+LABEL org.opencontainers.image.source="https://github.com/tagyoureit/nodejs-poolController"
+ENV NODE_ENV=production
+
+# Use existing 'node' user from base image; just ensure work directory exists
 WORKDIR /app
-COPY --chown=node:node --from=build /app .
+RUN mkdir -p /app
+RUN mkdir -p /app/logs /app/data /app/backups /app/web/bindings/custom \
+	&& chown -R node:node /app/logs /app/data /app/backups /app/web/bindings /app/web/bindings/custom || true
+
+# Copy only the necessary runtime artifacts from build stage
+COPY --chown=node:node --from=build /app/package*.json ./
+COPY --chown=node:node --from=build /app/node_modules ./node_modules
+COPY --chown=node:node --from=build /app/dist ./dist
+COPY --chown=node:node --from=build /app/defaultConfig.json ./defaultConfig.json
+COPY --chown=node:node --from=build /app/config.json ./config.json
+COPY --chown=node:node --from=build /app/README.md ./README.md
+COPY --chown=node:node --from=build /app/LICENSE ./LICENSE
+
 USER node
-ENV NODE_ENV=production
-EXPOSE 5150
+
+# Default HTTP / HTTPS (if enabled) ports from defaultConfig (http 4200, https 4201)
+EXPOSE 4200 4201
+
+# Basic healthcheck (container considered healthy if process responds to tcp socket open)
+HEALTHCHECK --interval=45s --timeout=6s --start-period=40s --retries=4 \
+	CMD node -e "const n=require('net');const s=n.createConnection({host:'127.0.0.1',port:4200},()=>{s.end();process.exit(0)});s.on('error',()=>process.exit(1));setTimeout(()=>{s.destroy();process.exit(1)},5000);" || exit 1
+
 ENTRYPOINT ["node", "dist/app.js"]

package/README.md

@@ -1,7 +1,7 @@
 ```diff
 - INTELLICENTER USERS: Do not upgrade Intellicenter to 2.006.  Rollback to 1.064 to use this application. 
 ```
-# nodejs-poolController - Version 8.1
+# nodejs-poolController - Version 8.3.0
 
 ## What is nodejs-poolController
 
@@ -26,6 +26,16 @@ Equipment supported
 ## Latest Changes
 See [Changelog](https://github.com/tagyoureit/nodejs-poolController/blob/master/Changelog)
 
+## What's new in 8.3.0?
+
+1. Configurable RS‑485 transmit pacing via new `controller.txDelays` for finer collision avoidance and throughput tuning.
+2. Startup & config resilience: empty or invalid `config.json` now auto‑recreated from defaults, corrupt originals backed up.
+3. Latitude / longitude environment overrides to eliminate early heliotrope warnings prior to UI configuration.
+4. Version check enhancements: git detection, safer redirects, throttled polling, warning suppression.
+5. Docker improvements: fixed Dockerfile and added docker‑compose example with named volumes & environment variable guidance.
+6. Add workflow to build and publish docker images to GitHub Container registry.
+7. Runtime requirements: elevated minimum Node.js version to 20+, safe dependency and security/patch updates.
+
 ## What's new in 8.1?
 
 Support for dual chlorinators with REM chem controllers.  It is now possible to have two separate chlorinators controlled in 'dynamic' mode by two separate REM chems.  Note: In order for REM chem to control each chlorinator, each needs to be on a dedicated RS-485 port (not shared with an OCP or any other chlorinator).
@@ -56,7 +66,7 @@ This is only the server code.  See [clients](#module_nodejs-poolController--clie
 ### Prerequisites
 If you don't know anything about NodeJS, these directions might be helpful.
 
-1. Install Nodejs (v16+ required). (https://nodejs.org/en/download/)
+1. Install Nodejs (v20+ required). (https://nodejs.org/en/download/)
 1. Update NPM (https://docs.npmjs.com/getting-started/installing-node).
 1. It is recommended to clone the source code as updates are frequently pushed while releases are infrequent
    clone with `git clone https://github.com/tagyoureit/nodejs-poolController.git`
@@ -73,14 +83,99 @@ For a very thorough walk-through, see [this](https://www.troublefreepool.com/thr
 #### Upgrade Instructions
 Assuming you cloned the repo, the following are easy steps to get the latest version:
 1. Change directory to the njsPC app
-2. `git pull`
-3. `npm i` (not always necessary, but if dependencies are upgraded this will bring them up to date)
-4. Start application as normal, or if using `npm run start:cached` then run `npm run build` to compile the code.
+2. **Important**: Ensure you have Node.js v20 or higher installed (`node --version`). If not, upgrade Node.js first.
+3. `git pull`
+4. **Important**: Run `npm i` to update dependencies. This is especially important when upgrading to version 8.3.0+ as it requires Node 20+ and has updated dependencies.
+5. Start application as normal, or if using `npm run start:cached` then run `npm run build` to compile the code.
 
 ### Docker instructions
 
 See the [wiki](https://github.com/tagyoureit/nodejs-poolController/wiki/Docker). Thanks @wurmr @andylippitt @emes.
 
+### Docker Compose (Controller + Optional dashPanel UI)
+
+Below is an example `docker-compose.yml` snippet showing this controller (`njspc`) and an OPTIONAL dashPanel UI service (`njspc-dash`). The dashPanel image is published separately; uncomment if you want a built-in web dashboard on port 5150.
+
+```yaml
+services:
+   njspc:
+      image: ghcr.io/sam2kb/njspc
+      container_name: njspc
+      restart: unless-stopped
+      environment:
+         - TZ=${TZ:-UTC}
+         - NODE_ENV=production
+         # Serial vs network connection options
+         # - POOL_NET_CONNECT=true
+         # - POOL_NET_HOST=raspberrypi
+         # - POOL_NET_PORT=9801
+         # Provide coordinates so sunrise/sunset (heliotrope) works immediately - change as needed
+         - POOL_LATITUDE=28.5383
+         - POOL_LONGITUDE=-81.3792
+      ports:
+         - "4200:4200"
+      devices:
+         - /dev/ttyACM0:/dev/ttyUSB0
+      # Persistence (create host directories/files first)
+      volumes:
+         - ./server-config.json:/app/config.json   # Persisted config file on host
+         - njspc-data:/app/data                    # State & equipment snapshots
+         - njspc-backups:/app/backups              # Backup archives
+         - njspc-logs:/app/logs                    # Logs
+         - njspc-bindings:/app/web/bindings/custom # Custom bindings
+      # OPTIONAL: If you get permission errors accessing /dev/tty*, prefer adding the container user to the host dialout/uucp group;
+      # only as a last resort temporarily uncomment the two lines below to run privileged/root (less secure).
+      # privileged: true
+      # user: "0:0"
+
+   njspc-dash:
+     image: ghcr.io/sam2kb/njspc-dash
+     container_name: njspc-dash
+     restart: unless-stopped
+     depends_on:
+       - njspc
+     environment:
+       - TZ=${TZ:-UTC}
+       - NODE_ENV=production
+       - POOL_WEB_SERVICES_IP=njspc      # Link to backend service name
+     ports:
+       - "5150:5150"
+     volumes:
+       - ./dash-config.json:/app/config.json
+       - njspc-dash-data:/app/data
+       - njspc-dash-logs:/app/logs
+       - njspc-dash-uploads:/app/uploads
+
+volumes:
+  njspc-data:
+  njspc-backups:
+  njspc-logs:
+  njspc-bindings:
+  njspc-dash-data:
+  njspc-dash-logs:
+  njspc-dash-uploads:
+```
+
+Quick start:
+1. Save compose file.
+2. (Optional) create an empty config file: `touch dash-config.json`.
+3. `docker compose up -d`
+4. Visit Dash UI at: `http://localhost:5150`.
+
+Notes:
+* Provide either RS-485 device OR enable network (ScreenLogic) connection.
+* Coordinates env vars prevent heliotrope warnings before the panel reports location.
+* Persistence (controller):
+   * `./server-config.json:/app/config.json` main runtime config. You can either:
+      * Seed it with a copy of `defaultConfig.json` (`cp defaultConfig.json server-config.json`), OR
+      * Start with an empty file and the app will auto-populate it from defaults on first launch. If the file exists but contains invalid JSON it will be backed up to `config.corrupt-<timestamp>.json` and regenerated.
+   * Remaining state (data, backups, logs, custom bindings) is typically stored in named volumes in the provided compose for cleaner host directories. If you prefer bind mounts instead, replace the named volumes with host paths similar to the example below.
+   * Data artifacts: `poolConfig.json`, `poolState.json` etc. live under `/app/data` (volume `njspc-data`).
+   * Backups: `/app/backups` (volume `njspc-backups`).
+   * Logs: `/app/logs` (volume `njspc-logs`).
+   * Custom bindings: `/app/web/bindings/custom` (volume `njspc-bindings`).
+* To migrate from bind mounts to named volumes, stop the stack, `docker run --rm -v oldPath:/from -v newVolume:/to alpine sh -c 'cp -a /from/. /to/'` for each path, then update compose.
+
 ### Automate startup of app
 See the [wiki](https://github.com/tagyoureit/nodejs-poolController/wiki/Automatically-start-at-boot---PM2-&-Systemd).
 
@@ -106,11 +201,11 @@ To do anything with this app, you need a client to connect to it.  A client can
 ## Home Automation Bindings (previously Integrations)
 
 Available automations:
-* [Vera Home Automation Hub](https://github.com/rstrouse/nodejs-poolController-veraPlugin) - A plugin that integrates with nodejs-poolController.  [Bindings Directions](https://github.com/tagyoureit/nodejs-poolController/wiki/Bindings-Integrations-in-2.0#vera)
-* [Hubitat](https://github.com/bsileo/hubitat_poolcontroller) by @bsileo (prev help from @johnny2678, @donkarnag, @arrmo).  [Bindings Directions](https://github.com/tagyoureit/nodejs-poolController/wiki/Bindings-Integrations-in-2.0#smartthingshubitat)
+* [Vera Home Automation Hub](https://github.com/rstrouse/nodejs-poolController-veraPlugin) - A plugin that integrates with nodejs-poolController.  [Bindings Directions](https://github.com/tagyoureit/nodejs-poolController/wiki/Bindings-Integrations#vera)
+* [Hubitat](https://github.com/bsileo/hubitat_poolcontroller) by @bsileo (prev help from @johnny2678, @donkarnag, @arrmo).  [Bindings Directions](https://github.com/tagyoureit/nodejs-poolController/wiki/Bindings-Integrations#smartthingshubitat)
 * [Homebridge/Siri/EVE](https://github.com/gadget-monk/homebridge-poolcontroller) by @gadget-monk, adopted from @leftyflip
-* InfluxDB - [Bindings Directions](https://github.com/tagyoureit/nodejs-poolController/wiki/Bindings-Integrations-in-2.0#influx)
-* [MQTT](https://github.com/crsherman/nodejs-poolController-mqtt) original release by @crsherman, re-write by @kkzonie, testing by @baudfather and others.  [Bindings Directions](https://github.com/tagyoureit/nodejs-poolController/wiki/Bindings-Integrations-in-2.0#mqtt)
+* InfluxDB - [Bindings Directions](https://github.com/tagyoureit/nodejs-poolController/wiki/Bindings-Integrations#influx)
+* [MQTT](https://github.com/crsherman/nodejs-poolController-mqtt) original release by @crsherman, re-write by @kkzonie, testing by @baudfather and others.  [Bindings Directions](https://github.com/tagyoureit/nodejs-poolController/wiki/Bindings-Integrations#mqtt)
    * [Homeseer](https://github.com/tagyoureit/nodejs-poolController/wiki/Homeseer-Setup-Instructions) - Integration directions by @miamijerry to integrate Homeseer through MQTT
 
 Outdated:
@@ -138,6 +233,29 @@ Most of these can be configured directly from the UI in dashPanel.
 * `netConnect` - used to connect via [Socat](https://github.com/tagyoureit/nodejs-poolController/wiki/Socat)
   * `netHost` and `netPort` - host and port for Socat connection.
 * `inactivityRetry` - # of seconds the app should wait before trying to reopen the port after no communications.  If your equipment isn't on all the time or you are running a virtual controller you may want to dramatically increase the timeout so you don't get console warnings.
+* `txDelays` - (optional) fine‑grained transmit pacing controls added in 8.1+ to better coexist with busy or bridged (socat / multiple panel / dual chlorinator) RS‑485 buses.  These values are all in milliseconds.  If the block is omitted, internal defaults are used (see `defaultConfig.json`).  All values can be hot‑reloaded from config.
+   * `idleBeforeTxMs` – Minimum quiet time on the bus (no RX or TX seen) before a new outbound frame may start.  Helps avoid collisions just after another device finishes talking.  Typical: 40‑80.  Set to 0 to disable.
+   * `interFrameDelayMs` – Delay inserted between completed outbound attempts (success, retry scheduling, or queue drain) and evaluation of the next outbound message.  Replaces the previous fixed 100ms.  Typical: 30‑75.  Lower values increase throughput but may raise collision / rewind counts.
+   * `interByteDelayMs` – Optional per‑byte pacing inside a single frame.  Normally 0 (disabled).  Set to 1‑2ms only if you observe hardware or USB adapter overruns, or are experimenting with very marginal wiring / long cable runs.
+
+Example tuning block - more conservative pacing for SunTouch that works way better than defaults:
+
+```json
+"txDelays": {
+   "idleBeforeTxMs": 60,
+   "interFrameDelayMs": 50,
+   "interByteDelayMs": 1
+}
+```
+
+Tuning guidance:
+- Start with the defaults. Only change one value at a time and observe stats (collisions, retries, rewinds) via rs485PortStats.
+- If you see frequent outbound retries or receive rewinds, first raise `idleBeforeTxMs` in small steps (e.g. +10ms) before touching `interFrameDelayMs`.
+- If overall throughput feels sluggish but collisions are low, you may lower `interFrameDelayMs` gradually.
+- Use `interByteDelayMs` only as a last resort; it elongates every frame and reduces total bus capacity.
+- Setting any value too high will simply slow configuration bursts (e.g. on startup); setting them too low can cause more retries and ultimately lower effective throughput.
+
+All three parameters are safe to adjust without restarting; edits to `config.json` are picked up by the existing config watcher.
 
 ## Web section - controls various aspects of external communications
 * `servers` - setting for different servers/services

package/config/Config.ts

@@ -36,21 +36,52 @@ class Config {
         // RKS 05-18-20: This originally had multiple points of failure where it was not in the try/catch.
         try {
             this._isLoading = true;
-            this._cfg = fs.existsSync(this.cfgPath) ? JSON.parse(fs.readFileSync(this.cfgPath, "utf8").trim()) : {};
+            // Read user config (if present) with graceful handling of empty or invalid JSON.
+            let userCfg: any = {};
+            if (fs.existsSync(this.cfgPath)) {
+                try {
+                    const raw = fs.readFileSync(this.cfgPath, "utf8");
+                    const trimmed = raw.trim();
+                    if (trimmed.length > 0) userCfg = JSON.parse(trimmed);
+                    else {
+                        console.log(`Config file '${ this.cfgPath }' is empty. Populating with defaults.`);
+                    }
+                } catch (parseErr: any) {
+                    // Backup corrupt file then continue with defaults.
+                    try {
+                        const backupName = this.cfgPath.replace(/\.json$/i, `.corrupt-${ Date.now() }.json`);
+                        fs.copyFileSync(this.cfgPath, backupName);
+                        console.log(`Config file '${ this.cfgPath }' contained invalid JSON and was backed up to '${ backupName }'. Using defaults.`);
+                    } catch (backupErr: any) {
+                        console.log(`Failed to backup corrupt config file '${ this.cfgPath }': ${ backupErr.message }`);
+                    }
+                    userCfg = {};
+                }
+            }
             const def = JSON.parse(fs.readFileSync(path.join(process.cwd(), "/defaultConfig.json"), "utf8").trim());
             const packageJson = JSON.parse(fs.readFileSync(path.join(process.cwd(), "/package.json"), "utf8").trim());
-            this._cfg = extend(true, {}, def, this._cfg, { appVersion: packageJson.version });
+            this._cfg = extend(true, {}, def, userCfg, { appVersion: packageJson.version });
             this._isInitialized = true;
             this.updateAsync((err) => {
                 if (typeof err === 'undefined') {
                     fs.watch(this.cfgPath, (event, fileName) => {
                         if (fileName && event === 'change') {
-                            if (self._isLoading) return; // Need a debounce here.  We will use a semaphore to cause it not to load more than once.
+                            if (self._isLoading) return; // Debounce via semaphore.
                             console.log('Updating config file');
                             const stats = fs.statSync(self.cfgPath);
                             if (stats.mtime.valueOf() === self._fileTime.valueOf()) return;
-                            this._cfg = fs.existsSync(this.cfgPath) ? JSON.parse(fs.readFileSync(this.cfgPath, "utf8")) : {};
-                            this._cfg = extend(true, {}, def, this._cfg, { appVersion: packageJson.version });
+                            let changedCfg: any = {};
+                            if (fs.existsSync(self.cfgPath)) {
+                                try {
+                                    const raw2 = fs.readFileSync(self.cfgPath, "utf8");
+                                    const trimmed2 = raw2.trim();
+                                    if (trimmed2.length > 0) changedCfg = JSON.parse(trimmed2);
+                                    else console.log(`Watched config file is empty; continuing with defaults + existing overrides.`);
+                                } catch (e: any) {
+                                    console.log(`Error parsing updated config file. Retaining existing configuration. Error: ${ e.message }`);
+                                }
+                            }
+                            this._cfg = extend(true, {}, def, changedCfg, { appVersion: packageJson.version });
                             logger.init(); // only reload logger for now; possibly expand to other areas of app
                             logger.info(`Reloading app config: ${fileName}`);
                             this.emitter.emit('reloaded', this._cfg);
@@ -63,8 +94,7 @@ class Config {
             this.getEnvVariables();
         } catch (err) {
             console.log(`Error reading configuration information.  Aborting startup: ${ err }`);
-            // Rethrow this error so we exit the app with the appropriate pause in the console.
-            throw err;
+            throw err; // Only throw if defaults/package.json could not be read.
         }
     }
     public async updateAsync(callback?: (err?) => void) {
@@ -189,6 +219,26 @@ class Config {
             this._cfg.controller.comms.netPort = env.POOL_NET_PORT;
             bUpdate = true;
         }
+        // Allow overriding location coordinates for heliotrope calculations
+        if (typeof env.POOL_LATITUDE !== 'undefined') {
+            const lat = parseFloat(env.POOL_LATITUDE as any);
+            if (!isNaN(lat) && (!this._cfg.controller?.general?.location || this._cfg.controller.general.location.latitude !== lat)) {
+                // Ensure nested objects exist
+                this._cfg.controller.general = this._cfg.controller.general || {};
+                this._cfg.controller.general.location = this._cfg.controller.general.location || {};
+                this._cfg.controller.general.location.latitude = lat;
+                bUpdate = true;
+            }
+        }
+        if (typeof env.POOL_LONGITUDE !== 'undefined') {
+            const lon = parseFloat(env.POOL_LONGITUDE as any);
+            if (!isNaN(lon) && (!this._cfg.controller?.general?.location || this._cfg.controller.general.location.longitude !== lon)) {
+                this._cfg.controller.general = this._cfg.controller.general || {};
+                this._cfg.controller.general.location = this._cfg.controller.general.location || {};
+                this._cfg.controller.general.location.longitude = lon;
+                bUpdate = true;
+            }
+        }
         if (bUpdate) this.updateAsync();
     }
 }