{"id":20346670,"url":"https://github.com/arthurfdlr/esp32-webapp","last_synced_at":"2025-09-23T10:31:29.371Z","repository":{"id":112736327,"uuid":"532668211","full_name":"ArthurFDLR/esp32-webapp","owner":"ArthurFDLR","description":"💡 The over-engineered ESP32 blinker example: ESP-IDF RESTful-API \u0026 Vue 2 Frontend","archived":false,"fork":false,"pushed_at":"2022-09-28T04:18:59.000Z","size":32917,"stargazers_count":12,"open_issues_count":1,"forks_count":1,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-11-14T22:14:31.577Z","etag":null,"topics":["esp-idf","esp32","rest-api","vue"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ArthurFDLR.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-09-04T21:58:27.000Z","updated_at":"2024-10-12T02:14:09.000Z","dependencies_parsed_at":null,"dependency_job_id":"f50d3359-1c38-47cd-a942-1b985816ef77","html_url":"https://github.com/ArthurFDLR/esp32-webapp","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ArthurFDLR%2Fesp32-webapp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ArthurFDLR%2Fesp32-webapp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ArthurFDLR%2Fesp32-webapp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ArthurFDLR%2Fesp32-webapp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ArthurFDLR","download_url":"https://codeload.github.com/ArthurFDLR/esp32-webapp/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":233967975,"owners_count":18758727,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["esp-idf","esp32","rest-api","vue"],"created_at":"2024-11-14T22:13:47.234Z","updated_at":"2025-09-23T10:31:22.219Z","avatar_url":"https://github.com/ArthurFDLR.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n\u003ca href=\"https://youtu.be/Ou1GtHqjWwc\"\u003e\u003cp align=\"center\"\u003e\u003cimg src=\"./.github/ESP32-WebApp.gif\" alt=\"Demo of the application\" width=\"85%\"\u003e\u003c/p\u003e\u003c/a\u003e\n[**See full video demonstration here**](https://youtu.be/Ou1GtHqjWwc)\n\n# ESP32 Web Application Example: ESP-IDF RESTful \u0026 Vue 2 Frontend\n\nThis repository is a refresher of the [ESP-IDF example](https://github.com/espressif/esp-idf/tree/master/examples/protocols/http_server/restful_server) to use Vue 2, and its UI library Vuetify.\n\nIt has been tested and developed on an [ESP32-S3 custom board with 8Mb of flash memory](https://github.com/ArthurFDLR/esp32-s3-darlington-array), but any ESP32 with at least 4Mb of memory should handle this application.\n\n- [ESP32 Web Application Example: ESP-IDF RESTful \u0026 Vue 2 Frontend](#esp32-web-application-example-esp-idf-restful--vue-2-frontend)\n  - [Overview](#overview)\n    - [About mDNS](#about-mdns)\n    - [About deploy mode](#about-deploy-mode)\n    - [About frontend framework](#about-frontend-framework)\n  - [How to use example](#how-to-use-example)\n    - [Hardware Required](#hardware-required)\n    - [Configure the project](#configure-the-project)\n    - [Build and Flash](#build-and-flash)\n    - [Extra steps to do for deploying website by semihost](#extra-steps-to-do-for-deploying-website-by-semihost)\n  - [Troubleshooting](#troubleshooting)\n\n## Overview\n\nThis example mainly introduces how to implement a RESTful API server and HTTP server on ESP32, with a frontend browser UI.\n\nThis example designs several APIs to fetch resources as follows:\n\n| API                        | Method | Resource Example                                      | Description                                                                              | Page URL |\n| -------------------------- | ------ | ----------------------------------------------------- | ---------------------------------------------------------------------------------------- | -------- |\n| `/api/v1/system/info`      | `GET`  | {\u003cbr /\u003eversion:\"v4.0-dev\",\u003cbr /\u003ecores:2\u003cbr /\u003e}        | Used for clients to get system information like IDF version, ESP32 cores, etc            | `/`      |\n| `/api/v1/blinker/duration`         | `POST`  | {\u003cbr /\u003e\"duration_ms\":1000\u003cbr /\u003e}                                  | Used for clients to get raw temperature data read from sensor                            | `/blinker` |\n| `/api/v1/blinker/state` | `POST` | { \u003cbr /\u003e\u003ct /\u003e\"state\":true\u003cbr /\u003e} | Used for clients to upload control values to ESP32 in order to control LED’s brightness  | `/blinker` |\n\n**Page URL** is the URL of the webpage which will send a request to the API.\n\n### About mDNS\n\nThe IP address of an IoT device may vary from time to time, so it’s impracticable to hard code the IP address in the webpage. By default, we use the `mDNS` to parse the domain name `esp-blinker.local`, so that we can always get access to the web server by this URL no matter what the real IP address behind it. See [here](https://docs.espressif.com/projects/esp-idf/en/latest/api-reference/protocols/mdns.html) for more information about mDNS.\n\n**Notes: mDNS is installed by default on most operating systems or is available as separate package.**\n\n### About deploy mode\n\nIn development mode, it would be awful to flash the whole webpages every time we update the html, js or css files. So it is highly recommended to deploy the webpage to host PC via `semihost` technology. Whenever the browser fetch the webpage, ESP32 can forward the required files located on host PC. By this mean, it will save a lot of time when designing new pages.\n\nAfter developing, the pages should be deployed to one of the following destinations:\n\n* SPI Flash - which is recommended when the website after built is small (e.g. less than 2MB).\n* SD Card - which would be an option when the website after built is very large that the SPI Flash have not enough space to hold (e.g. larger than 2MB).\n\n### About frontend framework\n\nMany famous frontend frameworks (e.g. Vue, React, Angular) can be used in this example. Here we just take [Vue](https://vuejs.org/) as example and adopt the [vuetify](https://vuetifyjs.com/) as the UI library.\n\n## How to use example\n\n### Hardware Required\n\nTo run this example, you need an ESP32 dev board (e.g. ESP32-WROVER Kit, ESP32-Ethernet-Kit) or ESP32 core board (e.g. ESP32-DevKitC). An extra JTAG adapter might also needed if you choose to deploy the website by semihosting. For more information about supported JTAG adapter, please refer to [select JTAG adapter](https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/jtag-debugging/index.html#jtag-debugging-selecting-jtag-adapter). Or if you choose to deploy the website to SD card, an extra SD slot board is needed.\n\n**Pin Assignment:**\n\nOnly if you deploy the website to SD card, then the following pin connection is used in this example.\n\n| ESP32  | SD Card |\n| ------ | ------- |\n| GPIO2  | D0      |\n| GPIO4  | D1      |\n| GPIO12 | D2      |\n| GPIO13 | D3      |\n| GPIO14 | CLK     |\n| GPIO15 | CMD     |\n\n\n### Configure the project\n\nOpen the project configuration menu (`idf.py menuconfig`). \n\nIn the `Example Connection Configuration` menu:\n\n* Choose the network interface in `Connect using`  option based on your board. Currently we support both Wi-Fi and Ethernet.\n* If you select the Wi-Fi interface, you also have to set:\n  * Wi-Fi SSID and Wi-Fi password that your esp32 will connect to.\n* If you select the Ethernet interface, you also have to set:\n  * PHY model in `Ethernet PHY` option, e.g. IP101.\n  * PHY address in `PHY Address` option, which should be determined by your board schematic.\n  * EMAC Clock mode, GPIO used by SMI.\n\nIn the `Example Configuration` menu:\n\n* Set the pin of the build-in LED (or any pin which has something blinkable connected) in `Blink GPIO number`.\n* Set the domain name in `mDNS Host Name` option.\n* Choose the deploy mode in `Website deploy mode`, currently we support deploy website to host PC, SD card and SPI Nor flash.\n  * If we choose to `Deploy website to host (JTAG is needed)`, then we also need to specify the full path of the website in `Host path to mount (e.g. absolute path to web dist directory)`.\n* Set the mount point of the website in `Website mount point in VFS` option, the default value is `/www`.\n\n### Build and Flash\n\nAfter the webpage design work has been finished, you should compile them by running following commands:\n\n```bash\ncd ./front/web-blinker\nnpm install\nnpm run build\n```\n\nAfter a while, you will see a `dist` directory which contains all the website files (e.g. html, js, css, images).\n\nRun `idf.py -p PORT flash monitor` to build and flash the project..\n\n(To exit the serial monitor, type ``Ctrl-]``.)\n\nSee the [Getting Started Guide](https://docs.espressif.com/projects/esp-idf/en/latest/get-started/index.html) for full steps to configure and use ESP-IDF to build projects.\n\n### Extra steps to do for deploying website by semihost\n\nWe need to run the latest version of OpenOCD which should support semihost feature when we test this deploy mode:\n\n```bash\nopenocd-esp32/bin/openocd -s openocd-esp32/share/openocd/scripts -f board/esp32-wrover-kit-3.3v.cfg\n```\n\n## Troubleshooting\n\n1. Error occurred when building example: `...front/web-demo/dist doesn't exit. Please run 'npm run build' in ...front/web-demo`.\n   * When you choose to deploy website to SPI flash, make sure the `dist` directory has been generated before you building this example.\n\n(For any technical queries, please open an [issue](https://github.com/espressif/esp-idf/issues) on GitHub. We will get back to you as soon as possible.)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farthurfdlr%2Fesp32-webapp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Farthurfdlr%2Fesp32-webapp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farthurfdlr%2Fesp32-webapp/lists"}