sdm72 0.2.0

SDM72 protocol and commandline tool
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
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161

[![CI](https://github.com/acpiccolo/SDM72-Powermeter/actions/workflows/check.yml/badge.svg)](https://github.com/acpiccolo/SDM72-Powermeter/actions/workflows/check.yml)
[![dependency status](https://deps.rs/repo/github/acpiccolo/SDM72-Powermeter/status.svg)](https://deps.rs/repo/github/acpiccolo/SDM72-Powermeter)
[![CI](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/acpiccolo/SDM72-Powermeter/blob/main/LICENSE-MIT)
[![CI](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://github.com/acpiccolo/SDM72-Powermeter/blob/main/LICENSE-APACHE)
[![CI](https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg)](https://conventionalcommits.org)

# SDM72 Modbus Library and Tool

This repository contains a Rust library and a command-line tool for interacting with Eastron SDM72 series energy meters via the Modbus protocol.

## Table of Contents
- [Hardware Requirements](#hardware-requirements)
- [Technical Documentation](#technical-documentation)
- [Technical Specifications](#technical-specifications)
- [Installation & Compilation](#installation--compilation)
- [Command-Line Usage](#command-line-usage)
- [Library Usage](#library-usage)
- [Cargo Features](#cargo-features)
- [License](#license)

## Hardware Requirements
To use this tool, you need:
- An **Eastron SDM72 series energy meter**.
- A **USB-to-RS485 converter** (for RTU mode) or a **Modbus TCP gateway**.

## Technical Documentation
For more detailed information, please refer to the official datasheets available in the [`docs/`](./docs/) directory:
- [`eastron_sdm72dmv2.pdf`](./docs/eastron_sdm72dmv2.pdf)

## Technical Specifications
| Feature | Details |
|---|---|
| **Nominal Voltage** | 230/400V AC (3~) |
| **Operational Voltage** | 80%~120% of nominal voltage |
| **Current Measurement** | Up to 100A direct connection |
| **Communication Protocol** | Modbus RTU/TCP |
| **Baud Rates** | 2400, 4800, 9600, 19200, 38400 |
| **Data Format** | N, 8, 1 (No parity, 8 data bits, 1 stop bit) |

## Installation & Compilation

### Prerequisites
Ensure you have the following dependencies installed before proceeding:
- **Rust and Cargo**: Install via [rustup](https://rustup.rs/)
- **Git**: To clone the repository
- A C compiler and linker

### Building from Source
1. **Clone the repository**:
   ```sh
   git clone https://github.com/acpiccolo/SDM72-Powermeter.git
   cd SDM72-Powermeter
   ```
2. **Compile the project**:
   ```sh
   cargo build --release
   ```
   The compiled binary will be available at:
   ```sh
   target/release/sdm72
   ```
3. **(Optional) Install the binary system-wide**:
   ```sh
   cargo install --path .
   ```
   This installs `sdm72` to `$HOME/.cargo/bin`, making it accessible from anywhere.

## Command-Line Usage
### View Available Commands
To list all available commands and their options, run:
```sh
sdm72 --help
```
### Read All Values
For **RTU Modbus (RS485) connected** devices:
```sh
sdm72 rtu --address 1 --baudrate 9600 read-all
```
For **TCP Modbus connected** devices:
```sh
sdm72 tcp 192.168.0.222:502 read-all
```
### Daemon Mode with MQTT
You can also run the tool as a daemon that publishes data to an MQTT broker. The connection is configured via an `mqtt.yaml` file.
```sh
sdm72 rtu --address 1 --baudrate 9600 daemon mqtt
```

## Library Usage
The `sdm72_lib` crate provides two main ways to interact with the SDM72 energy meters:

1.  **High-Level, Safe Clients**: Stateful, thread-safe clients that are easy to share and use in concurrent applications. This is the recommended approach for most users. See `tokio_sync_safe_client::SafeClient` (blocking) and `tokio_async_safe_client::SafeClient` (`async`).

2.  **Low-Level, Stateless Functions**: A set of stateless functions that directly map to the device's Modbus commands. This API offers maximum flexibility but requires manual management of the Modbus context. See the `tokio_sync` and `tokio_async` modules.

### Quick Start: Synchronous Client

Here's a quick example of how to use the synchronous `SafeClient` to read all values over a TCP connection.

#### Dependencies

First, add the required dependencies to your project:
```sh
cargo add SDM72@0.2 --no-default-features --features "tokio-tcp-sync,safe-client-sync,serde"
cargo add tokio-modbus@0.16
cargo add tokio@1 --features full
```

#### Example Usage

```rust
use sdm72_lib::{
    protocol::Address,
    tokio_sync_safe_client::SafeClient,
};
use tokio_modbus::client::sync::tcp;
use tokio_modbus::Slave;
use std::time::Duration;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Connect to the device and create a stateful, safe client
    let socket_addr = "192.168.1.100:502".parse()?;
    let ctx = tcp::connect_slave(socket_addr, Slave(*Address::default()))?;
    let mut client = SafeClient::new(ctx);

    // Use the client to interact with the device
    let values = client.read_all(&Duration::from_millis(100))?;

    println!("Successfully read values: {:#?}", values);

    Ok(())
}
```

## Cargo Features

This crate uses a feature-based system to minimize dependencies. When using it as a library, you should disable default features and select only the components you need.

- **`default`**: Enables `bin-dependencies`, intended for compiling the `sdm72` command-line tool.

### Client Features
- **`tokio-rtu-sync`**: Synchronous (blocking) RTU client.
- **`tokio-tcp-sync`**: Synchronous (blocking) TCP client.
- **`tokio-rtu`**: Asynchronous (non-blocking) RTU client.
- **`tokio-tcp`**: Asynchronous (non-blocking) TCP client.

### High-Level Wrappers
- **`safe-client-sync`**: A thread-safe, stateful wrapper for synchronous clients.
- **`safe-client-async`**: A thread-safe, stateful wrapper for asynchronous clients.

### Utility Features
- **`serde`**: Implements `serde::Serialize` and `serde::Deserialize` for protocol structs.
- **`bin-dependencies`**: All features required to build the `sdm72` binary.

## License
Licensed under either of

 * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
 * MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)

at your option.