feat: Implementation of Function Code FC23 (0x17) - Read/Write Multiple Registers

rodbus/RWMR_README.md

@@ -0,0 +1,77 @@
+# 23 (0x17) Read/Write Multiple registers
+
+This document provides an overview of the Function Code 23 (0x17) (Read & Write Multiple Registers) request as specified in the MODBUS Application Protocol.
+
+
+## Description
+This function code performs a combination of one read operation and one write operation in a single MODBUS transaction. The write operation is performed before the read.
+
+The request specifies the starting address and number of holding registers to be read as well as the starting address, number of holding registers, and the data to be written. The byte count specifies the number of bytes to follow in the write data field.
+
+The normal response contains the data from the group of registers that were read. The byte count field specifies the quantity of bytes to follow in the read data field.
+
+
+## Request Structure
+| Parameter              | Size         | Range / Value            |
+|------------------------|--------------|--------------------------|
+| Function code          | 1 Byte       | 0x17                     |
+| Read Starting Address  | 2 Bytes      | 0x0000 to 0xFFFF         |
+| Quantity to Read       | 2 Bytes      | 0x0001 to 0x007D         |
+| Write Starting Address | 2 Bytes      | 0x0000 to 0xFFFF         |
+| Quantity to Write      | 2 Bytes      | 0x0001 to 0x0079         |
+| Write Byte Count       | 1 Byte       | 2 x N*                   |
+| Write Registers Value  | N* x 2 Bytes |                          |
+( N* = Quantity to Write )
+
+## Response Structure
+| Parameter            | Size         | Value / Description    |
+|----------------------|--------------|------------------------|
+| Function code        | 1 Byte       | 0x17                   |
+| Byte Count           | 1 Byte       | 2 x N*                 |
+| Read Registers value | N* x 2 Bytes |                        |
+( N* = Quantity to Read )
+
+## Error Handling
+| Parameter      | Size    | Description                       |
+|----------------|---------|-----------------------------------|
+| Error code     | 1 Byte  | Function code + 0x80 = 0x97 (151) |
+| Exception code | 1 Byte  | 01 or 02 or 03 or 04              |
+
+### Error Codes:
+- **01**: Illegal Function
+- **02**: Illegal Data Address
+- **03**: Illegal Data Value
+- **04**: Server Device Failure
+
+
+## Example
+Here is an example of a request to read six registers starting at register 4, and to write three
+registers starting at register 15:
+
+| Request Field                  | Hex | Response Field             | Hex |
+|--------------------------------|-----|----------------------------|-----|
+| Function                       | 17  | Function                   | 17  |
+| Read Starting Address Hi       | 00  | Byte Count                 | 0C  |
+| Read Starting Address Lo       | 03  | Read Registers value Hi    | 00  |
+| Quantity to Read Hi            | 00  | Read Registers value Lo    | FE  |
+| Quantity to Read Lo            | 06  | Read Registers value Hi    | 0A  |
+| Write Starting Address Hi      | 00  | Read Registers value Lo    | CD  |
+| Write Starting Address Lo      | 0E  | Read Registers value Hi    | 00  |
+| Quantity to Write Hi           | 00  | Read Registers value Lo    | 01  |
+| Quantity to Write Lo           | 03  | Read Registers value Hi    | 00  |
+| Write Byte Count               | 06  | Read Registers value Lo    | 03  |
+| Write Registers Value Hi (1st) | 00  | Read Registers value Hi    | 00  |
+| Write Registers Value Lo (1st) | FF  | Read Registers value Lo    | 0D  |
+| Write Registers Value Hi (2nd) | 00  | Read Registers value Hi    | 00  |
+| Write Registers Value Lo (2nd) | FF  | Read Registers value Lo    | FF  |
+| Write Registers Value Hi (3rd) | 00  |                            |     |
+| Write Registers Value Lo (3rd) | FF  |                            |     |
+
+
+## Troubleshooting Tips
+- Ensure the server and client are using the same communication method and are connected to each other
+- Check for any returned error code in the response and refer to the error handling section for resolution
+
+
+## Additional Resources
+- For more information on the MODBUS protocol and function codes, refer to the [MODBUS Application Protocol Specification V1.1b3](https://modbus.org/docs/Modbus_Application_Protocol_V1_1b3.pdf), Page 38 (Read/Write Multiple registers).

rodbus/WCFC_README.md

@@ -0,0 +1,64 @@
+# 69 (0x45) Write Custom Function Code
+
+This document provides a detailed overview of the custom function code (0x45) used in the MODBUS Application Protocol. This function code is user-defined and falls within the range of 65 to 72, as specified in the MODBUS Application Protocol Specification V1.1b3 (Page 10, Section 5: Function Code Categories).
+
+
+## Introduction
+The 0x45 function code enables the implementation of user-defined logic on a remote server device. It facilitates the transmission, reception, and processing of a custom function code with a fixed-size data buffer. This buffer currently supports 4 arguments, each 2 bytes (u16) in size, allowing for the execution of custom logic remotely.
+
+**Note:** To increase flexibility, support for a variable-length data buffer will be included in a future update.
+
+
+## Request Structure
+| Parameter          | Size     | Range / Value         |
+|--------------------|----------|-----------------------|
+| Function code      | 1 Byte   | 0x45                  |
+| Length             | 2 Bytes  | 0x0004                |
+| Data               | 8 Bytes  | 0x0000 to 0xFFFF      |
+
+
+## Response Structure
+| Parameter     | Size    | Value/Description    |
+|---------------|---------|----------------------|
+| Function code | 1 Byte  | 0x45                 |
+| Length        | 2 Bytes | 0x0004               |
+| Data          | 8 Bytes | 0x0000 to 0xFFFF     |
+
+
+## Error Handling
+| Parameter      | Size    | Description                       |
+|----------------|---------|-----------------------------------|
+| Function code  | 1 Byte  | Function code + 0x80 = 0xC5 (197) |
+| Exception code | 1 Byte  | 01 or 02 or 03 or 04              |
+
+### Error Codes:
+- **01**: Illegal Function
+- **02**: Illegal Data Address
+- **03**: Illegal Data Value
+- **04**: Server Device Failure
+
+
+## Usage Example
+### Request to send the custom buffer [0xC0, 0xDE, 0xCA, 0xFE]:
+
+| Request Field             | Hex | Response Field         | Hex |
+|---------------------------|-----|------------------------|-----|
+| Function                  | 45  | Function               | 45  |
+| Length                    | 04  | Byte Count             | 04  |
+| Arg1                      | C0  | Arg1                   | C0  |
+| Arg2                      | DE  | Arg2                   | DE  |
+| Arg3                      | CA  | Arg3                   | CA  |
+| Arg4                      | FE  | Arg4                   | FE  |
+
+
+## Modify and Test Server-Side Buffer Handling
+The server currently forwards the Custom Function Code buffer to the client again without alteration. To test modifying or processing the buffer on the remote server device, edit the `write_custom_function_code()` function in `src/examples/client.rs` and `src/examples/server.rs` as needed.
+
+
+## Troubleshooting Tips
+- Ensure the server and client are using the same communication and are connected to each other.
+- Check for any error codes in the response and refer to the error handling section for resolution.
+
+
+## Additional Resources
+- For more information on the MODBUS protocol and function codes, refer to the [MODBUS Application Protocol Specification V1.1b3](https://modbus.org/docs/Modbus_Application_Protocol_V1_1b3.pdf).

rodbus/examples/client.rs

@@ -61,7 +61,7 @@ where
 async fn run_tcp() -> Result<(), Box<dyn std::error::Error>> {
     // ANCHOR: create_tcp_channel
     let channel = spawn_tcp_client_task(
-        HostAddr::ip(IpAddr::V4(Ipv4Addr::LOCALHOST), 502),
+        HostAddr::ip(IpAddr::V4(Ipv4Addr::LOCALHOST), 10502),
         1,
         default_retry_strategy(),
         DecodeLevel::default(),
@@ -96,7 +96,7 @@ async fn run_rtu() -> Result<(), Box<dyn std::error::Error>> {
 async fn run_tls(tls_config: TlsClientConfig) -> Result<(), Box<dyn std::error::Error>> {
     // ANCHOR: create_tls_channel
     let channel = spawn_tls_client_task(
-        HostAddr::ip(IpAddr::V4(Ipv4Addr::LOCALHOST), 802),
+        HostAddr::ip(IpAddr::V4(Ipv4Addr::LOCALHOST), 10802),
         1,
         default_retry_strategy(),
         tls_config,
@@ -178,7 +178,7 @@ async fn run_channel(mut channel: Channel) -> Result<(), Box<dyn std::error::Err
     channel.enable().await?;
 
     // ANCHOR: request_param
-    let params = RequestParam::new(UnitId::new(1), Duration::from_secs(1));
+    let params = RequestParam::new(UnitId::new(1), Duration::from_secs(900));
     // ANCHOR_END: request_param
 
     let mut reader = FramedRead::new(tokio::io::stdin(), LinesCodec::new());
@@ -198,8 +198,8 @@ async fn run_channel(mut channel: Channel) -> Result<(), Box<dyn std::error::Err
                 channel
                     .set_decode_level(DecodeLevel::new(
                         AppDecodeLevel::DataValues,
-                        FrameDecodeLevel::Header,
-                        PhysDecodeLevel::Length,
+                        FrameDecodeLevel::Payload,
+                        PhysDecodeLevel::Data,
                     ))
                     .await?;
             }
@@ -267,6 +267,35 @@ async fn run_channel(mut channel: Channel) -> Result<(), Box<dyn std::error::Err
                 print_write_result(result);
                 // ANCHOR_END: write_multiple_registers
             }
+            "rwmr" => {
+                // ANCHOR: read_write_multiple_registers
+                let read_range = AddressRange::try_from(0x01, 0x04).unwrap();
+                let write_range = AddressRange::try_from(0x01, 0x04).unwrap();
+                let write_values = vec![0xC0DE, 0xCAFE, 0xC0DE, 0xCAFE];
+
+                let result = channel
+                    .read_write_multiple_registers(
+                        params,
+                        ReadWriteMultiple::new(read_range, write_range, write_values).unwrap(),                        
+                    )
+                    .await;
+                print_write_result(result);
+                // ANCHOR_END: read_write_multiple_registers
+            }
+            "wcfc" => {
+                // ANCHOR: write_custom_function_code
+                let length = 0x04 as usize;
+                let values = [0xC0, 0xDE, 0xCA, 0xFE]; // i.e.: Voltage Hi = 0xC0 / Voltage Lo = 0xDE / Current Hi = 0xCA / Current Lo = 0xFE
+
+                let result = channel
+                    .write_custom_function_code(
+                        params,
+                        CustomFunctionCode::new(length, values)
+                    )
+                    .await;
+                print_write_result(result);
+                // ANCHOR_END: write_custom_function_code
+            }
             _ => println!("unknown command"),
         }
     }

rodbus/examples/server.rs

@@ -78,6 +78,16 @@ impl RequestHandler for SimpleHandler {
         }
     }
 
+    fn write_custom_function_code(&mut self, values: CustomFunctionCode) -> Result<(), ExceptionCode> {
+        let mut custom_fc_args = [0_u16; 4]; // i.e.: Voltage Hi = 0x02, Voltage Lo = 0x03, Current Hi = 0x04, Current Lo = 0x05
+        for (i, &value) in values.iter().enumerate() {
+            custom_fc_args[i] = value;
+        }
+        tracing::info!("processing custom function code arguments: {:?}", custom_fc_args);
+
+        Ok(())
+    }
+
     fn write_single_register(&mut self, value: Indexed<u16>) -> Result<(), ExceptionCode> {
         tracing::info!(
             "write single register, index: {} value: {}",
@@ -167,7 +177,7 @@ async fn run_tcp() -> Result<(), Box<dyn std::error::Error>> {
     // ANCHOR: tcp_server_create
     let server = rodbus::server::spawn_tcp_server_task(
         1,
-        "127.0.0.1:502".parse()?,
+        "127.0.0.1:10502".parse()?,
         map,
         AddressFilter::Any,
         DecodeLevel::default(),
@@ -206,7 +216,7 @@ async fn run_tls(tls_config: TlsServerConfig) -> Result<(), Box<dyn std::error::
     // ANCHOR: tls_server_create
     let server = rodbus::server::spawn_tls_server_task_with_authz(
         1,
-        "127.0.0.1:802".parse()?,
+        "127.0.0.1:10802".parse()?,
         map,
         ReadOnlyAuthorizationHandler::create(),
         tls_config,
@@ -281,8 +291,8 @@ async fn run_server(
                 server
                     .set_decode_level(DecodeLevel::new(
                         AppDecodeLevel::DataValues,
-                        FrameDecodeLevel::Header,
-                        PhysDecodeLevel::Length,
+                        FrameDecodeLevel::Payload,
+                        PhysDecodeLevel::Data,
                     ))
                     .await?;
             }

rodbus/src/client/channel.rs

@@ -5,10 +5,13 @@ use crate::client::requests::read_bits::ReadBits;
 use crate::client::requests::read_registers::ReadRegisters;
 use crate::client::requests::write_multiple::{MultipleWriteRequest, WriteMultiple};
 use crate::client::requests::write_single::SingleWrite;
+use crate::client::requests::read_write_multiple::{MultipleReadWriteRequest, ReadWriteMultiple};
+use crate::client::requests::write_custom_fc::WriteCustomFunctionCode;
 use crate::error::*;
-use crate::types::{AddressRange, BitIterator, Indexed, RegisterIterator, UnitId};
+use crate::types::{AddressRange, BitIterator, Indexed, RegisterIterator, UnitId, CustomFunctionCode};
 use crate::DecodeLevel;
 
+
 /// Async channel used to make requests
 #[derive(Debug, Clone)]
 pub struct Channel {
@@ -163,6 +166,21 @@ impl Channel {
         rx.await?
     }
 
+    /// Write a Custom Function Code to the server
+    pub async fn write_custom_function_code(
+        &mut self,
+        param: RequestParam,
+        request: CustomFunctionCode,
+    ) -> Result<CustomFunctionCode, RequestError> {
+        let (tx, rx) = tokio::sync::oneshot::channel::<Result<CustomFunctionCode, RequestError>>();
+        let request = wrap(
+            param,
+            RequestDetails::WriteCustomFunctionCode(WriteCustomFunctionCode::new(request, Promise::channel(tx))),
+        );
+        self.tx.send(request).await?;
+        rx.await?
+    }
+
     /// Write a single coil on the server
     pub async fn write_single_coil(
         &mut self,
@@ -229,6 +247,24 @@ impl Channel {
         rx.await?
     }
 
+    /// Read & Write multiple contiguous registers on the server
+    pub async fn read_write_multiple_registers(
+        &mut self,
+        param: RequestParam,
+        request: ReadWriteMultiple<u16>,
+    ) -> Result<Vec<Indexed<u16>>, RequestError> {
+        let (tx, rx) = tokio::sync::oneshot::channel::<Result<Vec<Indexed<u16>>, RequestError>>();
+        let request = wrap(
+            param,
+            RequestDetails::ReadWriteMultipleRegisters(MultipleReadWriteRequest::new(
+                    request,
+                    Promise::channel(tx)
+                )),
+        );
+        self.tx.send(request).await?;
+        rx.await?
+    }
+
     /// Dynamically change the protocol decoding level of the channel
     pub async fn set_decode_level(&mut self, level: DecodeLevel) -> Result<(), Shutdown> {
         self.tx