Serial Port Monitor - Software Serial Port sniffer, logger & protocol analyzer for Windows
Download Device Monitoring Studio Hide this button

IModbusBuilder Interface

This interface is implemented by the MODBUS Builder Object. You create an instance of this object by calling the IModbusManager.createBuilder method.

Please consult the MODBUS protocol documentation for term definitions.

Declaration

interface IModbusBuilder {

    // Methods
    ${error}(functionID: number, exceptionCode: number): Uint8Array;
    ${requestDiagnostics}(subfunction: number, data: number): Uint8Array;
    ${requestGetCommEventCounter}(): Uint8Array;
    ${requestGetCommEventLog}(): Uint8Array;
    ${requestMaskWriteRegister}(referenceAddress: number, andMask: number, orMask: number): Uint8Array;
    ${requestReadCoils}(startingAddress: number, numberOfCoils: number): Uint8Array;
    ${requestReadDiscreteInputs}(startingAddress: number, numberOfInputs: number): Uint8Array;
    ${requestReadExceptionStatus}(): Uint8Array;
    ${requestReadFIFOQueue}(fifoPointerAddress: number): Uint8Array;
    ${requestReadFileRecord}(requests: ${ReadFileRequest}[]): Uint8Array;
    ${requestReadHoldingRegisters}(startingAddress: number, numberOfRegisters: number): Uint8Array;
    ${requestReadInputRegisters}(startingAddress: number, numberOfRegisters: number): Uint8Array;
    ${requestReadWriteMultipleRegisters}(readStartingAddress: number,
        numberToRead: number,
        writeStartingAddress: number,
        data: number [] | Uint16Array): Uint8Array;
    ${requestReportSlaveID}(): Uint8Array;
    ${requestUserFunction}(functionID: number, data: number[] | Uint8Array): Uint8Array;
    ${requestWriteFileRecord}(requests: ${FileRecord}[]): Uint8Array;
    ${requestWriteMultipleCoils}(startingAddress: number, data: boolean[]): Uint8Array;
    ${requestWriteMultipleRegisters}(startingAddress: number, data: number[] | Uint16Array): Uint8Array;
    ${requestWriteSingleCoil}(outputAddress: number, outputValue: number): Uint8Array;
    ${requestWriteSingleRegister}(registerAddress: number, registerValue: number): Uint8Array;
    ${responseDiagnostics}(subFunction: number, data: number [] | Uint8Array): Uint8Array;
    ${responseGetCommEventCounter}(status: number, eventCount: number): Uint8Array;
    ${responseGetCommEventLog}(status: number, events: number [] | Uint8Array): Uint8Array;
    ${responseMaskWriteRegister}(referenceAddress: number, andMask: number, orMask: number): Uint8Array;
    ${responseReadCoilStatus}(items: number [] | Uint8Array): Uint8Array;
    ${responseReadDiscreteInputs}(items: number [] | Uint8Array): Uint8Array;
    ${responseReadExceptionStatus}(outputData: number): Uint8Array;
    ${responseReadFIFOQueue}(registers: number [] | Uint16Array): Uint8Array;
    ${responseReadFileRecord}(requests: ${ReadFileResponse}[]): Uint8Array;
    ${responseReadHoldingRegisters}(registers: number [] | Uint16Array): Uint8Array;
    ${responseReadInputRegisters}(registers: number [] | Uint16Array): Uint8Array;
    ${responseReadWriteRegisters}(registers: number [] | Uint16Array): Uint8Array;
    ${responseReportSlaveID}(runIndicatorStatus: number,
        slaveIds: number [] | Uint8Array,
        data: number [] | Uint8Array): Uint8Array;
    ${responseWriteFileRecord}(requests: ${FileRecord}[]): Uint8Array;
    ${responseWriteMultipleCoils}(startingAddress: number, quantityOfOutputs: number): Uint8Array;
    ${responseWriteMultipleRegisters}(startingAddress: number, quantityOfRegisters: number): Uint8Array;
    ${responseWriteSingleCoil}(outputAddress: number, outputValue: number): Uint8Array;
    ${responseWriteSingleRegister}(outRegisterAddress: number, outValue: number): Uint8Array;
}
// This interface is not available in managed environment
// This interface is not available in native environment

IModbusBuilder Methods

error

error(functionID: number, exceptionCode: number): Uint8Array;
// This method is not available in managed environment
// This method is not available in native environment
functionID
Function code (ID). The function code is a number from 0 to 127. Internally, the MODBUS Send module appends 0x80 to it.
exceptionCode
Exception code (see MODBUS protocol documentation).

Construct the error response.

var message = builder.error(1, 20);

requestDiagnostics

requestDiagnostics(subfunction: number, data: number): Uint8Array;
// This method is not available in managed environment
// This method is not available in native environment
subfunction
Diagnostics sub-function code (0 to 65535). Please refer to the protocol documentation for a list of predefined sub-function codes.
data
Data to be returned (looped back) in the device response. Returned data should match the original for the request to be considered successful.

Send the Diagnostics (see MODBUS protocol documentation) request to the selected device.

var message = builder.requestDiagnostics(1, 65535);

requestGetCommEventCounter

requestGetCommEventCounter(): Uint8Array;
// This method is not available in managed environment
// This method is not available in native environment

Construct the Get Comm Event Counter request.

var message = builder.requestGetCommEventCounter();

requestGetCommEventLog

requestGetCommEventLog(): Uint8Array;
// This method is not available in managed environment
// This method is not available in native environment

Construct the Get Comm Event Log request.

requestMaskWriteRegister

requestMaskWriteRegister(referenceAddress: number, andMask: number, orMask: number): Uint8Array;
// This method is not available in managed environment
// This method is not available in native environment
referenceAddress
Reference address. It can be a number from 0 to 65535.
andMask
And Mask is used for bitwise AND operation on the selected register address. It can be a number from 0 to 65535.
orMask
And Mask is used for bitwise OR operation on the selected register address. It can be a number from 0 to 65535.

Construct the Mask Write Register request.

requestReadCoils

requestReadCoils(startingAddress: number, numberOfCoils: number): Uint8Array;
// This method is not available in managed environment
// This method is not available in native environment
startingAddress
First coil address.
numberOfCoils
Total number of coils to read. This parameter can take values from 1 to 65535 (0x0001 to 0xFFFF). However, the documentation allows only 1 to 2000 (0x0001 to 0x07D0) values to be used (see the MODBUS protocol documentation).

Construct the Read Coils request.

requestReadDiscreteInputs

requestReadDiscreteInputs(startingAddress: number, numberOfInputs: number): Uint8Array;
// This method is not available in managed environment
// This method is not available in native environment
startingAddress
First discrete input address. In some implementations device interprets this value as an offset - this value is added to default MODBUS base discrete input address (see MODBUS protocol documentation) 10000. Specify the 0 value for this parameter to read discrete input with 10000 address.
numberOfInputs
Total count of discrete inputs to be read. This parameter can take values from 1 to 65535 (0x0001 to 0xFFFF). However, the documentation allows only 1 to 2000 (0x0001 to 0x07D0) values to be used (see the MODBUS protocol documentation).

Construct the Read Discrete Inputs request.

requestReadExceptionStatus

requestReadExceptionStatus(): Uint8Array;
// This method is not available in managed environment
// This method is not available in native environment

Construct the Read Exception Status request.

requestReadFIFOQueue

requestReadFIFOQueue(fifoPointerAddress: number): Uint8Array;
// This method is not available in managed environment
// This method is not available in native environment
fifoPointerAddress
Queue pointer address. This parameter can take values from 0 to 65535 (0x0000 to 0xFFFF).

Construct the Read FIFO Queue request.

requestReadFileRecord

requestReadFileRecord(requests: ${ReadFileRequest}[]): Uint8Array;
// This method is not available in managed environment
// This method is not available in native environment
requests
Array of read file requests.

Construct the Read File Record request.

var message = builder.requestReadFileRecord([
  { referenceType: 1, fileNumber: 10, recordNumber: 20, registerLength: 30 }
  ]); // 1 request with refernce type 1 and 10 as file number value
  
var message = builder.requestReadFileRecord([
  { referenceType: 1, fileNumber: 10, recordNumber: 20, registerLength: 30 },
  { referenceType: 1, fileNumber: 11, recordNumber: 21, registerLength: 31 }
  ]); // 2 requests: first with 20 as the Record Number value; second with 21 as the Record Number value

requestReadHoldingRegisters

requestReadHoldingRegisters(startingAddress: number, numberOfRegisters: number): Uint8Array;
// This method is not available in managed environment
// This method is not available in native environment
startingAddress
First register address (0 to 65535). In some implementations device interprets this value as an offset - this value is added to default MODBUS base register address (see Modbus protocol documentation) 40000. Specify the 0 value for this parameter to write registers starting from 40000 address.
numberOfRegisters
Total count of registers to read. This parameter can take values from 1 to 65535 (0x0001 to 0xFFFF). However, the documentation allows only 1 to 125 (0x0001 to 0x007D) values to be used (see the MODBUS protocol documentation).

Construct the Read Holding Registers request.

requestReadInputRegisters

requestReadInputRegisters(startingAddress: number, numberOfRegisters: number): Uint8Array;
// This method is not available in managed environment
// This method is not available in native environment
startingAddress
First register address (0 to 65535). In some implementations device interprets this value as an offset - this value is added to default MODBUS base register address (see MODBUS protocol documentation) 30000. Specify the 0 value for this parameter to write registers starting from 30000 address.
numberOfRegisters
Total number of registers to read. This parameter can take values from 1 to 65535 (0x0001 to 0xFFFF). However, the documentation allows only 1 to 125 (0x0001 to 0x007D) values to be used (see the MODBUS protocol documentation).

Construct the Read Input Registers request.

requestReadWriteMultipleRegisters

requestReadWriteMultipleRegisters(readStartingAddress: number,
    numberToRead: number,
    writeStartingAddress: number,
    data: number [] | Uint16Array): Uint8Array;
// This method is not available in managed environment
// This method is not available in native environment
readStartingAddress
Read starting address (8-bit).
numberToRead
Number of values to read (8-bit).
writeStartingAddress
Write starting address (8-bit).
data
Data to write. Treated as unsigned 16-bit integers.

Construct the Read Write Multiple Registers request.

The function throws an exception if you specify incorrect values for the data parameter. The function also throws an exception if there is too many or too little values, as well as if the total length of the packet exceeds 255 bytes.

var message1 = builder.requestReadWriteMultipleRegisters(1, 2, 30, [ 32500 ]);  // only one value is written
var message2 = builder.requestReadWriteMultipleRegisters(1, 2, 30, [ 32500, 32000, 65535, 65535, 65535 ]);  // 5 values are written

requestReportSlaveID

requestReportSlaveID(): Uint8Array;
// This method is not available in managed environment
// This method is not available in native environment

Construct the Report SlaveID request.

requestUserFunction

requestUserFunction(functionID: number, data: number[] | Uint8Array): Uint8Array;
// This method is not available in managed environment
// This method is not available in native environment
functionID
8-bit function ID.
data
Integer array of function parameters. Each item is treated as 8-bit unsigned value.

Construct the user-defined message to the device.

var message = builder.requestUserFunction(15, [ 1, 2, 3, 4, 5, 6, 7 ]); // User function 15 with 7 parameters

requestWriteFileRecord

requestWriteFileRecord(requests: ${FileRecord}[]): Uint8Array;
// This method is not available in managed environment
// This method is not available in native environment
requests
An array of file records. The function throws an exception if you specify incorrect values for the parameter. The function also throws an exception if there is too many values, as well as if the total length of the packet exceeds 255 bytes.

Construct the Write File Record request.

var message = builder.requestWriteFileRecord([
  { referencyType: 1, fileNumber: 10, recordNumber: 20, records: [ 255 ] },
  { referencyType: 1, fileNumber: 10, recordNumber: 20, records: [ 255, 255 ] },
  { referencyType: 1, fileNumber: 11, recordNumber: 21, records: [ 127, 127, 127] }
  ]);

requestWriteMultipleCoils

requestWriteMultipleCoils(startingAddress: number, data: boolean[]): Uint8Array;
// This method is not available in managed environment
// This method is not available in native environment
startingAddress
Starting address (number from 0 to 65535).
data
An array of COIL values.

Construct the Write Multiple Coils request.

requestWriteMultipleRegisters

requestWriteMultipleRegisters(startingAddress: number, data: number[] | Uint16Array): Uint8Array;
// This method is not available in managed environment
// This method is not available in native environment
startingAddress
Starting address (number from 0 to 65535).
data
An array of register values. Each value must be between 0 and 65535.

Construct the Write Multiple Registers request.

requestWriteSingleCoil

requestWriteSingleCoil(outputAddress: number, outputValue: number): Uint8Array;
// This method is not available in managed environment
// This method is not available in native environment
outputAddress
16-bit coil address (0 to 65535).
outputValue
Output value is used to set the coil state to FALSE/TRUE values. Only 0 to 65535 (0x0000 to 0xFFFF) values are accepted. However, the documentation allows only 0 and 65280 (0x0000 and 0xFF00) values to be used (see the MODBUS protocol documentation) to switch the coil state to FALSE/TRUE.

Construct the Write Single Coil request .

var m1 = builder.requestWriteSingleCoil(0, 65280); // set the 1 (TRUE) value to coil 0
var m2 = builder.requestWriteSingleCoil(1, 0); // set the 0 (FALSE) value to coil 1
var m3 = builder.requestWriteSingleCoil(2, 15);  // WARNING: the value 15 is undefined by standard. 
// coil #2 will have unknown value now (FALSE or TRUE)

requestWriteSingleRegister

requestWriteSingleRegister(registerAddress: number, registerValue: number): Uint8Array;
// This method is not available in managed environment
// This method is not available in native environment
registerAddress
Register address (0 to 65535). In some implementations device interprets this value as an offset — this value is added to default MODBUS base register address (see MODBUS protocol documentation) 40000. Specify the 0 value for this parameter to write register with 40000 address.
registerValue
Value to be set. The parameter can take values from 0 to 65535 (0x0000 to 0xFFFF).

Construct the Write Single Register request.

responseDiagnostics

responseDiagnostics(subFunction: number, data: number [] | Uint8Array): Uint8Array;
// This method is not available in managed environment
// This method is not available in native environment
subFunction
The sub-function index. It can be a number from 0 (0x0000) to 65535 (0xFFFF).
data
Byte array with diagnostics response data.

Send the Diagnostics response.

The function throws an exception if you specify incorrect values for the data parameter. The function also throws an exception if the total length of the packet exceeds 255 bytes.

responseGetCommEventCounter

responseGetCommEventCounter(status: number, eventCount: number): Uint8Array;
// This method is not available in managed environment
// This method is not available in native environment
status
Status value. It can be a number from 0 (0x0000) to 65535 (0xFFFF).
eventCount
Event count value. It can be a number from 0 (0x0000) to 65535 (0xFFFF).

Construct the Get Comm Event Counter response.

responseGetCommEventLog

responseGetCommEventLog(status: number, events: number [] | Uint8Array): Uint8Array;
// This method is not available in managed environment
// This method is not available in native environment
status
Status value. It can be a number from 0 (0x0000) to 65535 (0xFFFF). messageCount: numberEvent count value. It can be a number from 0 (0x0000) to 65535 (0xFFFF).
events
Integer array of 8-bit event values.

Construct the Get Comm Event Log response.

responseMaskWriteRegister

responseMaskWriteRegister(referenceAddress: number, andMask: number, orMask: number): Uint8Array;
// This method is not available in managed environment
// This method is not available in native environment
referenceAddress
Reference address. It can be a number from 0 to 65535.
andMask
And Mask is used for bitwise AND operation on the selected register address. It can be a number from 0 to 65535.
orMask
And Mask is used for bitwise OR operation on the selected register address. It can be a number from 0 to 65535.

Construct the Mask Write Register response.

responseReadCoilStatus

responseReadCoilStatus(items: number [] | Uint8Array): Uint8Array;
// This method is not available in managed environment
// This method is not available in native environment
items
Integer array of 8-bit coil values.

Construct the Read Coil Status response.

responseReadDiscreteInputs

responseReadDiscreteInputs(items: number [] | Uint8Array): Uint8Array;
// This method is not available in managed environment
// This method is not available in native environment
items
Integer array of 8-bit coils values.

Construct the Read Discrete Inputs response.

responseReadExceptionStatus

responseReadExceptionStatus(outputData: number): Uint8Array;
// This method is not available in managed environment
// This method is not available in native environment
outputData
The output value. It can be a number from 0 (0x00) to 255 (0xFF).

Construct the Read Exception Status response.

responseReadFIFOQueue

responseReadFIFOQueue(registers: number [] | Uint16Array): Uint8Array;
// This method is not available in managed environment
// This method is not available in native environment
registers
Integer array of 16-bit register values.

Send the Read FIFO Queue response.

The function throws an exception if you specify incorrect values for the registers parameter. The function also throws an exception if the total length of the packet exceeds 255 bytes.

responseReadFileRecord

responseReadFileRecord(requests: ${ReadFileResponse}[]): Uint8Array;
// This method is not available in managed environment
// This method is not available in native environment
requests
An array of file response records. The function throws an exception if you specify incorrect values for the parameter. The function also throws an exception if there are too many values, as well as if the total length of the packet exceeds 255 bytes.

Construct the Read File Record response.

var message = builder.responseReadFileRecord([
  { referenceType: 6, data: [ 255 ] },
  { referenceType: 6, data: [ 65535, 65535 ] },
  { referenceType: 6, data: [ 120 ] }
  ]);

responseReadHoldingRegisters

responseReadHoldingRegisters(registers: number [] | Uint16Array): Uint8Array;
// This method is not available in managed environment
// This method is not available in native environment
registers
Register values array. Each item is treated as unsigned 16-bit integer.

Construct the Read Holding Registers response.

The function throws an exception if you specify incorrect values for the registers parameter. The function also throws an exception if the total length of the packet exceeds 255 bytes.

responseReadInputRegisters

responseReadInputRegisters(registers: number [] | Uint16Array): Uint8Array;
// This method is not available in managed environment
// This method is not available in native environment
registers
Array with register values. Each value is treated as unsigned 16-bit integer.

Construct the Read Input Registers response.

The function throws an exception if you specify incorrect values for the registers parameter. The function also throws an exception if the total length of the packet exceeds 255 bytes.

responseReadWriteRegisters

responseReadWriteRegisters(registers: number [] | Uint16Array): Uint8Array;
// This method is not available in managed environment
// This method is not available in native environment
registers
Array of 16-bit register values.

Construct the Read Write Registers response.

responseReportSlaveID

responseReportSlaveID(runIndicatorStatus: number,
    slaveIds: number [] | Uint8Array,
    data: number [] | Uint8Array): Uint8Array;
// This method is not available in managed environment
// This method is not available in native environment
runIndicatorStatus
RunIndicatorStatus value. It can be a value from 0 to 255.
slaveIds
An array of slave identifiers.
data
Additional data to send.

Construct the Report SlaveID response.

The function throws an exception if you specify incorrect values for the requests parameter. The function also throws an exception if there is too many or too little values, as well as if the total length of the packet exceeds 255 bytes.

// send 1 byte (255 in this example) as SlaveId field data
// and 2 bytes (255,100 in this example) as AdditionalData field data
// RunIndicatorStatus field is 0
var message = builder.responseReportSlaveID(0, [ 255 ], [ 255, 100 ]);

responseWriteFileRecord

responseWriteFileRecord(requests: ${FileRecord}[]): Uint8Array;
// This method is not available in managed environment
// This method is not available in native environment
requests
An array of file records. The function throws an exception if you specify incorrect values for the parameter. The function also throws an exception if there is too many values, as well as if the total length of the packet exceeds 255 bytes.

Construct the Write File Record response.

var message = builder.responseWriteFileRecord([
  { referenceType: 1, fileNumber: 2, recordNumber: 1, records: [ 65535 ] }, // first request (with 1 record data value)
  { referenceType: 1, fileNumber: 40000, recordNumber: 2, records: [ 65535, 65535, 65535 ] }, // second request (with 3 record data values)
  { referenceType: 1, fileNumber: 2, recordNumber: 3, records: [ 120 ] }  // third request (with 1 record data value)
  ]);

responseWriteMultipleCoils

responseWriteMultipleCoils(startingAddress: number, quantityOfOutputs: number): Uint8Array;
// This method is not available in managed environment
// This method is not available in native environment
startingAddress
Starting address value. It can be a number from 0 (0x0000) to 65535 (0xFFFF).
quantityOfOutputs
Outputs count value. It can be a number from 0 (0x0001) to 1968 (0x07B0).

Construct the Write Multiple Coils response.

responseWriteMultipleRegisters

responseWriteMultipleRegisters(startingAddress: number, quantityOfRegisters: number): Uint8Array;
// This method is not available in managed environment
// This method is not available in native environment
startingAddress
Starting address value. It can be a number from 0 (0x0000) to 65535 (0xFFFF).
quantityOfRegisters
Event count value. It can be a number from 1 (0x0001) to 123 (0x007B).

Construct the Write Multiple Registers response.

responseWriteSingleCoil

responseWriteSingleCoil(outputAddress: number, outputValue: number): Uint8Array;
// This method is not available in managed environment
// This method is not available in native environment
outputAddress
The address of a coil. It can be a number from 0 (0x0000) to 65535 (0xFFFF).
outputValue
The output value. It can be a number from 0 (0x0000) to 65280 (0xFF00). A value of 65280 (0xFF00) requests the output to be ON (TRUE). A value of 0 (0x0000) requests it to be OFF (FALSE).

Construct the Write Single Coil response.

responseWriteSingleRegister

responseWriteSingleRegister(outRegisterAddress: number, outValue: number): Uint8Array;
// This method is not available in managed environment
// This method is not available in native environment
outRegisterAddress
The register address. It can be a number from 0 (0x0000) to 65535 (0xFFFF).
outValue
The output value. It can be a number from 0 (0x0000) to 65535 (0xFFFF).

Construct the Write Single Register response.