nodbus-plus 0.8.2 → 1.0.0

package/.readthedocs.yaml

@@ -0,0 +1,35 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+    # You can also specify other tool versions:
+    # nodejs: "19"
+    # rust: "1.64"
+    # golang: "1.19"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+   configuration: docs/conf.py
+
+# Optionally build your docs in additional formats such as PDF and ePub
+# formats:
+#    - pdf
+#    - epub
+
+# Optional but recommended, declare the Python requirements required
+# to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+
+# Optionally declare the Python requirements required to build your docs
+python:
+   install:
+   - requirements: docs/requirements.txt
+     

package/LICENSE.md

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2017 Héctor Enrique Socarrás Cabrera
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2017 Héctor Enrique Socarrás Cabrera
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,48 +1,163 @@
-# Nodbus-Plus
-
-A nodejs modbus library fully writed in javascript.
-
-## Getting Started
-* ### Install
-#### installing nodbus-plus as a node package
-    $ npm install nodbus-plus
-#### installing nodbus from source
-
-* ### Basic Usage:
-
-Create a modbus tcp server.
-
-      var ModbusTcpServer = require('nodbus-plus').ModbusTcpServer;
-      var Slave = new ModbusTcpServer(502);
-      Slave.Start();
-or use function CreateSlave:
-
-      var nodbus = require('nodbus-plus');
-      var ModbusTcpServer = nodbus.CreateSlave(502);
-
-  Create a modbus serial slave over tcp.
-
-        var ModbusSTcpServer = require('nodbus-plus').ModbusSTcpServer;
-        var Slave = new ModbusSTcpServer(502, 1);
-        Slave.Start();
-
-  or use function CreateSlave:
-
-        var nodbus = require('nodbus-plus');
-        var ModbusSTcpServer = nodbus.CreateSlave(502, 1);
-
-Create a modbus tcp client.
-
-    var ModbusTcpClient = require('nodbus-plus').ModbusTcpClient;
-    var client = new ModbusTcpClient();
-
-## Documentation and Tutorials
-See: https://github.com/hsocarras/nodbus-plus/wiki
-## Contributing
-
-If you have a suggestion or found a issue, let us known and [create an issue](https://github.com/hsocarras/nodbus-plus/issues)
-
-
-## License
-
-This project is licensed under the MIT License - see the LICENSE.md file for details
+# Nodbus-Plus
+
+A Modbus protocol library for Node.js, written entirely in JavaScript. It supports both Modbus Serial and Modbus TCP.
+
+## Introduction
+
+Nodbus Plus has been designed as a stack for the Modbus protocol. It can be used to create both your own Modbus client and server using its API, or you can use its build in client or server and have an application with Modbus communication in just minutes.
+
+## Installation
+
+```console
+$ npm install nodbus-plus
+``` 
+
+## Basic Usage:
+
+### Create a modbus server.
+
+```javascript
+const nodbus = require('nodbus-plus');
+
+//Basic config for tcp server. Default values.
+const cfg = {
+    inputs : 2048, //total inputs
+    coils : 2048,  //total coils
+    holdingRegisters : 2048, //total holding register
+    inputRegisters : 2048,  //total input register
+    port : 502,    //port to listen to
+}
+
+let server = nodbus.createTcpServer('tcp', cfg);
+```
+The first argument for createTcpServer function is the type of transport layer used. The nodbus-plus tcp server suport 'tcp', 'udp4' and 'udp6'. To create a 
+serial server the procedure is the same, but calling createSerialServer function instead.
+
+```javascript
+//Basic config for tcp server. Default values.
+let cfg = {
+    address : 1,
+    transmitionMode: 0, //0-rtu, 1 - ascii
+    inputs : 2048,
+    coils : 2048,
+    holdingRegisters : 2048,
+    inputRegisters : 2048,  
+    port : 502,    
+}
+
+let server = nodbus.createSerialServer('tcp', cfg);
+```
+The createSerialServer function can take the value 'serial' as fist argument as well, however the property port mus be a string
+with the path to a serial port and adicional port configuration property may be needed. See nodbus-plus api for more details.
+
+Add listeners for srever's events
+
+```javascript
+//listenning event
+server.on('listening', function(port){
+    console.log('Server listening on: ' + port);        
+});
+
+//event emited when a request are received
+server.on('request', function(sock, req){
+    console.log('Request received')
+    console.log(req)
+});
+
+//Event emited when server send a response to client
+server.on('response', function(sock, res){
+    console.log('Responding')
+    console.log(res)
+});
+
+server.on('error', function(err){
+    console.log(err)
+});
+```
+Finally the server must be started.
+
+```javascript
+server.start();
+```
+### Create a modbus client.
+
+To create a modbus client use the functions createTcpClient or createSerialClient.
+
+```javascript
+const nodbus = require('nodbus-plus');
+let client = nodbus.createSerialClient();
+
+//emitted when the client stablish connection with the server
+client.on('connection', (id)=>{
+    console.log('connection stablish')    
+})
+
+//emited when error occurs
+client.on('error', (e)=>{    
+    console.log(e)    
+})
+
+//emitted when a request is sended to server
+client.on('request', (id, req)=>{
+    console.log('request sended to device: ' + id);        
+})
+
+//emited when no response is received
+client.on('req-timeout', (id, adu)=>{
+    console.log('timeout')        
+})
+
+//emited when a response is received
+client.on('response', (id, res)=>{
+    console.log(res)        
+})
+```
+
+Then channels must be add to the client. The client will create a connection per channel. The following example add a modbus serial over tcp server, and conect to it.
+
+```javascript
+
+//channel
+channelCfg = {        
+    ip:'127.0.0.1',
+    port:502,
+    timeout:250,
+}
+
+client.addChannel('device', 'tcp1', channelCfg);
+client.connect('device')
+
+```
+
+Once the client is connected, and event listener configured, data can be exchange using availables modbus function.
+
+```javascript
+
+//reading from cannel 'device', modbus address 1, two coils from 0 coil's address
+    client.readCoils('device', 1, 0, 2);
+
+```
+
+### Official Documentation
+
+For comprehensive information on how to use NodbusPlus, refer to the [official documentation](https://nodbus-plus.readthedocs.io/en/latest/).
+
+### Getting Started
+
+If you're new to NodbusPlus, the [Getting Started Guide](https://nodbus-plus.readthedocs.io/en/latest/starting.html) is a great place to begin.
+It will walk you through the installation process and provide a basic usage example.
+
+
+### Examples
+
+Inside the root folder of Nodbus plus, there is a directory './samples' that contains three example programs that make use of the library.
+
+
+## Contributing
+
+If you have a suggestion or found a issue, let us known and [create an issue](https://github.com/hsocarras/nodbus-plus/issues)
+
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE.md file for details

package/docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

package/docs/client/channel.rst

@@ -0,0 +1,209 @@
+.. _nodbus_net_channel:
+
+===========================
+API: Net Channel
+===========================
+
+**Nodbus-Plus v1.0 Documentation**
+
+.. contents:: Table of Contents
+   :depth: 3
+
+Nodbus implementation for a  modbus TCP or serial client use a netChanner object to implement the network layer. This object can be one of the following types:
+
+* **TcpChannel**: A wrapper around node `net.Socket <https://nodejs.org/api/net.html#class-netserver>`_.
+
+* **UdpChannel**: A wrapper around node `dgram.Socket <https://nodejs.org/api/dgram.html#class-dgramsocket>`_.
+
+* **SerialChannel**: A wrapper around node `serialport <https://serialport.io/>`_ .
+
+
+Creating a Nodbus NetChannel Instance
+====================================
+
+new NetChannel([options])
+-------------------------
+
+* **options** <object>: Configuration object with the following properties (for tcp and udp channel) :
+
+   * port <number> : The tcp or udp port to listen. Default 502.
+   * ip <string>: Ip address
+
+* **options** <object>: Configuration object with the following properties (for serial channel):
+
+   * port <string> : The path to the serial port. Example 'COM1.
+   * speed <number>: Enum with following baudrates in bps : 0-110, 1-300, 2-1200, 3-2400, 4-4800, 5-9600, 6-14400, 7-19200, 8-38400, 9-57600, 10-115200. Default 7.
+   * dataBits <number>: 7 or 8. Default 8.
+   * stopBits <number>: 0 or 1.
+   * parity <number>: Enum with following value. 0-'none', 1-'even', 2-'odd'. Default 1.
+   * timeBetweenFrame <number>: Number of millisends to await without receiving data to consider end of modbus frame.
+
+Constructor for new NetChannel instance.
+
+
+NetChannel Event's Hooks
+========================
+
+The net channel object is not a event emitter, instead it uses the core channel's events to call hooks functions.
+
+onConnectHook
+-------------------------
+
+This function is called when the core channel object emits the 'connect' event.
+
+onDataHook
+-----------
+
+
+* **data** <Buffer>: Data received.
+
+This function is called when the core channel emits the data event.
+
+onErrorHook
+-----------
+
+* **e** <object>: error object.
+
+This function is called when the core channel emits the 'error' event.
+
+
+onMbAduHook
+-------------
+
+
+* **data** <Buffer>: Data received.
+
+This hook function is similar to onDataHook, but is only called when the buffer received has been validated.
+
+
+onCloseHook
+------------------
+
+This hook function is called when core channel emits the 'close' event. It is called with no arguments.
+
+onWriteHook
+-----------
+
+* **data** <Buffer>: Data sended.
+
+This hook function is called when data has been sennded to a server. It is called when connection socket write some data.
+
+
+NetChannel's Atributes
+=======================
+
+Atribute: netChannel.coreChannel
+---------------------------------
+
+* <object>
+
+   * **net.Socket**: For tcp `node <https://nodejs.org/api/net.html#class-netsocket>`_. 
+   * **dgram.Socket**: For udp `node <https://nodejs.org/api/dgram.html#class-dgramsocket>`_.
+   * **SerialPort**: A wrapper around node `serialport <https://serialport.io/docs/api-serialport>`_ .
+
+This property is a node net.Socket or  udp.Socket in nodbus tcpClient class or serialport from serialport library in nodbus serial client. 
+The netChannel class in Nodbus-Plus library is a wrapper around one of this main class.
+
+Atribute: netChannel.ip
+--------------------------------------------
+
+* <string>: server's ip address.
+
+
+Atribute: netChannel.onConnectHook
+----------------------------------------------
+
+* <function>
+
+This property is a reference for a hook function. See :ref:`onConnectHook`
+
+
+Atribute: netChannel.onDataHook
+----------------------------------
+
+* <function>
+
+This property is a reference for a hook function. See :ref:`onDataHook`
+
+
+Atribute: netChannel.onErrorHook
+----------------------------------
+
+* <function>
+
+This property is a reference for a hook function. See :ref:`onErrorHook`
+
+
+
+Atribute: netChannel.onMbAduHook
+----------------------------------
+
+* <function>
+
+This property is a reference for a hook function. See :ref:`onMbAduHook`
+
+
+
+Atribute: netChannel.onWriteHook
+----------------------------------
+
+* <function>
+
+This property is a reference for a hook function. See :ref:`onWriteHook`
+
+Atribute: netChannel.port
+-----------------------------
+
+* <number>
+
+Port where the server is listening.
+
+Atribute: netChannel.tcpCoalescingDetection
+--------------------------------------------
+
+* <boolean>
+
+Activate o deactivate the tcp coalscing detection function for modbus tcp protocol. Default false.
+
+
+Atribute: netChannel.validateFrame
+----------------------------------
+
+* <function>
+
+This property is a reference to a function that performs validation.
+ It defines how the nodbus server executes certain protocols for validating data at the network layer level.
+
+ It is called with a Buffer as argument with the modbus frame received.
+
+
+netChannel's Methods
+====================
+
+
+Method: netChannel.connect()
+-------------------------------
+
+* **Return** <Promise>: Promise that will be resolve when the connection is stabished whit  a socket as argument, or rejected with ip and port as parameter.
+
+This method try to connect to channels ip and port, return a promise that resolve if the connectios is stablished successfully, otherwhise is rejected.
+
+
+Method: netChannel.disconnect()
+-------------------------------
+
+* **Return** <Promise>: Promise that will be resolve when the connection is closed.
+
+Method: netChannel.isConnected()
+-------------------------------
+
+* **Return** <bool>: Return true is the socket is connected.
+
+
+Method: netChannel.write(socket, frame)
+-------------------------------------------------
+
+* **socket** <object>: buffer containig the pdu's data.
+* **frame** <Buffer>: buffer with response pdu.
+
+function to write data to a server. It takes a srteam object and a buffer to write to. When data has been send, the function calls onWriteHook funtion.