{"id":16220246,"url":"https://github.com/brianpugh/cookiecutter-esp32-webserver","last_synced_at":"2025-06-15T13:34:16.559Z","repository":{"id":55939381,"uuid":"261628063","full_name":"BrianPugh/cookiecutter-esp32-webserver","owner":"BrianPugh","description":"Cookiecutter template to get you quickly started with an ESP32-based webserver project.","archived":false,"fork":false,"pushed_at":"2020-12-12T22:05:05.000Z","size":731,"stargazers_count":14,"open_issues_count":0,"forks_count":3,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-17T06:35:40.853Z","etag":null,"topics":["cookiecutter","esp-idf","esp32","ota","rest-api","webserver"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/BrianPugh.png","metadata":{"files":{"readme":"README.md","changelog":"HISTORY.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-05-06T02:02:28.000Z","updated_at":"2025-01-18T03:27:19.000Z","dependencies_parsed_at":"2022-08-15T09:50:55.306Z","dependency_job_id":null,"html_url":"https://github.com/BrianPugh/cookiecutter-esp32-webserver","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BrianPugh%2Fcookiecutter-esp32-webserver","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BrianPugh%2Fcookiecutter-esp32-webserver/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BrianPugh%2Fcookiecutter-esp32-webserver/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BrianPugh%2Fcookiecutter-esp32-webserver/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/BrianPugh","download_url":"https://codeload.github.com/BrianPugh/cookiecutter-esp32-webserver/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244416895,"owners_count":20449358,"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":["cookiecutter","esp-idf","esp32","ota","rest-api","webserver"],"created_at":"2024-10-10T11:58:14.640Z","updated_at":"2025-03-19T11:30:52.549Z","avatar_url":"https://github.com/BrianPugh.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"This is a [cookiecutter](https://github.com/cookiecutter/cookiecutter) template \nfor anyone who wants to create an ESP32 application with webserver capabilities\n(including serving a simple REST API).\n\n# Usage\nTo render this template into a working project directory, you need to use the\ncommand-line utility `cookiecutter`. This can be installed via `pip3 install cookiecutter`.\n\n```\ncookiecutter -c v0.3.2 https://github.com/BrianPugh/cookiecutter-esp32-webserver.git\n```\n\nNote: this template was developed with esp-idf v4.2 in mind. If you need to\nuse v4.1, run:\n```\ncookiecutter -c 4.1-compat https://github.com/BrianPugh/cookiecutter-esp32-webserver.git\n```\n\n## Routes\n\nAdd new source files containing route handlers to `src/route/v1/*`. \nMake sure to also add these files to `src/CMakeLists.txt` otherwise they\nwill not be compiled.\nAs you make backwards incompatible updates to certain endpoints, \nyou can create a new folder `v2` while maintaining older routes.\n\nAdding routes involves 2 parts:\n\n1. Writing the handler function (see `src/route/v1/examples.c`)\n2. Registering the handler with a route and command type in the `register_routes`\n   function of `src/route.c`.\n\nThats it! If you add a new source file, don't forget to add it to `CMakeLists.txt`.\n\n\n# Additional Features\n\n![](assets/root.png)\n\nFeatures descrbied in this section are linked in the root route `/` for easy access.\n\nFor admin endpoints, if the request has `text/html` in the `ACCEPT` field of the\nhttp header, then the server will respond with the webgui. Otherwise, JSON or\nbinary data will be returned.\n\n## Admin Filesystem Interface\n\n![](assets/filesystem.gif)\n\nThis project comes with a [port of LittleFS](https://github.com/joltwallet/esp_littlefs),\na small fail-safe filesystem with higher performance than SPIFFS. Also bundled\nis a web-accessible file explorer to browse, upload, and delete files at \n`/api/v1/filesystem`.\n\nFile contents can be gathered by issuing `GET` to `/api/v1/filesystem/path/to/file`.\n\nFolder contents can also be queried via a `GET` command. For example:\n\n```\n$ curl ${ESP32_IP}/api/v1/filesystem\n{\n    \"contents\":[\n        {\n            \"name\":\"foo\",\n            \"type\":\"dir\",\n            \"size\":0\n        },\n        {\n            \"name\":\"test.txt\",\n            \"type\":\"file\",\n            \"size\":45\n        }\n    ]\n}\n```\n\n## Admin Non-Volatile Storage Interface\n\n![](assets/nvs.gif)\n\nNVS offers a convenient way to store key/value pairs to flash. The admin \ninterface at `/api/v1/nvs` allows for viewing and modifying existing NVS\nentries. Clicking away from an editted value will save the value to flash.\n\nValues can be manually queried via `GET`:\n\n```\n$ curl ${ESP32_IP}/api/v1/nvs/user/key1\n{\n        \"namespace\":    \"user\",\n        \"key\": \t\t\t\"key1\",\n        \"dtype\":        \"uint8\",\n        \"value\":        9,\n        \"size\": \t\t1\n}\n```\n\nEntire namespaces (or even the entire system) can also be queried. Binary data\nwill be converted into a hexidecimal representation.\n\n```\n$ curl ${ESP32_IP}/api/v1/nvs/user\n{\n\t\"contents\":[\n\t\t{\n            \"namespace\":\"user\",\n            \"key\":\"key2\",\n            \"value\":\"test string\",\n            \"dtype\":\"string\",\n            \"size\":12\n        },\n        {\n            \"namespace\":\"user\",\n            \"key\":\"key1\",\n            \"value\":\"9\",\n            \"dtype\":\"uint8\",\n            \"size\":1\n        },\n        {\n            \"namespace\":\"user\",\n            \"key\":\"key3\",\n            \"value\":\"deadbeef\",\n            \"dtype\":\"binary\",\n            \"size\":4\n        }\n    ]\n}\n```\n\nValues can be manually updated via `POST`:\n\n```\ncurl -X POST ${ESP32_IP}/api/v1/nvs/some_namespace --data '{\"key1\": 7}'\n```\n\nMultiple key/value pairs for a single namespace can be provided at once.\n\n\n## OTA\n\nNew firmware can be flashed over wifi by sending a `POST` command to the \n`/api/v1/ota` endpoint like:\n\n```\ncurl -X POST http://myesp32app.local/api/v1/ota --data-binary @- \u003c my_esp32_webapp.bin\n```\n\nOTA has significant implications on how the ESP32 flash is partitioned.\nSee/Modify `partitions.csv` to suit your project's needs. Warning: if the \nuploaded firmware has a bug that prevents access to this endpoint, subsequent\nfirmware updates must be preferred via UART.\n\n## System\n\nGet system information by sending a `GET` command to `/api/v1/system/info`:\n\n```\n$ curl ${ESP32_IP}/api/v1/system/info\n{\n        \"idf-version\":  \"v4.2-dev-1416-g34a92385d\",\n        \"model\":        \"ESP32\",\n        \"cores\":        2,\n        \"silicon-revision\":     1,\n        \"project-name\": \"my_esp32_webapp\",\n        \"project-version\":      \"0.3.2\",\n        \"compile-date\": \"May 14 2020\",\n        \"compile-time\": \"09:23:07\",\n        \"secure-version\":       0,\n        \"app-elf-sha256\":       \"f6ef9c7e0e0c260994351f994b3a87114ad91b6a8c85cfa30dd9fc3045a2cc77\"\n}\n```\n\nReboot the system by sending a `POST` command to `/api/v1/system/reboot`\n\n```\ncurl -X POST ${ESP32_IP}/api/v1/system/reboot\n```\n\n## SNTP System Time\nAt startup, the device will attempt to contact an NTP server (defaults to \n`pool.ntp.org`, settable at NVS storage location `ntp/server`) to set system\ntime.\n\n\n## Git Repo\n\nA small nicety is that this cookiecutter template will automatically intializes \ngit in your newly created project.\n\n## Demo\n\nA small demo endpoint  at `/api/v1/led/timer` is provided to show a REST API \ncontrolling a physical object. Flash an led (the LED pin must be properly \nconfigured via `idf.py menuconfig` under `\u003cmy project name\u003e Configuration` at \nthe root level) for 1000 milliseconds by the following command.\n\n```\ncurl -X POST ${ESP32_IP}/api/v1/led/timer --data '{\"duration\": 1000}'\n```\n\n# Design Decisions\n\nMany of the Admin features could have been included in the form of another\nesp-idf component. However, to keep it easier to tailor to varying needs,\nthe files are directly included in the project to allow easier modifications.\n\n# Misc tips\n\nIf you are unfamiliar with working with C/esp-idf projects, this section is \nmeant to help out simple oversights/issues.\n\n## Undefined references\nIf everything compiles, but you are having undefined references at the end\nduring linking, its probably because your forgot to add the c-file to \n`src/CMakeLists.txt`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrianpugh%2Fcookiecutter-esp32-webserver","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbrianpugh%2Fcookiecutter-esp32-webserver","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrianpugh%2Fcookiecutter-esp32-webserver/lists"}