API: Net Server

Nodbus-Plus v1.0 Documentation

The Nodbus library uses a NetServer abstraction to implement the network layer for Modbus servers (TCP, UDP, or serial). A build-in NetServer instance may wrap one of the following transport implementations:

  • tcpServer — wrapper around Node’s net.Server (node.net.Server).

  • udpServer — wrapper around Node’s dgram.Socket (node.dgram.Socket).

  • serialServer — wrapper around the serialport package (serialport).

Creating a NetServer instance

new NetServer([options])

options is an object whose supported properties depend on the transport type.

TCP / UDP options

  • port <number>: TCP/UDP port to listen on (default: 502).

  • maxConnections <number>: Maximum simultaneous TCP connections (TCP only). Default: 32.

  • udpType <string>: For UDP channels, either udp4 or udp6 (default: udp6).

Serial options

  • port <string>: Serial port path (example: COM1).

  • baudRate <number>: Baud rate in bps (for example: 110, 300, 1200, 2400, 4800, 9600, 14400, 19200, 38400, 57600, 115200). Default: 19200.

  • dataBits <number>: 7 or 8 (default: 8).

  • stopBits <number>: 1 or 2 (default: 1).

  • parity <string>: none, even, or odd (default: none).

  • timeBetweenFrame <number>: Milliseconds to consider the end of a Modbus RTU frame.

Constructor returns a configured NetServer instance for the chosen transport.

Event hooks

NetServer is not an EventEmitter. Instead, it exposes hook properties that the caller assigns to handle transport events. Hook signatures are documented below.

onConnectionAcceptedHook()

Called when the underlying transport accepts a new connection (TCP).

  • socket <object>: The connection/socket object created by the transport.

netServer.onConnectionAcceptedHook = (socket) => {
  console.log('New connection accepted:', socket.remoteAddress);
};

onDataHook(data)

Called when raw data arrives from the transport. This is invoked before any protocol-level validation.

  • source <object>: The source of the data (socket in tcp, rinfo in udp or serial port in serial).

  • data <Buffer>: Raw bytes received.

netServer.onDataHook = (source, data) => {
  console.log('Data received from', source, ':', data);
};

onErrorHook(err)

Called when the transport reports an error.

  • err <Error>: Error object.

netServer.onErrorHook = (err) => {
  console.error('Transport error:', err);
};

onListeningHook()

Called when the underlying server starts listening. No arguments are passed.

netServer.onListeningHook = () => {
  console.log('Server is now listening on port', netServer.port);
};

onMbAduHook(source,data)

Called when received data has been validated as a Modbus ADU (after protocol-level validation).

  • source <object>: The source of the data (socket in tcp, rinfo in udp or serial port in serial).

  • data <Buffer>: Validated Modbus ADU.

onServerCloseHook()

Called when the underlying transport closes. No arguments are passed.

netServer.onServerCloseHook = () => {
  console.log('Server has closed');
};

onWriteHook(source, data)

Called after data has been written to the transport.

  • source <object>: The source of the data (socket in tcp, rinfo in udp or serial port in serial).

  • data <Buffer>: Bytes that were written.

netServer.onWriteHook = (source, data) => {
  console.log('Data written to', source, ':', data);
};

Attributes

Attribute: netServer.activeConnections (TCP only)

  • <Array>: List of active connections/sockets.

Attribute: netServer.coreServer

  • <object> — Underlying transport instance:

    • net.Server for TCP

    • dgram.Socket for UDP

    • SerialPort for serial transport (from the serialport package)

This property stores the actual transport object used by the NetServer wrapper.

Attribute: netServer.isListening

  • <boolean>: true when the underlying transport is listening/open, otherwise false.

Attribute: netServer.maxConnections

  • <number>: Maximum number of TCP connections (TCP only).

Attribute: netServer.port

  • <number|string>: TCP/UDP port number or serial port path.

Attribute: netServer.tcpCoalescingDetection

  • <boolean>: Enable or disable TCP coalescing detection for Modbus TCP frames (default: false).

Attribute: netServer.validateFrame

  • <function>: Function used to validate incoming frames at the network layer.

It receives a Buffer containing the frame and should return true when the frame is complete and valid for the chosen protocol.

Attributes: hook properties

The following hook properties reference functions described in the “Event hooks” section above:

  • onConnectionAcceptedHook

  • onDataHook

  • onErrorHook

  • onListeningHook

  • onMbAduHook

  • onServerCloseHook

  • onWriteHook

Methods

Method: netServer.start()

Start the server and begin accepting connections or listening on the configured transport.

netServer.start();

Method: netServer.stop()

Stop the server. Existing connections may be closed and no new connections will be accepted.

netServer.stop();

Method: netServer.write(socket, frame)

Write a frame to a client socket.

  • socket <object>: The destination socket/connection.

  • frame <Buffer>: Buffer containing the ADU or PDU to send.

After writing, the implementation should call the onWriteHook hook.