rigolds1000z

https://docs.rs/rigolds1000z/
Admin
rigolds1000z is a Rust crate designed to control and interface with Rigol DS1000Z series...
Tokens:3,380
Snippets:24
Trust Score:9.1
Update:2 months ago
Show doc for...
Tokens:
Raw
### Example usage of a library function

Source: https://docs.rs/rigolds1000z/latest/scrape-examples-help.html

Create an example file that calls the library function to trigger the scraping mechanism.

```rust
// examples/ex.rs
fn main() {
  a_crate::a_func();
}
```

--------------------------------

### Define a public function for scraping

Source: https://docs.rs/rigolds1000z/latest/scrape-examples-help.html

Place this public function in your library source to make it eligible for example scraping.

```rust
// src/lib.rs
pub fn a_func() {}
```

--------------------------------

### DS1000::new

Source: https://docs.rs/rigolds1000z/latest/src/rigolds1000z/lib.rs.html

Initializes a new connection to the oscilloscope at the specified host address.

```APIDOC
## DS1000::new(host: &str) -> DS1000

### Description
Creates a new instance of the DS1000 controller and establishes a TCP connection to the provided host address.

### Parameters
- **host** (&str) - Required - The IP address or hostname of the oscilloscope.
```

--------------------------------

### Identify and Query Oscilloscope

Source: https://docs.rs/rigolds1000z/latest/rigolds1000z/struct.DS1000.html

Demonstrates initializing the scope, retrieving the identification string, and sending manual commands.

```rust
3fn main() -> std::io::Result<()> {
4    let mut scope = DS1000::new(&std::env::var("SCOPE_HOST").unwrap());
5
6    let id = scope.idn()?;
7    println!("Scope id: {}", id);
8
9    scope.send_command("*IDn?")?;
10    let id_2 = scope.read_string()?;
11
12    assert!(id == id_2);
13
14    Ok(())
15}
```

--------------------------------

### Dump Sample Memory from DS1000

Source: https://docs.rs/rigolds1000z/latest/src/dump_sample_memory/dump_sample_memory.rs.html

Initializes the DS1000 connection using the SCOPE_HOST environment variable and retrieves samples from CHAN1.

```rust
1use rigolds1000z::DS1000;

fn main() -> std::io::Result<()> {
    let mut scope = DS1000::new(&std::env::var("SCOPE_HOST").unwrap());

    println!("Scope id: {}", scope.idn()?);

    scope.stop()?; //stop to dump internal memory

    let samples = scope.get_waveform("CHAN1")?;

    println!("got {} samples", samples.len());

    Ok(())
}
```

--------------------------------

### DS1000::new

Source: https://docs.rs/rigolds1000z/latest/rigolds1000z/struct.DS1000.html

Creates a new instance of the DS1000 client connected to the specified host.

```APIDOC
## pub fn new(host: &str) -> DS1000

### Description
Initializes a new DS1000 client instance using the provided host address.

### Parameters
- **host** (&str) - Required - The network address of the oscilloscope.
```

--------------------------------

### System and Acquisition Configuration

Source: https://docs.rs/rigolds1000z/latest/src/rigolds1000z/lib.rs.html

Methods to configure system settings and acquisition parameters.

```APIDOC
## System and Acquisition Configuration

### Methods
- **beep(beep: bool) -> Result<(), std::io::Error>** - Enables or disables the system beeper.
- **get_srate() -> Result<f64, std::io::Error>** - Retrieves the current sample rate.
- **get_mdepth() -> Result<MDepth, std::io::Error>** - Retrieves the current memory depth setting.
- **set_mdepth(mdepth: MDepth) -> Result<(), std::io::Error>** - Sets the memory depth (Auto or Manual).
```

--------------------------------

### Retrieve Device Identification

Source: https://docs.rs/rigolds1000z/latest/src/idn/idn.rs.html

Demonstrates connecting to a scope and fetching the identification string using the library method and raw SCPI commands.

```rust
1use rigolds1000z::DS1000;

fn main() -> std::io::Result<()> {
    let mut scope = DS1000::new(&std::env::var("SCOPE_HOST").unwrap());

    let id = scope.idn()?;
    println!("Scope id: {}", id);

    scope.send_command("*IDn?")?;
    let id_2 = scope.read_string()?;

    assert!(id == id_2);

    Ok(())
}
```

--------------------------------

### Test memory depth configuration

Source: https://docs.rs/rigolds1000z/latest/src/rigolds1000z/lib.rs.html

Verifies that the oscilloscope correctly sets and retrieves manual and automatic memory depth settings.

```rust
#[test]
fn test_1() {
    let mut scope = DS1000::new(&std::env::var("SCOPE_HOST").unwrap());

    scope.run().unwrap();

    scope.set_mdepth(MDepth::Manual(24000000)).unwrap();

    assert!(scope.get_mdepth().unwrap() == MDepth::Manual(24000000));

    scope.set_mdepth(MDepth::Manual(12000000)).unwrap();

    assert!(scope.get_mdepth().unwrap() == MDepth::Manual(12000000));

    scope.set_mdepth(MDepth::Auto).unwrap();

    assert!(scope.get_mdepth().unwrap() == MDepth::Auto);
}
```

--------------------------------

### DS1000 Struct and Implementation

Source: https://docs.rs/rigolds1000z/latest/src/rigolds1000z/lib.rs.html

The core structure for managing the oscilloscope connection and the implementation of basic control and data retrieval methods.

```rust
1use std::io::prelude::*;
2use std::io::BufReader;
3use std::io::BufWriter;
4use std::net::TcpStream;
5
6use log::*;
7
8pub struct DS1000 {
9    reader: BufReader<TcpStream>,
10    writer: BufWriter<TcpStream>,
11}
12
13#[derive(PartialEq, Debug)]
14pub enum MDepth {
15    Auto,
16    Manual(usize),
17}
18
19impl DS1000 {
20    pub fn new(host: &str) -> DS1000 {
21        let stream = TcpStream::connect(host).unwrap();
22
23        let reader = BufReader::new(stream.try_clone().unwrap());
24        let writer = BufWriter::new(stream.try_clone().unwrap());
25
26        DS1000 { reader, writer }
27    }
28
29    pub fn send_command(&mut self, command: &str) -> Result<(), std::io::Error> {
30        trace!("Sending command: {}", command);
31        self.writer.write(format!("{}\n", command).as_bytes())?;
32        self.writer.flush()?;
33
34        std::thread::sleep(std::time::Duration::from_millis(10));
35
36        Ok(())
37    }
38
39    pub fn read_string(&mut self) -> Result<String, std::io::Error> {
40        let mut line = String::new();
41        self.reader.read_line(&mut line)?;
42        let line = line.trim().to_string();
43        trace!("Received string: {}", line);
44
45        Ok(line)
46    }
47
48    pub fn idn(&mut self) -> std::io::Result<String> {
49        self.send_command("*IDn?")?;
50        self.read_string()
51    }
52
53    pub fn run(&mut self) -> std::io::Result<()> {
54        self.send_command(":RUN")
55    }
56
57    pub fn stop(&mut self) -> std::io::Result<()> {
58        self.send_command(":STOP")
59    }
60
61    pub fn single(&mut self) -> std::io::Result<()> {
62        self.send_command(":SINGle")
63    }
64
65    pub fn clear(&mut self) -> std::io::Result<()> {
66        self.send_command(":CLEar")
67    }
68
69    pub fn trigger_force(&mut self) -> std::io::Result<()> {
70        self.send_command(":TFORce")
71    }
72
73    pub fn autoscale(&mut self) -> std::io::Result<()> {
74        self.send_command(":AUToscale")
75    }
76
77    pub fn beep(&mut self, beep: bool) -> std::io::Result<()> {
78        self.send_command(&format!(":SYSTem:BEEPer {}", if beep { 1 } else { 0 }))
79    }
80
81    pub fn get_srate(&mut self) -> std::io::Result<f64> {
82        self.send_command(":ACQuire:SRATe?")?;
83
84        let res = self.read_string()?;
85        let res = res.trim();
86
87        Ok(res.parse::<f64>().unwrap())
88    }
89
90    pub fn get_mdepth(&mut self) -> std::io::Result<MDepth> {
91        self.send_command(":ACQuire:MDEPth?")?;
92
93        let res = self.read_string()?;
94        let res = res.trim();
95
96        if res == "AUTO" {
97            Ok(MDepth::Auto)
98        } else {
99            Ok(MDepth::Manual(res.parse::<usize>().unwrap()))
100        }
101    }
102
103    pub fn set_mdepth(&mut self, mdepth: MDepth) -> std::io::Result<()> {
104        match mdepth {
105            MDepth::Auto => self.send_command(":ACQuire:MDEPth AUTO"),
106            MDepth::Manual(mdep) => self.send_command(&format!(":ACQuire:MDEPth {}", mdep)),
107        }
108    }
109
110    pub fn get_waveform(&mut self, channel: &str) -> std::io::Result<Vec<u8>> {
111        self.send_command(&format!(":WAV:SOUR {}", channel))?;
112        self.send_command(":WAV:MODE RAW")?;
113        self.send_command(":WAV:FORM BYTE")?;
114
115        if let MDepth::Manual(depth) = self.get_mdepth().unwrap() {
116            let mut ret: Vec<u8> = Vec::with_capacity(depth);
117
118            let n_per_iter = 250000; //from the rigol manual
119
120            let niter = (depth as f64 / n_per_iter as f64).ceil() as usize;
121
122            info!("Expecting {} points, {} iterations", depth, niter);
123
124            for i in 0..niter {
125                self.send_command(&format!(":WAV:STAR {}", i * n_per_iter + 1))?;
126                self.send_command(&format!(":WAV:STOP {}", depth.min((i + 1) * n_per_iter)))?;
127                self.send_command(":WAV:DATA?")?;
128
129                let mut header = [0; 11];
130                self.reader.read_exact(&mut header)?;
131
132                let header_str = std::str::from_utf8(&(header[2..])).unwrap();
133                trace!("header: {:?}", header_str);
134
135                let npoints = header_str.parse::<usize>().unwrap();
136
137                info!("Iter {}/{}, number of points: {}", i + 1, niter, npoints);
138
139                let mut buf: Vec<u8> = Vec::with_capacity(npoints);
140                buf.resize(npoints, 0);
141
142                self.reader.read_exact(&mut buf)?;
143
144                self.reader.read_line(&mut String::new()).unwrap();
145
146                ret.append(&mut buf);
147            }
148
149            assert!(ret.len() == depth);
150            Ok(ret)
151        } else {
```

--------------------------------

### Dump Waveform Memory

Source: https://docs.rs/rigolds1000z/latest/rigolds1000z/struct.DS1000.html

Shows how to stop the oscilloscope and retrieve waveform samples from a specific channel.

```rust
3fn main() -> std::io::Result<()> {
4    let mut scope = DS1000::new(&std::env::var("SCOPE_HOST").unwrap());
5
6    println!("Scope id: {}", scope.idn()?);
7
8    scope.stop()?; //stop to dump internal memory
9
10    let samples = scope.get_waveform("CHAN1")?;
11
12    println!("got {} samples", samples.len());
13
14    Ok(())
15}
```

--------------------------------

### DS1000::send_command

Source: https://docs.rs/rigolds1000z/latest/rigolds1000z/struct.DS1000.html

Sends a raw SCPI command to the oscilloscope.

```APIDOC
## pub fn send_command(&mut self, command: &str) -> Result<(), Error>

### Description
Sends a raw command string to the instrument.

### Parameters
- **command** (&str) - Required - The SCPI command to execute.
```

--------------------------------

### Instrument Control Methods

Source: https://docs.rs/rigolds1000z/latest/src/rigolds1000z/lib.rs.html

Methods for controlling the state and operation of the oscilloscope.

```APIDOC
## Instrument Control Methods

### Methods
- **idn() -> Result<String, std::io::Error>** - Queries the device identification string.
- **run() -> Result<(), std::io::Error>** - Starts the oscilloscope acquisition.
- **stop() -> Result<(), std::io::Error>** - Stops the oscilloscope acquisition.
- **single() -> Result<(), std::io::Error>** - Sets the oscilloscope to single trigger mode.
- **clear() -> Result<(), std::io::Error>** - Clears the display and memory.
- **trigger_force() -> Result<(), std::io::Error>** - Forces a trigger event.
- **autoscale() -> Result<(), std::io::Error>** - Performs an autoscale operation.
```

--------------------------------

### DS1000::idn

Source: https://docs.rs/rigolds1000z/latest/rigolds1000z/struct.DS1000.html

Queries the oscilloscope for its identification string.

```APIDOC
## pub fn idn(&mut self) -> Result<String>

### Description
Sends an identification query to the instrument and returns the response string.
```

--------------------------------

### Define DS1000 Struct

Source: https://docs.rs/rigolds1000z/latest/rigolds1000z/struct.DS1000.html

The internal structure definition for the DS1000 interface.

```rust
pub struct DS1000 { /* private fields */ }
```

--------------------------------

### get_waveform

Source: https://docs.rs/rigolds1000z/latest/src/rigolds1000z/lib.rs.html

Retrieves waveform data from a specific channel.

```APIDOC
## get_waveform(channel: &str) -> Result<Vec<u8>, std::io::Error>

### Description
Fetches raw waveform data from the specified channel. This method automatically configures the oscilloscope for raw data transfer and handles multi-part data retrieval based on the current memory depth.

### Parameters
- **channel** (&str) - Required - The channel identifier (e.g., "CHAN1").
```

--------------------------------

### DS1000::get_waveform

Source: https://docs.rs/rigolds1000z/latest/rigolds1000z/struct.DS1000.html

Retrieves waveform data from a specific channel.

```APIDOC
## pub fn get_waveform(&mut self, channel: &str) -> Result<Vec<u8>>

### Description
Fetches the raw waveform data for the specified channel.

### Parameters
- **channel** (&str) - Required - The channel identifier (e.g., "CHAN1").
```

--------------------------------

### DS1000::stop

Source: https://docs.rs/rigolds1000z/latest/rigolds1000z/struct.DS1000.html

Stops the oscilloscope acquisition.

```APIDOC
## pub fn stop(&mut self) -> Result<()>

### Description
Sends a command to stop the oscilloscope's current acquisition process.
```

--------------------------------

### MDepth Enum Definition

Source: https://docs.rs/rigolds1000z/latest/rigolds1000z/enum.MDepth.html

The MDepth enum structure with Auto and Manual variants.

```rust
pub enum MDepth {
    Auto,
    Manual(usize),
}
```
Tokens:
Raw