node-red-contrib-bg-hercules 0.3.2

Node-RED nodes for B&G Hercules / H5000 GoFree websocket

npm install node-red-contrib-bg-hercules

node-red-contrib-bg-hercules

Node-RED nodes for B&G Hercules (and H5000 / Triton Edge) processors over Navico GoFree websocket, default port 2053.

Not affiliated with or endorsed by Navico or B&G.

All flow nodes share one websocket per CPU config node, with keepalive, connect timeout, write queue, and automatic reconnect.

Script bridge is the only WTP-specific node and lives in the Hercules WTP palette. Everything else is under Hercules.

Install

From Manage palette → Install, search for node-red-contrib-bg-hercules.

Or from the command line:

cd ~/.node-red
npm install node-red-contrib-bg-hercules

Restart Node-RED after a command-line install.

CPU config

Create a hercules-cpu config: hostname or IP, port 2053, optional name, keepalive (pong default, or ping if your processor expects that), and optional PIN. After deploy, the config dialog shows the live connection status (for example connected · Hercules® WTP).

One config holds one connection. Child nodes multiplex over that socket.

On connect the CPU identifies itself (node-red-contrib-bg-hercules) and probes Authentication. If the processor reports authentication_required, the stored PIN is sent (id 2) and a session token is kept for reconnects (id 3). Discovery (ProductIdReq, FriendlyNameReq, DataListReq, DeviceListReq, setting groups) waits until auth succeeds or is not required. The PIN is stored as Node-RED credentials, not in the flow. Status is PIN required or auth failed when login cannot proceed, and shows the friendly name when connected (for example connected · Hercules® WTP). If the processor is offline, the editor falls back to a built-in dictionary.

Nodes

Palette labels are the short names (data subscribe, script bridge) under Hercules or Hercules WTP. Canvas colour follows core Node-RED roles: input (#a6bbcf), output (#87a980), action (#E2D96E), function (#fdd0a2).

Data subscribe (hercules-data-sub) — Hercules

Subscribes to one channel.

• msg.topic is the short name (e.g. BSP), long name, or numeric id
• msg.payload is the GoFree data item plus long_name, short_name, unit, and value
• payload.value copies the chosen field (val by default, or dampedVal / sysVal). payload.unit matches val, not necessarily sysVal
• Optional output rate: only send when the value changes, and/or at most every N ms
• Optional Source (n2kName) subscribes to one NMEA 2000 producer (labelled from DeviceList model names); optional Max rate sets GoFree maxRate on DataReq
• Unsubscribe uses UnsubscribeData

Search the channel list by name or id. If a channel is missing, enter its numeric id. With no node name, the canvas label is the short name (or subscribe plus the id).

Remote channel (hercules-remote-channel) — Hercules

Writes a numeric msg.payload to a Remote or Linear channel. A subscribe-shaped object uses value, then val. Empty or missing values are ignored. On connect it sets captions. With no node name, the canvas label is the short caption.

Start line (hercules-start-line) — Hercules

Choose Ping port or Ping starboard on the node. Any input (or the canvas button) fires it.

From msg still accepts a string ("port"), { "ping": "port" }, or msg.topic.

Race timer (hercules-race-timer) — Hercules

Choose Start, Stop, Sync, or Reset on the node. Any input (or the canvas button) fires it.

From msg still accepts a string ("start"), { "timer": "start" }, or msg.topic.

Setting (hercules-setting) — Hercules

Read or write a CPU setting, or a per-sensor setting on an NMEA 2000 device.

• Source empty = CPU (SettingListReq by group, SettingInfoReq, SettingReq with register: true)
• Source = an NMEA 2000 device from DeviceList (Manufacturer + ModelId, stored as NDP2kName) wraps the same messages in DeviceMessage after DeviceSubscribe
• Empty payload or { "get": true } reads
• A value or { "value": ... } writes (objects/arrays pass through for tables and enums)
• Output: { "id", "name", "value", "type", "readOnly", "n2kName?", "setting" }

User event (hercules-user-event) — Hercules

Log a race mark or sail change. Choose the event on the node (from CPU setting 122, or a built-in list). Any input (or the canvas button) fires it.

From msg accepts a string ("J1"), { "event": "Reef 1" } / { "userEventString": "End Race" }, or msg.topic. Custom strings such as Test Start are valid.

Sends { "EventSet": [{ "id": 36, "action": "logUserEvent", "userEventString": "..." }] }.

Status (hercules-status) — Hercules

Emit processor identity when the connection comes up, when product info arrives, when it drops, or on any input.

• msg.topic is the friendly name, then model id, then hercules
• msg.payload includes connected, host, port, handshake fields (productId, friendlyName, cpuId, auth flags), and DeviceList processor fields (modelId, manufacturer, swVersion, serialNumber, n2kName, deviceType)
• Input while disconnected still sends a snapshot with connected: false
• Identical snapshots are not repeated (except on input)

With no node name, the canvas label is the friendly name once known, otherwise status.

Event (hercules-event) — Hercules

Register for a GoFree event (EventReg) and emit each EventSet item.

• Known ids: 21 CAN Diagnostics, 44 Heartbeat
• Any input sends { "EventSet": [{ "id": N, "action": "request" }] } (needed for CAN diagnostics)

Script bridge (wtp-script-bridge) — Hercules WTP

WTP only. Pick a channel (same dictionary as subscribe) and a bridge number. With no node name, the canvas label is the channel short name plus the bridge number. msg.payload is the number to write:

6.2

null or { "value": 6.2, "valid": false } marks the channel invalid. Channel from msg still accepts { "id": 42, "value": 6.2, "valid": true }.

Writes while disconnected

Data, Setting, EventSet, and DeviceMessage (when the inner payload is a write) are queued (up to 32) and flushed when the socket reopens. Subscriptions, setting registrations, and event registrations are re-sent on every connect.

Examples

Import Hercules data subscribe, Hercules race start, Hercules setup, Hercules remote channel, Hercules user event, and Hercules WTP script bridge from the node's examples menu, then set the CPU host.

Tests

npm test

The suite starts a mock GoFree websocket server (no Hercules required).

Protocol notes

The mock in test/helpers/gofree-mock.js follows the Hercules captures (DeviceListReq with DeviceTypes: [], SettingListReq by groupId, SettingInfo, SettingReq.register, UnsubscribeData, DeviceMessage). Adjust from a websocket capture if firmware differs.