nodbus-plus 0.8.2 → 1.0.0

package/docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

package/docs/protocol/modbus_master.rst

@@ -0,0 +1,276 @@
+.. _modbus_master:
+
+==========================
+Class: ModbusClient
+==========================
+
+.. contents:: Table of Contents
+   :depth: 3
+
+**Nodbus-Plus v1.0 Documentation**
+
+This class is an EventEmitter. It provides the basic functionalities to make Modbus Protocol Data Units (PDU).
+
+.. Figure:: /images/modbus_pdu.png
+
+   *Modbus Protocol Data Unis*
+
+
+Creating a ModbusClient Instance
+================================
+
+new ModbusClient()
+------------------
+
+* **Returns:** <ModbusClient>
+
+Constructor for new ModbusClient instance.
+
+.. code-block:: javascript
+
+      const ModbusClient = require('nodbus-plus').ModbusClient;
+      let modbusClient = new ModbusClient();                
+
+
+ModbusClient's Methods
+======================
+
+.. _modbus_client_methods:
+
+Method: modbusClient.readCoilStatusPdu([startCoil],[coilQuantity])
+------------------------------------------------------------------
+
+* **startCoil** <number>: First coil to read, starting at address 0. Default value is 0
+* **coilQuantity** <number>: Number of coils to read. Default value is 1
+* **Return** <Buffer>: buffer with req pdu.
+
+.. Figure:: /images/01-readcoils.png
+
+   *Modbus Read Coils Request and Response*
+
+This method create the read coil status request pdu. Function code 01.
+
+Method: modbusClient.readInputStatusPdu([startInput],[inputQuantity])
+---------------------------------------------------------------------
+
+* **startInput** <number>: First input to read, starting at address 0. Default value is 0
+* **inputQuantity** <number>: Number of inputs to read. Default value is 1
+* **Return** <Buffer>: buffer with req pdu.
+
+.. Figure:: /images/02-readinputs.png
+
+   *Modbus Read Inputs Request and Response*
+
+This method create the read input status request pdu. Function code 02.
+
+Method: modbusClient.readHoldingRegistersPdu([startRegister],[registerQuantity])
+--------------------------------------------------------------------------------
+
+* **startRegister** <number>: First register to read, starting at address 0. Default value is 0
+* **registerQuantity** <number>: Number of registers to read. Default value is 1
+* **Return** <Buffer>: buffer with req pdu.
+
+.. Figure:: /images/03-readholding.png
+
+   *Modbus Read Holding Registers Request and Response*
+
+This method create the read holding register request pdu. Function code 03.
+
+Method: modbusClient.readInputRegistersPdu([startRegister],[registerQuantity])
+------------------------------------------------------------------------------
+
+* **startRegister** <number>: First register to read, starting at address 0. Default value is 0
+* **registerQuantity** <number>: Number of registers to read. Default value is 1
+* **Return** <Buffer>: buffer with req pdu.
+
+.. Figure:: /images/04-readinputsreg.png
+
+   *Modbus Read Inputs Registers Request and Response*
+
+This method create the read inputs register request pdu. Function code 04.
+
+
+Method: modbusClient.forceSingleCoilPdu(value, [startCoil])
+------------------------------------------------------------
+
+* **value** <Buffer>: Two bytes length buffer. Valid values are [0x00, 0x00] for false and [0xFF, 0x00] for true.
+* **startCoil** <number>: Coil to be writed. Default value is 0.
+* **Return** <Buffer>: buffer with req pdu.
+
+.. Figure:: /images/05-writecoil.png
+
+   *Modbus Write Single Coil Request and Response*
+
+This method create the force single coil request pdu. Function code 05. If value is not a Buffer throw a TypeError and if value's length is diferent than 2 
+throw a RangeError.
+
+
+Method: modbusClient.presetSingleRegisterPdu(value, [startRegister])
+--------------------------------------------------------------------
+
+* **value** <Buffer>: Two bytes length buffer.
+* **startRegister** <number>: Register's address to be writed. Default value is 0.
+* **Return** <Buffer>: buffer with req pdu.
+
+.. Figure:: /images/06-writeregister.png
+
+   *Modbus Write Single holding Register Request and Response*
+
+This method create the preset single register request pdu. Function code 06. If value is not a Buffer throw a TypeError and if value's length is diferent than 2 
+throw a RangeError.
+
+
+Method: modbusClient.forceMultipleCoilsPdu(values, startCoil, coilQuantity)
+---------------------------------------------------------------------------
+
+* **values** <Buffer>: Buffer with coils values.
+* **startCoil** <number>: First Coil starting address.
+* **coilQuantity** <number>: Number of coils to write.
+* **Return** <Buffer>: buffer with req pdu.
+
+.. Figure:: /images/15-writecoil.png
+
+   *Modbus Write Multiple Coils Request and Response*
+
+This method create the force multiples coils request pdu. Function code 15. If values is not a Buffer throw a TypeError and if value's length is higher than 246
+throw a RangeError.
+
+
+Method: modbusClient.presetMultipleRegistersPdu(values, startRegister, [registerQuantity])
+-------------------------------------------------------------------------------------------
+
+* **values** <Buffer>: Buffer with registers values.
+* **startRegister** <number>: First register starting address.
+* **registerQuantity** <number>: Number of registers to write. Default value is values.length/2.
+* **Return** <Buffer>: buffer with req pdu.
+
+.. Figure:: /images/16.png
+
+   *Modbus Write Multiple Registers Request and Response*
+
+This method create the preset multiples registers request pdu. Function code 16. If values is not a Buffer throw a TypeError and if value's length is higher than 246
+throw a RangeError.
+
+
+Method: modbusClient.maskHoldingRegisterPdu(values, [startRegister])
+---------------------------------------------------------------------
+
+* **values** <Buffer>: Buffer with registers values.
+* **startRegister** <number>: Register address to modify.
+* **Return** <Buffer>: buffer with req pdu.
+
+.. Figure:: /images/22-mask.png
+
+   *Modbus Mask Register Request and Response*
+
+This method create the mask holding register request pdu. Function code 22. If values is not a Buffer throw a TypeError and if value's length is diferent than 4
+throw a RangeError.
+
+
+Method: modbusClient.readWriteMultipleRegistersPdu(values,  readStartingAddress, quantitytoRead, writeStartingAddress, quantityToWrite)
+---------------------------------------------------------------------------------------------------------------------------------------
+
+* **values** <Buffer>: Buffer with registers values to write.
+* **readStartingAddress** <number>: First register's address to read.
+* **quantitytoRead** <number>: Number of register to read.
+* **writeStartingAddress** <number>: First register's address to write.
+* **quantityToWrite** <number>: Number of registers to write.
+* **Return** <Buffer>: buffer with req pdu.
+
+.. Figure:: /images/23.png
+
+   *Modbus Read and Write Multiple Registers Request and Response*
+
+This method create the read and write holding register request pdu. Function code 23. If values is not a Buffer throw a TypeError and if value's length is greater than 243
+throw a RangeError.
+
+
+Method: modbusClient.boolToBuffer(value)
+---------------------------------------------------------------------
+
+* **value** <boolean>
+* **Return** <Buffer>: Two bytes length Buffer. 
+
+This is a utitlity method. It returns a buffer with a boolean value encoded for use on forceSingleCoilPdu function as value argument. Example:
+
+.. code-block:: javascript
+
+    let value = modbusClient.boolToBuffer(false);
+    console.log(value); //Buffer:[0x00, 0x00]
+    value = modbusClient.boolToBuffer(true);
+    console.log(value); //Buffer:[0xFF, 0x00]
+
+
+Method: modbusClient.getMaskRegisterBuffer(value)
+---------------------------------------------------------------------
+
+* **value** <Array>: An 16 numbers length array indicating how to mask the register.
+* **Return** <Buffer>: Four bytes length Buffer. 
+
+This is a utility method that return a four-byte length buffer with the AND_MASK and OR_MASK values encoded for use in the maskHoldingRegisterPdu function as the value argument. 
+
+The value argument is a 16-number array, with each number representing the position of one bit inside the register. If the number is 1, then the corresponding bit will be set to 1. 
+If the number is 0, then the corresponding bit will be set to 0. If the number is different from 0 or 1, then the corresponding bit will remain unchanged. For example:
+
+.. code-block:: javascript
+
+    let value = [-1, 0, 1, -1, -1, -1, 0, 0, 1, -1, -1, -1, -1, -1, 1, 1];
+    maskBuffer = modbusClient.getMaskRegisterBuffer(value);
+
+    //masks
+    let andMask =  maskBuffer.readUInt16BE(0);     
+    let orMask =   maskBuffer.readUInt16BE(2);
+
+    let testRegister = Buffer.from([0x9A, 0xFB]);
+    console.log(testRegister)
+    let currentContent = testRegister.readUInt16BE(0);
+    let finalResult = (currentContent & andMask) | (orMask & (~andMask)); //Modbus Spec 
+
+    let finalRegister = Buffer.alloc(2);
+    finalRegister.writeUInt16BE(finalResult, 0);    
+    console.log(finalRegister)
+
+    //Output
+    //<Buffer 9a fb>
+    //<Buffer db 3d>
+
+Method: modbusClient.boolsToBuffer(value)
+---------------------------------------------------------------------
+
+* **value** <Array>: A boolean array.
+* **Return** <Buffer>: a buffer with binary representation of boolean array. 
+
+This is a utility method that return a buffer from a boolean array for modbus function code 15. 
+
+The value argument is an array of boolean with values to be force to coils. For example:
+
+.. code-block:: javascript
+
+    let values = [0, 1, 0, 0, 0, 0, 1, 1, 0, 0, 1]; //at 0 index stat LSB Byte
+    valBuffer = modbusClient.boolsToBuffer(values);
+
+    //result valBuffer [0xC2 0x04]
+    // calling force multiples colis
+    let pdu = modbusClient.forceMultipleCoilsPdu(valBuffer, 10, values.length)  //calling force multiples coils at coil 10 and 11 coils to force
+
+
+
+Method: modbusClient.getWordFromBuffer(targetBuffer, [offset])
+--------------------------------------------------------------
+
+* **targetBuffer** <Buffer>: Buffer with the objetive 16 bits register to read.
+* **offset** <number>: A number with register's offset inside the buffer.
+* **Return** <Buffer>: A two bytes length buffer.
+
+
+This method read two bytes from target buffer with 16 bits align. Offset 0 get bytes 0 and 1, offset 4 gets bytes 8 and 9
+
+
+Method: modbusClient.setWordToBuffer(value, targetBuffer, [offset])
+-------------------------------------------------------------------
+
+* **value** <Buffer>: two bytes length buffer.
+* **targetBuffer** <Buffer>: Buffer with the objetive 16 bits register to write.
+* **offset** <number>: A number with register's offset inside the buffer.
+
+This method write a 16 bits register inside a buffer. The offset is 16 bits aligned.

package/docs/protocol/modbus_master_serial.rst

@@ -0,0 +1,290 @@
+.. _modbus_serial_master:
+
+===========================
+Class: ModbusSerialClient
+===========================
+
+**Nodbus-Plus v1.0 Documentation**
+
+.. contents:: Table of Contents
+   :depth: 3
+
+This class extends :ref:`ModbusClient Class <modbus_master>`. It provides the basic functionalities to handle Modbus Serial Aplication Data Units (ADU).
+
+.. Figure:: /images/serial_adu.png
+
+   *Modbus Serial Aplication Data Unis*
+
+Creating a ModbusSerialClient Instance
+======================================
+
+new ModbusSerialClient()
+-------------------------
+
+* **Returns:** <ModbusSerialClient>
+
+Constructor for new ModbusSerialClient instance.
+
+.. code-block:: javascript
+
+      const ModbusSerialClient = require('nodbus-plus').ModbusSerialClient;
+      let modbusSerialClient = new ModbusSerialClient();
+
+
+ModbusSerialClient's Events
+===========================
+
+Event: 'broadcast-timeout'
+---------------------------
+
+This event is emmited when the number of milliseconds pass to :ref:`Method: modbusSerialClient.setTurnAroundDelay([timeout])` is reached. Indicate that client
+has no pending broadcast request and is free to send another request.
+
+
+Event: 'req-timeout'
+--------------------
+
+
+* **req** <Buffer>: Modbus request adu buffer.
+
+  .. code-block:: javascript
+
+      modbusSerialClient.on('req-timeout', (req) ->{
+         console.log('Timeout error from slave: ' + req[0] + '\n');
+      })
+
+This event is emmited when the number of milliseconds pass to :ref:`Method: modbusSerialClient.setReqTimer([timeout])` ends without call 
+:ref:`Method: modbusSerialClient.clearReqTimer()`.
+
+
+
+Event: 'transaction'
+--------------------
+
+* **req** <Buffer>: Modbus Tcp request adu. 
+* **res** <Buffer>: Modbus Tcp request adu.
+
+  
+
+This event is emmited when the :ref:`Method: modbusSerialClient.processResAdu(bufferAdu, [ascii])` is called to manage a server response.
+
+
+ModbusSerialClient's Atributes
+===============================
+
+Atribute: modbusSerialClient.activeRequest
+------------------------------------------
+
+* <Buffer>    
+
+This property store the current active request, if no request is pending then is null.
+
+
+Atribute: modbusSerialClient.activeRequestTimerId
+-------------------------------------------------
+
+* <Number>    
+
+A property to store active request's timer. Each request start a timeout timer when is sended to server. This map store the timer for the active request.
+
+Atribute: modbusSerialClient.turnAroundDelay
+---------------------------------------------
+
+* <number>
+   
+When the serial client send a broadcast request have to await for the turnaround timer to send a new request. This property staore the value in milliseconds for this timer.
+Default value is 10 ms.
+
+ModbusSerialClient's Methods
+============================
+
+.. _modbus_serial_client_methods:
+
+See :ref:`ModbusClient Class Methods <modbus_client_methods>` for base class inherited methods.
+
+
+Method: modbusSerialClient.aduAsciiToRtu(asciiFrame)
+----------------------------------------------------
+
+* **asciiFrame** <Buffer>: A serial ascii adu.
+* **Returns** <Buffer>: A serial rtu adu.
+
+This method get a ascii adu and convert it in a equivalent rtu adu, including the crc checksum.
+
+
+Method: modbusSerialClient.aduRtuToAscii(rtuFrame)
+----------------------------------------------------
+
+* **rtuFrame** <Buffer>: A serial rtu adu.
+* **Returns** <Buffer>: A serial ascii adu.
+
+This method get a rtu adu and convert it in a equivalent ascii adu, including the lrc checksum.
+
+
+Method: modbusSerialClient.boolToBuffer(value)
+---------------------------------------------------------------------
+
+* **value** <boolean>
+* **Return** <Buffer>: Two bytes length Buffer. 
+
+This is a utitlity method. It gets a buffer with a boolean value encoded for use on forceSingleCoilPdu function as value argument. Example:
+
+.. code-block:: javascript
+
+    let value = modbusSerialClient.boolToBuffer(false);
+    console.log(value); //Buffer:[0x00, 0x00]
+    value = modbusSerialClient.boolToBuffer(true);
+    console.log(value); //Buffer:[0xFF, 0x00]
+
+
+Method: modbusSerialClient.calcCRC(frame)
+--------------------------------------------------
+
+* **frame** <Buffer>: A serial rtu adu request buffer received by server.
+* **Returns** <number>: crc value for request.
+
+This method calculate the checksum for he buffer request and return it. It receives a complete rtu frame and ignore the crc field (last two bytes) when calculate the crc value.
+
+
+Method: modbusSerialClient.calcLRC(frame)
+--------------------------------------------------
+
+* **frame** <Buffer>: A serial ascii adu request buffer received by server.
+* **Returns** <number>: lrc value for request.
+
+This method calculate the checksum for he buffer request and return it. It receives a complete ascii frame including start character (:) and ending characters.
+
+
+Method: modbusSerialClient.getMaskRegisterBuffer(value)
+---------------------------------------------------------------------
+
+* **value** <Array>: An 16 numbers length array indicating how to mask the register.
+* **Return** <Buffer>: Four bytes length Buffer. 
+
+This is a utility method that return a four-byte length buffer with the AND_MASK and OR_MASK values encoded for use in the maskHoldingRegisterPdu function as the value argument. 
+
+The value argument is a 16-number array, with each number representing the position of one bit inside the register. If the number is 1, then the corresponding bit will be set to 1. 
+If the number is 0, then the corresponding bit will be set to 0. If the number is different from 0 or 1, then the corresponding bit will remain unchanged. For example:
+
+.. code-block:: javascript
+
+    let value = [-1, 0, 1, -1, -1, -1, 0, 0, 1, -1, -1, -1, -1, -1, 1, 1];
+    maskBuffer = modbusSerialClient.getMaskRegisterBuffer(value);
+
+    //masks
+    let andMask =  maskBuffer.readUInt16BE(0);     
+    let orMask =   maskBuffer.readUInt16BE(2);
+
+    let testRegister = Buffer.from([0x9A, 0xFB]);
+    console.log(testRegister)
+    let currentContent = testRegister.readUInt16BE(0);
+    let finalResult = (currentContent & andMask) | (orMask & (~andMask)); //Modbus Spec 
+
+    let finalRegister = Buffer.alloc(2);
+    finalRegister.writeUInt16BE(finalResult, 0);    
+    console.log(finalRegister)
+
+    //Output
+    //<Buffer 9a fb>
+    //<Buffer db 3d>
+
+
+Method: modbusSerialClient.boolsToBuffer(value)
+---------------------------------------------------------------------
+
+* **value** <Array>: A boolean array.
+* **Return** <Buffer>: a buffer with binary representation of boolean array. 
+
+This is a utility method that return a buffer from a boolean array for modbus function code 15. 
+
+The value argument is a array of boolean with values to bu force to coils. For example:
+
+.. code-block:: javascript
+
+    let values = [0, 1, 0, 0, 0, 0, 1, 1, 0, 0, 1]; //at 0 index stat LSB Byte
+    valBuffer = modbusSerialClient.boolsToBuffer(values);
+
+    //result valBuffer [0xC2 0x04]
+    // calling force multiples colis
+    let pdu = modbusSerialClient.forceMultipleCoilsPdu(valBuffer, 10, values.length)  //calling force multiples coils at coil 10 and 11 coils to force
+
+
+Method: modbusSerialClient.makeRequest(address, pdu, asciiMode)
+---------------------------------------------------------
+
+* **address** <number>: Modbus address.
+* **pdu** <Buffer>: The pdu's buffer.
+* **asciiMode** <boolean> A flag to indicate if the request must be in ascii format. Default value is false, rtu mode.
+* **Returns** <Buffer>: return a serial adu request's buffer
+
+This functions create a modbus serial request ready to be send to the client.
+
+
+Method: modbusSerialClient.setReqTimer([timeout])
+---------------------------------------------------
+
+* **timeout** <number>: Number of milliseconds to await for a response or fire timeout event.
+* **Returns** <number>: Timer's id to be use on clearTimeout.
+
+This functions store a timerId in the :ref:`request timers pool <Atribute: modbusSerialClient.activeRequestTimerId>`.
+
+
+Method: modbusSerialClient.setTurnAroundDelay([timeout])
+---------------------------------------------------
+
+* **timeout** <number>: Number of milliseconds to await for fire broadcast-timeout event.
+* **Returns** <number>: Timer's id to be use on clearTimeout.
+
+This functions store a timerId in the :ref:`request timers pool <Atribute: modbusSerialClient.turnAroundDelay>`. Is used when a broadcast request
+is sended.
+
+
+Method: modbusSerialClient.clearReqTimer()
+--------------------------------------------
+
+
+This functions call the build in clearTimeout function to avoid emit the'req-timeout' event.
+
+
+Method: modbusSerialClient.processResAdu(bufferAdu, [ascii])
+-------------------------------------------------------------
+
+* **bufferAdu** <Buffer>: A modbus tcp adu response buffer.
+* **ascii** <boolean>: A flag indicating if the response is in ascii mode.
+
+
+This method is used to managed server response. Call the :ref:`Method: modbusSerialClient.clearReqTimer()` to avoid emit 'req-timeout' event and emit the 'transaction' event.
+
+
+Method: modbusSerialClient.getWordFromBuffer(targetBuffer, [offset])
+--------------------------------------------------------------
+
+* **targetBuffer** <Buffer>: Buffer with the objetive 16 bits register to read.
+* **offset** <number>: A number with register's offset inside the buffer.
+* **Return** <Buffer>: A two bytes length buffer.
+
+
+This method read two bytes from target buffer with 16 bits align. Offset 0 get bytes 0 and 1, offset 4 gets bytes 8 and 9
+
+
+Method: modbusSerialClient.setWordToBuffer(value, targetBuffer, [offset])
+-------------------------------------------------------------------
+
+* **value** <Buffer>: two bytes length buffer.
+* **targetBuffer** <Buffer>: Buffer with the objetive 16 bits register to write.
+* **offset** <number>: A number with register's offset inside the buffer.
+
+This method write a 16 bits register inside a buffer. The offset is 16 bits aligned.
+
+
+Method: modbusSerialClient.storeRequest(bufferReq, ascciiMode)
+-------------------------------------------------------------------
+
+
+* **bufferRequest** <Buffer>: A buffer with the modbus request.
+* **asciiMode** <boolean>: A flag that indicate that request stored is ascii.
+* **return** <boolean>: True if success
+
+This method checks if activeRequest property is null, if not it return false indicating tha are still a request pending.
+It also checks if the request is ascii or not and set the internal ascii flag for active request.
+