ModbusRTUASCiiServer class

 Top  Previous 

ModbusRTUASCiiServer

 

Connection to Modbus RTU/ASCii Server simulator

Since R2019b

 

Description

A ModbusRTUASCiiServer object represents as many as 5 Modbus RTU/ASCii  nodes for communication with the Modbus Master in the same Modbus network. After creating the object, use dot notation to  call methods.

 

Creation

 

Syntax

 

m = ModbusRTUASCiiServer(portName)

m = ModbusRTUASCiiServer(portName, Name, Value)

 

 

Description

example

m = ModbusRTUASCiiServer(portName) connects to the Modbus network by USB or Bluetooth serial port specified by portName.  It will use default Modbus parameters for connecting.

m = ModbusRTUASCiiServer(portName, Name, Value) connects to the Modbus network by USB or Bluetooth serial port specified by portName and sets additional private properties using optional name-value pair arguments.

 

Input Arguments

 

portName  -- USB or Bluetooth serial port name which is used by "Modbus slave simulator" hardware.

character vector | string scalar

 

USB or Bluetooth serial port name, specified as a character vector or string scalar. This is mandatory argument.  Use serialportlist to get a list of connected ports.

 

For example, m=ModbusRTUASCiiServer("COM1") will use "COM1" in windows. It may be "/dev/ttyUSB0" under Linux

 

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after portName, but the order of the pairs does not matter.

Please, use commas to separate each name and value, and enclose Name in quotes.

For example, m=ModbusRTUASCiiServer("COM1","ServerID",[3 4],"SupportedHoldingRegs1to4Segs",{[1 10]}, "SupportedInputRegs1to4Segs", {[22 25]}); It will set Server ID =3 and 4 (Device QTY=2). Theses 2 server nodes are the same register structure. Its holding register range is address 1 to 10, and Input register range is address 22 to 25.

You can use Name-Value pairs to set the following arguments:

 

•ServerID

Value is scalar/vector double.  vector element qty denotes how many devices we support.  Maximum Qty=5, and element value is 1 to 247.  Default=1

•WordOrder

Value is scalar string or char array. It denote the words order when register data type is "uint32/int32/single/uint64/int64/double". Valid value is "big-endian" or "little-endian". Default="big-endian"

•SupportedHoldingRegs1to4Segs

Value is cell, cell element is 2 elements' row vector. It tells system how many continuous Holding register segments to support for Device 1 to 4.

Elements QTY of cell denotes supported read-write holding register segment Qty. Maximum segment QTY=10. Row vector denotes "Start address" and "End address".  For example, {[1 10], [15 20]} denotes it supports 2 read-write holding register segments, and the 1st segment address is from 1 to 10, the 2nd segment address is from 15 to 20.  Default={[1 350]}

•SupportedInputRegs1to4Segs

Value is cell, cell element is 2 elements' row vector. It tells system how many continous read-only input regsiser segments to support for Device 1 to 4.

Elements QTY of cell denotes supported read-only input register segment Qty. Maximum segment QTY=10. Row vector denotes "Start address" and "End address".  For example, {[31 40], [45 120]} denotes it supports 2 read-only input register segments, and the 1st segment address is from 31 to 40, the 2nd segment address is from 45 to 120.  Default={[1 350]}

•HoldingReplaceInputRegs1to4

Value is logical true or false.  true means we will use holding register to replace input registers for read-only registers when device number is 1 to 4. Default=false

•SupportDigitalInOut1to4

Value is logical true or false.  true means we support Discrete/Coil registers for Device 1 to 4 .  Default=true

•SupportedCoils1to4Segs

Value is cell, cell element is 2 elements' row vector. It tells system how many continuous coil register segments to support for Device 1 to 4.

Elements QTY of cell denotes supported read-write coil register segment Qty. Maximum segment QTY=10. Row vector denotes "Start address" and "End address".  For example, {[1 10], [15 20]} denotes it supports 2 read-write coil register segments, and the 1st segment address is from 1 to 10, the 2nd segment address is from 15 to 20.  Default={[1 500]}

•SupportedDiscreteRegs1to4Segs

Value is cell, cell element is 2 elements' row vector. It tells system how many continuous read-only discrete register segments to support for Device 1 to 4.

Elements QTY of cell denotes supported read-only discrete register segment Qty. Maximum segment QTY=10. Row vector denotes "Start address" and "End address".  For example, {[31 40], [45 120]} denotes it supports 2 read-only discrete register segments, and the 1st segment address is from 31 to 40, the 2nd segment address is from 45 to 120.  Default={[1 500]}

•SupportedHoldingRegs5Segs

Value is cell, cell element is 2 elements' row vector. It tells system how many continuous Holding regsiser segments to support for Device 5.

Elements QTY of cell denotes supported read-write holding register segment Qty. Maximum segment QTY=10. Row vector denotes "Start address" and "End address".  For example, {[1 10], [15 20]} denotes it supports 2 read-write holding register segments, and the 1st segment address is from 1 to 10, the 2nd segment addess is from 15 to 20.  Default={[1 350]}

•SupportedInputRegs5Segs

Value is cell, cell element is 2 elements' row vector. It tells system how many continuous read-only input register segments to support for Device 5.

Elements QTY of cell denotes supported read-only input register segment Qty. Maximum segment QTY=10. Row vector denotes "Start address" and "End address".  For example, {[31 40], [45 120]} denotes it supports 2 read-only input register segments, and the 1st segment address is from 31 to 40, the 2nd segment address is from 45 to 120.  Default={[1 350]}

•HoldingReplaceInputRegs5

Value is logical true or false.  true means we will use holding register to replace input registers for read-only registers when device number is 5. Default=false

•SupportDigitalInOut5

Value is logical true or false.  true means we support Discrete/Coil registers for Device 5 .  Default=true

•SupportedCoils5Segs

Value is cell, cell element is 2 elements' row vector. It tells system how many continuous coil register segments to support for Device 5.

Elements QTY of cell denotes supported read-write coil register segment Qty. Maximum segment QTY=10. Row vector denotes "Start address" and "End address".  For example, {[1 10], [15 20]} denotes it supports 2 read-write coil register segments, and the 1st segment address is from 1 to 10, the 2nd segment address is from 15 to 20.  Default={[1 500]}

•SupportedDiscreteRegs5Segs

Value is cell, cell element is 2 elements' row vector. It tells system how many continuous read-only discrete register segments to support for Device 5.

Elements QTY of cell denotes supported read-only discrete register segment Qty. Maximum segment QTY=10. Row vector denotes "Start address" and "End address".  For example, {[31 40], [45 120]} denotes it supports 2 read-only discrete register segments, and the 1st segment address is from 31 to 40, the 2nd segment address is from 45 to 120.  Default={[1 500]}

•WatchdogEnable1to4

Value is logical true or false.  true means we use hardware watchdog for Device 1 to 4.  Default=false

•WatchdogUseInputReg1to4

Value is logical true or false.  true means we use read-only word register as watchdog for device 1 to 4. Default=false

•WatchdogType1to4

Value is scalar number which can be 0, 1, 2 for read-write address or 0 ,1 for read-only address. Default=0. It is Device1 to 4's watchdog type.

 

Watchdog has 3 different types for read-write holding regs Watchdog.

Type 0: Watchdog Vlaue will keep the value from outside master writing. In normal situation, Master must write different value to Watchdog holding regs periodically.

Type 1: Watchdog initial value is 0. Watchdog is free running up-counter each Watchdog period. When it arrives at Preset value, it will keep it. So if no communication between Master and slave, it will arrive at Preset value.

          And Modbus server can know it has problem for communication.  In normal situation, Master must write Watchdog holding regs to value which is much smaller than Preset value.

Type 2: Watchdog initial value is Preset Value. Watchdog is free running down-counter each Watchdog period. When it arrives at 0, it will keep 0.

So if no communication between Master and slave, it will arrive at 0 value. And Modbus server can know it has problem for communication.  In normal situation, Master must write Watchdog holding regs to value which is much bigger than 0.

 

Watchdog has 2 different types for read-only input regs Watchdog.

Type 0: Watchdog initial value is 0. Watchdog is free running up-counter each Watchdog period. Overflow will return to zero

Type 1: Watchdog initial value is 0. Watchdog is free running down-counter each Watchdog period. underflow will return to 0xFFFF

 

•WatchdogPeriod1to4

Value is scalar double which can be 1 to 65535. Default=500. It is Device 1 to 4's watchdog periods in ms.

•WatchdogPreset1to4

Value is scalar double which can be 1 to 65535. Default=600. It is Device 1 to 4's watchdog Preset Value.

•WatchdogAddr1to4

Value is scalar double. Default=2. It is Device 1 to 4's Watchdog 1-based address.

•WatchdogEnable5

Value is logical true or false.  true means we use hardware watchdog for Device 5.  Default=false

•WatchdogUseInputReg5

Value is logical true or false.  true means we use read-only word register as watchdog for device 5. Default=false

•WatchdogType5

Value is scalar number which can be 0, 1, 2 for read-write address or 0 ,1 for read-only address. Default=0. It is Device 5's watchdog type.

 

Watchdog has 3 different types for read-write holding regs Watchdog.

Type 0: Watchdog Vlaue will keep the value from outside master writing. In normal situation, Master must write different value to Watchdog holding regs periodically.

Type 1: Watchdog initial value is 0. Watchdog is free running up-counter each Watchdog period. When it arrives at Preset value, it will keep it. So if no communication between Master and slave, it will arrive at Preset value.

          And Modbus server can know it has problem for communication.  In normal situation, Master must write Watchdog holding regs to value which is much smaller than Preset value.

Type 2: Watchdog initial value is Preset Value. Watchdog is free running down-counter each Watchdog period. When it arrives at 0, it will keep 0.

So if no communication between Master and slave, it will arrive at 0 value. And Modbus server can know it has problem for communication.  In normal situation, Master must write Watchdog holding regs to value which is much bigger than 0.

 

Watchdog has 2 different types for read-only input regs Watchdog.

Type 0: Watchdog initial value is 0. Watchdog is free running up-counter each Watchdog period. Overflow will return to zero

Type 1: Watchdog initial value is 0. Watchdog is free running down-counter each Watchdog period. underflow will return to 0xFFFF

 

•WatchdogPeriod5

Value is scalar double which can be 1 to 65535. Default=500. It is Device 5's watchdog periods in ms.

•WatchdogPreset5

Value is scalar double which can be 1 to 65535. Default=600. It is Device 5's watchdog Preset Value.

•WatchdogAddr5

Value is scalar double. Default=2. It is Device 5's Watchdog 1-based address.

 

 

Examples

 

In general, you only need to set up USB or Bluetooth serial port, the default behaviour is disable watchdogs and one Server with Server ID=1.  And the holding register address is from 1 to 350, input register address is from 1 to 350, coil register address is from 1 to 500, discrete register address is from 1 to 500  The following statement is usually used in general project:

 

m=ModbusRTUASCiiServer("COM2");

 

In the following example, we support 2 Modbus RTU/ASCii server with server ID=3 and 4, Read-write word register address ranges are 1 to 10 and 50 to 60, Read-only word register address ranges is  22 to 25.  We use holding register to replace read-only input register. The coil bit register address ranges is 1 to 15. The discrete bit register address ranges is 2 to 8. We don't support watchdog.

 

m=ModbusRTUASCiiServer("COM5","ServerID",[3 4],"SupportedHoldingRegs1to4Segs",{[1 10], [50 60]}, "SupportedInputRegs1to4Segs", {[22 25]}, ...

"SupportedCoils1to4Segs", {[1,15]},"SupportedDiscreteRegs1to4Segs",{[2,8]},"HoldingReplaceInputRegs1to4",true);

 

You may ask questions about how to decide baud rate and RTU or ASCii in above examples. This is decided by running PC_Utility software to set up Bus settings.

 

 

 

Properties

 

•WordOrder — words order for multiple words' data type

scalar string or char array. It denote the words order when register data type is "uint32/int32/single/uint64/int64/double". Valid value is "big-endian" or "little-endian". Default="big-endian". This is public Property, so you can change it in the run-time by assignment

 

 

 

Object Functions (Or Methods)

 

read

read Server registers values

write

write Server read-only registers or discrete bit registers.

resetDevice

Clear all register values Device supports to zero.

enableDevice

Enable Device Modbus communication

geteCOMStatus

get DeviceNo communication state

 

Events

 

None

 

 

 

All methods details

 

read

read Server registers values

Since R2019b

 

Syntax

 

[moddata,Error] = read(obj,target,address)

[moddata,Error] = read(obj,target,address,count)

[moddata,Error] = read(obj,target,address,count,precision)

[moddata,Error] = read(obj,target,address,count,DeviceNo)

[moddata,Error] = read(obj,target,address,count,precision,DeviceNo)

 

Description

 

This function will get my Server register values from one of four target addressable areas: Coils, Inputs, Holding Registers, or Input Registers.  Usually we only need to read Coils and Holding registers because Inputs (bits) and Input Registers (words) values are set by ours. We should know their values.

 

Input Arguments

 

•obj — ModbusRTUASCiiServer object. This argument is mandatory.

 

•target — Specifies the area to read. The valid choices are 'coils', 'inputs', 'inputregs' and 'holdingregs'.  This argument is mandatory.

 

•address — The starting address to read from. This is 1-based address without 4x/3x... prefix. This argument is mandatory.

 

•count — The number of values to read. Optional, default is 1. Count is a scalar when doing reads of the same data type. Count is a vector of integers for reading multiple contiguous registers containing different data types. The number of values for count must match the number of values for precision.

 

•precision — Specifies the data format of the register being read from on the Modbus server. Valid values are 'uint16', 'int16', 'uint32', 'int32', 'uint64', 'int64', 'single', and 'double'. Optional, default is 'uint16'

 

'single' and 'double' conversions conform to the IEEE 754 floating point standard. For signed integers a two's complement conversion is performed. Note that 'precision' does not refer to the return type (always 'double'), it only specifies how to interpret the register data.

 

Precision is a string or char array when doing reads of the same data type. For reading multiple contiguous registers containing different data types, precision must be a cell array of strings or character vectors, or a string array of precisions. The number of precision values must match the number of count values.

 

Only for tagets: inputregs and holdingregs.

 

•DeviceNo — 1 to 5. It Specifies which device we read from (Because one hardware can simulate max 5 devices).  Optional, default is 1

 

 

Output Arguments

 

•moddata — Register Values to read.

Row vector for reading result in double number type. It will be [ ] if failed

 

•Error — failure for reading.

Logical value. True means fail to read.

 

Examples

 

Firstly, we set up a Modbus RTU/ASCii Server object with COM5 and 2 Servers, one server ID is 3, the other server ID is 4. They support Read-write holding registers addressing from 1 to 100. They support Read-only input registers addressing from 22 to 25. They support coil registers addressing from 1 to 15. They support discrete registers addressing from 2 to 8. Word order is big-endian.

 

m=ModbusRTUASCiiServer("COM5","ServerID",[3 4],"SupportedHoldingRegs1to4Segs",{[1 100]}, "SupportedInputRegs1to4Segs", {[22 25]}, ...

"SupportedCoils1to4Segs", {[1,15]},"SupportedDiscreteRegs1to4Segs",{[2,8]});

 

% Read 3 coil values starting at address 5 from Device1

 

address = 5;

[moddata,Error] = read(m,'coils',address,3,1);

 

% Read 2 holding registers whose data format is unsigned 16 bits integer and 4 holding registers

% whose data format is double, in one read, at address 10 and Device 2.

 

address = 10;

precision = {'uint16', 'double'};

count = [2, 4];

[moddata, Error] = read(m, 'holdingregs', address, count, precision,2);

 

write

write Server read-only registers or discrete bit registers.

Since R2019b

 

Syntax

 

Error=write(obj,target,address,values)

Error=write(obj,target,address,values,DeviceNo)

Error=write(obj,target,address,values,precision)

Error=write(obj,target,address,values,precision,DeviceNo)

 

Description

 

This function will perform a write operation to one of two simulated target addressable areas: inputs (Discrete) or input Registers (read-only word registers).

 

Input Arguments

 

•obj — ModbusRTUASCiiServer object. This argument is mandatory.

 

•target — Specifies the area to write. The valid choices are 'inputs'  (discrete bit) and 'inputregs' (read-only words). This argument is mandatory.

 

•address — The starting address to write to. This is 1-based address without 4x/3x... prefix. This argument is mandatory.

 

•values — Array of values to write. For target 'inputs' valid values are false and true. For target 'inputregs' valid values must be in the range of the specified 'precision'. This argument is mandatory.

 

•DeviceNo —1 to 5. It Specifies which device we write to (Because one hardware can simulate max 5 devices). Optional, default is 1.

 

•precision — Specifies the data format of the register being written to on the Modbus server device. Valid values are 'uint16', 'int16', 'uint32', 'int32', 'uint64','int64', 'single', and 'double'. Optional, default is ‘uint16’.

 

The values passed in to be written will be converted to register values based on the specified precision. 'single' and 'double' conversions conform to the IEEE 754 floating point standard. For signed integers a 2's complement conversion is performed.

 

 

Output Arguments

 

•Error — failure for writing.

Logical value. True means fail to write.

 

Examples

Firstly, we set up a Modbus RTU/ASCii Server object with COM5 and 2 Servers, one server ID is 3, the other server ID is 4. They support Read-write holding registers addressing from 1 to 100. They support Read-only input registers addressing from 22 to 25. They support coil registers addressing from 1 to 15. They support discrete registers addressing from 2 to 8. Word order is big-endian.

 

m=ModbusRTUASCiiServer("COM5","ServerID",[3 4],"SupportedHoldingRegs1to4Segs",{[1 100]}, "SupportedInputRegs1to4Segs", {[22 25]}, ...

"SupportedCoils1to4Segs", {[1,15]},"SupportedDiscreteRegs1to4Segs",{[2,8]});

 

% set the input word registers at address 22 device 1 to the value 2000

 

Error = write(m,'inputregs',22,2000,1);

 

 

resetDevice

Clear all register values Device supports to zero.

Since R2019b

 

Syntax

 

Error=resetDevice(obj, DeviceNo)

 

Description

 

This function will put all registers simulator DeviceNo supports to zero.

 

 

Input Arguments

 

•obj — ModbusRTUASCiiServer object. This argument is mandatory.

 

•DeviceNo — 1 to 5. It Specifies which device we want to reset (Because one hardware can simulate max 5 devices). This argument is mandatory.

 

 

Output Arguments

 

•Error — failure for reset.

Logical value. True means fail to reset.

 

 

enableDevice

Enable Device Modbus communication

Since R2019b

 

Syntax

 

Error=enableDevice(obj, enabled)

 

Description

 

This function will enable/disable some simulated devices

 

 

Input Arguments

 

•obj — ModbusRTUASCiiServer object. This argument is mandatory.

 

•enabled — logical scalar or vector. The n-th element is true means we enable Device n modbus server. The n-th element is false means we disable Device n modbus server. n cannot be over Device qty we support (ServerID vector's element QTY)

 

Output Arguments

 

•Error — failure for enable/disable.

Logical value. True means fail to enable/disable.

 

 

Note:  If we never call this enableDevice method, all devices are enabled.

 

 

geteCOMStatus

get DeviceNo communication state.

Since R2019b

 

Syntax

 

ComOK=geteCOMStatus(obj, DeviceNo)

 

Description

 

This function will get DeviceNo communication state (ok or fault) when DeviceNo supports read-write holding regs Watchdog and Watchdog type is type 1 or type 2.

 

Input Arguments

 

•obj — ModbusRTUASCiiServer object. This argument is mandatory.

 

•DeviceNo — 1 to 5. It Specifies which device communication state we want to know. This argument is mandatory.

 

 

Output Arguments

 

•ComOK — Comunication OK between DeviceNo and Master node.

Logical value. True means Comunication OK between DeviceNo and Master node.

 

 

Note:  If server does not support watchdog, or watchdog is not type1/type2 and watchdog is not in read-write holding register, then this method will create exception. You can use "Try catch" structure to know this situation.