Feat: Custom Defined Function Codes (FC 65..=72, 100..=110)

rodbus/SCFC_README.md

@@ -0,0 +1,87 @@
+# Send Custom Function Code (65-72 & 100-110)
+
+This document provides a detailed overview of the implemented rodbus custom function code feature. These user-defined function codes fall within the range of 65 to 72 and 100 to 110, as specified in the MODBUS Application Protocol Specification V1.1b3 (Page 10, Section 5: Function Code Categories), and allow custom server-side execution logic.
+
+
+## Introduction
+The custom function codes enable 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 variable-size data buffer.
+
+
+## Request Structure
+| Parameter           | Size          | Range / Value         |
+|---------------------|---------------|-----------------------|
+| Function code       | 1 Byte        | 0x41-0x48 / 0x64-0x6E |
+| Byte Count (Input)  | 1 Byte        | 0x00 to 0xFF (N*)     |
+| Byte Count (Output) | 1 Byte        | 0x00 to 0xFF          |
+| Data                | N* x 2 Bytes  | 0x0000 to 0xFFFF      |
+
+
+## Response Structure
+| Parameter           | Size         | Value/Description     |
+|---------------------|--------------|-----------------------|
+| Function code       | 1 Byte       | 0x41-0x48 / 0x64-0x6E |
+| Byte Count (Input)  | 1 Byte       | 0x00 to 0xFF (N*)     |
+| Byte Count (Output) | 1 Byte       | 0x00 to 0xFF          |
+| Data                | N* x 2 Bytes | 0x0000 to 0xFFFF      |
+
+
+## Error Handling
+| Parameter      | Size    | Description          |
+|----------------|---------|----------------------|
+| Function code  | 1 Byte  | Function code + 0x80 |
+| 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 FC 69 with a buffer of [0xC0DE, 0xCAFE, 0xC0DE, 0xCAFE] (Byte Count = 4 -> 8 bytes):
+| Request Field             | Hex | Response Field         | Hex |
+|---------------------------|-----|------------------------|-----|
+| Function code             | 45  | Function code          | 45  |
+| Byte Count (Input)        | 04  | Byte Count (Input)     | 04  |
+| Byte Count (Output)       | 04  | Byte Count (Output)    | 04  |
+| Arg1 Hi                   | C0  | Arg1 Hi                | C0  |
+| Arg1 Lo                   | DE  | Arg1 Lo                | DF  |
+| Arg2 Hi                   | CA  | Arg2 Hi                | CA  |
+| Arg2 Lo                   | FE  | Arg2 Lo                | FF  |
+| Arg3 Hi                   | C0  | Arg3 Hi                | C0  |
+| Arg3 Lo                   | DE  | Arg3 Lo                | DF  |
+| Arg4 Hi                   | CA  | Arg4 Hi                | CA  |
+| Arg4 Lo                   | FE  | Arg4 Lo                | FF  |
+
+
+## Usage
+Make sure that you are in the `rodbus` project directory.
+
+
+### Start the custom_server example
+- `cargo run --example custom_server -- tcp`
+- Once it's up, run `ed` to enable decoding
+
+Leave the terminal open and open another terminal.
+
+
+### Start the custom_client example
+- `cargo run --example custom_client -- tcp`
+- Once it's up, run `ed` to enable decoding
+
+
+### Send the Custom Function Code 69
+In the terminal with the running custom_client example, run:
+- `scfc <u8 Function Code> <u8 Byte Count Input> <u8 Byte Count Output> <u16 Arguments>`
+- E.g. `scfc 0x45 0x02 0x02 0xC0DE 0xCAFE`
+- The response would be for example: `fc: 0x45, bytes in: 2, bytes out: 2, values: [49375, 51967], hex: [0xC0DF, 0xCAFF]`
+
+
+## Troubleshooting Tips
+- Ensure the server and client are using the same communication method 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,
@@ -267,6 +267,22 @@ async fn run_channel(mut channel: Channel) -> Result<(), Box<dyn std::error::Err
                 print_write_result(result);
                 // ANCHOR_END: write_multiple_registers
             }
+            "scfc" => {
+                // ANCHOR: send_custom_function_code
+                let fc = 0x45 as u8;
+                let byte_count_in = 0x04 as u8;
+                let byte_count_out = 0x04 as u8;
+                let values = vec![0xC0DE, 0xCAFE, 0xC0DE, 0xCAFE]; // i.e.: Voltage Hi = 0xC0 / Voltage Lo = 0xDE / Current Hi = 0xCA / Current Lo = 0xFE
+
+                let result = channel
+                    .send_custom_function_code(
+                        params,
+                        CustomFunctionCode::new(fc, byte_count_in, byte_count_out, values),
+                    )
+                    .await;
+                print_write_result(result);
+                // ANCHOR_END: send_custom_function_code
+            }
             _ => println!("unknown command"),
         }
     }

rodbus/examples/custom_client.rs

@@ -0,0 +1,235 @@
+use std::error::Error;
+use std::net::{IpAddr, Ipv4Addr};
+use std::process::exit;
+use std::time::Duration;
+
+use tokio_stream::StreamExt;
+use tokio_util::codec::{FramedRead, LinesCodec};
+
+use rodbus::client::*;
+use rodbus::*;
+
+// ANCHOR: runtime_init
+#[tokio::main(flavor = "multi_thread")]
+async fn main() -> Result<(), Box<dyn Error>> {
+    // ANCHOR_END: runtime_init
+
+    // ANCHOR: logging
+    tracing_subscriber::fmt()
+        .with_max_level(tracing::Level::INFO)
+        .with_target(false)
+        .init();
+    // ANCHOR_END: logging
+
+    let args: Vec<String> = std::env::args().collect();
+    let transport: &str = match &args[..] {
+        [_, x] => x,
+        _ => {
+            eprintln!("please specify a transport:");
+            eprintln!("usage: outstation <transport> (tcp, rtu, tls-ca, tls-self-signed)");
+            exit(-1);
+        }
+    };
+    match transport {
+        "tcp" => run_tcp().await,
+        #[cfg(feature = "serial")]
+        "rtu" => run_rtu().await,
+        #[cfg(feature = "tls")]
+        "tls-ca" => run_tls(get_ca_chain_config()?).await,
+        #[cfg(feature = "tls")]
+        "tls-self-signed" => run_tls(get_self_signed_config()?).await,
+        _ => {
+            eprintln!(
+                "unknown transport '{transport}', options are (tcp, rtu, tls-ca, tls-self-signed)"
+            );
+            exit(-1);
+        }
+    }
+}
+
+struct LoggingListener;
+impl<T> Listener<T> for LoggingListener
+where
+    T: std::fmt::Debug,
+{
+    fn update(&mut self, value: T) -> MaybeAsync<()> {
+        tracing::info!("Channel Listener: {:?}", value);
+        MaybeAsync::ready(())
+    }
+}
+
+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), 11502),
+        1,
+        default_retry_strategy(),
+        DecodeLevel::default(),
+        Some(Box::new(LoggingListener)),
+    );
+    // ANCHOR_END: create_tcp_channel
+
+    run_channel(channel).await
+}
+
+#[cfg(feature = "serial")]
+async fn run_rtu() -> Result<(), Box<dyn std::error::Error>> {
+    // ANCHOR: create_rtu_channel
+    let channel = spawn_rtu_client_task(
+        "/dev/ttySIM0",                    // path
+        rodbus::SerialSettings::default(), // serial settings
+        1,                                 // max queued requests
+        default_retry_strategy(),          // retry delays
+        DecodeLevel::new(
+            AppDecodeLevel::DataValues,
+            FrameDecodeLevel::Payload,
+            PhysDecodeLevel::Nothing,
+        ),
+        Some(Box::new(LoggingListener)),
+    );
+    // ANCHOR_END: create_rtu_channel
+
+    run_channel(channel).await
+}
+
+#[cfg(feature = "tls")]
+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), 11802),
+        1,
+        default_retry_strategy(),
+        tls_config,
+        DecodeLevel::new(
+            AppDecodeLevel::DataValues,
+            FrameDecodeLevel::Nothing,
+            PhysDecodeLevel::Nothing,
+        ),
+        Some(Box::new(LoggingListener)),
+    );
+    // ANCHOR_END: create_tls_channel
+
+    run_channel(channel).await
+}
+
+#[cfg(feature = "tls")]
+fn get_self_signed_config() -> Result<TlsClientConfig, Box<dyn std::error::Error>> {
+    use std::path::Path;
+    // ANCHOR: tls_self_signed_config
+    let tls_config = TlsClientConfig::self_signed(
+        Path::new("./certs/self_signed/entity2_cert.pem"),
+        Path::new("./certs/self_signed/entity1_cert.pem"),
+        Path::new("./certs/self_signed/entity1_key.pem"),
+        None, // no password
+        MinTlsVersion::V1_2,
+    )?;
+    // ANCHOR_END: tls_self_signed_config
+
+    Ok(tls_config)
+}
+
+#[cfg(feature = "tls")]
+fn get_ca_chain_config() -> Result<TlsClientConfig, Box<dyn std::error::Error>> {
+    use std::path::Path;
+    // ANCHOR: tls_ca_chain_config
+    let tls_config = TlsClientConfig::full_pki(
+        Some("test.com".to_string()),
+        Path::new("./certs/ca_chain/ca_cert.pem"),
+        Path::new("./certs/ca_chain/client_cert.pem"),
+        Path::new("./certs/ca_chain/client_key.pem"),
+        None, // no password
+        MinTlsVersion::V1_2,
+    )?;
+    // ANCHOR_END: tls_ca_chain_config
+
+    Ok(tls_config)
+}
+
+/*fn print_read_result<T>(result: Result<Vec<Indexed<T>>, RequestError>)
+where
+    T: std::fmt::Display,
+{
+    match result {
+        Ok(registers) => {
+            for register in registers {
+                println!("index: {} value: {}", register.index, register.value);
+            }
+        }
+        Err(rodbus::RequestError::Exception(exception)) => {
+            println!("Modbus exception: {exception}");
+        }
+        Err(err) => println!("read error: {err}"),
+    }
+}*/
+
+fn print_write_result<T>(result: Result<T, RequestError>) {
+    match result {
+        Ok(_) => {
+            println!("write successful");
+        }
+        Err(rodbus::RequestError::Exception(exception)) => {
+            println!("Modbus exception: {exception}");
+        }
+        Err(err) => println!("writer error: {err}"),
+    }
+}
+
+async fn run_channel(mut channel: Channel) -> Result<(), Box<dyn std::error::Error>> {
+    channel.enable().await?;
+
+    // ANCHOR: request_param
+    let params = RequestParam::new(UnitId::new(1), Duration::from_secs(1));
+    // ANCHOR_END: request_param
+
+    let mut reader = FramedRead::new(tokio::io::stdin(), LinesCodec::new());
+    while let Some(line) = reader.next().await {
+        let line = line?; // This handles the Some(Err(e)) case by returning Err(e)
+        let parts = line.split_whitespace().collect::<Vec<&str>>();
+        match parts.as_slice() {
+            ["x"] => return Ok(()),
+            ["ec"] => {
+                channel.enable().await?;
+            }
+            ["dc"] => {
+                channel.disable().await?;
+            }
+            ["ed"] => {
+                channel
+                    .set_decode_level(DecodeLevel::new(
+                        AppDecodeLevel::DataValues,
+                        FrameDecodeLevel::Payload,
+                        PhysDecodeLevel::Data,
+                    ))
+                    .await?;
+            }
+            ["dd"] => {
+                channel.set_decode_level(DecodeLevel::nothing()).await?;
+            }
+            ["scfc", fc_str, bytes_in_str, bytes_out_str, values @ ..] => {
+                let fc = u8::from_str_radix(fc_str.trim_start_matches("0x"), 16).unwrap();
+                let byte_count_in =
+                    u8::from_str_radix(bytes_in_str.trim_start_matches("0x"), 16).unwrap();
+                let byte_count_out =
+                    u8::from_str_radix(bytes_out_str.trim_start_matches("0x"), 16).unwrap();
+                let values: Vec<u16> = values
+                    .iter()
+                    .filter_map(|&v| u16::from_str_radix(v.trim_start_matches("0x"), 16).ok())
+                    .collect();
+
+                if (fc >= 65 && fc <= 72) || (fc >= 100 && fc <= 110) {
+                    let result = channel
+                        .send_custom_function_code(
+                            params,
+                            CustomFunctionCode::new(fc, byte_count_in, byte_count_out, values),
+                        )
+                        .await;
+                    print_write_result(result);
+                } else {
+                    println!("Error: CFC number is not inside the range of 65-72 or 100-110.");
+                }
+            }
+            _ => println!("unknown command"),
+        }
+    }
+    Ok(())
+}