TODO: Provide a short overview of the document and the protocol binding features.
++ In the context of the Web of Things (WoT), a Binding Template is a blueprint that gives + guidance on how to implement a specific IoT protocol, data format or IoT platform. This document gives implementation guidelines regarding + the Modbus protocol. Modbus protocol is a well-known cost-effective IoT protocol for communication between + industrial control and automation devices. +
++ The following defines a set of standard terms and rules with relevant examples that can be used inside + a Thing Description document to describe a WoT operation using the Modbus protocol + over the network. +
the following is a draft introduction
- The ModBus is a data communication protocol originally developed by Modicon which is now a part of Schneider Electric. + The Modbus is a data communication protocol originally developed by Modicon which is now a part of Schneider Electric. The protocol was specifically designed for the remote management of the hardware devices in the industrial environment. For this reason, it has low level of abstraction and it has built in bit handling capabilities oriented to the direct control of the relays and generic contact statuses. The physical layer it is mainly an RS485 differential bus which has less susceptibility to the EMC interference. This Limit the usability of the protocol in short distance networks, typically within a kilometer. Due to its age the protocol does not implement any safety system, so usually when wide internet access is needed it is - encapsulated in a TCP/IP protocol and with Ethernet as a physical layer. Thanks to this encapsulation strategy, the ModBus protocol + encapsulated in a TCP/IP protocol and with Ethernet as a physical layer. Thanks to this encapsulation strategy, the Modbus protocol can reach remote nodes deployed in distant facilities over the internet. Moreover, in the years due to its simplicity and cost-effectiveness - the ModBus protocol becomes a standard all over the world. This fame together with the advancement of the microcontroller/microprocessor led to + the Modbus protocol becomes a standard all over the world. This fame together with the advancement of the microcontroller/microprocessor led to a shift on how applications pack the information. Today it is usual to store and read any type of data in the Holdings Registers like bit,bytes,words, float etc.
- This document describes how the Web of Things specification can be use to present devices that use the ModBus protocol in a Thing Description. In - particular, the document explain how to create valid URLs and Forms for the different operations that the ModBus protocol can perform. Developers are + This document describes how the Web of Things specification can be use to present devices that use the Modbus protocol in a Thing Description. In + particular, the document explain how to create valid URLs and Forms for the different operations that the Modbus protocol can perform. Developers are encouraged to use this document as an implementation guidelines and as a reference for the creation of their own binding implementations. The following sections will cover the URL format, the Vocabulary and a list of Form examples.
@@ -57,9 +66,9 @@modbus+tpc://, modbus+ascii:// and modbus+rtu://.
+ Historically different URL scheme has been used inside the Modbus community: modbus+tpc://, modbus+ascii:// and modbus+rtu://.
Considering that in Web of Things context all protocol bindings are required to at least support the Internet Protocol, for the Modbus protocol modbus+tcp://
- was selected as the only valid URL scheme. The following shows the typical structure of an URL of the ModBus protocol:
+ was selected as the only valid URL scheme. The following shows the typical structure of an URL of the Modbus protocol:
modbus+tcp://{address}:{port}/{?unitID}
@@ -67,15 +76,15 @@ Where:
{address} is the IP address of the ModBus device{port} is the port of the ModBus device{unitID} is the unit ID of the ModBus device. See vocabulary{address} is the IP address of the Modbus device{port} is the port of the Modbus device{unitID} is the unit ID of the Modbus device. See vocabularymodbus:quantitymodbus:addressmodbus:addressmodbus:unitIDmodbus:unitIDmodbus:quantitythe following is just a draft description of the Entity class -
A more user-friendly property to specify [[[#function]]]. The client will then determine the right function code to be applied in the modbus request. Futhermore, it can be used in multi-operation forms whereasmodbus:function cannot (See the
[[[#example-read-coil-entity]]])
@@ -212,8 +219,6 @@ the following is just a draft description of the Function Code class -
Function Code class represent the value of the function field in a Modbus frame. The following table list the supported codes and their description:| Operation | +Default | +Comments | +
|---|---|---|
modbus:quantity |
+
+ 1
+ |
+ + |
modbus:zeroBaseAddressing |
+
+ false
+ |
+ + |
modbus:timeout |
+
+ infinite
+ |
+ + |
TODO: This section should describe other mappings that can be used by TD designers. It is meant to be informative but it provides guidelines for implementers.
++ Additional to the default mappings, users may decide to use other [[[#function]]]s for a specific operation. The following table + lists examples of possible mappings for some operation types. +
+| Operation | +Possible Binding | +
|---|---|
writeproperty |
+
+ "modbus:function":"writeMultipleCoils"
+ |
+
writeproperty |
+
+ "modbus:function":"writeSingleHoldingRegister"
+ |
+
readproperty |
+
+ "modbus:function":"readDeviceIdentification"
+ |
+
readproperty |
+
+ "modbus:function":"readDiscreteInput"
+ |
+
observeproperty |
+
+ "modbus:function":"readCoil";
+ "modbus:pollingTime": 1000
+ |
+
{
@@ -412,7 +498,7 @@ Examples
Reducing effectively the verbosity of a TD.
- Thanks to the expressiveness of the modbus ontology users can describe also the total
+ Thanks to the expressiveness of the Modbus ontology users can describe also the total
number of registries read or wrote in a WoT operation. [[[#example-read-holding]]] shows how to read or write
8 HoldingRegisters.
@@ -427,8 +513,8 @@- When possible WoT consumers will use modbus features to read the desired amount of data with a single - protocol request. However, it may be possible to still specify a total length for modbus operations + When possible WoT consumers will use Modbus features to read the desired amount of data with a single + protocol request. However, it may be possible to still specify a total length for Modbus operations that do not support reading or writing on a range of registers (see [[[#example-read-coil-range]]]). In these circumstances consumers will perform different requests to satisfy the configuration requirements.Examples
"modbus:quantity": 8 }
@@ -443,7 +529,7 @@- Another notable configuration of a form using the modbus vocabulary is the polling mechanism. Thanks + Another notable configuration of a form using the Modbus vocabulary is the polling mechanism. Thanks to the keywordExamples
"modbus:quantity": 8 }
pollingTime the user can indicate the intervals for observing a particular
set of registers. Supposing that the device knows that the value of coil register 1 does change every
1000 ms, in [[[#example-polling]]], it suggest that the polling time should not be faster than 10 ms. WoT
@@ -460,7 +546,7 @@
{
"@context": [
@@ -491,7 +577,7 @@ Examples
"href": "modbus+tcp://192.168.178.32:502",
"modbus:function": "readDiscreteInput",
"modbus:quantity": 1,
- "modbus:address": "10003",
+ "modbus:address": 10003,
"modbus:unitID": 1,
"contentType": "application/octet-stream"
}
@@ -507,7 +593,7 @@ Examples
"href": "modbus+tcp://192.168.178.32:502",
"modbus:function": "readDiscreteInput",
"modbus:quantity": 1,
- "modbus:address": "10002",
+ "modbus:address": 10002,
"modbus:unitID": 1,
"contentType": "application/octet-stream"
}
@@ -527,7 +613,7 @@ Examples
"href": "modbus+tcp://192.168.178.32:502",
"modbus:entity": "Coil",
"modbus:quantity": 1,
- "modbus:address": "00006",
+ "modbus:address": 6,
"modbus:unitID": 1,
"modbus:pollingTime": 100,
"contentType": "application/octet-stream"
@@ -548,7 +634,7 @@ Examples
"href": "modbus+tcp://192.168.178.32:502",
"modbus:entity": "Coil",
"modbus:quantity": 1,
- "modbus:address": "00003",
+ "modbus:address": 3,
"modbus:unitID": 1,
"modbus:pollingRate": 100,
"contentType": "application/octet-stream"
diff --git a/bindings/protocols/modbus/index.template.html b/bindings/protocols/modbus/index.template.html
index 644f9a4c..63fb3507 100644
--- a/bindings/protocols/modbus/index.template.html
+++ b/bindings/protocols/modbus/index.template.html
@@ -20,32 +20,41 @@
github: "https://github.com/w3c/wot-binding-templates/tree/main/bindings/protocols/modbus",
};
- MODBUS binding template
+ Modbus binding template
- TODO: Provide a short overview of the document and the protocol binding features.
+
+ In the context of the Web of Things (WoT), a Binding Template is a blueprint that gives
+ guidance on how to implement a specific IoT protocol, data format or IoT platform. This document gives implementation guidelines regarding
+ the Modbus protocol. Modbus protocol is a well-known cost-effective IoT protocol for communication between
+ industrial control and automation devices.
+
+
+ The following defines a set of standard terms and rules with relevant examples that can be used inside
+ a Thing Description document to describe a WoT operation using the Modbus protocol
+ over the network.
+
Introduction
- the following is a draft introduction
- The ModBus is a data communication protocol originally developed by Modicon which is now a part of Schneider Electric.
+ The Modbus is a data communication protocol originally developed by Modicon which is now a part of Schneider Electric.
The protocol was specifically designed for the remote management of the hardware devices in the industrial environment.
For this reason, it has low level of abstraction and it has built in bit handling capabilities oriented to the direct
control of the relays and generic contact statuses.
The physical layer it is mainly an RS485 differential bus which has less susceptibility to the EMC interference. This Limit
the usability of the protocol in short distance networks, typically within a kilometer.
Due to its age the protocol does not implement any safety system, so usually when wide internet access is needed it is
- encapsulated in a TCP/IP protocol and with Ethernet as a physical layer. Thanks to this encapsulation strategy, the ModBus protocol
+ encapsulated in a TCP/IP protocol and with Ethernet as a physical layer. Thanks to this encapsulation strategy, the Modbus protocol
can reach remote nodes deployed in distant facilities over the internet. Moreover, in the years due to its simplicity and cost-effectiveness
- the ModBus protocol becomes a standard all over the world. This fame together with the advancement of the microcontroller/microprocessor led to
+ the Modbus protocol becomes a standard all over the world. This fame together with the advancement of the microcontroller/microprocessor led to
a shift on how applications pack the information. Today it is usual to store and read any type of data in the Holdings Registers like bit,bytes,words, float etc.
- This document describes how the Web of Things specification can be use to present devices that use the ModBus protocol in a Thing Description. In
- particular, the document explain how to create valid URLs and Forms for the different operations that the ModBus protocol can perform. Developers are
+ This document describes how the Web of Things specification can be use to present devices that use the Modbus protocol in a Thing Description. In
+ particular, the document explain how to create valid URLs and Forms for the different operations that the Modbus protocol can perform. Developers are
encouraged to use this document as an implementation guidelines and as a reference for the creation of their own binding implementations. The following sections
will cover the URL format, the Vocabulary and a list of Form examples.
@@ -57,9 +66,9 @@ Introduction
URL format
- Historically different URL scheme has been used inside the ModBus community: modbus+tpc://, modbus+ascii:// and modbus+rtu://.
+ Historically different URL scheme has been used inside the Modbus community: modbus+tpc://, modbus+ascii:// and modbus+rtu://.
Considering that in Web of Things context all protocol bindings are required to at least support the Internet Protocol, for the Modbus protocol modbus+tcp://
- was selected as the only valid URL scheme. The following shows the typical structure of an URL of the ModBus protocol:
+ was selected as the only valid URL scheme. The following shows the typical structure of an URL of the Modbus protocol:
modbus+tcp://{address}:{port}/{?unitID}
@@ -67,15 +76,15 @@ URL format
Where:
- {address} is the IP address of the ModBus device{port} is the port of the ModBus device{unitID} is the unit ID of the ModBus device. See vocabulary{address} is the IP address of the Modbus device{port} is the port of the Modbus device{unitID} is the unit ID of the Modbus device. See vocabulary
Modbus Vocabulary
- This section describes the vocabulary used in the ModBus protocol. A protocol binding implementation should use the vocabulary defined in this section to
+ This section describes the vocabulary used in the Modbus protocol. A protocol binding implementation should use the vocabulary defined in this section to
describe the different configuration that can be used to exchanged data between Web of Things.
Form terms
@@ -96,8 +105,6 @@ Form terms
Entity
- the following is just a draft description of the Entity class
-
A more user-friendly property to specify [[[#function]]]. The client will then determine the right function code to be applied in
the modbus request. Futhermore, it can be used in multi-operation forms whereas modbus:function cannot (See the
[[[#example-read-coil-entity]]])
@@ -118,8 +125,6 @@ Entity
Function
- the following is just a draft description of the Function Code class
-
Function Code class represent the value of the function field in a Modbus frame. The
following table list the supported codes and their description:
@@ -144,6 +149,10 @@ Mappings
model.
Default mappings
+
+ The following table lists the default mappings between the protocol specific concepts and the WoT concepts. Please note that operations that are not
+ listed in the table are not supported by this binding template. For example, since the Modbus protocol is a request-response based protocol, the
+ subscribeevent operation is not supported.
@@ -156,17 +165,94 @@ Default mappings
%s
+ The next table defines default values for other terms, regardless of their use in combination with one of the operations listed in the table above.
+
+
+
+ Operation
+ Default
+ Comments
+
+
+
+
+ modbus:quantity
+ 1
+
+
+
+ modbus:zeroBaseAddressing
+ false
+
+
+
+ modbus:timeout
+ infinite
+
+
+
+
Possible mappings
- TODO: This section should describe other mappings that can be used by TD designers. It is meant to be informative but it provides guidelines for implementers.
+
+ Additional to the default mappings, users may decide to use other [[[#function]]]s for a specific operation. The following table
+ lists examples of possible mappings for some operation types.
+
+
+
+
+ Operation
+ Possible Binding
+
+
+
+
+ writeproperty
+ "modbus:function":"writeMultipleCoils"
+
+
+
+ writeproperty
+ "modbus:function":"writeSingleHoldingRegister"
+
+
+
+ readproperty
+ "modbus:function":"readDeviceIdentification"
+
+
+
+ readproperty
+ "modbus:function":"readDiscreteInput"
+
+
+
+ observeproperty
+ "modbus:function":"readCoil";
+ "modbus:pollingTime": 1000
+
+
+
+
Examples
This section will present a set of examples about how the terms defined in this document can be used
to describe and configure a Form. The [[[#example-read-coil]]] shows the minimal set of terms
- to configure a single coil reading using modbus. Notice that the unitID is contained in the href as the
+ to configure a single coil reading using Modbus. Notice that the unitID is contained in the href as the
first element of the path.
{
@@ -212,7 +298,7 @@ Examples
Reducing effectively the verbosity of a TD.
- Thanks to the expressiveness of the modbus ontology users can describe also the total
+ Thanks to the expressiveness of the Modbus ontology users can describe also the total
number of registries read or wrote in a WoT operation. [[[#example-read-holding]]] shows how to read or write
8 HoldingRegisters.
@@ -227,8 +313,8 @@ Examples
"modbus:quantity": 8
}
- When possible WoT consumers will use modbus features to read the desired amount of data with a single
- protocol request. However, it may be possible to still specify a total length for modbus operations
+ When possible WoT consumers will use Modbus features to read the desired amount of data with a single
+ protocol request. However, it may be possible to still specify a total length for Modbus operations
that do not support reading or writing on a range of registers (see [[[#example-read-coil-range]]]).
In these circumstances consumers will perform different requests to satisfy the configuration requirements.
@@ -243,7 +329,7 @@ Examples
"modbus:quantity": 8
}
- Another notable configuration of a form using the modbus vocabulary is the polling mechanism. Thanks
+ Another notable configuration of a form using the Modbus vocabulary is the polling mechanism. Thanks
to the keyword pollingTime the user can indicate the intervals for observing a particular
set of registers. Supposing that the device knows that the value of coil register 1 does change every
1000 ms, in [[[#example-polling]]], it suggest that the polling time should not be faster than 10 ms. WoT
@@ -260,7 +346,7 @@ Examples
"modbus:address": 1
}
- Finally, [[[#full-td]]] shows a complete device described using modbus ontology.
+ Finally, [[[#full-td]]] shows a complete device described using Modbus ontology.
{
"@context": [
@@ -291,7 +377,7 @@ Examples
"href": "modbus+tcp://192.168.178.32:502",
"modbus:function": "readDiscreteInput",
"modbus:quantity": 1,
- "modbus:address": "10003",
+ "modbus:address": 10003,
"modbus:unitID": 1,
"contentType": "application/octet-stream"
}
@@ -307,7 +393,7 @@ Examples
"href": "modbus+tcp://192.168.178.32:502",
"modbus:function": "readDiscreteInput",
"modbus:quantity": 1,
- "modbus:address": "10002",
+ "modbus:address": 10002,
"modbus:unitID": 1,
"contentType": "application/octet-stream"
}
@@ -327,7 +413,7 @@ Examples
"href": "modbus+tcp://192.168.178.32:502",
"modbus:entity": "Coil",
"modbus:quantity": 1,
- "modbus:address": "00006",
+ "modbus:address": 6,
"modbus:unitID": 1,
"modbus:pollingTime": 100,
"contentType": "application/octet-stream"
@@ -348,7 +434,7 @@ Examples
"href": "modbus+tcp://192.168.178.32:502",
"modbus:entity": "Coil",
"modbus:quantity": 1,
- "modbus:address": "00003",
+ "modbus:address": 3,
"modbus:unitID": 1,
"modbus:pollingRate": 100,
"contentType": "application/octet-stream"
diff --git a/bindings/protocols/modbus/mapping.ttl b/bindings/protocols/modbus/mapping.ttl
index f2beab9e..668d887e 100644
--- a/bindings/protocols/modbus/mapping.ttl
+++ b/bindings/protocols/modbus/mapping.ttl
@@ -43,16 +43,17 @@
sh:property [
sh:path modbus:hasAddress ;
sh:maxCount 1 ;
+ sh:minCount 1 ;
sh:datatype xsd:integer ;
] ;
sh:property [
sh:path modbus:hasUnitID ;
+ sh:minCount 1 ;
sh:maxCount 1 ;
sh:datatype xsd:integer ;
] ;
sh:property [
sh:path modbus:hasQuantity ;
- sh:minCount 1 ;
sh:maxCount 1 ;
sh:datatype xsd:integer ;
] ;
diff --git a/bindings/protocols/modbus/modbus.schema.json b/bindings/protocols/modbus/modbus.schema.json
index b4e81257..f31c0691 100644
--- a/bindings/protocols/modbus/modbus.schema.json
+++ b/bindings/protocols/modbus/modbus.schema.json
@@ -49,11 +49,10 @@
"modbus:address" : { "type" : "integer", "minimum": 0},
"modbus:quantity" : { "type": "integer", "minimum": 1},
"modbus:zeroBasedAddressing" : { "type" : "boolean"},
- "modbus:timeout" : { "type": "number", "minimum": 0}
- },
- "required": [
- "modbus:offset"
- ]
+ "modbus:timeout" : { "type": "number", "minimum": 0},
+ "modbus:unitID": { "type": "integer", "minimum": 0},
+ "required": ["modbus:address", "modbus:unitID"]
+ }
},
"affordance": {
"type": "object",
@@ -94,9 +93,6 @@
},
"events": {
"$ref": "#/definitions/affordance"
- },
- "lama": {
- "$ref": "#/definitions/affordance"
}
}
}
\ No newline at end of file
diff --git a/ontology/modbus.html b/ontology/modbus.html
index 9dbb9562..212d2e05 100644
--- a/ontology/modbus.html
+++ b/ontology/modbus.html
@@ -49,10 +49,10 @@ Introduction
Request
IRI: https://www.w3.org/2019/wot/modbus#Request
A Request message is sent by a client device to a server device. The comunication client/server stats only with a request sent by the client.Sub-class of A Modbus Message
Response
IRI: https://www.w3.org/2019/wot/modbus#Response
A Response message is sent by a server device to client device in return to a client's query.Sub-class of A Modbus MessageSuper-class of Exception response
Normal response
Exception code
IRI: https://www.w3.org/2019/wot/modbus#ResponseCode
For an Exception Response, the server returns an exception code as data response field. Exception code defines the server condition that caused the exception as well as the reason of the error.Sub-class of Data FieldEnumeration members ILLEGAL FUNCTION
ILLEGAL DATA ADDRESS
ILLEGAL DATA VALUE
SLAVEDEVICE FAILURE
ACKNOWLEDGE
SLAVEDEVICE BUISY
Object Properties
hasEntity
IRI: https://www.w3.org/2019/wot/modbus#hasEntity
A registry type to let the runtime automatically detect the right function codeDomain RequestRange Entity
hasFunction
IRI: https://www.w3.org/2019/wot/modbus#hasFunction
Function Code sent by the master in every request. Specifying the desired interaction.Domain Normal response
RequestRange Function
Datatype Properties
hasAddress
IRI: https://www.w3.org/2019/wot/modbus#hasAddress
Specifies the starting address of the modbus operationsDomain RequestRange integer
hasFunction
IRI: https://www.w3.org/2019/wot/modbus#hasFunction
Function Code sent by the master in every request. Specifying the desired interaction.Domain Normal response
RequestRange Function
Datatype Properties
hasAddress
IRI: https://www.w3.org/2019/wot/modbus#hasAddress
Specifies the starting address of the Modbus operationsDomain RequestRange integer
hasCodeNumber
IRI: https://www.w3.org/2019/wot/modbus#hasCodeNumber
Specifies the Modbus function/exception code numberDomain Exception function
Function
Exception codeRange integer
hasPollingTime
IRI: https://www.w3.org/2019/wot/modbus#hasPollingTime
Modbus TCP maximum polling rate. The Modbus specification does not define a maximum or minimum allowed polling rate, however specific implementations might introduce such limits. Defined as integer of milliseconds.Domain RequestRange integer
hasQuantity
IRI: https://www.w3.org/2019/wot/modbus#hasQuantity
Specifies the amount of either registers or coils to be read/writtenDomain RequestRange integer
hasQuantity
IRI: https://www.w3.org/2019/wot/modbus#hasQuantity
Specifies the amount of either registers or coils to be read or written toDomain RequestRange integer
hasTimeout
IRI: https://www.w3.org/2019/wot/modbus#hasTimeout
Modbus response maximum waiting time. Defines how much time the runtime should wait until it receives a reply from the device.Domain RequestRange integer
hasUnitID
IRI: https://www.w3.org/2019/wot/modbus#hasUnitID
The Unit ID is usually not needed for ModbusTCP, since the IP-address works as unique identifier, but for compability reasons still often includedDomain RequestRange integer
hasZeroBasedAddressingFlag
IRI: https://www.w3.org/2019/wot/modbus#hasZeroBasedAddressingFlag
Modbus implementations can differ in the way addressing works, as the first coil/register can be either referred to as True or False.Domain EntityRange boolean
Named Individuals
Coil
IRI: https://www.w3.org/2019/wot/modbus#Coil
Represent a modbus coil register. These entities can be read or writtenInstance of Entity