resources/I-CUBE-Mongoose/README.md
This pack provides an easy to use CubeMX integration.
This module installs Mongoose Library itself: mogoose.c, mongoose.h and
mongoose_config.h. It is required for any other module to work. Below are
the steps to make it work with you CubeMX application:
In CubeMX, configure USART (for debug), RNG (for TLS), ETH.
Open Core/Src/main.c and add this snippet:
/* USER CODE BEGIN 0 */
int _write(int fd, unsigned char *buf, int len) {
HAL_UART_Transmit(&huart3, buf, len, HAL_MAX_DELAY);
return len;
}
/* USER CODE END 0 */
Open Core/Src/main.c. Add at the top of the file:
/* USER CODE BEGIN Includes */
#include "mongoose.h"
/* USER CODE END Includes */
Inside main() function:
Inside the `main()` function:
```c
/* USER CODE BEGIN WHILE */
struct mg_mgr mgr;
mg_mgr_init(&mgr);
while (1)
{
mg_mgr_poll(&mgr, 1);
/* USER CODE END WHILE */
This starts the TCP/IP stack. In the serial console logs, you should see something like this:
0 2 mongoose.c:26153:mg_phy_init PHY ID: 0x07 0xc131 (LAN87x)
6 2 mongoose.c:5834:mg_mgr_init Driver: stm32h, MAC: 2a:37:94:03:d5:74
d 3 mongoose.c:5841:mg_mgr_init MG_IO_SIZE: 512, TLS: builtin
13 3 mongoose.c:5758:mg_listen 1 0 http://0.0.0.0:80
19 1 mongoose.c:6260:onstatechange Link down
7d6 3 mongoose.c:28424:mg_tcpip_driv Link is 100M full-duplex
7db 3 mongoose.c:6404:tx_dhcp_discov DHCP discover sent. Our MAC: 2a:37:94:03:d5:74
831 3 mongoose.c:6382:tx_dhcp_reques DHCP req sent
836 2 mongoose.c:6559:rx_dhcp_client Lease: 3600 sec (3602)
83c 2 mongoose.c:6249:onstatechange READY, IP: 192.168.2.31
842 2 mongoose.c:6250:onstatechange GW: 192.168.2.1
847 2 mongoose.c:6253:onstatechange MAC: 2a:37:94:03:d5:74
Now, you should be able to ping your device. However, it runs no network services.
Let's add the simplest web server possible. After the mg_mgr_init()
call, add one more line to start the HTTP listener:
mg_mgr_init(&mgr);
mg_http_listen(&mgr, "http://0.0.0.0:80", http_ev_handler, NULL);
And after the _write() override, add this HTTP event handler function:
static void http_ev_handler(struct mg_connection *c, int ev, void *ev_data) {
if (ev == MG_EV_HTTP_MSG) {
mg_http_reply(c, 200, "", "Hi from Mongoose! Tick %lu\r\n", HAL_GetTick());
}
}
Rebuild, reflash your board, open the device's IP address in the browser, and see the message displayed, something like:
Hi from Mongoose! Tick 38187
Remove the hello world server if you added it.
Create Mongoose directory in the project root and copy
the following files there:
html2c.js is a node.js script that generates file_data.c using this command:
node html2c.js dashboard.html -o file_data.c. This script first inlines all
external resources into an amalgamated HTML file - so it does not depend on
anything external, and then zips it and packs into a Mongoose embedded
filesystem. This way it takes the minimum space on flash.
In top-level CMakeLists.txt, add two extra source files to the build,
and add the rule to generate file_data.c from dashboard.html.
Note that requires Nodejs installed:
# Generate file_data.c from dashboard.html
add_custom_command(
OUTPUT ${CMAKE_SOURCE_DIR}/Mongoose/file_data.c
COMMAND node ${CMAKE_SOURCE_DIR}/Mongoose/html2c.js ${CMAKE_SOURCE_DIR}/Mongoose/dashboard.html -o ${CMAKE_SOURCE_DIR}/Mongoose/file_data.c
DEPENDS ${CMAKE_SOURCE_DIR}/Mongoose/dashboard.html
VERBATIM
)
# Add sources to executable
target_sources(${CMAKE_PROJECT_NAME} PRIVATE
# Add user sources here
Mongoose/dashboard.c
Mongoose/file_data.c
)
Modify your while loop to look like this:
/* USER CODE BEGIN WHILE */
struct mg_mgr mgr;
mg_mgr_init(&mgr);
mg_dash_init(&mgr);
while (1)
{
mg_mgr_poll(&mgr, 1);
mg_dash_poll(&mgr);
/* USER CODE END WHILE */
Rebuild and reflash your board, then open the device's IP address in your
browser. Log in using admin as the password. You should see the full
dashboard, including the status panel, device settings, firmware update, and
file manager. You can easily customize it for your product, but we will start
by implementing a simple LED control dashboard to demonstrate the principles.
Copy a minimal LED control dashboard example to your Mongoose/ directory:
Rebuild and reflash
For agentic development, use https://github.com/cesanta/mongoose/tree/master/AGENTS.md Use a prompt like this:
Read and apply https://github.com/cesanta/mongoose/tree/master/AGENTS.md
Copy mqtt.c
to the Mongoose/ directory. Add it to the extra source files in CMakeLists.txt
Add MQTT init and poll to your while loop:
/* USER CODE BEGIN WHILE */
struct mg_mgr mgr;
mg_mgr_init(&mgr);
mg_mqtt_init(&mgr);
while (1)
{
mg_mgr_poll(&mgr, 1);
mg_mqtt_poll(&mgr);
/* USER CODE END WHILE */
Rebuild, reflash your board. This MQTT Client connects to the HiveMQ public MQTT broker. Also it add a JSON-RPC "ota.update" function via MQTT, so you can update your firmware over MQTT, see https://mongoose.ws/mqtt/