Struct Controller 

pub struct Controller { /* private fields */ }

Available on crate feature alloc only.

The Homie 5 controller; see the module documentation.

Implementations

impl Controller

pub fn handle_message(&mut self, now: Instant, msg: Message<'_>) -> Handled

Handles one received message. A message while the link is down is taken as evidence of a new session (reason=implicitLinkUp): devices are re-paced as after a clean session, while filters already sent stay counted as on the broker, so releasing one still unsubscribes it. The host should still forward every CONNACK.

impl Controller

pub fn handle_link(&mut self, now: Instant, link: Link)

Handles a change in the broker link.

Up after a clean session, or after session_present: true unless Config::trust_session, queues the discovery filter, then stage one for every known device (in tree mode the root unpaced, then every tracked descendant), with a fresh $description required before property filters are paced again; it marks every device unconfirmed and arms the absence and sync timers. A trusted resumed session keeps everything. Event::Link follows the commands. Down while the link is down changes nothing and emits nothing.

pub fn handle_timeout(&mut self, now: Instant)

Handles every deadline at or before now.

pub fn handle_dropped(&mut self, now: Instant, topic: &str)

Reports that the host dropped messages for the device topic addresses (for example on inbox overflow). The next handle_timeout, which a driver calls once its backlog drains, resubscribes the device so the broker replays its retained messages. In wildcard mode a dropped $state also resubscribes the discovery filter, which carries every $state.

A host that reports a drop only after it has handed later messages to the controller calls handle_lost first, before those messages.

pub fn handle_lost(&mut self, topic: &str)

Reports, at its place in the message order, that the host dropped a message for the device topic addresses: no message after it ends a re-sync window open for that device, so nothing the drop hid is cleared. It heals nothing; handle_dropped still follows once the backlog drains.

pub fn handle_command_failed(&mut self, now: Instant, cmd: Command)

Reports a command the host could not hand to its client. A Subscribe or Unsubscribe is retried with a 1-30 s backoff; a Publish is dropped (reason=setDropped), since QoS 0 is never held (convention.md:695).

impl Controller

pub fn new(config: Config) -> Result<Self, ConfigError>

A controller for config. Discovery is subscribed on the first handle_link Up, or on the first message, which counts as one.

pub fn config(&self) -> &Config

The configuration in use.

pub fn poll_command(&mut self) -> Option<Command>

The next command for the MQTT client.

pub fn poll_event(&mut self) -> Option<Event>

The next event.

pub fn poll_timeout(&self) -> Option<Instant>

When to call handle_timeout next, or None when no timer is armed. The instant is never later than the earliest deadline, and may be earlier when a deadline was disarmed since the last handle_timeout, which then finds nothing due and recomputes it. Constant time in the number of devices.

pub fn wants(&self, topic: &str) -> bool

True when topic is in the controller’s domain ({domain}/5/..., or any domain at version 5 for Domain::Any).

pub fn is_connected(&self) -> bool

True between a link-up and the next link-down, and before shutdown.

pub fn device(&self, id: &str) -> Option<&DeviceView>

The device with this id, once its first valid $state has arrived (convention.md:272). With Domain::Any, an id known in several domains resolves to the first domain in byte order.

pub fn devices(&self) -> impl Iterator<Item = &DeviceView> + '_

Every device whose first valid $state has arrived, in id order.

pub fn devices_with_id<'a>( &'a self, id: &'a str, ) -> impl Iterator<Item = &'a DeviceView> + 'a

Every device with this id whose first valid $state has arrived, one per domain, in domain order. At most one with a Domain::Named domain.

pub fn effective_state(&self, id: &str) -> Option<DeviceState>

The device’s effective state (convention.md:262-267).

pub fn is_tree_complete(&self, root: &str) -> bool

True when the device root and every device its description declares under it, transitively, have published a description. A declared device counts whatever its $state.

pub fn set( &mut self, addr: &PropertyAddr, payload: &str, opts: SetOptions, ) -> Result<(), SetError>

Queues a /set for addr (QoS 0, not retained). Ok means validated and queued; nothing confirms delivery (convention.md:474-475).

QoS 0 follows framework.md:87 for every property. convention.md:45-49 recommends QoS 2 except for /set on non-retained properties; the eBus specification decides where the two differ.

Checked in order: the link is up; the device and property are known; the property is settable; the device’s effective state is ready unless opts.allow_not_ready; unless opts.unchecked, the payload passes datatype::parse_set_payload with the last valid value as the step base. The payload is sent as given, except that "" for a string property is sent as a single 0x00 byte (convention.md:60-71).

pub fn broadcast( &mut self, subtopic: &str, payload: &str, ) -> Result<(), SetError>

Queues payload to {domain}/5/$broadcast/{subtopic} (QoS 0, not retained), after checking that every subtopic level is a valid id (convention.md:531-535).

pub fn shutdown(&mut self)

Unsubscribes every filter the controller holds, except host filters, and stops: later input is ignored, no timer is armed, and set returns SetError::NotConnected. The views stay readable.

Trait Implementations

impl Debug for Controller

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Role for Controller

fn owns(&self, cmd: &Command) -> bool

The controller’s commands are /set and $broadcast publishes in its domain, and subscriptions to filters in its domain other than /set filters.

fn handle_link(&mut self, now: Instant, link: Link)

A CONNACK, or a lost connection.

fn handle_message(&mut self, now: Instant, msg: Message<'_>) -> Handled

One received message.

fn handle_command_failed(&mut self, now: Instant, cmd: Command)

A command the host could not hand to its client.

fn handle_timeout(&mut self, now: Instant)

The instant poll_timeout returned has passed.

fn handle_dropped(&mut self, now: Instant, topic: &str)

The host dropped messages for topic’s device; ignored by default.

fn handle_lost(&mut self, topic: &str)

handle_dropped at its place in the message order; ignored by default.

fn poll_command(&mut self) -> Option<Command>

The next command for the MQTT client.

fn poll_timeout(&self) -> Option<Instant>

When to call handle_timeout next.

fn wants(&self, topic: &str) -> bool

True when the role takes messages on topic.

fn holds(&self, filter: &str) -> bool

True when this role holds a subscription to filter.

fn handle_receipt(&mut self, _now: Instant, _receipt: &Receipt)

A delivery report; ignored by default.