First, create a project and add the autd3 library as a dependency. Also, add the autd3-link-soem library for communication with the device.

cargo new --bin autd3-sample
cd autd3-sample
cargo add autd3
cargo add autd3-link-soem

Next, edit the src/main.rs file as follows. This is the source code for applying AM modulation of $150\mathrm{Hz}$ to a single focal point.

use autd3::prelude::*;
use autd3_link_soem::{SOEMOption, Status, SOEM};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Open controller with SOEM link
    // Here, the AUTD3 device is placed at the origin
    let mut autd = Controller::open(
        [AUTD3 {
            pos: Point3::origin(),
            rot: UnitQuaternion::identity(),
        }],
        SOEM::new(
            // The first argument is a callback that is called when error occurs
            |slave, status| {
                eprintln!("slave[{}]: {}", slave, status);
                if status == Status::Lost {
                    // You can also wait for the link to recover, without exitting the process
                    std::process::exit(-1);
                }
            },
            // The second argument is a option of SOEM link.
            SOEMOption::default(),
        ),
    )?;

    // Check firmware version
    // This code assumes that the version is v11.0.0 or v10.0.1
    autd.firmware_version()?.iter().for_each(|firm_info| {
        println!("{}", firm_info);
    });

    // Enable silencer
    // Note that this is enabled by default, so it is not actually necessary
    // To disable, send Silencer::disable()
    autd.send(Silencer::default())?;

    // A focus at 150mm directly above the center of the device
    let g = Focus {
        pos: autd.center() + Vector3::new(0., 0., 150.0 * mm),
        option: FocusOption::default(),
    };

    // 150 Hz sine wave modulation
    let m = Sine {
        freq: 150 * Hz,
        option: SineOption::default(),
    };

    // Send data
    autd.send((m, g))?;

    println!("press enter to quit...");
    let mut _s = String::new();
    std::io::stdin().read_line(&mut _s)?;

    // Close controller
    autd.close()?;

    Ok(())
}

Then, run it.

cargo run --release

Notes for Linux and macOS Users

On Linux and macOS, administrator privileges are required to use SOEM. In that case, run:

cargo build --release && sudo ./target/release/autd3_sample

Installing Dependencies

This tutorial uses CMake, so make sure it is installed.

Creating an AUTD3 Client Program

First, open a terminal and prepare an appropriate directory.

mkdir autd3-sample
cd autd3-sample

Next, create CMakeLists.txt and main.cpp files under autd3-sample.

└─autd3-sample
        CMakeLists.txt
        main.cpp

Next, edit CMakeLists.txt as follows.

cmake_minimum_required(VERSION 3.21)

project(autd3-sample)

set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
set(CMAKE_CXX_EXTENSIONS OFF)

if(${CMAKE_VERSION} VERSION_GREATER_EQUAL "3.24.0") 
  cmake_policy(SET CMP0135 NEW)
endif()

include(FetchContent)
if(WIN32)
  FetchContent_Declare(
    autd3
    URL https://github.com/shinolab/autd3-cpp/releases/download/v30.0.1/autd3-v30.0.1-win-x64.zip
  )
  FetchContent_Declare(
    autd3-link-soem
    URL https://github.com/shinolab/autd3-cpp-link-soem/releases/download/v30.0.1/autd3-link-soem-v30.0.1-win-x64.zip
  )
elseif(APPLE)
  FetchContent_Declare(
    autd3
    URL https://github.com/shinolab/autd3-cpp/releases/download/v30.0.1/autd3-v30.0.1-macos-aarch64.tar.gz
  )
  FetchContent_Declare(
    autd3-link-soem
    URL https://github.com/shinolab/autd3-cpp-link-soem/releases/download/v30.0.1/autd3-link-soem-v30.0.1-macos-aarch64.tar.gz
  )
else()
  FetchContent_Declare(
    autd3
    URL https://github.com/shinolab/autd3-cpp/releases/download/v30.0.1/autd3-v30.0.1-linux-x64.tar.gz
  )
  FetchContent_Declare(
    autd3-link-soem
    URL https://github.com/shinolab/autd3-cpp-link-soem/releases/download/v30.0.1/autd3-link-soem-v30.0.1-linux-x64.tar.gz
  )
endif()
set(USE_SYSTEM_EIGEN OFF)
FetchContent_MakeAvailable(autd3 autd3-link-soem)

add_executable(main main.cpp)

target_link_libraries(main PRIVATE autd3::autd3 autd3::link::soem)

NOTE: In the above example, the dependency library (Eigen3) is automatically downloaded. If Eigen3 is already installed, you can disable the automatic download by turning on USE_SYSTEM_EIGEN and use the installed one.

Also, edit main.cpp as follows. This is the source code for applying AM modulation of $150\mathrm{Hz}$ to a single focal point.

#include <autd3_link_soem.hpp>
#include <iostream>

#include "autd3.hpp"

using namespace autd3;

int main() try {
  auto autd = Controller::open(
      {AUTD3{
          .pos = Point3::origin(),
          .rot = Quaternion::Identity(),
      }},
      link::SOEM(
          [](const uint16_t slave, const link::Status status) {
            std::cout << "slave [" << slave << "]: " << status << std::endl;
            if (status == link::Status::Lost()) exit(-1);
          },
          link::SOEMOption{}));

  const auto firm_version = autd.firmware_version();
  std::copy(firm_version.begin(), firm_version.end(),
            std::ostream_iterator<FirmwareVersion>(std::cout, "\n"));

  autd.send(Silencer{});

  Focus g(autd.center() + Vector3(0, 0, 150), FocusOption{});
  Sine m(150 * Hz, SineOption{});

  autd.send((m, g));

  std::cout << "press enter to finish..." << std::endl;
  std::cin.ignore();

  autd.close();

  return 0;
} catch (std::exception& ex) {
  std::cerr << ex.what() << std::endl;
}

Next, build with CMake.

mkdir build
cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
cmake --build . --config Release

This will generate an executable file, so run it.

.\Release\main.exe

sudo ./main

Troubleshooting

• There may be build errors if anaconda (miniconda) is activated.
  • In this case, delete the build directory, run conda deactivate, and then run cmake again.

First, open a terminal, create an appropriate project, and add the AUTD3Sharp library.

dotnet new console --name autd3-sample
cd autd3-sample
dotnet add package AUTD3Sharp
dotnet add package AUTD3Sharp.Link.SOEM

Next, edit Program.cs as follows. This is the source code for applying AM modulation of $150\mathrm{Hz}$ to a single focal point.

using AUTD3Sharp;
using AUTD3Sharp.Utils;
using AUTD3Sharp.Link;
using AUTD3Sharp.Gain;
using AUTD3Sharp.Modulation;
using static AUTD3Sharp.Units;

using var autd = Controller.Open(
    [new AUTD3(pos: Point3.Origin, rot: Quaternion.Identity)],
    new SOEM(
        (slave, status) =>
            {
                Console.Error.WriteLine($"slave [{slave}]: {status}");
                if (status == Status.Lost)
                    Environment.Exit(-1);
            },
        new SOEMOption()
    )
);

var firmList = autd.FirmwareVersion();
foreach (var firm in firmList)
    Console.WriteLine(firm);

autd.Send(new Silencer());

var g = new Focus(
    pos: autd.Center() + new Vector3(0, 0, 150),
    option: new FocusOption()
);
var m = new Sine(
    freq: 150u * Hz,
    option: new SineOption()
);
autd.Send((m, g));

Console.ReadKey(true);

autd.Close();

Then, run it.

dotnet run -c:Release

Notes for Linux and macOS Users

On Linux and macOS, administrator privileges may be required to use SOEM. In that case, run:

sudo dotnet run -c:Release

Installing the pyautd3 Library

First, install the pyautd3 and pyautd3_link_soem libraries via pip.

pip install pyautd3
pip install pyautd3_link_soem

Next, create main.py and edit it as follows. This is the source code for applying AM modulation of $150\mathrm{Hz}$ to a single focal point.

import os

import numpy as np
from pyautd3 import (
    AUTD3,
    Controller,
    Focus,
    FocusOption,
    Hz,
    Silencer,
    Sine,
    SineOption,
)
from pyautd3_link_soem import SOEM, SOEMOption, Status


def err_handler(slave: int, status: Status) -> None:
    print(f"slave [{slave}]: {status}")
    if status == Status.Lost():
        os._exit(-1)


if __name__ == "__main__":
    with Controller.open(
        [AUTD3(pos=[0.0, 0.0, 0.0], rot=[1, 0, 0, 0])],
        SOEM(err_handler=err_handler, option=SOEMOption()),
    ) as autd:
        firmware_version = autd.firmware_version()
        print(
            "\n".join(
                [f"[{i}]: {firm}" for i, firm in enumerate(firmware_version)],
            ),
        )

        autd.send(Silencer())

        g = Focus(
            pos=autd.center() + np.array([0.0, 0.0, 150.0]),
            option=FocusOption(),
        )
        m = Sine(
            freq=150 * Hz,
            option=SineOption(),
        )
        autd.send((m, g))

        _ = input()

        autd.close()

Then, run it.

python main.py

Notes for Linux Users

On Linux, administrator privileges are required to use SOEM. In that case, run:

sudo setcap cap_net_raw,cap_net_admin=eip <your python path>

Then, run main.py.

python main.py

Notes for macOS Users

On macOS, administrator privileges are required to use SOEM. In that case, run:

sudo chmod +r /dev/bpf*

Then, run main.py.

python main.py