Client

Client is the central object that sends commands and reads state. The basic and command APIs, including Client, are provided by the main package. Connecting to real hardware and the like additionally requires a Link.

Installation

Rust

cargo add autd3-rs

Python

pip install autd3

C#

dotnet add package AUTD3

Rust

Client::open(&geometry, link, option).await?;

Python

await Client.open(geometry, link, option)

C#

await Client.OpenAsync(geometry, link, option);

Parameter	Type	Description
geometry	&Geometry	Physical layout of the devices
link	impl IntoLink	Link
config	ClientConfig	See below

To continuously monitor the operating state of the link, use open_with_checker and drive the returned Checker (see Link State Monitoring).

API

Rust

let num_devices = client.num_devices();

let firmware = client.read_firmware_version().await?;
let fpga_state = client.read_fpga_state().await?;
let error_detail = client.read_error_detail().await?;

let datagram_builder = client.datagram_builder();
let resp = client.send(frame).await?.await?;
client.send_checked(frame).await?;

client.stop().await?;
client.close().await?;

Python

num_devices = client.num_devices()

firmware = await client.read_firmware_version()
fpga_state = await client.read_fpga_state()
error_detail = await client.read_error_detail()

datagram_builder = client.datagram_builder()
resp = await (await client.send(frame))
await client.send_checked(frame)

await client.stop()
await client.close()

C#

var numDevices = client.NumDevices;

var firmware = await client.ReadFirmwareVersionAsync();
var fpgaState = await client.ReadFpgaStateAsync();
var errorDetail = await client.ReadErrorDetailAsync();

var datagramBuilder = client.DatagramBuilder();
var resp = await await client.SendAsync(frame);
await client.SendCheckedAsync(frame);

await client.StopAsync();
await client.CloseAsync();

Method	async	Returns	Description
num_devices()	—	usize	Number of connected devices
read_firmware_version()	✓	Result<Vec<FirmwareVersion>, Error>	CPU/FPGA firmware version of each device
read_fpga_state()	✓	Result<Vec<FpgaState>, Error>	FPGA state of each device
read_error_detail()	✓	Result<Vec<u8>, Error>	Error detail of each device
datagram_builder()	—	DatagramBuilder	DatagramBuilder
send(frame)	✓	Result<ResponseFuture, Error>	Enqueue a frame into the send queue. Awaiting the ResponseFuture yields the response (Response)
send_checked(frame)	✓	Result<(), Error>	Send and confirm the response
stop()	✓	Result<(), Error>	Stop all transducers
close()	✓	Result<(), Error>	Close the connection

ClientConfig

Rust

ClientConfig {
    timeout_cycles: NonZeroU32::new(10).unwrap(),
    max_inflight: NonZeroUsize::new(MAX_INFLIGHT).unwrap(),
    max_resync_rounds: NonZeroU32::new(8).unwrap(),
    low_latency: false,
    reset_resend_cycles: NonZeroU32::new(2).unwrap(),
    rt_priority: Some(ThreadPriority::Crossplatform(
        ThreadPriorityValue::try_from(80).unwrap(),
    )),
    rt_policy: RtSchedulePolicy::Fifo,
    rt_affinity: None,
    validate_state: true,
    require_supported_firmware: false,
    ..Default::default()
}

Python

ClientConfig(
    timeout_cycles=10,
    max_inflight=MAX_INFLIGHT,
    max_resync_rounds=8,
    low_latency=False,
    reset_resend_cycles=2,
    rt_priority=80,
    disable_rt_priority=False,
    rt_affinity=None,
    validate_state=True,
)

C#

new ClientConfig(
    timeoutCycles: 10,
    maxInflight: (uint)Client.MaxInflight,
    maxResyncRounds: 8,
    lowLatency: false,
    resetResendCycles: 2,
    rtPriority: 80,
    disableRtPriority: false,
    rtAffinity: null,
    validateState: true
)

Field	Type	Default	Description
timeout_cycles	NonZeroU32	10	Response-wait timeout (in send cycles)
max_inflight	NonZeroUsize	127	Send queue size
max_resync_rounds	NonZeroU32	8	Maximum number of rounds to attempt resynchronization
low_latency	bool	false	Low-latency mode
reset_resend_cycles	NonZeroU32	2	Number of cycles to send a reset command
rt_priority	Option<ThreadPriority>	Windows: TimeCritical / otherwise: 80	Priority of the RT thread. Setting None leaves the OS default.
rt_policy	RtSchedulePolicy	Fifo	Scheduling policy used when rt_priority is set: Normal, Fifo (SCHED_FIFO), RoundRobin (SCHED_RR)
rt_affinity	Option<CoreId>	None	CPU core affinity of the RT thread (OS default if None)
validate_state	bool	true	Enable pre-send validation
require_supported_firmware	bool	false	Check the firmware series on open (Rust only)

max_inflight errors if it exceeds MAX_INFLIGHT (127).

Enabling low_latency bypasses the receive buffer inside the firmware, improving latency. However, this may make operation unstable.