Stridulus

Male grasshoppers spend much of the day stridulating (in latin: stridulus).

A library written in rust for listening and sending messages over mqtt. It simplifies the usage of rumqttc for use in grasshopper and future applications that needs to talk to grasshopper-devices.

How to use

Install to your project

Under [dependencies] in Cargo.toml add the line

stridulus = { git = "ssh://git@nms-git.telenor.net/cmp/stridulus.git", tag = "v0.5.0" }

Notice: To make git over ssh to work properly you must also edit ./cargo/config.toml with the following: [net] git-fetch-with-cli = true

Setup

Stridulus can either be configured with simple mqtt settings (no tls) or mqtt with Tls.

Simple

let mqtt_config = MqttConfig::Simple("mqtt://localhost:1883?client_id=123".to_string());

Tls

let mqtt_config = MqttConfig::Tls(MqttTlsConfig {
  ca: vec![], // a vector of u8 of the ca
  cert: vec![], // a vector of u8 of the cert
  key: vec![], // a vector of u8 of the key
  url: "mqtts://localhost:8883?client_id=123".to_string(),
  key_type: stridulus::MqttTlsKey::ECC,
});

• ca is the CA certificate
• cert is the client certificate
• key is the client key

Create

Before creation you must specify which topics to subscribe to:

let topics = vec!["some/topic".to_string()];
// or topics = vec![]; if you don't want to subscribe to any.

Then you use mqtt_config and topics to create a client and event_reciever

let (stridulus_client, stridulus_event_reciever) = stridulus::create(mqtt_config, topics)
  .await
  .unwrap_or_else(|_| {
    panic!("Could not connect with stridulus");
  });

Sending messages

As long as the setup is correct all you need to send messages is:

if let Err(e) = stridulus_client
  .publish(StridulusMessage {
    topic: "some/topic".to_string(),
    message: "{\"your\":{\"data\":true}}".to_string(),
  }) {
    panic!("Failed to publish message: {}", e);
}

Message can be any string, but JSON format is preffered.

Notice! sending messages are best effort. Meaning that if it fails the message is not resent. It is up to you as the user of the client to resend.

Subscribing to topics and recieving messages

If you have populated topics on creation, you will be able to listen for messages on those topics. When a message is recieved on the topic, either a StridulusEvent::Message or a StridulusEvent::Unknown can be recieved by the stridulus_event_reciever:

loop {
  if let Some(stridulus_event) = stridulus_event_reciever.recv().await {
    match stridulus_event {
      Incoming(incoming_event) => {
        match incoming_event => {
          Message(m) => {},
          Unknown => {},
        }
      }
      Outgoing => {}
    }
  }
}

StridulusEvent

You can listen to to the events from stridulus. These can either be Incoming or Outgoing. Incoming messages are messages recieved from the server. Outgoing is messages sent from the client.

Incoming messages Message or Unknown:

• Message
  • Is a regular incoming mqtt message
  • Holds a message and a topic.
  • Is created when the mqtt message is on the form a/topic/xyz {"some": "message"}
  • can also have a reply_topic if specified on the icoming topic like a/topic/xyz/reply-to=some%2Freply2%Ftopic {"some": "message"}. It is intended to be used when the sender expects the reciever to confirm when the message is handled
• Unknown
  • when stridulus recieves a message over mqtt that it don't understand or it don't yet handles.