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.

ReadFileRequest FileRecord ReadFileResponse