Mongoose

https://mongoose.ws/docs
Admin
Mongoose is a production-grade embedded web server and networking library for C and C++ with HTTP,...
Tokens:84,179
Snippets:788
Trust Score:9.1
Update:2 months ago
Show doc for...
Tokens:
Raw
### JSON-RPC get command examples

Source: https://mongoose.ws/docs/api/dash

Demonstrates retrieving all data fields or a specific field from the device.

```json
// Request and response
{"id": 1, "method": "get"}
{"id": 1, "result": {"led1": true, "led2": false, "volume": 17}}
```

```json
// Request and response
{"id": 1, "method": "get", "params": "volume"}
{"id": 1, "result": {"volume": 17}}
```

--------------------------------

### Build and Run Mongoose Dashboard with Watch

Source: https://mongoose.ws/docs/guides/web-dashboard-guide

Navigates to the minimal device dashboard example and runs 'make watch' to build, run, and monitor for changes. Starts a server on port 8000.

```bash
cd tutorials/device-dashboard/minimal
make watch

```

--------------------------------

### Mongoose HTTP Handler Setup Examples

Source: https://mongoose.ws/docs/guides/web-ui-builder

Illustrates how to set up different types of REST API endpoint handlers in Mongoose.

```c
mongoose_set_http_handlers("data", my_get_XXX, my_set_XXX);
mongoose_set_http_handlers("array", my_get_XXX, my_set_XXX);
mongoose_set_http_handlers("action", my_check_XXX, my_start_XXX);
mongoose_set_http_handlers("file", my_read_XXX, my_write_XXX);
mongoose_set_http_handlers("ota", my_open_XXX, my_close_XXX, my_write_XXX);


```

--------------------------------

### Install Development Tools on macOS

Source: https://mongoose.ws/docs/guides/web-dashboard-guide

Installs Homebrew, then installs gcc, make, git, and node using Homebrew.

```bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
brew install gcc make git node

```

--------------------------------

### Mongoose String Formatting Usage Examples

Source: https://mongoose.ws/docs/api/string

Examples demonstrating standard formatting and the use of custom %m and %M print extensions.

```c
mg_snprintf(buf, sizeof(buf), "%lld", (int64_t) 123);                  // 123                  (64-bit integer)
mg_snprintf(buf, sizeof(buf), "%.2s", "abcdef");                       // ab                   (part of a string)
mg_snprintf(buf, sizeof(buf), "%.*s", 2, "abcdef");                    // ab                   (part of a string)
mg_snprintf(buf, sizeof(buf), "%05x", 123);                            // 00123                (padded integer)
mg_snprintf(buf, sizeof(buf), "%%-%3s", "a");                          // %-  a                (padded string)
mg_snprintf(buf, sizeof(buf), "hi, %m", mg_print_base64, 1, "a");      // hi, "YWJj"           (base64-encode)
mg_snprintf(buf, sizeof(buf), "[%m]", mg_print_esc, 0, "two\nlines");  // ["two\nlines"]       (JSON-escaped string)
mg_snprintf(buf, sizeof(buf), "{%m:%g}", mg_print_esc, 0, "val", 1.2); // {"val": 1.2}         (JSON object)
mg_snprintf(buf, sizeof(buf), "hi, %M", mg_print_hex, 3, "abc");       // hi, 616263           (hex-encode)
mg_snprintf(buf, sizeof(buf), "IP: %M", mg_print_ip, &c->rem);         // IP: 1.2.3.4          (struct mg_addr)
mg_snprintf(buf, sizeof(buf), "Peer: %M", mg_print_ip_port, &c->rem);  // Peer: 1.2.3.4:21345  (struct mg_addr with port)
mg_snprintf(buf, sizeof(buf), "%M", mg_print_ip4, "abcd");             // 97.98.99.100         (IPv4 address)
mg_snprintf(buf, sizeof(buf), "%M", mg_print_ip6, "abcdefghijklmnop"); // [4142:4344:4546:4748:494a:4b4c:4d4e:4f50]
mg_snprintf(buf, sizeof(buf), "%M", mg_print_mac, "abcdef");           // 61:62:63:64:65:66    (MAC address)
mg_printf(c, "<title>Index of %M</title>", mg_print_html_esc, (int) uri.len, uri.buf);
```

--------------------------------

### MQTT Connection Event Handler Example

Source: https://mongoose.ws/docs/api/mqtt

Example event handler function demonstrating how to process MG_EV_CONNECT and MG_EV_MQTT_OPEN events for MQTT connections.

```c
void fn(struct mg_connection *c, int ev, void *ev_data, void *fnd) {
  if (ev == MG_EV_CONNECT) {
    // TCP connection succeeded,
    // If target URL is TLS, set it up
  } else if (ev == MG_EV_MQTT_OPEN) {
    // MQTT connection process finished
    struct mg_mqtt_message *mm = (struct mg_mqtt_message *) ev_data;
    if(mm->ack)  // MQTT connection succeeded
  }
}

```

--------------------------------

### Start Modbus-TCP Listener

Source: https://mongoose.ws/docs/api/util

Example of how to start a Modbus-TCP listener on a specific URL using the `mg_modbus_listen` function and a custom event handler.

```c
mg_modbus_listen(&g_mgr, "tcp://0.0.0.0:502", modbus_ev_handler, NULL);
```

--------------------------------

### mg_ota_begin()

Source: https://mongoose.ws/docs/api/ota

Starts a firmware update session. This function should be called before writing any firmware data.

```APIDOC
## mg_ota_begin()

Start a firmware update session.

### Function Signature
```c
bool mg_ota_begin(size_t new_firmware_size);
```

### Parameters
* `new_firmware_size` (size_t) - Expected size of the new firmware image.

### Return Value
* `true` on success, `false` on failure.

### Usage Example
```c
if (mg_ota_begin(firmware_size)) {
  // Ready to write firmware
} else {
  // OTA begin failed
}
```
```

--------------------------------

### TLS initialization usage examples

Source: https://mongoose.ws/docs/api/tls

Demonstrates initializing TLS within event handlers for both client and server connections.

```c
// client event handler:
  if (ev == MG_EV_CONNECT) {
    struct mg_tls_opts opts = {.ca = mg_str(s_tls_ca)};
    mg_tls_init(c, &opts);

// server event handler:
  if (ev == MG_EV_ACCEPT) {
    struct mg_tls_opts opts = {.cert = mg_str(s_tls_cert),
                               .key = mg_str(s_tls_key)};
    mg_tls_init(c, &opts);
```

--------------------------------

### Mongoose Logging Example

Source: https://mongoose.ws/docs/api/logging

Example of how to use the MG_INFO macro to log a formatted string message.

```c
MG_INFO(("Hello %s!", "world"));  // Output "Hello, world"
```

--------------------------------

### Install Build Tools on Linux (Ubuntu)

Source: https://mongoose.ws/docs/getting-started/build-environment

Installs essential build tools including GCC and ARM GCC for Ubuntu Linux.

```bash
sudo apt -y update
sudo apt -y install build-essential make gcc-arm-none-eabi git

```

--------------------------------

### Example: Custom REST API Handler

Source: https://mongoose.ws/docs/guides/web-ui-builder

Shows how to create a custom API handler that responds to HTTP requests. This example logs POST data, URI, and query parameters, then replies with 'ok'.

```c
#include "mongoose/mongoose_glue.h"

// curl -qs IP/my/api
// curl -qs IP/my/api/1/2/3?foo=bar -d '{"a":42}'
static void my_ev_handler(struct mg_connection *c, int ev, void *ev_data) {
  if (ev == MG_EV_HTTP_MSG) {
    struct mg_http_message *hm = (struct mg_http_message *) ev_data;
    MG_INFO(("POST data: [%.*s], URI: [%.*s], QUERY: [%.*s]",  //
             hm->body.len, hm->body.buf,                       //
             hm->uri.len, hm->uri.buf,                         //
             hm->query.len, hm->query.buf));
    mg_http_reply(c, 200, "", "ok\n");
  }
}

int main(void) {
  mongoose_init();
  mongoose_add_custom_handler("/my/api#", my_ev_handler);

  for (;;) {
    mongoose_poll();
  }

  return 0;
}

```

--------------------------------

### Install Development Tools on Linux/WSL

Source: https://mongoose.ws/docs/guides/web-dashboard-guide

Installs essential development tools like git, make, gcc, and nodejs using apt package manager.

```bash
sudo apt -y update
sudo apt -y install build-essential make git nodejs

```

--------------------------------

### Build and flash Mongoose examples

Source: https://mongoose.ws/docs/guides/rp-tcpip-stack

Commands to build and flash firmware for specific Raspberry Pi Pico hardware targets.

```bash
cd ~/src/mongoose/tutorials/rp/w5500-evb-pico2
make build flash
```

```bash
cd ~/src/mongoose/tutorials/rp/pico2-w
make build flash
```

--------------------------------

### Install Build Tools on macOS

Source: https://mongoose.ws/docs/getting-started/build-environment

Installs Git, GCC, Make, and ARM GCC using Homebrew on macOS.

```bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
brew install gcc make git gcc-arm-embedded

```

--------------------------------

### Initialize MQTT Listener

Source: https://mongoose.ws/docs/api/mqtt

Example of initializing an MQTT listener on all interfaces and port 1883, with error checking.

```c
struct mg_connection *c = mg_mqtt_listen(&mgr, "mqtt://0.0.0.0:1883", fn, arg);
if (c == NULL) return -1; // Could not create connection

```

--------------------------------

### Example: Wrapping MQTT Login Message with mg_ws_wrap

Source: https://mongoose.ws/docs/api/websocket

This example demonstrates how to use `mg_ws_wrap` to wrap an MQTT login message into WebSocket format. It first stores the current output buffer length, writes the MQTT login message, and then wraps the written data.

```c
size_t len = c->send.len;         // Store output buffer len
mg_mqtt_login(c, s_url, &opts);   // Write MQTT login message
mg_ws_wrap(c, c->send.len - len, WEBSOCKET_OP_BINARY); // Wrap it into WS

```

--------------------------------

### HTTP OTA Update Handler Example

Source: https://mongoose.ws/docs/api/http

Example of how to use `mg_http_start_ota` within an event handler. This snippet demonstrates handling `MG_EV_HTTP_HDRS` to initiate the OTA process when an OTA request is received.

```c
static void ota_done(struct mg_connection *c, const char *errmsg) {
  mg_http_reply(c, errmsg == NULL ? 200 : 500, "", "%s\n",
                errmsg == NULL ? "ok" : errmsg);
  c->is_draining = 1;
}

static void fn(struct mg_connection *c, int ev, void *ev_data) {
  if (ev == MG_EV_HTTP_HDRS) {
    struct mg_http_message *hm = (struct mg_http_message *) ev_data;
    if (mg_match(hm->uri, mg_str("/ota"), NULL)) {
      mg_http_start_ota(c, hm, ota_done);
    }
  }
}

```

--------------------------------

### Compile and Run HTTP Server

Source: https://mongoose.ws/docs/getting-started/first-web-server

These commands show how to compile the C source code using GCC and then run the resulting executable to start the HTTP server.

```bash
cc main.c mongoose.c -I. -o http_server
./http_server

```

--------------------------------

### Send RPC OK Response Usage Example

Source: https://mongoose.ws/docs/api/json-rpc

Example of using mg_rpc_ok() within an RPC handler to send a successful response with the calculated sum.

```c
static void rpc_sum(struct mg_rpc_req *r) {
  double a = 0.0, b = 0.0;
  mg_json_get_num(r->frame, "$.params[0]", &a);
  mg_json_get_num(r->frame, "$.params[1]", &b);
  mg_rpc_ok(r, "%g", a + b);
}

```

--------------------------------

### Hardware-Specific GPIO Read Example

Source: https://mongoose.ws/docs/guides/web-dashboard-guide

Example C snippet for reading a GPIO pin state (GPIOB, GPIO_PIN_0) and assigning it to 's_led1', specific to MG_ARCH_CUBE.

```c
#if MG_ARCH == MG_ARCH_CUBE
  s_led1 = HAL_GPIO_ReadPin(GPIOB, GPIO_PIN_0);  // Read LED state into field
#endif


```

--------------------------------

### Usage Example for mg_rpc_err()

Source: https://mongoose.ws/docs/api/json-rpc

Example demonstrating how to use mg_rpc_err to send an error response, formatting a string with dynamic content.

```c
static void rpc_dosome(struct mg_rpc_req *r) {
  ...
  mg_rpc_err(r, -32109, "\"%.*s not found\"", len, &r->frame.buf[offset]);
}

```

--------------------------------

### Minimal Mongoose Server

Source: https://mongoose.ws/docs/getting-started/programming-model

A complete example of a minimal Mongoose server. It initializes the event manager, sets up an HTTP listener, and runs the event loop.

```c
#include "mongoose.h"

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, "", "hello\n");
  }
}

int main(void) {
  struct mg_mgr mgr;
  mg_mgr_init(&mgr);
  
  mg_http_listen(&mgr, "http://0.0.0.0:8000", http_ev_handler, NULL);
  
  for (;;) {
    mg_mgr_poll(&mgr, 1000);
  }
  return 0;
}
```

--------------------------------

### Usage Example for mg_iobuf_del()

Source: https://mongoose.ws/docs/api/core/content.html

Demonstrates how to initialize an iobuf, add data to it, and then delete a portion of that data using `mg_iobuf_del()`.

```c
struct mg_iobuf io;
mg_iobuf_init(&io, 0, 16);          // Empty buffer, 16-bytes aligned
mg_iobuf_add(&io, 0, "hello", 5);   // io->len is 5, io->size is 16
mg_iobuf_del(&io, 1, 3);            // io->len is 2, io->size is still 16

```

--------------------------------

### Expected serial console output

Source: https://mongoose.ws/docs/guides/rp-tcpip-stack

Example log output showing successful Mongoose initialization and DHCP lease acquisition.

```text
mongoose.c:...:mg_mgr_init       Mongoose version ...
mongoose.c:...:MG_TCPIP_DRIVER   Driver: W5500, MAC: 02:...
mongoose.c:...:tx_dhcp_discover DHCP discover sent
mongoose.c:...:rx_dhcp_client   Lease: 86400 sec
mongoose.c:...:onstatechange    READY, IP: 192.168.1.42
```

--------------------------------

### Add RPC Method Usage Example

Source: https://mongoose.ws/docs/api/json-rpc

Demonstrates how to add RPC methods like 'sum' and 'mul' to a linked list using mg_rpc_add().

```c
struct mg_rpc *s_rpc_head = NULL;

static void rpc_sum(struct mg_rpc_req *r) {
  double a = 0.0, b = 0.0;
  mg_json_get_num(r->frame, "$.params[0]", &a);
  mg_json_get_num(r->frame, "$.params[1]", &b);
  mg_rpc_ok(r, "%g", a + b);
}

static void rpc_mul(struct mg_rpc_req *r) {//...}


  mg_rpc_add(&s_rpc_head, mg_str("sum"), rpc_sum, NULL);
  mg_rpc_add(&s_rpc_head, mg_str("mul"), rpc_mul, NULL);

```

--------------------------------

### Client WebSocket Connection

Source: https://mongoose.ws/docs/api/websocket

Shows how to initiate a client-side WebSocket connection using `mg_ws_connect()`. This function allocates resources and starts the connection process.

```c
struct mg_connection *mg_ws_connect(struct mg_mgr *mgr, const char *url,
                                    mg_event_handler_t fn, void *fn_data,
                                    const char *fmt, ...);

```

```c
struct mg_connection *c = mg_ws_connect(&mgr, "ws://test_ws_server.com:1000",
                                        handler, NULL, "%s", "Sec-WebSocket-Protocol: echo\r\n");
if(c == NULL) fatal("Cannot create connection");

```

--------------------------------

### JSON-RPC set command example

Source: https://mongoose.ws/docs/api/dash

Updates device fields with specified values and returns a boolean success status.

```json
// Request and response
{"id": 1, "method": "set", "params": {"led1": true, "volume":0}}
{"id": 1, "result": true}
```

--------------------------------

### Example: Real-time Data Update

Source: https://mongoose.ws/docs/guides/web-ui-builder

Demonstrates how to send real-time data from a device to the UI. It initializes Mongoose, sets up a getter function for real-time data, and registers a WebSocket reporter.

```c
#include "mongoose_glue.h"

static void my_getter(struct real_time_data *data) {
  data->value1 = read_adc();
}

int main(void) {

  mongoose_init();

  mongoose_set_http_handlers("real_time_data", my_getter, NULL);
  mongoose_add_ws_reporter(200, "real_time_data");

  for (;;) {
    mongoose_poll();
  }
}

```

--------------------------------

### Mongoose Protocol Handler Setup Functions

Source: https://mongoose.ws/docs/guides/web-ui-builder

Provides reference for setting up handlers for MQTT, Modbus, SNTP, Authentication, and Modbus requests in Mongoose.

```c
struct mongoose_mqtt_handlers {
  struct mg_connection *(*connect_fn)(mg_event_handler_t);
  void (*tls_init_fn)(struct mg_connection *);
  void (*on_connect_fn)(struct mg_connection *, int);
  void (*on_message_fn)(struct mg_connection *, struct mg_str, struct mg_str);
  void (*on_cmd_fn)(struct mg_connection *, struct mg_mqtt_message *);
};
void mongoose_set_mqtt_handlers(struct mongoose_mqtt_handlers *);

struct mongoose_modbus_handlers {
  bool (*read_reg_fn)(uint16_t address, uint16_t *value);
  bool (*write_reg_fn)(uint16_t address, uint16_t value);
};
void mongoose_set_modbus_handlers(struct mongoose_modbus_handlers *);

void mongoose_set_sntp_handler(void (*fn)(uint64_t epoch_ms));

void mongoose_set_auth_handler(int (*fn)(const char *user, const char *pass));

void mongoose_set_modbus_handler(void (*fn)(struct mg_modbus_req *req));


```

--------------------------------

### JSON API Response Example

Source: https://mongoose.ws/docs/getting-started/first-web-server

This is the expected JSON output from the /api/hello endpoint when accessed via a web browser or client.

```json
{"status":1}

```

--------------------------------

### DHCP Discover Log Output

Source: https://mongoose.ws/docs/guides/stm32-tcpip-stack

Example log output indicating the device is attempting to discover a DHCP server.

```text
130b0  3 mongoose.c:4776:tx_dhcp_discov DHCP discover sent. Our MAC: 02:03:04:05:06:07
13498  3 mongoose.c:4776:tx_dhcp_discov DHCP discover sent. Our MAC: 02:03:04:05:06:07
```

--------------------------------

### Register mg_rpc_list() Method

Source: https://mongoose.ws/docs/api/json-rpc

Example showing how to register the built-in mg_rpc_list function as an RPC method named 'rpc.list'.

```c
mg_rpc_add(&s_rpc_head, mg_str("rpc.list"), mg_rpc_list, &s_rpc_head);

```

--------------------------------

### Implementing a Custom Print Function

Source: https://mongoose.ws/docs/api/string

Example showing how to define a custom print function to format a structure as a JSON string.

```c
struct a { int a, b; };

size_t print_a(void (*out)(char, void *), void *ptr, va_list *ap) {
  struct a *p = va_arg(*ap, struct a *);
  return mg_xprintf(out, ptr, "{%m:%d}", MG_ESC("a"), p->a); // MG_ESC invokes mg_print_esc
}

struct a temp = { 42, 43 };
mg_snprintf(buf, sizeof(buf), "%M", print_a, &temp);    // {"a":42}
```

--------------------------------

### Custom MIME Type Configuration

Source: https://mongoose.ws/docs/api/http

Example of configuring custom MIME types, including a wildcard for default types and specific overrides.

```c
sopts.mime_types = "*=preferred/default,txt=override/text"
```

--------------------------------

### Start OTA Firmware Update

Source: https://mongoose.ws/docs/api/ota

Initiates an OTA firmware update session. Call this before writing any firmware data. It requires the expected size of the new firmware image.

```c
bool mg_ota_begin(size_t new_firmware_size);
```

```c
if (mg_ota_begin(firmware_size)) {
  // Ready to write firmware
} else {
  // OTA begin failed
}
```

--------------------------------

### mg_connect()

Source: https://mongoose.ws/docs/api/core

Initiates an outbound connection to a specified URL. It appends the connection to the event manager and starts the connection process asynchronously.

```APIDOC
## mg_connect()

### Description
Creates an outbound connection and appends it to the event manager's connection list. This function initiates the process of connecting to a remote peer. A notification event (`MG_EV_CONNECT`) is sent when the connection is established.

### Parameters
* `mgr` (struct mg_mgr *) - An event manager to use.
* `url` (const char *) - A URL specifying the remote IP address and port to connect to (e.g., `http://a.com`). If the URL is a known TLS URL, the `is_tls` flag will be set. If name resolution is required, it will start asynchronously.
* `fn` (mg_event_handler_t) - An event handler function to be called for events related to this connection.
* `fn_data` (void *) - An arbitrary pointer that will be stored in the connection structure as `c->fn_data`, accessible by the event handler.

### Return Value
Returns a pointer to the created connection, or `NULL` on error. Possible errors include insufficient memory, a NULL URL, or network issues if using the built-in TCP/IP stack.

### Notes
* This function allocates resources and starts the connection process; it does not guarantee an immediate connection.
* mDNS resolution for '.local' domain addresses requires an mDNS listener to be started separately using `mg_mdns_listen()`.

### Usage Example
```c
struct mg_connection *c = mg_connect(&mgr, "http://example.org", fn, NULL);
```
```

--------------------------------

### Example mongoose_config.h for STM32

Source: https://mongoose.ws/docs/getting-started/build-options

This configuration is for an STM32 firmware project using the Cube framework. It sets the build environment, IO buffer size, TLS support, TCP/IP stack, and specific STM32H5 drivers.

```c
#define MG_ARCH MG_ARCH_CUBE         // Build environment is Cube
#define MG_IO_SIZE 1024              // IO buffer growth granularity is 1Kb
#define MG_TLS MG_TLS_BUILTIN        // Use built-in TLS 1.3 stack
#define MG_ENABLE_TCPIP 1            // Use built-in TCP/IP stack
#define MG_ENABLE_DRIVER_STM32H5 1   // With STM32H5 ethernet driver
#define MG_OTA MG_OTA_STM32H5        // Use built-in OTA for STM32H5

```

--------------------------------

### Pushing Firmware Image via HTTP

Source: https://mongoose.ws/docs/guides/firmware-ota-updates

Command-line example to push a signed firmware image to the device using curl. Ensure the firmware file is correctly signed before uploading.

```bash
curl http://DEVICE_IP/api/ota/update --data-binary @firmware.signed.bin

```

--------------------------------

### Create MQTT Client Connection

Source: https://mongoose.ws/docs/api/mqtt

Initiates an MQTT client connection to a broker. This function allocates resources and starts the TCP connection process, followed by the MQTT connection.

```c
struct mg_connection *mg_mqtt_connect(struct mg_mgr *mgr, const char *url,
                                      const struct mg_mqtt_opts *opts,
                                      mg_event_handler_t fn, void *fn_data);

```

--------------------------------

### Serving Directory with Custom Root and Aliases

Source: https://mongoose.ws/docs/api/http

Example Mongoose event handler demonstrating how to use mg_http_serve_dir with custom root directory and URI-to-path mappings.

```c
// Mongoose events handler
void fn(struct mg_connection *c, int ev, void *ev_data) {
  if (ev == MG_EV_HTTP_MSG) {
    struct mg_http_message *hm = (struct mg_http_message *) ev_data;
    struct mg_http_serve_opts opts;
    memset(&opts, 0, sizeof(opts));
    opts.root_dir = "/var/www,/conf=/etc";  // Serve /var/www. URIs starting with /conf are served from /etc
    mg_http_serve_dir(c, hm, &opts);
  }
}
```

--------------------------------

### mg_wifi_ap_start

Source: https://mongoose.ws/docs/api/wifi

Starts the device as a Wi-Fi Access Point (AP) mode. The configuration for the AP, such as SSID and password, is provided via a `mg_wifi_data` structure.

```APIDOC
## mg_wifi_ap_start()

### Description
Start being an Access Point (AP mode), as defined by the argument.

### Method
`bool mg_wifi_ap_start(struct mg_wifi_data *wifi);
`

### Parameters
* **wifi** (`struct mg_wifi_data *`) - Required - Pointer to a structure containing AP configuration details, including SSID, password, IP address, and security settings.
```

--------------------------------

### API Access Control Example

Source: https://mongoose.ws/docs/guides/web-ui-builder

Demonstrates how to use cURL to interact with an API endpoint, showing different access levels for reading and writing data. 'admin' has full access, while 'user' can only read.

```bash
$ curl -u admin:admin DEVICE_IP/api/leds
{"led1": false, "led2": false}
```

```bash
$ curl -u admin:admin DEVICE_IP/api/leds -d '{"led2": true}'
{"led1": false, "led2": true}
```

```bash
$ curl -u user:user DEVICE_IP/api/leds -d '{"led2": true}'
Forbidden
```

--------------------------------

### Start Access Point Mode

Source: https://mongoose.ws/docs/api/wifi

Initiates the device to act as a WiFi Access Point (AP mode). Configuration details for the AP should be provided in the 'struct mg_wifi_data' argument.

```c
bool mg_wifi_ap_start(struct mg_wifi_data *wifi);
```

--------------------------------

### Configure Wi-Fi credentials in main.c

Source: https://mongoose.ws/docs/guides/rp-tcpip-stack

Define Wi-Fi credentials and implement the wifi_setconfig function to initialize network settings.

```c
#define WIFI_NAME "mywifi"
#define WIFI_PASS "mypassword"
#define WIFI_AP_NAME "mywifi2"
#define WIFI_AP_PASS "mypassword2"
#define ENABLE_AP 0

#include "mongoose.h"

void wifi_setconfig(void *data) {
  struct mg_tcpip_driver_pico_w_data *d =
      (struct mg_tcpip_driver_pico_w_data *) data;
  struct mg_wifi_data *wifi = &d->wifi;
  wifi->ssid = WIFI_NAME;
  wifi->pass = WIFI_PASS;
  wifi->apssid = WIFI_AP_NAME;
  wifi->appass = WIFI_AP_PASS;
  wifi->apip = MG_IPV4(192, 168, 111, 1);
  wifi->apmask = MG_IPV4(255, 255, 255, 0);
  wifi->security = 0;
  wifi->apsecurity = 0;
  wifi->apchannel = 10;
  wifi->apmode = ENABLE_AP;
}
```

--------------------------------

### Create an Outbound Connection with mg_connect

Source: https://mongoose.ws/docs/api/core/content.html

Use mg_connect to initiate an outbound connection to a specified URL. This function allocates resources and starts the connection process, with the actual connection event handled asynchronously.

```c
struct mg_connection *mg_connect(struct mg_mgr *mgr, const char *url,
                                 mg_event_handler_t fn, void *fn_data);

```

```c
struct mg_connection *c = mg_connect(&mgr, "http://example.org", fn, NULL);

```

--------------------------------

### mg_mqtt_connect()

Source: https://mongoose.ws/docs/api/mqtt

Creates a client MQTT connection to a broker. It allocates resources and initiates the TCP connection process. After a successful TCP connection, an MG_EV_CONNECT event is sent, followed by the MQTT connection process. Upon a successful MQTT connection response, an MG_EV_MQTT_OPEN event is sent.

```APIDOC
## mg_mqtt_connect()

### Description
Creates a client MQTT connection to a broker. It allocates resources and initiates the TCP connection process. After a successful TCP connection, an MG_EV_CONNECT event is sent, followed by the MQTT connection process. Upon a successful MQTT connection response, an MG_EV_MQTT_OPEN event is sent.

### Method
`struct mg_connection *mg_mqtt_connect(struct mg_mgr *mgr, const char *url, const struct mg_mqtt_opts *opts, mg_event_handler_t fn, void *fn_data);`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
* `mgr` - Event manager to use.
* `url` - Specifies the broker URL, e.g. `mqtt://cloud.hivemq.com`. If this URL is 'mqtts', the `is_tls` flag will be set. See mg_connect().
* `opts` - Pointer to MQTT options like client ID, clean session, last will, etc. Can be NULL.
* `fn` - The event handler function.
* `fn_data` - An arbitrary pointer, which will be stored in the connection structure as `c->fn_data`, so the event handler can use it when called.

### Return Value
Created connection, or `NULL` on error. Possible errors are: not enough memory, a NULL URL, or, in the case of our built-in TCP/IP stack, the network not being ready.

### Note
This function does not connect to a broker; it allocates the required resources and starts the TCP connection process. Once that connection is established, an `MG_EV_CONNECT` event is sent to the connection event handler, then the MQTT connection process is started (by means of mg_mqtt_login()); and once the MQTT connection request gets a response from the broker, an `MG_EV_MQTT_OPEN` event is sent to the connection event handler; connection results are inside a struct mg_mqtt_message.

### Usage Example
```c
void fn(struct mg_connection *c, int ev, void *ev_data, void *fnd) {
  if (ev == MG_EV_CONNECT) {
    // TCP connection succeeded,
    // If target URL is TLS, set it up
  } else if (ev == MG_EV_MQTT_OPEN) {
    // MQTT connection process finished
    struct mg_mqtt_message *mm = (struct mg_mqtt_message *) ev_data;
    if(mm->ack)  // MQTT connection succeeded
  }
}

```

```c
mg_mqtt_connect(&mgr, "mqtt://test.org:1883", NULL, fn, NULL);

```

or

```c
struct mg_mqtt_opts opts = {.qos = 1,
                            .retain = true,
                            .topic = mg_str("mytopic"),
                            .message = mg_str("goodbye")};
mg_mqtt_connect(&mgr, "mqtt://test.org:1883", &opts, fn, NULL);

```
```

--------------------------------

### Modbus Event Handler Example

Source: https://mongoose.ws/docs/api/util

An example event handler function for Modbus requests. It processes `MG_EV_MODBUS_REQ` events, checking the function code and setting coil values or error codes.

```c
static void modbus_ev_handler(struct mg_connection *c, int ev, void *ev_data) {
  if (ev == MG_EV_MODBUS_REQ) {
    struct mg_modbus_req *mr = (struct mg_modbus_req *) ev_data;
    if (mr->func == MG_MODBUS_FUNC_READ_COILS) {
      for (uint16_t i = 0; i < mr->len; i++) {
        mr->u.bits[i] = 1;
      }
    } else {
      mr->error = MG_MODBUS_ERR_DEVICE_FAILURE;
    }
  }
}
```

--------------------------------

### Connect to MQTT Broker (Default Options)

Source: https://mongoose.ws/docs/api/mqtt

Connects to an MQTT broker using default options.

```c
mg_mqtt_connect(&mgr, "mqtt://test.org:1883", NULL, fn, NULL);

```

--------------------------------

### Get Uptime with mg_millis

Source: https://mongoose.ws/docs/api/time

Retrieves the current system uptime in milliseconds.

```c
uint64_t mg_millis(void);
```

```c
uint64_t uptime = mg_millis();
```

--------------------------------

### mg_mqtt_listen()

Source: https://mongoose.ws/docs/api/mqtt

Creates an MQTT listener, allowing the system to act as an MQTT broker. It listens on a specified local IP address and port for incoming MQTT connections.

```APIDOC
## mg_mqtt_listen()

### Description
Creates an MQTT listener (act like a broker). It listens on a specified local IP address and port for incoming MQTT connections.

### Method
`struct mg_connection *mg_mqtt_listen(struct mg_mgr *mgr, const char *url, mg_event_handler_t fn, void *fn_data);
`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
* `mgr` - Event manager to use.
* `url` - Specifies the local IP address and port to listen on, e.g. `mqtt://0.0.0.0:1883`. If this URL is 'mqtts', the `is_tls` flag will be set.
* `fn` - The event handler function.
* `fn_data` - An arbitrary pointer, which will be stored in the connection structure as `c->fn_data`, so the event handler can use it when called.

### Return Value
Pointer to the created connection or `NULL` on error.

### Usage Example
```c
struct mg_connection *c = mg_mqtt_listen(&mgr, "mqtt://0.0.0.0:1883", fn, arg);
if (c == NULL) return -1; // Could not create connection

```
```

--------------------------------

### STM32 Serial Log Output

Source: https://mongoose.ws/docs/guides/stm32-tcpip-stack

Example of expected serial output during device initialization and network connection.

```text
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
```

--------------------------------

### mg_md5_init()

Source: https://mongoose.ws/docs/api/util

Initializes a context for MD5 hashing.

```APIDOC
## mg_md5_init()

### Description
Initialize context for MD5 hashing.

### Parameters
- **c** (*mg_md5_ctx ") - Pointer to `mg_md5_ctx` structure to initialize

### Return value
None

### Usage example
```c
mg_md5_ctx ctx;
mg_md5_init(&ctx);
```
```

--------------------------------

### JSON-RPC change notification example

Source: https://mongoose.ws/docs/api/dash

Broadcasts a value change from the device to all connected clients without requiring a response.

```json
{"method": "change", "params": {"volume":12}}
```

--------------------------------

### mg_mgr_init()

Source: https://mongoose.ws/docs/api/core/content.html

Initializes an event manager structure, setting up default DNS servers and timeouts.

```APIDOC
## mg_mgr_init()

### Description
Initializes event manager structure: sets a list of active connections to NULL, sets default DNS servers for IPv4 and IPv6, and sets default DNS lookup timeout.

### Method
`void mg_mgr_init(struct mg_mgr *mgr)`

### Parameters
* `mgr` - a pointer to `mg_mgr` structure that needs to be initialized

### Return value
none

### Usage example
```c
struct mg_mgr mgr;
mg_mgr_init(&mgr);
```
```

--------------------------------

### Example JSON Update Request

Source: https://mongoose.ws/docs/api/dash

The format of the JSON request sent from the UI to the device to update a specific field.

```json
{"status": {"led1": true}}
```

--------------------------------

### Connect to MQTT Broker (Custom Options)

Source: https://mongoose.ws/docs/api/mqtt

Connects to an MQTT broker with custom options, including QoS, retain flag, topic, and message.

```c
struct mg_mqtt_opts opts = {.qos = 1,
                            .retain = true,
                            .topic = mg_str("mytopic"),
                            .message = mg_str("goodbye")};
mg_mqtt_connect(&mgr, "mqtt://test.org:1883", &opts, fn, NULL);

```

--------------------------------

### mg_modbus_listen

Source: https://mongoose.ws/docs/api/util

Starts a Modbus-TCP listener. When a Modbus-TCP request arrives, Mongoose calls the provided event handler function.

```APIDOC
## mg_modbus_listen

### Description
Starts a Modbus-TCP listener. When a Modbus-TCP request arrives, Mongoose calls the provided event handler function.

### Parameters
* `mgr` - Event manager
* `url` - Listening URL
* `fn` - Event handler function. Should catch `MG_EV_MODBUS_REQ` and process `struct mg_modbus_req *` passed as `ev_data`
* `fn_data` - Arbitrary user data

### Return Value
listening connection or NULL

### Usage Example
```c
static void modbus_ev_handler(struct mg_connection *c, int ev, void *ev_data) {
  if (ev == MG_EV_MODBUS_REQ) {
    struct mg_modbus_req *mr = (struct mg_modbus_req *) ev_data;
    if (mr->func == MG_MODBUS_FUNC_READ_COILS) {
      for (uint16_t i = 0; i < mr->len; i++) {
        mr->u.bits[i] = 1;
      }
    } else {
      mr->error = MG_MODBUS_ERR_DEVICE_FAILURE;
    }
  }
}

/// ...
mg_modbus_listen(&g_mgr, "tcp://0.0.0.0:502", modbus_ev_handler, NULL);
```
```

--------------------------------

### Get HTTP Request Length

Source: https://mongoose.ws/docs/api/http

Calculates the length of the HTTP request headers within a buffer. It does not include the body.

```c
int mg_http_get_request_len(const unsigned char *buf, size_t buf_len);

```

```c
const char *buf = "GET /test \n\nGET /foo\n\n";
int req_len = mg_http_get_request_len(buf, strlen(buf));  // req_len == 12

```

--------------------------------

### Configuration File Structure

Source: https://mongoose.ws/docs/guides/web-ui-builder

The main configuration file defines various sections for API, UI, and protocol support.

```json
{
  "version": "1.0.1",   // format version
  "api":     { ... },   // RESTful API definitions
  "ui":      { ... },   // Web UI controls
  "http":    { ... },   // HTTP protocol support
  "mqtt":    { ... },   // MQTT protocol support
  "dns":     { ... },   // DNS/MDNS protocol support
  "sntp":    { ... },   // SNTP (network time sync) protocol protocol support
  "modbus":  { ... },   // Modbus-TCP protocol support
  "build":   { ... }    // Target hardware, IDE, OS
}

```

--------------------------------

### Initialize Dashboard Library

Source: https://mongoose.ws/docs/api/dash

Include the dashboard.js library and initialize it with debug mode and initial data state.

```html
<script src="https://cdn.jsdelivr.net/gh/cesanta/mongoose@master/resources/dashboard.js"></script>
    <script>
      Dashboard.init({
        debug: true,
        data: { status: { led1: false, version: '1.0.0' } },
      });
    </script>
```

--------------------------------

### REST API 'data' Type Configuration

Source: https://mongoose.ws/docs/guides/web-ui-builder

Example configuration for a 'data' type REST API endpoint named 'settings'.

```json
"settings": {
  "type": "data",
  "attributes": {
    "level": { "type": "int", "value": 42},
    "name": { "type": "string", "value": "unit1", "size": 20}
  }
}

```

--------------------------------

### Implement SPI Support for W5500

Source: https://mongoose.ws/docs/guides/rp-tcpip-stack

Provide the necessary SPI callbacks and initialization function for the W5500 Ethernet driver in main.c.

```c
#include "hardware/spi.h"
#include "pico/stdlib.h"
#include "pico/unique_id.h"
#include "mongoose.h"

enum { SPI_CS = 17, SPI_CLK = 18, SPI_TX = 19, SPI_RX = 16 };

void spi_begin(void *spi) {
  gpio_put(SPI_CS, 0);
}

void spi_end(void *spi) {
  gpio_put(SPI_CS, 1);
}

void spi_txn(void *spi, uint8_t *tx, uint8_t *rx, size_t len) {
  if (tx != NULL && rx != NULL) {
    spi_write_read_blocking(spi0, tx, rx, len);
  } else if (tx != NULL) {
    spi_write_blocking(spi0, tx, len);
  } else {
    spi_read_blocking(spi0, 0xff, rx, len);
  }
}

static void ethernet_init(void) {
  spi_init(spi0, 500 * 1000);
  gpio_set_function(SPI_RX, GPIO_FUNC_SPI);
  gpio_set_function(SPI_TX, GPIO_FUNC_SPI);
  gpio_set_function(SPI_CLK, GPIO_FUNC_SPI);
  gpio_init(SPI_CS);
  gpio_set_dir(SPI_CS, GPIO_OUT);
  gpio_put(SPI_CS, 1);
}
```

--------------------------------

### mg_tls_init()

Source: https://mongoose.ws/docs/api/tls

Initializes TLS on a given connection. This should be called from the user-supplied event handler on MG_EV_ACCEPT for servers or MG_EV_CONNECT for clients, before any application data is sent.

```APIDOC
## void mg_tls_init(struct mg_connection *c, const struct mg_tls_opts *opts)

### Description
Initializes TLS on a given connection. Servers typically set cert and key, while clients typically set ca and name for SNI and hostname verification.

### Parameters
- **c** (struct mg_connection *) - Required - The connection for which TLS should be initialized.
- **opts** (const struct mg_tls_opts *) - Required - The TLS initialization parameters.

### Usage Example
```c
// client event handler:
if (ev == MG_EV_CONNECT) {
  struct mg_tls_opts opts = {.ca = mg_str(s_tls_ca)};
  mg_tls_init(c, &opts);
}

// server event handler:
if (ev == MG_EV_ACCEPT) {
  struct mg_tls_opts opts = {.cert = mg_str(s_tls_cert),
                             .key = mg_str(s_tls_key)};
  mg_tls_init(c, &opts);
}
```
```

--------------------------------

### AI-Driven Dashboard Modification Prompt

Source: https://mongoose.ws/docs/guides/web-dashboard-guide

Example prompt for AI to apply changes from AGENTS.md and modify the dashboard theme to dark.

```bash
Read and apply https://github.com/cesanta/mongoose/blob/master/AGENTS.md
Change dashboard.html, make HTML theme dark

```

--------------------------------

### Custom Modbus API Handler

Source: https://mongoose.ws/docs/guides/web-ui-builder

Example of a custom Modbus handler in C for reading coils. Requires mongoose_init() and mongoose_set_modbus_handler().

```c
// See modbus definitions at https://github.com/cesanta/mongoose/blob/modbus/src/modbus.h
static void my_modbus_handler(struct mg_modbus_req *req) {
  if (req->func == MG_MODBUS_FUNC_READ_COILS) {
    for (uint16_t i = 0; i < req->len; i++) {
      req->u.bits[i] = READ_COIL(i);
    }
  } else {
    req->error = MG_MODBUS_ERR_DEVICE_FAILURE;
  }
}

// ....
mongoose_init();
mongoose_set_modbus_handler(my_modbus_handler);  // <-- Add this


```

--------------------------------

### mg_ota_end()

Source: https://mongoose.ws/docs/api/ota

Finalizes the firmware update session, verifying the written firmware and preparing it for boot.

```APIDOC
## mg_ota_end()

Finalize the firmware update session. This function verifies the written firmware and prepares it for boot.

### Function Signature
```c
bool mg_ota_end(void);
```

### Return Value
* `true` on success, `false` on failure.

### Usage Example
```c
if (mg_ota_end()) {
  // Firmware update complete, reboot to apply
} else {
  // OTA end failed
}
```
```

--------------------------------

### Sending a Formatted JSON Response

Source: https://mongoose.ws/docs/api/http

Example of constructing a JSON string using mg_mprintf and sending it as an HTTP response with mg_http_reply.

```c
char *json = mg_mprintf("{%m:%d}", MG_ESC("name"), 123);
mg_http_reply(c, 200, "Content-Type: application/json\r\n", "%s\n", json);
mg_free(json);
```

--------------------------------

### Delete RPC Method Usage Example

Source: https://mongoose.ws/docs/api/json-rpc

Shows how to remove a specific RPC handler ('rpc_mul') or all RPC handlers from the list.

```c
struct mg_rpc *s_rpc_head = NULL;
// add methods
// ...

// Time to cleanup
mg_rpc_del(&s_rpc_head, rpc_mul);    // Deallocate specific handler
mg_rpc_del(&s_rpc_head, NULL);       // Deallocate all RPC handlers

```

--------------------------------

### Generate Keys and Sign Firmware

Source: https://mongoose.ws/docs/guides/firmware-ota-updates

Use the sign.js script to generate ECDSA-P256 keys and sign firmware binaries. The private key is kept secure on the build machine.

```bash
node sign.js keygen            # generate private.pem, print public key #define
node sign.js sign firmware.bin # append 64-byte signature

```

--------------------------------

### JSON-RPC get

Source: https://mongoose.ws/docs/api/dash

Fetches data fields from the device. Can retrieve all fields or a specific field by providing the field name as a parameter.

```APIDOC
## JSON-RPC get

### Description
Fetches data fields from the device and updates the Dashboard.data object.

### Request
{"id": 1, "method": "get", "params": "optional_field_name"}

### Response
{"id": 1, "result": { "field": "value" }}
```

--------------------------------

### mg_iobuf_init()

Source: https://mongoose.ws/docs/api/core/content.html

Initializes a generic IO buffer structure, allocating a specified amount of memory for data storage.

```APIDOC
### mg_iobuf_init()

### Description
Initialize IO buffer, allocate `size` bytes.

### Parameters
* `io` - Pointer to `mg_iobuf` structure to initialize
* `size` - Amount of bytes to allocate
* `align` - Align `size` to the `align` mem boundary. `0` means no alignment

### Return Value
1 on success, 0 on allocation failure

### Usage Example
```c
struct mg_iobuf io;
if (mg_iobuf_init(&io, 0, 64)) {
  // io successfully initialized
}
```
```

--------------------------------

### REST API 'array' Type Configuration

Source: https://mongoose.ws/docs/guides/web-ui-builder

Example configuration for a 'sensors' REST API endpoint of type 'array' (used for sensors).

```json
"wifi": {
  "type": "sensors",
  "attributes": {
    "type": { "type": "int", "value": 10},
    "name": { "type": "string", "value": "temp1", "size": 20}
  }
}

```

--------------------------------

### Clone Mongoose Git Repository

Source: https://mongoose.ws/docs/guides/stm32-cubeide-mongoose

Clones the Mongoose library repository from GitHub. This is a prerequisite for importing Mongoose examples into your STM32CubeIDE workspace.

```bash
git clone https://github.com/cesanta/mongoose
```
Tokens:
Raw