How to use Modbus with MiR robots

Date: 10/2020
Document version: 1.3
Valid for: All MiR robots
Valid for software version: N/A
Valid for hardware version: N/A

Modbus is a software communication tool that is used to communicate between MiR robots
and other devices. You can enable or disable it as needed.

This article explains what Modbus is, how it can be utilized, and how to set up Modbus on
your MiR robots.

To enable the Modbus feature on the robot, go to System > Settings > Features and enable
Modbus. Select Save changes at the bottom of the page.

Purpose of Modbus
Modbus TCP can be used to communicate between MiR robots and other devices to achieve
the following purposes:

How to guide (en) 10/2020 - v.1.3 ©Copyright 2020: Mobile Industrial Robots A/S. 1
• To control the status of the robot, such as Pause/Continue, Cancel current mission, Clear
mission queue, and Clear error message.
• To get basic information from the robot, such as its status, power percentage, and error
messages.
• To read and write registers in the robot.
• To trigger a mission.

If a PLC is connected to the internal network of the robot, it is not possible to

access the external network through the robot.

How Modbus works on MiR robots

The Modbus slave/server is running on the robot and broadcasting on both local network IP
(192.168.12.20) and an external WiFi IP address. It is listening on the standard port 502 for
commands from outside devices. Usually, the device would be a PLC acting as the
master/client device, and the MiR robot would be the slave/server device. The master/client
device is the one in charge of polling the data.

In a typical case, the PLC (master/client) establishes a connection with the robot
(slave/server). The robot waits for an incoming connection from the PLC. Once a connection
is established, the robot responds to the queries from the PLC until the PLC closes the
connection.

Several masters/clients can connect to the robot at the same time. Each connection is
threaded.

The data is cached to avoid a high-frequency load of requests on the API while providing a
response to any request.

Function code
The server can respond to function codes described in Table 1.1.

How to guide (en) 10/2020 - v.1.3 ©Copyright 2020: Mobile Industrial Robots A/S. 2
 Table 1.1.
Modbus function codes for MiR robots .
Function Code Definition

01 Read Read coils

02 Read Read discrete inputs

03 Read Read holding registers

04 Read Read input register

05 Write Write single coil

06 Write Write single register

16 Write Write multiple registers

In the MiR robot, the content of coils and discrete inputs are matched with each other, as
are the input registers and holding registers. So you can get the same data from them, but
you can only send information to coils and holding registers.

Error codes
Modbus can respond with the error codes (called exception codes) described in Table 1.2 if
the user sends a wrong signal to Modbus.

Table 1.2.
Modbus exception codes.
Exception
code (hex Name Definition
code)

1 (01 hex) Illegal The function code received in the query is not an allowable
Function action for the slave. It could also indicate that the slave is
in the wrong state to process a request of this type, for
example, because it is unconfigured and is being asked to
return register values. If a Poll Program Complete
command was issued, this code indicates that no program
function preceded it.

How to guide (en) 10/2020 - v.1.3 ©Copyright 2020: Mobile Industrial Robots A/S. 3
 Exception
code (hex Name Definition
code)

2 (02 hex) Illegal Data The data address received in the query is not an allowable
Address address for the slave. Specifically, the combination of
reference number and transfer length is invalid. For a
controller with 100 registers, a request with offset 96 and
length 4 would succeed, a request with offset 96 and
length 5 will generate exception 02.

3 (03 hex) Illegal Data A value contained in the query data field is not an
Value allowable value for the slave. This indicates a fault in the
structure of remainder of a complex request, such as that
the implied length is incorrect. It specifically does NOT
mean that a data item submitted for storage in a register
has a value outside the expectation of the application
program since the MODBUS protocol is unaware of the
significance of any particular value of any particular
register.

4 (04 hex) Slave Device An unrecoverable error occurred while the slave was
Failure attempting to perform the requested action.

5 (05 hex) Acknowledge Specialized use in conjunction with programming

commands. The slave has accepted the request and is
processing it but a long duration of time will be required
to do so. This response is returned to prevent a timeout
error from occurring in the master. The master can next
issue a Poll Program Complete message to determine if
processing is completed.

6 (06 hex) Slave Device Specialized use in conjunction with programming

Busy commands. The slave is engaged in processing a long-
duration program command. The master should
retransmit the message later when the slave is free.

7 (07 hex) Negative The slave cannot perform the program function received
Acknowledge in the query. This code is returned for an unsuccessful
programming request using function code 13 or 14

How to guide (en) 10/2020 - v.1.3 ©Copyright 2020: Mobile Industrial Robots A/S. 4
 Exception
code (hex Name Definition
code)

decimal. The master should request diagnostic or error

information from the slave.

8 (08 hex) Memory Specialized use in conjunction with function codes 20 and
Parity Error 21 and reference type 6 to indicate that the extended file
area failed to pass a consistency check. The slave
attempted to read extended memory or record a file but
detected a parity error in memory. The master can retry
the request, but service may be required on the slave
device.

10 (0A Gateway Specialized use in conjunction with gateways. Indicates

hex) Path that the gateway was unable to allocate an internal
Unavailable communication path from the input port to the output port
for processing the request. Usually means the gateway is
misconfigured or overloaded.

11 (0B Gateway Specialized use in conjunction with gateways. Indicates

hex) Target that no response was obtained from the target device.
Device Usually means that the device is not present on the
Failed to network.
Respond

Data model
The data model is described with the following points:

• Addressing
• The Modbus address that the robot uses can be found in the tables under Modbus data
addresses reference on the next page.
• The Modbus server has 0-based addressing. Be aware that some other devices are 1-
based, for example, Anybus X-gateways. When using a 1-based device, add one to the
address on that device, for example, address 3 on the robot will be address 4 on the
Anybus X-gateway.

How to guide (en) 10/2020 - v.1.3 ©Copyright 2020: Mobile Industrial Robots A/S. 5
• Read/write scheme
• Status messages: Read only.
• Registers: Read and write.
• Mission triggers: Write available. Reading always return 0 if triggers have been set.
• Action commands: Write available. Reading always returns 0.
• Integer register
• MiR robots save the integer in 32 bits, but the Modbus communications are 16 bits
encoded. To accomodate this, In the Modbus server, two addresses are combined to
represent one integer value in the robot. MiR Modbus uses big endian encoding as
default configuration. This method is applied to all the integer registers and integer
values of the robot’s information.
• Floating register
• MiR Modbus usees IEEE 754 ISO standard to encode floating point values.

1.1 Modbus data addresses reference

The following tables describe which Modbus addresses can be used on the robot, including
their function, permission, and data type.

Action commands
Table 1.3.
Action commands you can use with MiR robots.
Data
Title Description Permission Address
type

Pause robot Address of the coil used to trigger the W Bool [00002]
Pause action on the robot

Cancel Address of the coil used to cancel the W Bool [00003]

current ongoing mission, if any
mission

Clear Address of the coil used to clear the W Bool [00004]

mission entire mission queue
queue

Clear error Address of the coil used to clear the W Bool [00005]
errors on the robot

How to guide (en) 10/2020 - v.1.3 ©Copyright 2020: Mobile Industrial Robots A/S. 6
 Data
Title Description Permission Address
type

Continue Address of the coil used to trigger the W Bool [00006]

robot Continue action on the robot

Mission triggers
Table 1.4.
Mission triggers you can use with MiR robots.

Data
Title Description Permission Address
type

Triggers Trigger the linked mission in W Bool [01001]…

system settings. [02000]

Status messages
Table 1.5.
Statuses you can read from MiR robots.
Data
Title Description Permission Address
type

Software Robot software version. Each R int16 [40001,

version address represents one digit of the 40002,
software version 40003]

Mode The current mode of the robot. R int16 [40004]

Refer to Code Definition for more
information

State The current state of the robot. Refer R int16 [40005]

to Code Definition for more
information

Error code The last error registered on the R int16 [40006,

robot. 0 if no errors were detected 40007]

Battery Remaining charge in percent [%] R int16 [40008]

level

How to guide (en) 10/2020 - v.1.3 ©Copyright 2020: Mobile Industrial Robots A/S. 7
 Data
Title Description Permission Address
type

Uptime The robots uptime R int32 [40009,

40010]

Distance The total distance run by the robot R float32 [40011,

run 40012]

Position X Position X in global coordinates R float32 [40013,

40014]

Position Y Position Y in global coordinates R float32 [40015,

40016]

Position Orientation of the robot in global R float32 [40017,

Orientation coordinates [in degrees] 40018]

Length of Number of missions pending or R int16 [40019]

mission executing
queue

Registers
Table 1.6.
Registers you can get/set on MiR robots.
Data
Title Description Permission Address
type

Integer Value of integer R/W int32 [41001,41002]…[41199,

Registers registers 41200]

Float Value of float R/W float32 [42001,42002]…[42199,

Registers registers 42200]

1.2 Setting up Modbus

By default you will be able to set up a Modbus master on your PLC to get status messages,
get/set registers, and set action commands from the robot. If you need to trigger missions
on the robot, mission triggers need to be set up as described below.

How to guide (en) 10/2020 - v.1.3 ©Copyright 2020: Mobile Industrial Robots A/S. 8
After you have turned on the Modbus feature and created a mission, go to System >
Triggers > Create trigger to create a new trigger. The coil ID can be assigned to any integer
between 1001 and 2000. After the trigger is created, the robot will trigger the mission once
you set the coil to True via Modbus.

If the mission uses variables for any parameters, you must set the variable
value when you create the trigger.

How to guide (en) 10/2020 - v.1.3 ©Copyright 2020: Mobile Industrial Robots A/S. 9
Code Definition
The following tables describe the ID values for the robot's modes and states.

Robot mode Robot state

Mode ID Description State ID Description

0 Start mode 0 None

3 Robot is mapping 1 Starting

4 Robot is finalizing 2 Shutting down

the map
3 Ready
7 Robot is
executing 4 Pause

255 Robot is 5 Executing

transitioning to a 6 Aborted
map
7 Completed

8 Docked

9 Docking

10 Emergency/Protective
stop

11 Manual control

12 Error

How to guide (en) 10/2020 - v.1.3 ©Copyright 2020: Mobile Industrial Robots A/S. 10
Document history
Version Date Description
1.0 2019-12-03 First edition.
1.1 2020-09-15 Added robot states 10-12.

Small corrections throughout the guide.

1.2 2020-09-30 Added table with Modbus exception codes.
1.3 2020-10-28 Added note regarding PLC connection.

How to guide (en) 10/2020 - v.1.3 ©Copyright 2020: Mobile Industrial Robots A/S. 11