Dgarratt: Updated by push_wiki.py

2026-07-15T20:10:43Z

Updated by push_wiki.py

Dgarratt: Updated by push_wiki.py

2026-07-02T16:46:29Z

Updated by push_wiki.py

← Older revision		Revision as of 18:46, 2 July 2026
Line 56:		Line 56:
	<id>1</id>		<id>1</id>
	<pollIntervalMs>1000</pollIntervalMs>		<pollIntervalMs>1000</pollIntervalMs>
			<maxHoldMs>60000</maxHoldMs>
	</modbus>		</modbus>
	<webserver>		<webserver>
Line 62:		Line 63:
	</webserver>		</webserver>
	<points>		<points>
	<point name="pump_run" kind="COIL" address="0"/>		<point name="pump_run" kind="COIL" address="0" initialise="false" value="false"
	<point name="tank_level" kind="HOLDING_REGISTER" address="100"/>		minHoldMs="500" maxHoldMs="10000" defaultHoldMs="3000"/>
			<point name="tank_level" kind="HOLDING_REGISTER" address="100" initialise="false" value="0"/>
	<point name="fault" kind="DISCRETE_INPUT" address="10"/>		<point name="fault" kind="DISCRETE_INPUT" address="10"/>
	<point name="flow_rate" kind="INPUT_REGISTER" address="30"/>		<point name="flow_rate" kind="INPUT_REGISTER" address="30"/>
Line 69:		Line 71:
	</config>		</config>

	The <code><modbus></code> block points the Bridge at the remote Modbus server: its host <code><ip></code>, TCP <code><port></code> (the Modbus standard is '''502'''; the example uses '''1502''' because ports below 1024 need root on macOS/Linux), the unit / slave <code><id></code> to address, and the <code><pollIntervalMs></code> between reads. The <code><webserver></code> block sets the bind address for the HTTP server (<code>0.0.0.0</code> = all interfaces) and the port it listens on.		The <code><modbus></code> block points the Bridge at the remote Modbus server: its host <code><ip></code>, TCP <code><port></code> (the Modbus standard is '''502'''; the example uses '''1502''' because ports below 1024 need root on macOS/Linux), the unit / slave <code><id></code> to address, and the <code><pollIntervalMs></code> between reads. The optional <code><maxHoldMs></code> is the default hold cap for points that do not set their own <code>maxHoldMs</code> attribute (60 000 ms if absent) — see [[#Pulse (momentary output)\|Pulse]] below. The <code><webserver></code> block sets the bind address for the HTTP server (<code>0.0.0.0</code> = all interfaces) and the port it listens on.

	Each <code><point></code> gives a human-friendly '''name''' (how REST clients and the web UI refer to it), a Modbus data table '''kind''', and a zero-based protocol '''address'''. Valid kinds are <code>COIL</code>, <code>DISCRETE_INPUT</code>, <code>HOLDING_REGISTER</code> and <code>INPUT_REGISTER</code>. Only '''coils''' and '''holding registers''' are writable — discrete inputs and input registers are read-only in the Modbus data model (there is no client-write function code for them).		Each <code><point></code> gives a human-friendly '''name''' (how REST clients and the web UI refer to it), a Modbus data table '''kind''', and a zero-based protocol '''address'''. Valid kinds are <code>COIL</code>, <code>DISCRETE_INPUT</code>, <code>HOLDING_REGISTER</code> and <code>INPUT_REGISTER</code>. Only '''coils''' and '''holding registers''' are writable — discrete inputs and input registers are read-only in the Modbus data model (there is no client-write function code for them).

			=== Startup initialisation (optional) ===

			Add <code>initialise="true" value="..."</code> to a writable point to have the Bridge drive it to a known state at startup:

			* On the '''first successful connect''' after the Bridge starts, it reads the point's current value and writes <code>value</code> '''only if it differs''' (an already-correct point is left untouched). This runs once — a later link drop and reconnect does '''not''' re-apply it, so runtime REST/operator changes survive an outage.
			* If the Modbus server is unavailable at startup, initialisation simply waits and runs on the first connect once it becomes reachable.
			* <code>value</code> is <code>true</code>/<code>false</code> (or <code>1</code>/<code>0</code>) for coils, and a <code>0..65535</code> integer for holding registers. <code>initialise</code> defaults to <code>false</code>.

			Configuration is rejected at startup if <code>initialise="true"</code> is set on a read-only kind, or without a <code>value</code>, or with a value that does not match the kind.

			=== Per-point pulse hold policy (optional, writable points only) ===

			<code>minHoldMs</code>, <code>maxHoldMs</code> and <code>defaultHoldMs</code> control what a [[#Pulse (momentary output)\|pulse]] request may ask this point to hold for:

			* <code>minHoldMs</code> / <code>maxHoldMs</code> are the enforced bounds — a pulse whose <code>holdMs</code> falls outside them is rejected with '''400'''. Defaults: min <code>1</code>, max = the global <code><maxHoldMs></code> (60 000 if that is absent too). A tight per-point range (e.g. <code>500..10000</code> on a relay coil) means a typo like <code>30000</code> for <code>3000</code> can't hold the relay closed for half a minute.
			* <code>defaultHoldMs</code> is what the web UI pre-fills in the row's hold field (and is reported by the API for other clients to use the same way). Default: <code>3000</code> — sized for switching an electrical relay — clamped into the min/max range.
			* Config-load validation enforces <code>1 ≤ minHoldMs ≤ defaultHoldMs ≤ maxHoldMs</code> and rejects the attributes on read-only kinds.

	Logging is configured in <code>xml/config/log4j2.xml</code> (rolling file at <code>logs/modbusBridge.log</code>, 10 MB cap, 5 generations). The Bridge's own classes log at <code>debug</code>; the Netty transport at <code>warn</code>.		Logging is configured in <code>xml/config/log4j2.xml</code> (rolling file at <code>logs/modbusBridge.log</code>, 10 MB cap, 5 generations). The Bridge's own classes log at <code>debug</code>; the Netty transport at <code>warn</code>.
Line 87:		Line 107:
	\| <code>PUT</code> \|\| <code>/api/points/{name}</code> <code>{"value": N}</code> \|\| Write a coil (0/1, or <code>true</code>/<code>false</code>) or holding register (0–65535). 400 for read-only kinds or out-of-range; 503 if the server is unreachable.		\| <code>PUT</code> \|\| <code>/api/points/{name}</code> <code>{"value": N}</code> \|\| Write a coil (0/1, or <code>true</code>/<code>false</code>) or holding register (0–65535). 400 for read-only kinds or out-of-range; 503 if the server is unreachable.
	\|-		\|-
	\| <code>GET</code> \|\| <code>/api/status</code> \|\| Connection health: connected, target, unit id, poll interval, last-poll time, point count.		\| <code>POST</code> \|\| <code>/api/points/{name}/pulse</code> <code>{"value": N, "holdMs": N, "restValue": N}</code> \|\| Momentary output: set the point active, hold <code>holdMs</code>, then guarantee a reset to <code>restValue</code> (default 0). See [[#Pulse (momentary output)\|below]]. 200 once energised; 503 if it couldn't be; 409 if too many pulses are already queued for the point; 400 for read-only kinds, out-of-range values, or <code>holdMs</code> outside the point's <code>minHoldMs..maxHoldMs</code>.
			\|-
			\| <code>GET</code> \|\| <code>/api/status</code> \|\| Connection health: connected, target, unit id, poll interval, max hold, last-poll time, point count.
	\|-		\|-
	\| <code>GET</code> \|\| <code>/api/licence</code> \|\| Third-party licence list (from <code>lib/license/LicenseInfo.xml</code>).		\| <code>GET</code> \|\| <code>/api/licence</code> \|\| Third-party licence list (from <code>lib/license/LicenseInfo.xml</code>).
Line 105:		Line 127:
	curl -X PUT -H 'Content-Type: application/json' -d '{"value":1}' http://localhost:8080/api/points/pump_run		curl -X PUT -H 'Content-Type: application/json' -d '{"value":1}' http://localhost:8080/api/points/pump_run
	curl -X PUT -H 'Content-Type: application/json' -d '{"value":4242}' http://localhost:8080/api/points/tank_level		curl -X PUT -H 'Content-Type: application/json' -d '{"value":4242}' http://localhost:8080/api/points/tank_level

			=== Pulse (momentary output) ===

			<code>POST /api/points/{name}/pulse</code> sets a writable point active, holds it, then '''guarantees''' it returns to a rest value — with the timing owned by the Bridge, not the caller. It exists to drive a PLC relay safely: a dropped web session, a client crash, or a link blip during the hold can never leave the relay energised.

			The following energises <code>pump_run</code> for 3 seconds, then resets it to 0:

			curl -X POST -H 'Content-Type: application/json' -d '{"value":1,"holdMs":3000,"restValue":0}' http://localhost:8080/api/points/pump_run/pulse

			* '''The response is a real confirmation.''' <code>200</code> means the relay was energised and its reset is scheduled; <code>503</code> means nothing was energised (link down) and nothing is owed. The set runs on the request thread; the hold and reset run in the background.
			* '''The reset is guaranteed''' across a dropped caller session, a link drop during the hold (it retries as the Bridge reconnects), and a graceful service stop (the reset is flushed ''before'' the Modbus link closes). It is '''not''' guaranteed across a hard kill or power loss — for that, configure a PLC-side hardware watchdog that de-energises a coil that stops being refreshed.
			* '''<code>holdMs</code>''' must be within the point's <code>minHoldMs..maxHoldMs</code> (see [[#Per-point pulse hold policy (optional, writable points only)\|the config section]]; defaults <code>1..60000</code>) so a typo can't hold a relay for hours — set a tight per-point range on real relay coils. '''<code>restValue</code>''' is optional (default 0). The point's bounds and its <code>defaultHoldMs</code> are reported in every points payload for clients to discover.
			* '''Concurrency:''' pulses on the same point run one complete set→hold→reset cycle at a time, so the relay returns to rest between them; a caller that outruns the queue gets <code>409</code>. Pulses on different points are independent. Note that a '''queued''' pulse's HTTP response is delayed until its turn to fire (up to <code>holdMs</code> × its position in the queue), so a client's request timeout must exceed the worst-case wait, or it may abandon a pulse that still fires server-side.

	== Web UI ==		== Web UI ==
Line 110:		Line 145:
	Open <code>http://<host>:8080/</code> in a browser:		Open <code>http://<host>:8080/</code> in a browser:

	* '''Points''' (<code>index.html</code>) — a live table of every configured point, updated by push (SSE) with no refresh needed. Writable points have an inline editor; type a value and click '''Set''' (or press Enter) to issue the PUT. Stale values (link down) are shown in red. A manual '''Refresh''' button is kept as a fallback.		* '''Points''' (<code>index.html</code>) — a live table of every configured point, updated by push (SSE) with no refresh needed. Writable points have an inline editor; type a value and click '''Set''' (or press Enter) to issue the PUT. Next to it, a '''Pulse''' button with a hold-time field (pre-filled from the point's <code>defaultHoldMs</code>, bounded by its <code>minHoldMs</code>/<code>maxHoldMs</code>) sets the value, holds it for that time, then auto-resets to 0 — the timing runs server-side (see [[#Pulse (momentary output)\|Pulse]]), so closing the page mid-hold cannot leave the point energised. You can watch the value go active and drop back live in the table. Stale values (link down) are shown in red. A manual '''Refresh''' button is kept as a fallback.
	* '''Log''' (<code>log.html</code>) — the recent log backlog followed live as new lines are written, with an auto-scroll toggle. <code>WARN</code> / <code>ERROR</code> lines are colour-coded.		* '''Log''' (<code>log.html</code>) — the recent log backlog followed live as new lines are written, with an auto-scroll toggle. <code>WARN</code> / <code>ERROR</code> lines are colour-coded.
	* '''Licences''' (<code>licence.html</code>) — the third-party libraries and their licences rendered as a table (the underlying <code>/api/licence</code> endpoint returns the same data as raw JSON).		* '''Licences''' (<code>licence.html</code>) — the third-party libraries and their licences rendered as a table (the underlying <code>/api/licence</code> endpoint returns the same data as raw JSON).

Dgarratt: Updated by push_wiki.py

2026-06-22T14:23:07Z

Updated by push_wiki.py

← Older revision		Revision as of 16:23, 22 June 2026
Line 131:		Line 131:
	* [[ModbusClient]] — the interactive desktop Modbus client; the Bridge reuses its Modbus engine		* [[ModbusClient]] — the interactive desktop Modbus client; the Bridge reuses its Modbus engine
	* [[ModbusServer]] — the server-side companion tool, useful as a bench target for the Bridge		* [[ModbusServer]] — the server-side companion tool, useful as a bench target for the Bridge
	* [[AutoLab4j]] — ~~an automatic labeller that~~ uses the same Modbus stack to ~~watch production-line signals~~		* [[AutoLab4j]] — uses the same Modbus stack to monitor a coil and trigger a labeller on a change of state
	* [[SocketTest]] — a raw TCP/IP testing utility		* [[SocketTest]] — a raw TCP/IP testing utility

	[[Category:Commander4j]]		[[Category:Commander4j]]

Dgarratt: Updated by push_wiki.py

2026-06-22T14:22:34Z

Updated by push_wiki.py

← Older revision		Revision as of 16:22, 22 June 2026
Line 131:		Line 131:
	* [[ModbusClient]] — the interactive desktop Modbus client; the Bridge reuses its Modbus engine		* [[ModbusClient]] — the interactive desktop Modbus client; the Bridge reuses its Modbus engine
	* [[ModbusServer]] — the server-side companion tool, useful as a bench target for the Bridge		* [[ModbusServer]] — the server-side companion tool, useful as a bench target for the Bridge
	* [[AutoLab4j]] — uses the same Modbus stack to ~~read laboratory instruments~~		* [[AutoLab4j]] — an automatic labeller that uses the same Modbus stack to watch production-line signals
	* [[SocketTest]] — a raw TCP/IP testing utility		* [[SocketTest]] — a raw TCP/IP testing utility

	[[Category:Commander4j]]		[[Category:Commander4j]]

Dgarratt: Updated by push_wiki.py

2026-06-22T14:00:59Z

Updated by push_wiki.py

Show changes

Dgarratt: Created blank page

2026-06-22T13:44:23Z

Created blank page

New page

ModbusBridge - Revision history

Dgarratt: Updated by push_wiki.py

Dgarratt: Updated by push_wiki.py

Dgarratt: Updated by push_wiki.py

Dgarratt: Updated by push_wiki.py

Dgarratt: Updated by push_wiki.py

Dgarratt: Created blank page