hick-embassy 0.1.0

Async mDNS / DNS-SD for the embassy runtime — responder, querier, and discovery on embassy-net, no_std + alloc.

Introduction

hick-embassy is the embassy async driver for the [hick] mDNS family. It builds on the hick-smoltcp engine, supplying an embassy-net UdpIo transport, the embassy-time clock bridge, and an async driver future you spawn as an embassy task.

For the std / hosted runtimes (tokio, smol, compio), use hick-reactor, hick-compio, or the hick facade instead.

Installation

[dependencies]
hick-embassy = "0.1"

Example

Share one MdnsState between the driver task and the application (via Rc or a &'static StaticCell):

use hick_embassy::MdnsState;
use mdns_proto::{EndpointConfig, Name, ServiceRecords, ServiceSpec};

let state: &'static MdnsState<_> =
    make_static!(MdnsState::new(EndpointConfig::new(), rng));

// Advertise a service.
let mut records = ServiceRecords::new(
    Name::try_from_str("_http._tcp.local.").unwrap(),
    Name::try_from_str("My Device._http._tcp.local.").unwrap(),
    Name::try_from_str("mydevice.local.").unwrap(),
    80,
    120,
);
records.add_a(my_ipv4_addr);
state.register_service(ServiceSpec::new(records)).unwrap();

// Bind v4/v6 sockets to :5353 and join the mDNS group(s), then spawn the driver task
// (it enforces the RFC 6762 §11 egress hop-limit 255 itself — pass sockets by &mut):
spawner.must_spawn(mdns_task(state, v4_socket, v6_socket, scratch));

#[embassy_executor::task]
async fn mdns_task(
    state: &'static MdnsState<MyRng>,
    v4: &'static mut UdpSocket<'static>,
    v6: &'static mut UdpSocket<'static>,
    scratch: &'static mut [u8],
) -> ! {
    state.run(Some(v4), Some(v6), scratch).await
}

Feature flags

Feature	Description
`tracing`	Forward structured `tracing` events from `mdns-proto` and `hick-smoltcp` (no-op on bare-metal without a subscriber).
`stats`	Enable `no_std`-safe atomic counters; read a snapshot via `state.stats()`.
`defmt`	Emit `defmt` log events — the idiomatic choice for embassy bare-metal targets.

Observability

For embassy targets the recommended logging path is defmt combined with stats:

hick-embassy = { version = "0.1", features = ["defmt", "stats"] }

Enable defmt to have the driver emit structured log events through the defmt framework alongside embassy's own logging.

Enable stats and call state.stats() to obtain a hick_trace::stats::StatsSnapshot:

let snap = state.stats();
// snap.packets_rx, snap.services_active, snap.cache_size, etc.

The tracing feature is available but is a no-op on bare-metal targets that do not set up a tracing subscriber.

The metrics feature (bridging counters to the metrics facade) requires std and is not available on embassy bare-metal targets. Use stats + defmt instead for observability on embedded.

Design

Single-executor !Send: no Arc, no atomics. MdnsState holds the engine behind a RefCell plus an embassy_sync wake Signal; every handle method takes &self, and a borrow never spans an .await.
Dual v4/v6 stack: the driver pumps a DualUdp over the present sockets and wakes on a select of either socket's RX-readiness, the next protocol deadline, or a handle signalling new work.
Builds entirely on the hick-smoltcp engine — embassy supplies only the transport, clock, and the task wrapper.

The hick family

hick (facade) · mdns-proto (Sans-I/O core) · hick-udp (UDP) · hick-reactor (tokio / smol driver) · hick-compio (compio driver) · hick-smoltcp (smoltcp engine) · hick-embassy (this crate).

License

hick-embassy is under the terms of both the MIT license and the Apache License (Version 2.0).

See LICENSE-APACHE, LICENSE-MIT for details.