ether-dream

Ether Dream激光DAC协议的纯Rust实现。

特性

此实现提供

• Ether Dream DAC协议的完整实现。

  在protocol模块中找到Ether Dream协议中描述的所有类型。此模块还提供trait以简化将协议类型写入和读取到小端字节的过程。这对于处理特别有用 - DAC与用户之间通信的主要方法。

• 一个生成网络上所有DAC广播的迭代器。

  查看recv_dac_broadcasts.rs示例以获取简单概述。这是在网络中定位DAC并尝试与其建立连接之前的第一步。

  for dac_broadcast in ether_dream::recv_dac_broadcasts().unwrap() {
      println!("{:#?}", dac_broadcast);
  }
  

• 简单、低级且全面的Stream API。

  这是围绕Ether Dream协议中描述的TCP流通信通道的薄层。它简化了将Command排队并发送到DAC以及接收Response的过程。

  以下是如何连接到找到的第一个DAC的方法

  let (dac_broadcast, source_addr) = ether_dream::recv_dac_broadcasts()
      .unwrap()
      .filter_map(Result::ok)
      .next()
      .unwrap();
  println!("Discovered DAC \"{}\" at \"{}\"! Connecting...", mac_address, source_addr);
  let stream = dac::stream::connect(&dac_broadcast, source_addr.ip().clone()).unwrap();
  

  以下是一次性排队多个命令的DAC的示例。以下代码发送“准备流”命令，提交一些初始点数据到DAC，然后告诉DAC以给定的速率开始处理点数据。

  stream
      .queue_commands()
      .prepare_stream()
      .data(generate_points())
      .begin(0, point_hz)
      .submit()
      .unwrap();
  

  submit方法通过TCP流发送所有排队的命令，然后等待验证每个命令的响应。返回结果以及可能发生的任何错误（包括NAK和io::Error）。

  查看dac_stream.rs示例以了解Stream API的更详细演示。

  请注意，此API不提供“点”的“帧”概念的高级封装。这被视为更高层次的实现细节，并预期由下游crate实现。例如，nannou创意编码框架提供（或将要提供）一个更高级的激光API，该API将此crate作为多个可能的激光协议目标之一。

• DAC协议类型的Rust式表示。 dac模块包含几个类型，这些类型反映了DAC协议类型，但具有Rust友好的API。

  例如，许多描述DAC属性的位域集合在此模块中具有bitflags!结构表示。类似地，在协议中以整数描述的一些状态机在此模块中具有Rust枚举表示。

  提供了将协议表示转换为这种Rust式表示（from_protocol）和相反方向的方法（to_protocol）。

• 为API的所有区域提供了传统的清晰错误处理。

DAC仿真器

此存储库还包含一个ether-dream-dac-emulatorcrate。此crate可用于构建和运行自定义的虚拟Ether Dream DAC，这对于测试和可视化可能很有用。

仿真包括所有网络（UDP广播、TCP监听、TCP流式传输）以及DAC中的全部状态机（光引擎、播放和源）。

由于虚拟DAC没有发出物理光的方法，它通过一个Output队列产生“帧”的“点”。可以通过指定DAC描述中的frame_rate字段来控制将帧推送到此队列的速率。

./dac-emulator/examples演示了如何使用crate进行简单的命令行测试以及完整可视化DAC仿真器的输出。

extern crate ether_dream_dac_emulator;

fn main() {
    let dac_description = Default::default();
    println!("Creating an emulator for the following Ether Dream DAC:\n{:#?}", dac_description);
    let (broadcaster, mut listener) = ether_dream_dac_emulator::new(dac_description).unwrap();
    println!("Broadcasting DAC once per second...");
    let broadcaster_handle = broadcaster.spawn().unwrap();
    broadcaster_handle.spawn_once_per_second_timer().unwrap();
    println!("Listening for stream connection requests...");
    while let Ok((stream, addr)) = listener.accept() {
        println!("Connected to {}!", addr);
        let output = stream.output();
        loop {
            match output.next_frame() {
                Ok(frame) => println!("\tReceived frame with {} points", frame.len()),
                Err(_) => break,
            }
        }
        println!("Stream connection shutdown. Awaiting new requests...");
    }
}

致谢

此crate基于Jacob Potter的工作，他是Ether Dream DAC的创造者。许多文档注释直接转录自他们在协议中的写作，而许多其他注释是基于我对原始写作和源代码本身的理解而改编的。

• ether-dream.com - Ether Dream网站。
• ether-dream.com/protocol - 协议参考。
• github.com/j4cbo/j4cDAC - 原始C实现。

许可

许可如下

• Apache License，版本2.0，(LICENSE-APACHE 或 http://www.apache.org/licenses/LICENSE-2.0)
• MIT许可 (LICENSE-MIT 或 http://opensource.org/licenses/MIT)

任选其一。

贡献

除非你明确声明，否则，根据Apache-2.0许可中定义的，任何有意提交以包含在你提交的工作中的贡献，均应按上述方式双许可，不附加任何额外条款或条件。