Proprietary

OptaSense Modbus Interface Specification

Valid for OptaSense OLA Software v. 5.3.1 and above

Date: February 2021

Issue: Issue 6

OptaSense Ref.: OptaSense/ENG/452

© OptaSense Ltd 2021 MODBUS Interface Specification

 Proprietary OptaSense/ENG/452 – Issue 6

Amendment Record
Issue Change Sheet / Reason for Change Date
By Whom
2 Engineering Correction to register start address 1st June 2015

3 Engineering Typographical error correction 8th June 2015

4 Engineering Updated to OS5.3 with Detailed Method 15th May 2017

5 Engineering Adding starting register address 24th July 2017

configuration
6 Corporate Updated corporate logo and GDPR 3rd February
2021

Contact :
Email: [email protected]

The document contains information proprietary to OptaSense® and whose unauthorised disclosure
would cause damage to the interests of OptaSense®. Requests for permission for wider use or dissemination should be
made to Chris Minto.

Specification is liable to change without warning – please contact OptaSense® for latest version.

Reference: OptaSense/ENG/452

Copyright © OptaSense® Ltd 2021, Cody Technology Park, Ively Road, Farnborough GU14 0LX

Proprietary
© OptaSense Ltd 2021 1 MODBUS Interface Specification
 Proprietary OptaSense/ENG/452 – Issue 6

Contents
1 Description ..................................................................................................................................... 3
2 MODBUS Summary Method ......................................................................................................... 4
2.1.1 Connectivity ........................................................................................................................ 4
2.1.2 Register Mapping................................................................................................................ 4
2.1.3 Alert Index Mapping ............................................................................................................ 5
3 MODBUS Detailed Method ............................................................................................................ 6
3.1 Connectivity ............................................................................................................................. 6
3.2 Devices .................................................................................................................................... 6
3.3 Register Mapping ..................................................................................................................... 7
3.3.1 Alert Index Mapping – 2 Register Mode ............................................................................. 7
3.3.2 Alert Index Mapping – 4 Register Mode ............................................................................. 9
3.3.3 Hardware and Software Status Registers ........................................................................ 11

Proprietary
© OptaSense Ltd 2021 2 MODBUS Interface Specification
 Proprietary OptaSense/ENG/452 – Issue 6

1 Description
The OptaSense Modbus interface is a 16 bit TCP/IP interface designed to allow the mapping of alerts
and errors to discrete Modbus channels. This therefore allows the presence of an alert on the
OptaSense system to be notified and can be further investigated and understood via the OptaSense
system interface.
There are two methods of interfacing with Modbus available in OS5. The first, which is applicable for
OS3.6 and above, utilises a summary method of publishing alarms. This method is the simplest of the
two methods, where alarm information will be published, but cannot receive any acknowledgement
information back from the Modbus system.
The second method, available to OS5.3 and above, utilises a detailed method of publishing individual
alarms from the OptaSense system. To present this data via a Modbus interface, the OptaSense
server will construct and hold an array of registers, sufficient in quantity to maintain an Alarm register
and an Acknowledgment register for each channel. Depending on how many alert types are required,
this can be a total of 2 registers per channel (up to 16 alert types) or 4 registers per channel (up to 32
alert types). The number of registers available can be worked from a knowledge of the types of
detectors available in the OptaSense project or can be read directly from the Modbus process logs
once started. This method also allows the Modbus system to acknowledge alarms without the use of
the OptaSense software.
Both interfaces will work over multiple OPS instances. For the purposes of describing this interface, a
single fibre installation will be used. A single installation of the OptaSense product consists of one
single length of optic fibre up to a length of 50 kilometres with a single Interrogator Unit (IU).
For more information on how to install and test the Modbus interface, please consult “OptaSense OS5
Manuals – Module 9 Incorporating Ancillary Equipment” and “OptaSense OS5 Manuals – Module 7 -
Configuration Wizard User Manual”. Selection of the type of MODBUS interface being used as well
as configuration and testing of the available parameters is described in these documents.
The following guide provides information on the registries available and their contents. Distribution of
the OptaSense Modbus interface is controlled by the OptaSense system licensing process.

Proprietary
© OptaSense Ltd 2021 3 MODBUS Interface Specification
 Proprietary OptaSense/ENG/452 – Issue 6

2 MODBUS Summary Method

2.1.1 Connectivity
The OptaSense Modbus interface will listen on a preconfigured IP address and port. As a default, the
port will be the Internet Assigned Numbers Authority (IANA) well-known port of 502. The Unit ID
(Slave ID) of the MODBUS interface is nominally 1. These settings are configured within the
OptaSense setup wizard and required for the correct functioning of the system.

2.1.2 Register Mapping

The available registers (address numbered consecutively 40001 through 49999) are arranged in a
standardised manner and shown in the following tables. The starting address is configurable within
the Modbus Summary wizard page and is limited to a valid holding register address number within
this range.

In this case, using 40,001 as an example, the first 4 register entries pertain to the system status:

Address Number (Alias) Function Value

40,001 System heartbeat -1 = bad / 1 = good
40,002 Total # High unacknowledged alerts Number
40,003 Total #Med unacknowledged alerts Number
40,004 Total #Low unacknowledged alerts Number

Table 1: Register Mapping (System Status)

The remainder of the register entries which follow the header are the read out of the number of
unacknowledged alerts of each type. Not all types will be available in all systems. For more detail on
which alert types are available in your system please consult the build record.

Address Number (Alias) Function Value

40,005 Alert type x Alert type index
40,006 #High unacknowledged alerts Number
40,007 #Med unacknowledged alerts Number
40,008 #Low unacknowledged alerts Number
40,009 Alert type y Alert type index
40,010 #High unacknowledged alerts Number
40,011 #Med unacknowledged alerts Number
40,012 #Low unacknowledged alerts Number
40,013 Alert type z Alert type index
40,014 #High unacknowledged alerts Number
40,015 #Med unacknowledged alerts Number
40,016 #Low unacknowledged alerts Number

Table 2: Register Mapping (Alerts)

This is repeated as needed until all the alert types available are matched.

Proprietary
© OptaSense Ltd 2021 4 MODBUS Interface Specification
 Proprietary OptaSense/ENG/452 – Issue 6

2.1.3 Alert Index Mapping

The available threat types that can be referenced in the MODBUS register are mapping to an index in
accordance with the list below.
Not all alert types will be available in each project.

Threat type resource Modbus int mapping

Threat.Type.Activity 1
Threat.Type.Digging 2
Threat.Type.Personnel 3
Threat.Type.MechDigging 4
Threat.Type.Stealth 5
Threat.Type.Valve 6
Threat.Type.Pig 7
Threat.Type.External 8
Threat.Type.Vehicle 9
Threat.Type.NPP 10
Threat.Type.DTGS 11
Threat.Type.OFN 12
Threat.Type.STRAIN 13
Threat.Type.Leak 14
Threat.Type.Cattle 15
Threat.Type.Landslide 16
Threat.Type.Seismic 17
Threat.Type.LocalisedEvent 18
Threat.Type.Condition 19
Threat.Type.FenceActivity 20
Threat.Type.VehAndPersonnel 21
Threat.Type.Train 22
Threat.Type.Perimeter 23
Threat.Type.Pipeline 24
Threat.Type.ManualDigging 25
Threat.Type.Degraded 26
Threat.Type.FibreBreak 27

Table 3: Summary Method: Alert Mapping Register

Proprietary
© OptaSense Ltd 2021 5 MODBUS Interface Specification
 Proprietary OptaSense/ENG/452 – Issue 6

3 MODBUS Detailed Method

3.1 Connectivity
The OptaSense Modbus interface will listen on a preconfigured IP address and port. As a default, the
port will be the IANA well-known port of 502. These settings are configured within the OptaSense
setup wizard and required for the correct functioning of the system.

3.2 Devices
For the Modbus interface, the OptaSense software will utilise discrete devices which will represent
preconfigured sections of the fibre. These devices will not exist as separate electronic devices but are
akin to predefined database ‘views’ allowing the interface consumer to request a segment of the fibre
data, rather than having to interpret the full data set.

Figure 1: OptaSense Fibre to Device Example

Each of these virtual devices will be addressed through the single configured IP address and Modbus
port using the Unit ID element of the Modbus TCP Request. Each device will have its own register
set, starting at 40001, containing the device status (system status) followed by the data for that
device’s specified channel range, as detailed later in this document.
A mapping of channel numbers to device IDs must be set up when the system is calibrated and the
physical locations are known. This will be entered via the Device section within the Modbus Interface
pages of the Wizard. Please note the channel coverage for a device cannot not exceed 63 channels.
The maximum number of devices that can be addressed in two register mode is 247 – thus the
maximum range configurable is 247 x 63 channel widths. In 4 register mode is this limited to 31
channel size (fixed number of Modbus registers)

Max #Registers #Registers / Channel #Devices Max Channel Size

127 2 247 63
127 4 247 31

Table 4: Illustration of impact of register size on coverage

Proprietary
© OptaSense Ltd 2021 6 MODBUS Interface Specification
 Proprietary OptaSense/ENG/452 – Issue 6

3.3 Register Mapping

The first register in the device, 40001, addressed by the TCP protocol as register 0, will contain a
single bit identifying the system status. To present the current system status, as normally identified by
the OptaSense toolbar status icon, the first available holding register will have its first bit set to 0 for
‘OK’ and to 1 for ‘Error’. This will correspond with the green/red status of the toolbar icon.
Each device will present the system status such that a third-party integrator will receive the status of
the controller they are trying to represent on their system. This is aimed at making integration an
easier task for third parties. This will therefore allow all the third-party controllers to flag an error if the
OptaSense system should enter an error state.
Following on from the system status, the registers will contain grouped register sets, each
representing a channel. This can be 2 or 4 registers long as identified in the following summary
tables.
To maintain consistency across the interface, all the devices will comply with the following layout of
register:

Register Type Register Size No. Of Alarm Types

40001 System Status 16-bit -
4000x Alarm 16-bit 16
4000x+1 Acknowledgment 16-bit 16

Table 5: Detailed Method: 2 Register Configuration

Register Type Size No. Of Alarm Types

40001 System Status 16-bit -
4000x Alarm 16-bit
32
4000x+1 Alarm 16-bit
4000x+2 Acknowledgment 16-bit
32
4000x+3 Acknowledgment 16-bit

Table 6: Detailed Method: 4 Register Configuration

3.3.1 Alert Index Mapping – 2 Register Mode

Having laid out the format of the messages and how registers will relate to channels, the contents of
the registers themselves are identified here.

Proprietary
© OptaSense Ltd 2021 7 MODBUS Interface Specification
 Proprietary OptaSense/ENG/452 – Issue 6

Name Address Type Access

System Status 40001 16 Bit Integer Read
System Status 40001.1 Boolean Read
Threat.Type.Register 4000x 16 Bit Integer Read
Threat.Type.Activity 4000x.1 Boolean Read
Threat.Type.Digging 4000x.2 Boolean Read
Threat.Type.Personnel 4000x.3 Boolean Read
Threat.Type.MechDigging 4000x.4 Boolean Read
Threat.Type.Vehicle 4000x.5 Boolean Read
Threat.Type.NPP 4000x.6 Boolean Read
Threat.Type.DTGS 4000x.7 Boolean Read
Threat.Type.OFN 4000x.8 Boolean Read
Threat.Type.STRAIN 4000x.9 Boolean Read
Threat.Type.Leak 4000x.10 Boolean Read
Threat.Type.Perimeter 4000x.11 Boolean Read
Threat.Type.FibreBreak 4000x.12 Boolean Read
Threat.Type.Future1 4000x.13 Boolean Read
Threat.Type.Future2 4000x.14 Boolean Read
Threat.Type.Future3 4000x.15 Boolean Read
Threat.Type.Future4 4000x.16 Boolean Read
Ack.Type..Register 4000x+1 16 Bit Integer Write
Ack.Type.Activity 4000x+1.1 Boolean Write
Ack.Type.Digging 4000x+1.2 Boolean Write
Ack.Type.Personnel 4000x+1.3 Boolean Write
Ack.Type.MechDigging 4000x+1.4 Boolean Write
Ack.Type.Vehicle 4000x+1.5 Boolean Write
Ack.Type.NPP 4000x+1.6 Boolean Write
Ack.Type.DTGS 4000x+1.7 Boolean Write
Ack.Type.OFN 4000x+1.8 Boolean Write
Ack.Type.STRAIN 4000x+1.9 Boolean Write
Ack.Type.Leak 4000x+1.10 Boolean Write
Ack.Type.Perimeter 4000x+1.11 Boolean Write
Ack.Type.FibreBreak 4000x+1.12 Boolean Write
Ack.Type.Future1 4000x+1.13 Boolean Write
Ack.Type.Future2 4000x+1.14 Boolean Write
Ack.Type.Future3 4000x+1.15 Boolean Write
Ack.Type.Future4 4000x+1.16 Boolean Write
Table 7: Detailed Method: Alert Mapping Register (2 register mode)

Proprietary
© OptaSense Ltd 2021 8 MODBUS Interface Specification
 Proprietary OptaSense/ENG/452 – Issue 6

3.3.2 Alert Index Mapping – 4 Register Mode

Name Address Type Access
System.HW.SW.Status 40001 32 Bit Integer Read**
System.HW.SW.Status 40001.1 Boolean Read
Threat.Type.Register 4000x 32 Bit Integer Read
Threat.Type.Activity 4000x.1 Boolean Read
Threat.Type.Digging 4000x.2 Boolean Read
Threat.Type.Personnel 4000x.3 Boolean Read
Threat.Type.MechDigging 4000x.4 Boolean Read
Threat.Type.Vehicle 4000x.5 Boolean Read
Threat.Type.NPP 4000x.6 Boolean Read
Threat.Type.DTGS 4000x.7 Boolean Read
Threat.Type.OFN 4000x.8 Boolean Read
Threat.Type.STRAIN 4000x.9 Boolean Read
Threat.Type.Leak 4000x.10 Boolean Read
Threat.Type.Perimeter 4000x.11 Boolean Read
Threat.Type.FiberBreak 4000x.12 Boolean Read
Threat.Type.Future1 4000x.13 Boolean Read
Threat.Type.Future2 4000x.14 Boolean Read
Threat.Type.Future3 4000x.15 Boolean Read
Threat.Type.Future4 4000x.16 Boolean Read
Threat.Type.Future5 4000x+1.1 Boolean Read
Threat.Type.Future6 4000x+1.2 Boolean Read
Threat.Type.Future7 4000x+1.3 Boolean Read
Threat.Type.Future8 4000x+1.4 Boolean Read
Threat.Type.Future9 4000x+1.5 Boolean Read
Threat.Type.Future10 4000x+1.6 Boolean Read
Threat.Type.Future11 4000x+1.7 Boolean Read
Threat.Type.Future12 4000x+1.8 Boolean Read
Threat.Type.Future13 4000x+1.9 Boolean Read
Threat.Type.Future14 4000x+1.10 Boolean Read
Threat.Type.Future15 4000x+1.11 Boolean Read
Threat.Type.Future16 4000x+1.12 Boolean Read
Threat.Type.Future17 4000x+1.13 Boolean Read
Threat.Type.Future18 4000x+1.14 Boolean Read
Threat.Type.Future19 4000x+1.15 Boolean Read
Threat.Type.Future20 4000x+1.16 Boolean Read
Ack.Type.Register 4000x+2 32 Bit Integer Write

Proprietary
© OptaSense Ltd 2021 9 MODBUS Interface Specification
 Proprietary OptaSense/ENG/452 – Issue 6

Name Address Type Access

Ack.Type.Activity 4000x+2.1 Boolean Write
Ack.Type.Digging 4000x+2.2 Boolean Write
Ack.Type.Personnel 4000x+2.3 Boolean Write
Ack.Type.MechDigging 4000x+2.4 Boolean Write
Ack.Type.Vehicle 4000x+2.5 Boolean Write
Ack.Type.NPP 4000x+2.6 Boolean Write
Ack.Type.DTGS 4000x+2.7 Boolean Write
Ack.Type.OFN 4000x+2.8 Boolean Write
Ack.Type.STRAIN 4000x+2.9 Boolean Write
Ack.Type.Leak 4000x+2.10 Boolean Write
Ack.Type.Perimeter 4000x+2.11 Boolean Write
Ack.Type.FiberBreak 4000x+2.12 Boolean Write
Ack.Type.Future1 4000x+2.13 Boolean Write
Ack.Type.Future2 4000x+2.14 Boolean Write
Ack.Type.Future3 4000x+2.15 Boolean Write
Ack.Type.Future4 4000x+2.16 Boolean Write
Ack.Type.Future5 4000x+3.1 Boolean Write
Ack.Type.Future6 4000x+3.2 Boolean Write
Ack.Type.Future7 4000x+3.3 Boolean Write
Ack.Type.Future8 4000x+3.4 Boolean Write
Ack.Type.Future9 4000x+3.5 Boolean Write
Ack.Type.Future10 4000x+3.6 Boolean Write
Ack.Type.Future11 4000x+3.7 Boolean Write
Ack.Type.Future12 4000x+3.8 Boolean Write
Ack.Type.Future13 4000x+3.9 Boolean Write
Ack.Type.Future14 4000x+3.10 Boolean Write
Ack.Type.Future15 4000x+3.11 Boolean Write
Ack.Type.Future16 4000x+3.12 Boolean Write
Ack.Type.Future17 4000x+3.13 Boolean Write
Ack.Type.Future18 4000x+3.14 Boolean Write
Ack.Type.Future19 4000x+3.15 Boolean Write
Ack.Type.Future20 4000x+3.16 Boolean Write

**Reserved

Table 8: Detailed Method: Alert Mapping Register (4 register mode)

Proprietary
© OptaSense Ltd 2021 10 MODBUS Interface Specification
 Proprietary OptaSense/ENG/452 – Issue 6

3.3.3 Hardware and Software Status Registers

Hardware and software errors would be sent as:
Status Address 32 Bit Integer Status
System.HW.SW.Status 40001 N/A N/A
System.HW.SW.Status 40001.1 00000000000000000000000000000000 Good
System.HW.SW.Status 40001.1 00000000000000000000000000000001 Bad

Table 7: Modbus Error table

In the event of a system error, a trained engineer must log into the OptaSense system to
remedy and clear the errors before clearing the errors on the EBI interface. Due to the level of
detail listing the OptaSense errors it is not possible to acknowledge and dismiss errors from
the EBI interface alone.
An example of Alarms in a given virtual zone would be sent as:
Status Addresses 32 Bit Integer
Threat.Type.Register 40005 N/A
Threat.Type.Activity 40005.1 00000000000000000000000000000001
Threat.Type.Activity 40005.1 00000000000000000000000000000011
Threat.Type.Digging 40005.2

Threat.Type.Leak 40005.10 00000000000001000000001000000000

Threat.Type.Future7 40006.3

Table 8: Modbus Alert table

Proprietary
© OptaSense Ltd 2021 11 MODBUS Interface Specification