espressif/mosquitto

readme

# ESP32 Mosquitto Port

This is a lightweight port of the Mosquitto broker designed to run on the ESP32. It currently supports a single listener with TCP transport or TLS transport based on ESP-TLS library.

## Supported Options

The Espressif port supports a limited set of options (with plans to add more in future releases). These options can be configured through a structure passed to the `mosq_broker_run()` function. For detailed information on available configuration options, refer to the [API documentation](api.md).

## API

### Starting the Broker

To start the broker, call the `mosq_broker_run()` function with a properly configured settings structure. The broker operates in the context of the calling task and does not create a separate task.

It's recommended to analyze the stack size needed for the task, but in general, the broker requires at least 4 kB of stack size.

```c
mosq_broker_run(&config);
```

## Memory Footprint Considerations

The broker primarily uses the heap for internal data, with minimal use of static/BSS memory. It consumes approximately 60 kB of program memory.

- **Initial Memory Usage**: ~2 kB of heap on startup
- **Per Client Memory Usage**: ~4 kB of heap for each connected client

When using the broker with multiple clients, ensure sufficient heap space is available to handle scenarios where clients disconnect abruptly and reconnect. In cases of clean disconnections, the broker releases the memory immediately. However, when a client loses connection abruptly, the broker retains its connection information for some time before eventually freeing this memory. If the client reconnects during this period, an additional 4 kB of heap is allocated for the new connection while the memory for the previous connection is still being retained. Therefore, extra heap space is necessary to manage these abrupt reconnections smoothly.

## Testing

Extensive long-term tests have been conducted with the broker handling 5 clients simultaneously. Each client publishes messages every second to a different topic, while all clients subscribe to all topics. The test also included abrupt disconnections, where clients were suspended and reconnected after 10 seconds, to simulate real-world network instability.

api

# API Reference

## Header files

- [mosq_broker.h](#file-mosq_brokerh)

## File mosq_broker.h





## Structures and Types

| Type | Name |
| ---: | :--- |
| struct | [**mosq\_broker\_config**](#struct-mosq_broker_config) <br>_Mosquitto configuration structure._ |

## Functions

| Type | Name |
| ---: | :--- |
|  int | [**mosq\_broker\_run**](#function-mosq_broker_run) (struct [**mosq\_broker\_config**](#struct-mosq_broker_config) \*config) <br>_Start mosquitto broker._ |
|  void | [**mosq\_broker\_stop**](#function-mosq_broker_stop) (void) <br>_Stops running broker._ |


## Structures and Types Documentation

### struct `mosq_broker_config`

_Mosquitto configuration structure._

ESP port of mosquittto supports only the options in this configuration structure.

Variables:

-  char \* host  <br>Address on which the broker is listening for connections

-  int port  <br>Port number of the broker to listen to

-  esp\_tls\_cfg\_server\_t \* tls_cfg  <br>ESP-TLS configuration (if TLS transport used) Please refer to the ESP-TLS official documentation for more details on configuring the TLS options. You can open the respective docs with this idf.py command: `idf.py docs -sp api-reference/protocols/esp_tls.html`


## Functions Documentation

### function `mosq_broker_run`

_Start mosquitto broker._
```c
int mosq_broker_run (
    struct mosq_broker_config *config
)
```


This API runs the broker in the calling thread and blocks until the mosquitto exits.



**Parameters:**


* `config` Mosquitto configuration structure


**Returns:**

int Exit code (0 on success)
### function `mosq_broker_stop`

_Stops running broker._
```c
void mosq_broker_stop (
    void
)
```


**Note:**

After calling this API, function mosq\_broker\_run() unblocks and returns.