ashv2

Implementation of Silicon Labs' Asynchronous Serial Host protocol v2 (ASHv2), host side.

Specification

Silicon Labs publishes the documentation online:

• https://docs.silabs.com/zigbee/latest/uart-gateway-protocol-reference/

Current implementation status

The crate currently provides:

• Frame parsing/encoding for DATA, ACK, NAK, RST, RST-ACK, and ERROR.
• CRC-16 validation/generation for all supported frame types.
• Byte stuffing/unstuffing and ASH payload randomization (masking/unmasking).
• Async actor futures created with start(...), with caller-owned transmitter/receiver execution.
• Transport-independent async I/O over caller-provided tokio::io::AsyncRead and tokio::io::AsyncWrite implementations.
• Automatic initial reset handshake (RST -> RST-ACK) before normal traffic.
• Automatic handling of inbound ACK/NAK and retransmission of queued DATA frames.
• Automatic reset/recovery on protocol errors (ERROR, RST, and selected I/O failures).
• Optional EZSP adapters implementing ezsp::Transmit and ezsp::Receive.

Important behavior details:

• start(reader, writer, response) accepts separate async reader and writer values. The caller is responsible for opening and configuring the transport and splitting it when necessary.
• The core crate does not depend on serialport or async-serialport. Serial ports, sockets, in-memory streams, and other transports can be used when they implement the required Tokio I/O traits.
• start(...) returns transmitter and receiver futures in a named Futures container for the caller to spawn or poll.
• The crate does not spawn Tokio tasks internally.
• The transmitter terminates after every Handle clone has been dropped and the outbound message queue has been drained. There is no terminate message.
• When the transmitter terminates, it signals the receiver to terminate as well.
• Handle::send(payload).await confirms local transmission attempt (I/O success), not the remote ASH response payload.
• Payload requests made before the ASH link is established remain queued while the initial reset handshake is driven.
• When the transmit window is full, the transmitter requeues the payload request without delay.
• Incoming DATA payloads are delivered through the response channel passed to start(...).
• Payload type is heapless::Vec<u8, MAX_PAYLOAD_SIZE> (MAX_PAYLOAD_SIZE defaults to 128).

Compile-time tunables (via const_env):

• ASHV2_MAX_PAYLOAD_SIZE (default: 128)
• ASHV2_T_RSTACK_MAX_MILLIS (default: 3200)
• ASHV2_TX_K (default: 5)
• ASHV2_T_RX_ACK_MAX_MILLIS (default: 3200)

Usage

use ashv2::start;
use tokio::io::{AsyncRead, AsyncWrite};
use tokio::sync::mpsc::channel;

async fn run<R, W>(reader: R, writer: W)
where
    R: AsyncRead + Send + Sync + Unpin + 'static,
    W: AsyncWrite + Send + Sync + Unpin + 'static,
{
    // Channel for inbound ASH DATA payloads from the NCP.
    let (response_tx, mut response_rx) = channel(64);

    // Create ASH actor futures from the transport halves and spawn them on the
    // application's runtime.
    let (handle, futures) = start(reader, writer, response_tx);
    let transmitter = tokio::spawn(futures.transmitter);
    let receiver = tokio::spawn(futures.receiver);

    // Example EZSP "version" request payload.
    let request_payload = [0x00, 0x00, 0x00, 0x02].into_iter().collect();
    handle
        .send(request_payload)
        .await
        .expect("Failed to transmit request frame");

    // Receive inbound DATA payload from NCP.
    if let Some(response_payload) = response_rx.recv().await {
        println!("Received response payload: {response_payload:?}");
    }

    // Dropping the final Handle closes the outbound queue. The transmitter
    // drains that queue, terminates, and signals the receiver to terminate.
    drop(handle);
    transmitter.await.expect("Transmitter task failed");
    receiver.await.expect("Receiver task failed");
}

The reader and writer can come from any transport integration. For a bidirectional type that implements both traits, use that transport's split operation (for example, tokio::io::split) before calling start(...).

Every clone of Handle, including a handle used through the optional EZSP transmitter adapter, must be dropped before termination can begin.

EZSP integration

Enable the ezsp feature to get typed EZSP adapters:

[dependencies]
ashv2 = { version = "11", features = ["ezsp"] }

With the feature enabled:

• ashv2::ezsp::Transmitter is an alias for ashv2::Handle, which implements ezsp::Transmit.
• ashv2::ezsp::Receiver owns the inbound ASHv2 payload receiver and implements ezsp::Receive. The EZSP layer supplies the currently negotiated protocol version to each receive call.

The same payload channel connects the core ASHv2 actor to the EZSP receiver:

use ashv2::ezsp::{Receiver as EzspReceiver, Transmitter as EzspTransmitter};
use ashv2::start;
use tokio::sync::mpsc::channel;

let (payload_tx, payload_rx) = channel(64);
let (ash_handle, futures) = start(reader, writer, payload_tx);

let ezsp_transmitter: EzspTransmitter = ash_handle;
let ezsp_receiver = EzspReceiver::new(payload_rx);

// Spawn or otherwise poll futures.transmitter and futures.receiver.
// Pass ezsp_transmitter and ezsp_receiver to the EZSP API.

Without the feature, the EZSP dependency and adapter module are not compiled.

Development

The CI workflow currently runs:

• cargo +nightly fmt --check
• cargo clippy --all-features -- -A clippy::multiple_crate_versions -D warnings
• cargo test --all-features
• cargo build --all-features --release
• cargo vet check

Legal

This project is free software and is not affiliated with Silicon Labs.

Credits

Special thanks to Simon Farnsworth, Kevin Reid, and the community at https://users.rust-lang.org/.