Struct TetherAgent

pub struct TetherAgent {
    pub message_receiver: Receiver<(TetherOrCustomTopic, Vec<u8>)>,
    /* private fields */
}

A Tether Agent struct encapsulates everything required to set up a single “Agent” as part of your Tether-based system. The only thing absolutely required is a “role” - everything else is optional and sensible defaults will be used when not explicitly specified.

By default, the Agent will connect (automatically) to an MQTT Broker on localhost:1883

It will not have an ID, and therefore publishing/subscribing topics will not append anything this into the topic string when ChannelSender and ChannelReceiver instances are created using this Tether Agent instance, unless explicitly provided on creation.

Note that you should typically not construct a new TetherAgent instance yourself; rather use the provided TetherAgentBuilder to specify any options you might need, and call .build to get a well-configured TetherAgent.

Fields

message_receiver: Receiver<(TetherOrCustomTopic, Vec<u8>)>

Implementations

impl<'a> TetherAgent

pub fn create_sender<T: Serialize>(&self, name: &str) -> ChannelSender<'_, T>

The simplest way to create a ChannelSender.

You provide only a Channel Name; configuration derived from your Tether Agent instance is used to construct the appropriate publishing topics.

pub fn create_sender_with_def<T: Serialize>( &self, definition: ChannelSenderDef, ) -> ChannelSender<'_, T>

Create a ChannelSender instance using a ChannelSenderDefinition already constructed elsewhere.

pub fn create_receiver<T: Deserialize<'a>>( &'a self, name: &str, ) -> Result<ChannelReceiver<'a, T>>

The simplest way to create a Channel Receiver.

You provide only a Channel Name; configuration derived from your Tether Agent instance is used to construct the appropriate subscribing topics.

The actual subscription is also initiated automatically.

pub fn create_receiver_with_def<T: Deserialize<'a>>( &'a self, definition: ChannelReceiverDef, ) -> Result<ChannelReceiver<'a, T>>

Create a ChannelReceiver instance using a ChannelReceiverDefinition already constructed elsewhere.

pub fn is_connected(&self) -> bool

pub fn auto_connect_enabled(&self) -> bool

pub fn role(&self) -> &str

pub fn id(&self) -> Option<&str>

pub fn description(&self) -> (String, String, String)

Returns the Agent Role, ID (group), Broker URI

pub fn client(&self) -> Option<&Client>

Get the underlying MQTT Client directly, immutable. WARNING: This allows you to do non-Tether-compliant things!

pub fn client_mut(&mut self) -> Option<&mut Client>

Get the underlying MQTT Client directly, mutably. WARNING: This allows you to do non-Tether-compliant things!

Can be useful for subscribing to a topic directly, for example, without knowing the message type (as would be the case with a Tether Channel).

pub fn broker_uri(&self) -> String

Return the URI (protocol, IP address, port, path) that was used to connect to the MQTT broker

pub fn set_role(&mut self, role: &str)

Change the role, even if it was set before. Be careful when you call this, as it could affect any new Channel Senders/Receivers created after that point.

pub fn set_id(&mut self, id: &str)

Change the ID, even if it was set (or left empty) before. Be careful when you call this, as it could affect any new Channel Senders/Receivers created after that point.

pub fn connect(&mut self) -> Result<()>

Use this function yourself only if you explicitly disallowed auto connection. Otherwise, this function is called automatically as part of the .build process.

This function spawns a separate thread for polling the MQTT broker. Any events and messages are relayed via mpsc channels internally; for example, you will call .check_messages() to see if any messages were received and are waiting to be parsed.

pub fn check_messages(&self) -> Option<(TetherOrCustomTopic, Vec<u8>)>

If a message is waiting to be parsed by your application, this function will return Topic, Message, i.e. (TetherOrCustomTopic, Message)

Messages received on topics that are not parseable as Tether Three Part Topics will be returned with the complete Topic string instead

pub fn send<T: Serialize>( &self, channel_sender: &ChannelSender<'_, T>, data: &T, ) -> Result<()>

Typically called via the Channel Sender itself.

This function serializes the data (using Serde/MessagePack) automatically before publishing.

Given a Channel Sender and serializeable data payload, publishes a message using an appropriate topic and with the QOS specified in the Channel Definition.

Note that this function requires that the data payload be the same type as the Channel Sender, so it will return an Error if the types do not match.

pub fn send_raw( &self, channel_definition: &ChannelSenderDef, payload: Option<&[u8]>, ) -> Result<()>

Typically called via the Channel Sender itself.

Unlike .send, this function does NOT serialize the data before publishing. It therefore does no type checking of the payload.

Given a Channel Sender and a raw (u8 buffer) payload, publishes a message using an appropriate topic and with the QOS specified in the Channel Definition

pub fn send_empty(&self, channel_definition: &ChannelSenderDef) -> Result<()>

pub fn publish_raw( &self, topic: &str, payload: &[u8], qos: Option<i32>, retained: Option<bool>, ) -> Result<()>

Publish an already-encoded payload using a provided full topic string - no need for passing a ChannelSender or ChannelSenderDefinition reference.

WARNING: This is a back door to using MQTT directly, without any guarrantees of correctedness in a Tether-based system!