Add changes for 2100650

_sources/overview.rst.txt

@@ -82,8 +82,8 @@ Modbus provides access to the following 4 types of data:
 Modbus communications
 ~~~~~~~~~~~~~~~~~~~~~
 
-Modbus communication consists of a *request message* sent from the
-*Modbus client* to the *Modbus server*. The server replies with a
+Modbus communication consists of a *request message* sent from a
+*Modbus master* (client) to a *Modbus slave* (server). The server replies with a
 *response message*. Modbus request messages contain:
 
 -  An 8-bit Modbus function code that describes the type of data
@@ -236,6 +236,82 @@ Modbus read operations are limited to transferring 125 16-bit words or
 2000 bits. Modbus write operations are limited to transferring 123
 16-bit words or 1968 bits.
 
+Modbus exceptions
+~~~~~~~~~~~~~~~~~
+
+If a Modbus requests is determined to be invalid by the server, it returns
+a Modbus exception message.
+The modbus driver will print an error message if an exception is returned.
+The following table describes the possible Modbus exceptions.
+
+Modbus exception codes
+______________________
+
+.. cssclass:: table-bordered table-striped table-hover
+.. list-table::
+  :header-rows: 1
+  :widths: auto
+
+  * - Exception code
+    - Name
+    - Meaning
+  * - 0x01
+    - Illegal Function
+    - The function code received in the query is not an allowable action for the slave.
+      This may be because the function code is only applicable to newer devices,
+      and was not implemented in the unit selected.
+      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.
+  * - 0x02
+    - Illegal Data Address
+    - The data address received in the query is not an allowable address for the slave.
+      More 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.
+  * - 0x03
+    - Illegal Data Value
+    - A value contained in the query data field is not an 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.
+  * - 0x04
+    - Slave Device Failure
+    - An unrecoverable error occurred while the slave was attempting to perform the requested action.
+  * - 0x05
+    - 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.
+      NOTE: The EPICS Modbus driver does not print an error message for this response, since it is not really an error.
+  * - 0x06
+    - Slave Device Busy
+    - Specialized use in conjunction with programming commands.
+      The slave is engaged in processing a long-duration program command.
+      The master should retransmit the message later when the slave is free.
+  * - 0x07
+    - Negative Acknowledge
+    - The slave cannot perform the program function received in the query.
+      This code is returned for an unsuccessful programming request using function code 13 or 14 decimal.
+      The master should request diagnostic or error information from the slave.
+  * - 0x08
+    - Memory Parity Error
+    - Specialized use in conjunction with function codes 20 and 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 file, but detected a parity error in memory.
+      The master can retry the request, but service may be required on the slave device.
+  * - 0x0A
+    - Gateway Path Unavailable
+    - Specialized use in conjunction with gateways, indicates that the gateway was unable to allocate an
+      internal communication path from the input port to the output port for processing the request.
+      Usually means the gateway is misconfigured or overloaded.
+  * - 0x0B
+    - Gateway Target Device Failed to Respond
+    - Specialized use in conjunction with gateways, indicates that no response was obtained from the target device.
+      Usually means that the device is not present on the network.
+
 More information on Modbus
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 

acknowledgments.html

@@ -100,7 +100,7 @@ <h1>Acknowledgments<a class="headerlink" href="#acknowledgments" title="Link to
 
   <div role="contentinfo">
     <p>&#169; Copyright 2023, Mark Rivers.
-      <span class="lastupdated">Last updated on 2024-November-25.
+      <span class="lastupdated">Last updated on 2024-December-01.
       </span></p>
   </div>
 

creating_driver.html

@@ -580,7 +580,7 @@ <h2>Number formats<a class="headerlink" href="#number-formats" title="Link to th
 
   <div role="contentinfo">
     <p>&#169; Copyright 2023, Mark Rivers.
-      <span class="lastupdated">Last updated on 2024-November-25.
+      <span class="lastupdated">Last updated on 2024-December-01.
       </span></p>
   </div>
 

debugging.html

@@ -220,7 +220,7 @@ <h2>asynRegister.adl<a class="headerlink" href="#asynregister-adl" title="Link t
 
   <div role="contentinfo">
     <p>&#169; Copyright 2023, Mark Rivers.
-      <span class="lastupdated">Last updated on 2024-November-25.
+      <span class="lastupdated">Last updated on 2024-December-01.
       </span></p>
   </div>
 

device_support.html

@@ -871,7 +871,7 @@ <h2>Template files<a class="headerlink" href="#template-files" title="Link to th
 
   <div role="contentinfo">
     <p>&#169; Copyright 2023, Mark Rivers.
-      <span class="lastupdated">Last updated on 2024-November-25.
+      <span class="lastupdated">Last updated on 2024-December-01.
       </span></p>
   </div>
 

driver_architecture.html

@@ -259,7 +259,7 @@ <h2>Platform independence<a class="headerlink" href="#platform-independence" tit
 
   <div role="contentinfo">
     <p>&#169; Copyright 2023, Mark Rivers.
-      <span class="lastupdated">Last updated on 2024-November-25.
+      <span class="lastupdated">Last updated on 2024-December-01.
       </span></p>
   </div>
 

example_applications.html

@@ -290,7 +290,7 @@ <h1>Example Applications<a class="headerlink" href="#example-applications" title
 
   <div role="contentinfo">
     <p>&#169; Copyright 2023, Mark Rivers.
-      <span class="lastupdated">Last updated on 2024-November-25.
+      <span class="lastupdated">Last updated on 2024-December-01.
       </span></p>
   </div>
 

genindex.html

@@ -89,7 +89,7 @@ <h1 id="index">Index</h1>
 
   <div role="contentinfo">
     <p>&#169; Copyright 2023, Mark Rivers.
-      <span class="lastupdated">Last updated on 2024-November-25.
+      <span class="lastupdated">Last updated on 2024-December-01.
       </span></p>
   </div>
 

index.html

@@ -100,6 +100,10 @@ <h2>Table of Contents<a class="headerlink" href="#table-of-contents" title="Link
 </ul>
 </li>
 <li class="toctree-l2"><a class="reference internal" href="overview.html#modbus-data-length-limitations">Modbus data length limitations</a></li>
+<li class="toctree-l2"><a class="reference internal" href="overview.html#modbus-exceptions">Modbus exceptions</a><ul>
+<li class="toctree-l3"><a class="reference internal" href="overview.html#modbus-exception-codes">Modbus exception codes</a></li>
+</ul>
+</li>
 <li class="toctree-l2"><a class="reference internal" href="overview.html#more-information-on-modbus">More information on Modbus</a></li>
 </ul>
 </li>
@@ -166,7 +170,7 @@ <h2>Table of Contents<a class="headerlink" href="#table-of-contents" title="Link
 
   <div role="contentinfo">
     <p>&#169; Copyright 2023, Mark Rivers.
-      <span class="lastupdated">Last updated on 2024-November-25.
+      <span class="lastupdated">Last updated on 2024-December-01.
       </span></p>
   </div>
 

medm_screens.html

@@ -185,7 +185,7 @@ <h2>Koyo_4ADC.adl<a class="headerlink" href="#koyo-4adc-adl" title="Link to this
 
   <div role="contentinfo">
     <p>&#169; Copyright 2023, Mark Rivers.
-      <span class="lastupdated">Last updated on 2024-November-25.
+      <span class="lastupdated">Last updated on 2024-December-01.
       </span></p>
   </div>
 

overview.html

@@ -55,6 +55,10 @@
 </ul>
 </li>
 <li class="toctree-l2"><a class="reference internal" href="#modbus-data-length-limitations">Modbus data length limitations</a></li>
+<li class="toctree-l2"><a class="reference internal" href="#modbus-exceptions">Modbus exceptions</a><ul>
+<li class="toctree-l3"><a class="reference internal" href="#modbus-exception-codes">Modbus exception codes</a></li>
+</ul>
+</li>
 <li class="toctree-l2"><a class="reference internal" href="#more-information-on-modbus">More information on Modbus</a></li>
 </ul>
 </li>
@@ -178,8 +182,8 @@ <h2>Modbus data types<a class="headerlink" href="#modbus-data-types" title="Link
 </section>
 <section id="modbus-communications">
 <h2>Modbus communications<a class="headerlink" href="#modbus-communications" title="Link to this heading"></a></h2>
-<p>Modbus communication consists of a <em>request message</em> sent from the
-<em>Modbus client</em> to the <em>Modbus server</em>. The server replies with a
+<p>Modbus communication consists of a <em>request message</em> sent from a
+<em>Modbus master</em> (client) to a <em>Modbus slave</em> (server). The server replies with a
 <em>response message</em>. Modbus request messages contain:</p>
 <ul class="simple">
 <li><p>An 8-bit Modbus function code that describes the type of data
@@ -358,6 +362,92 @@ <h2>Modbus data length limitations<a class="headerlink" href="#modbus-data-lengt
 2000 bits. Modbus write operations are limited to transferring 123
 16-bit words or 1968 bits.</p>
 </section>
+<section id="modbus-exceptions">
+<h2>Modbus exceptions<a class="headerlink" href="#modbus-exceptions" title="Link to this heading"></a></h2>
+<p>If a Modbus requests is determined to be invalid by the server, it returns
+a Modbus exception message.
+The modbus driver will print an error message if an exception is returned.
+The following table describes the possible Modbus exceptions.</p>
+<section id="modbus-exception-codes">
+<h3>Modbus exception codes<a class="headerlink" href="#modbus-exception-codes" title="Link to this heading"></a></h3>
+<table class="table-bordered table-striped table-hover docutils align-default">
+<thead>
+<tr class="row-odd"><th class="head"><p>Exception code</p></th>
+<th class="head"><p>Name</p></th>
+<th class="head"><p>Meaning</p></th>
+</tr>
+</thead>
+<tbody>
+<tr class="row-even"><td><p>0x01</p></td>
+<td><p>Illegal Function</p></td>
+<td><p>The function code received in the query is not an allowable action for the slave.
+This may be because the function code is only applicable to newer devices,
+and was not implemented in the unit selected.
+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.</p></td>
+</tr>
+<tr class="row-odd"><td><p>0x02</p></td>
+<td><p>Illegal Data Address</p></td>
+<td><p>The data address received in the query is not an allowable address for the slave.
+More 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.</p></td>
+</tr>
+<tr class="row-even"><td><p>0x03</p></td>
+<td><p>Illegal Data Value</p></td>
+<td><p>A value contained in the query data field is not an 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.</p></td>
+</tr>
+<tr class="row-odd"><td><p>0x04</p></td>
+<td><p>Slave Device Failure</p></td>
+<td><p>An unrecoverable error occurred while the slave was attempting to perform the requested action.</p></td>
+</tr>
+<tr class="row-even"><td><p>0x05</p></td>
+<td><p>Acknowledge</p></td>
+<td><p>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.
+NOTE: The EPICS Modbus driver does not print an error message for this response, since it is not really an error.</p></td>
+</tr>
+<tr class="row-odd"><td><p>0x06</p></td>
+<td><p>Slave Device Busy</p></td>
+<td><p>Specialized use in conjunction with programming commands.
+The slave is engaged in processing a long-duration program command.
+The master should retransmit the message later when the slave is free.</p></td>
+</tr>
+<tr class="row-even"><td><p>0x07</p></td>
+<td><p>Negative Acknowledge</p></td>
+<td><p>The slave cannot perform the program function received in the query.
+This code is returned for an unsuccessful programming request using function code 13 or 14 decimal.
+The master should request diagnostic or error information from the slave.</p></td>
+</tr>
+<tr class="row-odd"><td><p>0x08</p></td>
+<td><p>Memory Parity Error</p></td>
+<td><p>Specialized use in conjunction with function codes 20 and 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 file, but detected a parity error in memory.
+The master can retry the request, but service may be required on the slave device.</p></td>
+</tr>
+<tr class="row-even"><td><p>0x0A</p></td>
+<td><p>Gateway Path Unavailable</p></td>
+<td><p>Specialized use in conjunction with gateways, indicates that the gateway was unable to allocate an
+internal communication path from the input port to the output port for processing the request.
+Usually means the gateway is misconfigured or overloaded.</p></td>
+</tr>
+<tr class="row-odd"><td><p>0x0B</p></td>
+<td><p>Gateway Target Device Failed to Respond</p></td>
+<td><p>Specialized use in conjunction with gateways, indicates that no response was obtained from the target device.
+Usually means that the device is not present on the network.</p></td>
+</tr>
+</tbody>
+</table>
+</section>
+</section>
 <section id="more-information-on-modbus">
 <h2>More information on Modbus<a class="headerlink" href="#more-information-on-modbus" title="Link to this heading"></a></h2>
 <p>For more information about the Modbus protocol, the official Modbus
@@ -388,7 +478,7 @@ <h2>More information on Modbus<a class="headerlink" href="#more-information-on-m
 
   <div role="contentinfo">
     <p>&#169; Copyright 2023, Mark Rivers.
-      <span class="lastupdated">Last updated on 2024-November-25.
+      <span class="lastupdated">Last updated on 2024-December-01.
       </span></p>
   </div>
 

search.html

@@ -97,7 +97,7 @@
 
   <div role="contentinfo">
     <p>&#169; Copyright 2023, Mark Rivers.
-      <span class="lastupdated">Last updated on 2024-November-25.
+      <span class="lastupdated">Last updated on 2024-December-01.
       </span></p>
   </div>