SyMqttBox - the orchestrator class

When you work with SyMqtt, almost everything you do revolves around a single class: SyMqttBox.

Think of this class as the central orchestrator or the brain of the framework. It wraps the underlying MQTT client, manages connection states, handles automatic retries, and dispatches messages to the right places.

Instead of dealing with low-level MQTT topics and raw byte arrays, you will interact with SyMqttBox to register your high-level channels and trigger communication.

The lifecycle roadmap

To use SyMqttBox successfully, you need to follow a specific sequence of steps. Here is a quick bird’s-eye view of how the lifecycle works:

1. Instantiation: You create an instance of SyMqttBox. At this point, you can also inject your predefined channels or topic holders.
2. Global Configuration: You adjust public properties like prefixes, logging tools, or fallback delivery options.
3. Topology Registration: You add your sender/receiver topic holders and communication channels. Crucial rule: You can only add or remove these components while the connection is closed.
4. Initialization: You pass the network and security parameters to the box, preparing the internal MQTT client.
5. Connection: You open the connection actively. While connected, your topology is frozen and cannot be modified on the fly.
6. Operations: You use the box methods to send fire-and-forget messages or execute synchronous request-response cycles.
7. Cleanup or Reconfiguration: You close the connection gracefully to release resources or to tweak parameters before reconnecting.

In the following steps of this guide, we will break down each of these phases with practical code examples.

Let’s move to the next step, where you will see how to instantiate the box and configure its core properties.