|
| 1 | +# Console command mqtt |
| 2 | +The component provides a console where mqtt commands can be executed. |
| 3 | + |
| 4 | + |
| 5 | +## MQTT Configuration: |
| 6 | +1. Broker: Use menuconfig **"MQTT Configuration"** to configure the broker url. |
| 7 | + |
| 8 | + |
| 9 | +## API |
| 10 | + |
| 11 | +### Steps to enable console in an example code: |
| 12 | +1. Add this component to your project using ```idf.py add-dependency``` command. |
| 13 | +2. In the main file of the example, add the following line: |
| 14 | + ```c |
| 15 | + #include "console_mqtt.h" |
| 16 | + ``` |
| 17 | +3. Ensure esp-netif is initialized and default event loop is created in your app_main(): |
| 18 | + ```c |
| 19 | + ESP_ERROR_CHECK(esp_netif_init()); |
| 20 | + ESP_ERROR_CHECK(esp_event_loop_create_default()); |
| 21 | + ``` |
| 22 | +4. In your app_main() function, add the following line as the last line: |
| 23 | + ```c |
| 24 | + ESP_ERROR_CHECK(console_cmd_init()); // Initialize console |
| 25 | + |
| 26 | + // Register all plugin command added to your project |
| 27 | + ESP_ERROR_CHECK(console_cmd_all_register()); |
| 28 | + |
| 29 | + // To register only mqtt command skip calling console_cmd_all_register() |
| 30 | + ESP_ERROR_CHECK(console_cmd_mqtt_register()); |
| 31 | + |
| 32 | + ESP_ERROR_CHECK(console_cmd_start()); // Start console |
| 33 | + ``` |
| 34 | + |
| 35 | +Note: Auto-registration of a specific plugin command can be disabled from menuconfig. |
| 36 | + |
| 37 | +### Certificate Integration for Mutual Authentication |
| 38 | +To enhance security and enable secure communication over MQTT, three functions have been added to the API, allowing users to set client certificates, client keys, and broker certificates separately. |
| 39 | + |
| 40 | +Setting the client certificate: |
| 41 | +```c |
| 42 | +set_mqtt_client_cert(client_cert_pem_start, client_cert_pem_end); |
| 43 | +``` |
| 44 | +Setting the client key: |
| 45 | +```c |
| 46 | +set_mqtt_client_key(client_key_pem_start, client_key_pem_end); |
| 47 | +``` |
| 48 | +Setting the broker certificate: |
| 49 | +```c |
| 50 | +set_mqtt_broker_certs(broker_cert_pem_start, broker_cert_pem_end); |
| 51 | +``` |
| 52 | +Each function takes pointers to the start and end of the respective PEM-encoded data, allowing users to specify the necessary certificate and key information independently. For a complete secure MQTT setup, users should call all three functions in their application code. |
| 53 | +
|
| 54 | +To utilize these certificates, users need to include additional arguments when establishing MQTT connections using the library. Specifically, users should provide the `--cert`, `--key`, and `--cafile` options along with the MQTT connection command. |
| 55 | +
|
| 56 | +### Adding a plugin command or component: |
| 57 | +To add a plugin command or any component from IDF component manager into your project, simply include an entry within the `idf_component.yml` file. |
| 58 | +
|
| 59 | +For more details refer [IDF Component Manager](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/tools/idf-component-manager.html) |
| 60 | +
|
| 61 | +## Suported command: |
| 62 | +
|
| 63 | +### mqtt: |
| 64 | +``` |
| 65 | +mqtt [-CsD] [-h <host>] [-u <username>] [-P <password>] [--cert] [--key] [--cafile] |
| 66 | + mqtt command |
| 67 | + -C, --connect Connect to a broker (flag, no argument) |
| 68 | + -h, --host=<host> Specify the host uri to connect to |
| 69 | + -s, --status Displays the status of the mqtt client (flag, no argument) |
| 70 | + -u, --username=<username> Provide a username to be used for authenticating with the broker |
| 71 | + -P, --password=<password> Provide a password to be used for authenticating with the broker |
| 72 | + --cert Define the PEM encoded certificate for this client, if required by the broker (flag, no argument) |
| 73 | + --key Define the PEM encoded private key for this client, if required by the broker (flag, no argument) |
| 74 | + --cafile Define the PEM encoded CA certificates that are trusted (flag, no argument) |
| 75 | + --use-internal-bundle Use the internal certificate bundle for TLS (flag, no argument) |
| 76 | + -D, --disconnect Disconnect from the broker (flag, no argument) |
| 77 | + |
| 78 | +mqtt_pub [-t <topic>] [-m <message>] |
| 79 | + mqtt publish command |
| 80 | + -t, --topic=<topic> Topic to Subscribe/Publish |
| 81 | + -m, --message=<message> Message to Publish |
| 82 | + |
| 83 | +mqtt_sub [-U] [-t <topic>] |
| 84 | + mqtt subscribe command |
| 85 | + -t, --topic=<topic> Topic to Subscribe/Publish |
| 86 | + -U, --unsubscribe Unsubscribe from a topic |
| 87 | +``` |
0 commit comments