mountain-mqtt

This is a monorepo of crates for a no_std compatible MQTT v5 client.

Each folder is a separate rust crate (e.g. mountain-mqtt contains the main library crate). This is NOT a cargo workspace, it's just a set of crates that live alongside each other in the repo. This has been done for flexibility, in particular to allow for different targets to be used for each crate if needed - this in turn allows for example projects to build for embedded targets.

Note there are also README.md files in each crate folder, covering the respective crate.

For development, crates reference each other via relative paths, each crate is also published to crates.io (other than the examples).

Development Status

mountain-mqtt is still at an early stage of development, and the API is likely to have breaking changes in future.

• The codec, data and packets modules in the mountain-mqtt crate are relatively stable and complete, with at least some unit and integration tests.
• The client code in the mountain-mqtt crate is much less stable - this is likely to be updated to use a better async approach that doesn't rely on delays (PollClient and HandlerClient in the mountain-mqtt-embassy crate already use this kind of approach).
• The mountain-mqtt-embassy crate is being updated:
  • PollClient and HandlerClient are recommended for use instead of the older mqtt_manager since they promise to be simpler and easier to use, and may also be more reliable. See the embassy-poll-example-rp2040w crate for an example of using them.
  • mqtt_manager will likely be removed in future (most likely in version 0.6).

Projects

• mountain-mqtt - A no_std compatible MQTT v5 client. Designed to be independent of async implementation, networking etc., this provides encoding/decoding of MQTT packets, and an approximately sans-io approach to modelling the MQTT protocol using a state machine and a connection abstraction. Also contains implementations of connection for tokio and embedded-hal, and a simple client example using tokio.

• mountain-mqtt-embassy - A higher-level interface using embassy channels to provide an mqtt_manager that will handle reconnecting to the server, and slightly lower level clients PollClient and HandlerClient.

• embassy-example-rp2040w - An example application using embassy withmqtt_manager to demonstrate MQTT on a Raspberry Pi Pico board. The README also has a detailed explanation of an approach to using mountain-mqtt-embassy.

• embassy-poll-example - similar to the example above, but using PollClient or HandlerClient - this has shared code that can run on either a Raspberry Pi Pico or Raspberry Pi Pico 2. See embassy-poll-example/src/lib.rs function run_example for the code that is run from main.

• embassy-poll-example-rp2040w - this just sets up the target and build to run embassy-poll-example on a Pico, with the RP2040 chip.

• embassy-poll-example-rp2350w - this just sets up the target and build to run embassy-poll-example on a Pico 2, with the RP2350 chip.

Editing with Helix

Just run helix in the repository root, it should handle the multiple crates correctly.

Editing with VS Code

There are two approaches:

1. Open an individual crate as a project, and see just that crate in the VS Code window, or
2. Open the provided mountain-mqtt.code-workspace file as a VS Code workspace. This will open each crate as a separate root in the workspace, so they can all be edited together. Rust Analyzer will run on each crate. The contents of the root of the workspace (including this file) are displayed under the / entry in the explorer.

How Is the VS Code Workspace Configured?

This is an interesting one, since we want to be able to see each of the crates as a separate project, and at the same time show the root directory itself.

This is done in the .code-workspace file by adding a folder for each crate, then a folder for the root (we can give this a name, we've used / for simplicity). This would by default also show the crate folders within the root folder - we can prevent this by specifying file exclusions for each crate:

{
  "folders": [
    {
      "path": "crate-a"
    },
    {
      "path": "crate-b"
    },
    {
      "path": ".",
      "name": "/"
    }
  ],
  "settings": {
    "files.exclude": {
      "crate-a": true,
      "crate-b": true
    }
  }
}

You will need to add any new crates to both the folders array, and the files.exclude setting.

This approach of keeping crates as separate projects without a cargo workspace, and opening them as multiple roots in a VS Code workspace, is suggested here.The general approach to excluding the crate folders is covered in this comment on a VS Code issue.

Why Not a Cargo Workspace?

A Cargo workspace currently applies the same target to all projects/crates, and we require general-purpose crates like mountain-mqtt to run on either the host PC or embedded.

It sounds like there may be future additions to Cargo and/or Rust Analyzer to allow for different settings in different projects, but this didn't seem to cover our use case when the project was set up.