melsec_mc 0.4.0

A small Rust library to talk to Mitsubishi PLCs via MC Protocol (Ethernet) - transport layer and helpers
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119

# melsec_mc

A lightweight Rust library that provides sending/receiving and a small client for Mitsubishi Electric PLCs using the MC protocol (Ethernet / MC4E compatible).

Version: 0.4.0

Main features
- Tokio-based asynchronous transport
- Raw MC frame send/receive and parser
- High-level one-shot helpers and a reusable `McClient`
- Typed read/write support via `FromWords` / `ToWords`
- Error registry merge semantics and other registry improvements

Important changes in this release
- Hardened public API (removed panic/unwrap/expect/eprintln!), errors are returned as `Result<..., MelsecError>`.
- Introduced `McResponse::try_new` and migrated call sites.
- Added typed read/write traits and client helpers: `FromWords` / `ToWords` and `McClient::read_words_as` / `write_words_as`.

Contents
- Quickstart
- Installation
- Usage (simple example)
- Advanced usage (Typed API, McClient)
- Releases & publishing
- Contributing and license

## Quickstart

1. Clone and build:

```powershell
git clone https://github.com/tyaro/melsec_com.git
cd melsec_com
cargo build
```

2. Run an example (adjust PLC address in `examples`):

```powershell
cargo run --example simple
```

## Installation

If published on crates.io, add to your `Cargo.toml`:

```toml
[dependencies]
melsec_mc = "0.4.0"
```

For development from the Git repository:

```toml
[dependencies]
melsec_mc = { git = "https://github.com/tyaro/melsec_com", branch = "main" }
```

## Usage (simple example)

Example using async Tokio runtime:

```rust
use melsec_mc::{McClient, ConnectionTarget};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Specify the target and construct a client
    let target = ConnectionTarget::direct("192.168.1.40", 4020);
    let client = McClient::new().with_target(target);

    // Read bits (method name is `read_bits`)
    let bits = client.read_bits("M", 10, 3).await?;
    println!("bits: {:?}", bits);

    // Read words (method name is `read_words`)
    let words = client.read_words("D", 100, 2).await?;
    println!("words: {:?}", words);

    Ok(())
}
```

## Typed read/write (Typed API)

This release adds `FromWords` / `ToWords` traits that let you read/write multi-word types such as `f32`, `u32`, or fixed-size boolean arrays directly.

```rust
// Reading (element count = 2 of f32; internally requests 4 words)
let floats: Vec<f32> = client.read_words_as::<f32>("D1000", 2).await?;

// Writing
client.write_words_as("D1010", &vec![1.23f32, 4.56f32]).await?;
```

Typed reads parse element-by-element. On parse failure the client logs a warning, skips one word to resynchronize, and continues; successfully parsed elements are returned (partial results allowed).

## Releases & publishing

- The project uses GitHub Releases: https://github.com/tyaro/melsec_com/releases
- To publish to crates.io use `cargo publish` (requires credentials and 2FA).

Verify package creation with:

```powershell
cargo publish --dry-run
```

## Contributing & contact

- Pull requests welcome. For major API changes, open an Issue first.
- Report bugs or request features via GitHub Issues.

## License

MIT

---
The Japanese README (`README.md`) was updated; this file provides an English counterpart as `README.en.md`.