mongoose README

The project's README from github.com/cesanta/mongoose. As one markdown file: README.md.

Mongoose - Embedded Web Server / Embedded Network Library

License: GPLv2/Commercial Build Status Code Coverage Fuzzing Status

Two files. Drop mongoose.c and mongoose.h into any C/C++ project and get a full network stack — HTTP, WebSocket, MQTT, TLS, firmware OTA updates, device dashboard — on any microcontroller or desktop OS.

On the market since 2004, used by vast number of open source and commercial products - it even runs on the International Space Station! Features include:

Mongoose is ideal for IoT devices, embedded web servers, OTA updates, MQTT telemetry, secure device dashboards, REST APIs on microcontrollers

See https://mongoose.ws/ for complete documentation, videos, case studies, etc.

Supported platforms

Mongoose can work on top of any TCP/IP stack that supports BSD sockets API. Platforms supported by the 3rd party TCP/IP stacks:

TCP/IP stack Notes
lwIP All devices running lwIP, for example ESP32, ESP32S3, ESP32C3, ESP32C6, etc
Zephyr All devices supported by Zephyr
Other Any other TCP/IP stack that supports BSD socket API, for example Amazon FreeRTOS-TCP
Linux, Mac, Windows Workstations, server, single board computers, embedded Linux devices running on MPUs or FPGAs

Optionally, Mongoose provides its own built-in TCP/IP stack, eliminating the need for additional software to implement networking functionality. The built-in stack supports operation in both bare-metal and RTOS environments. Platforms supported by the Mongoose built-in TCP/IP stack:

Hardware Notes
STM32 All STM32 MCUs with built-in Ethernet: STM32Fxx, STM32H5xx, STM32H7xx
NXP All NXP MCUs with built-in Ethernet: IMXRT102x, IMXRT104x, IMXRT105x, IMXRT106x, IMXRT117x, RW612, MCXN94x
Microchip ATSAME54 MCUs with built-int Ethernet
Renesas RA5M, RA6M, RA8M MCUs with built-in Ethernet
Infineon XMC4, XMC7 MCUs with built-in Ethernet
Texas Instruments TM4C, TMS570 MCUs with built-in Ethernet
Cypress WiFi Any MCU with CY43xx WiFi chips, like RP2040 Pico-W, RP2350 Pico2-W, Arduino Portenta
Wiznet Ethernet Any MCU that use Wiznet W5500 or Wiznet 5100 MAC+PHY chips
Cellular NRF9160, SIM800

Usage Examples

Below are quick snippets that should give an idea how simple the API is and how easy it is to create applications with it.

Create a simple web server that serves a directory. The behavior of the HTTP server is specified by its event handler function:

#include "mongoose.h"   // To build, run: cc main.c mongoose.c

// HTTP server event handler function
void 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;
    struct mg_http_serve_opts opts = { .root_dir = "./web_root/" };
    mg_http_serve_dir(c, hm, &opts);
  }
}

int main(void) {
  struct mg_mgr mgr;  // Declare event manager
  mg_mgr_init(&mgr);  // Initialise event manager
  mg_http_listen(&mgr, "http://0.0.0.0:8000", ev_handler, NULL);  // Setup listener
  for (;;) {          // Run an infinite event loop
    mg_mgr_poll(&mgr, 1000);
  }
  return 0;
}

HTTP server implements a REST API that returns current time. JSON formatting:

static void 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;
    if (mg_match(hm->uri, mg_str("/api/time/get"), NULL)) {
      mg_http_reply(c, 200, "", "{%m:%lu}\n", MG_ESC("time"), time(NULL));
    } else {
      mg_http_reply(c, 500, "", "{%m:%m}\n", MG_ESC("error"), MG_ESC("Unsupported URI")); 
    }
  }
}

MQTT client that subscribes to a topic device1/rx and echoes incoming messages to device1/tx:

#include "mongoose.h"

static const char *s_mqtt_url = "mqtt://broker.hivemq.com:1883";
static struct mg_connection *s_mqtt_conn = NULL;

// MQTT connection event handler function
static void ev_handler(struct mg_connection *c, int ev, void *ev_data) {
  if (ev == MG_EV_OPEN) {
    MG_INFO(("%lu created, connecting to %s ...", c->id, s_mqtt_url));
  } else if (ev == MG_EV_MQTT_OPEN) {
    struct mg_mqtt_opts opts = {.qos = 1, .topic = mg_str("device1/rx")};
    mg_mqtt_sub(c, &opts);
    MG_INFO(("%lu connected, subscribing to %s", c->id, opts.topic.buf));
  } else if (ev == MG_EV_MQTT_MSG) {
    char response[100];
    struct mg_mqtt_message *mm = (struct mg_mqtt_message *) ev_data;
    struct mg_mqtt_opts opts = {.qos = 1, .topic = mg_str("device1/tx")};
    mg_snprintf(response, sizeof(response), "Received [%.*s] / [%.*s]",
                mm->topic.len, mm->topic.buf, mm->data.len, mm->data.buf);
    opts.message = mg_str(response);
    mg_mqtt_pub(c, &opts);
  } else if (ev == MG_EV_CLOSE) {
    MG_INFO(("%u closing", c->id));
    s_mqtt_conn = NULL;
  }
}

// Reconnection timer function. If we get disconnected, reconnect again
static void timer_fn(void *arg) {
  struct mg_mgr *mgr = (struct mg_mgr *) arg;
  if (s_mqtt_conn == NULL) {
    struct mg_mqtt_opts opts = {.clean = true};
    s_mqtt_conn = mg_mqtt_connect(mgr, s_mqtt_url, &opts, ev_handler, NULL);
  }
}

int main() {
  struct mg_mgr mgr;  // Mongoose event manager. Holds all connections
  mg_mgr_init(&mgr);  // Initialise event manager
  mg_timer_add(&mgr, 3000, MG_TIMER_REPEAT | MG_TIMER_RUN_NOW, timer_fn, &mgr);
  for (;;) {
    mg_mgr_poll(&mgr, 1000);  // Infinite event loop
  }
  return 0;
}

Commercial use

Security

We take security seriously:

  1. Mongoose repository runs a continuous integration test powered by GitHub, which runs through hundreds of unit tests on every commit to the repository. Our unit tests are built with modern address sanitizer technologies, which help to find security vulnerabilities early
  2. Mongoose repository is integrated into Google's oss-fuzz continuous fuzzer which scans for potential vulnerabilities continuously
  3. We receive periodic vulnerability reports from the independent security groups like Cisco Talos, Microsoft Security Response Center, MITRE Corporation, Compass Security and others. In case of the vulnerability found, we act according to the industry best practice: hold on to the publication, fix the software and notify all our customers that have an appropriate subscription
  4. Some of our customers (for example NASA) have specific security requirements and run independent security audits, of which we get notified and in case of any issue, act similar to (3).

How to report security vulnerabilities

Please report via https://github.com/cesanta/mongoose/security/advisories. Do NOT create a github issue.

Articles

Technical guides and deep dives into embedded web servers, WebUI integration and embedded networking technologies:

Contributions

Contributions are welcome! Please follow the guidelines below:

mongoose (cesanta/mongoose)

mqtt
Searching Database…

13.1K ·GitHub
Mongoose
What is this?An embedded web server and network library: drop two C files into any C/C++ project and you get HTTP, WebSocket, MQTT, TLS, OTA firmware updates and a device dashboard on a microcontroller or a desktop OS.
So it's not a program I run on its own — it's code I build into my own app?Exactly — it's a library. You compile mongoose.c and mongoose.h into your application or firmware, and the source is both ISO C and ISO C++ compliant.
How do I add it to a project?Copy mongoose.c and mongoose.h into your C/C++ project, write an event handler that defines your server's behavior, and build — no package manager or install step involved.
Do I need other libraries for networking or TLS?No. It carries its own TCP/IP stack for bare metal and RTOS plus a built-in TLS 1.3 ECC stack; it can alternatively run atop lwIP or Zephyr and use mbedTLS or OpenSSL.
Firmware updates sound like the killer feature — is there a catch?Turnkey built-in OTA covers specific chip families only: STM32 H5/H7, NXP i.MX RT, RP2040/2350, ESP32 and a few more. On other hardware you implement the update logic yourself.
What do people actually build with it?Device Web UIs and dashboards, REST APIs on microcontrollers, MQTT telemetry, remote control and remote firmware updates — hundreds of millions of devices run it in production.
What hardware and operating systems does it run on?Desktops: Linux/UNIX, macOS, Windows, Android. Chips: STM32, NXP i.MX RT, ESP32, RP2040/2350, Nordic, TI, Microchip, Infineon, Renesas — via its own stack or any BSD-sockets stack.
Can I ship it inside a commercial product for free?Not automatically — it's dual-licensed: you can evaluate it for free, but production use requires a commercial license from Cesanta, available with support and proactive security updates.
Which protocols does it support out of the box?Plain TCP and UDP, HTTP, WebSocket, MQTT, Modbus-TCP and SNTP, plus an asynchronous DNS resolver — enough to build a complete device network stack from one library.
How battle-tested is it?It has been on the market since 2004, is deployed on hundreds of millions of devices and even runs on the International Space Station, with commercial users from Siemens and Bosch to Google and Samsung.
Does the built-in TCP/IP stack cover every microcontroller?No — it targets MCUs with built-in Ethernet (STM32F/H5/H7, NXP i.MX RT, Microchip ATSAME54, Renesas RA, Infineon XMC, TI TM4C/TMS570), plus Cypress WiFi chips like Pico-W and Wiznet W5500/5100 modules. Everything else goes over an external stack.
How does the project handle security?Every commit runs hundreds of unit tests built with address sanitizers, the repo is integrated into Google's oss-fuzz, and reports come from groups like Cisco Talos and Microsoft MSRC; commercial subscribers additionally get proactive security updates, and the codebase is CRA-compliant.
What are similar projects?Marlin, hermes-gadget-sdk, muse-gadget-sdk, tinygo, arduino-esp32, micropython, esphome, Tasmota
Which topics is it in?webserver, stm32, udp, mqtt, tcp, microcontroller, web-server, esp32, embedded-systems, firmware, iot, raspberry-pi
Creator
cesanta
Size
51 MB
Stars
13.1K
Updated
CommitOct 17Release7.23Aug 12
Age
14y
Commits · 90 Days