Utilities for Tether, a standardised MQTT+MessagePack system for inter-process communication.
This is both a library (for Tether Agents to use) and CLI tool (for development and troubleshooting), written in Rust.
With the CLI tool, users are provided a single binary with subcommands as follows:
- receive: Subscribe to all/some messages and attempt to decode them
- send: Publish a single message with optional custom payload
- topics: Subscribe to all/some messages and parse the topic parts such as Agent Role, Agent ID and Plug Name
- record: Record messages to disk. Useful for simulation, in combination with
playback
below - playback: Playback messages with their original topics and timing, to simulate one or more Agents
Usage as a library is not documented well yet, but see examples/api.rs for a quick overview.
There are always two parts to the CLI command
- The main command
tether
- Followed by optional parameters for general configuration such as
--host
or--loglevel
- Followed by optional parameters for general configuration such as
- The subcommand
receive
,send
,topics
,record
orplayback
- Followed by optional paramaters relating to the specific subcommand
Here's an example of using the receive
subcommand but specifying some non-default details for the MQTT Broker, and a non-default topic:
tether --host 10.0.0.1 --username myUserName --password myPaSsWorD! receive --topic +/+/someSpecificPlug
The simplest installation method is using the homebrew package manager for Mac. This is currently only working for MacOS running Apple Silicon.
Simply run the following two commands:
brew tap randomstudio/tether
brew install tether
(The formula and release files are hosted at https://github.com/RandomStudio/homebrew-tether - but you don't need to know that.)
If you have the Rust toolchain installed, you can install the executable using...
cargo install tether-utils
... This has the advantage of re-compiling for your architecture automatically. The crate is published at https://crates.io/crates/tether-utils
- Run with defaults:
tether receive
- More options can be found using
tether send --help
- Run with defaults:
tether send
- More options can be found using
tether send --help
This will be automatically converted into a MessagePack payload if it is valid JSON. You can typically enclose everything in single-quotes, like this:
tether send --message '{"foo":[1,2,3]}
tether send --message '[0,1,2]'
tether send --message '{"hello":"world", "arr":[1,2,3]}'
Alternatively, escape characters such as "
, [
, ]
, {
and }
:
tether send --message \{\"hello\":\"world\"\,\"arr\":\[1,2,3\]\}
Super useful for seeing which Agents are online, and how message topics are being parsed according to Agent Role, Agent ID and Plug Name. Now also provides live rate calculations (messages per second) and activity graph as below:
💡 This utility can't see into the past (except in the case of retained messages), so keep this in mind for Agents that don't publish frequently.
- Run with defaults:
tether topics
- More options can be found using
tether topics --help
- Run with defaults:
tether record
- More options can be found using
tether record --help
By default, a file named recording-00000000.json
(where the numbers are a timestamp) is generated in the current directory.
- Run with defaults:
tether playback
- More options can be found using
tether playback --help
If you don't specify a file with --file.path
, an included demo file (demo.json
) will be used instead. You probably want to specify a path to a real file, in most cases.
💡Tip: loop the playback infinitely by passing
--loops.infinite