{"id":20492320,"url":"https://github.com/husarnet/esp32-internet-ota","last_synced_at":"2025-04-13T17:01:33.633Z","repository":{"id":113651606,"uuid":"424583981","full_name":"husarnet/esp32-internet-ota","owner":"husarnet","description":"ESP32 + GitHub Actions + Husarnet. A boilerplate project for ESP32 allowing in-field firmware update using GitHub Actions workflow.","archived":false,"fork":false,"pushed_at":"2024-07-09T10:39:10.000Z","size":45,"stargazers_count":44,"open_issues_count":1,"forks_count":5,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-03-27T07:51:33.284Z","etag":null,"topics":["asyncwebserver","esp32","esp32-arduino","github-actions","husarnet","iot-device","iot-edge","nginx-proxy-manager","ota-updates","platformio"],"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/husarnet.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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":"2021-11-04T12:17:12.000Z","updated_at":"2025-02-19T21:54:42.000Z","dependencies_parsed_at":null,"dependency_job_id":"991765d6-7c24-49f4-bcf5-ad35f3cb4a9d","html_url":"https://github.com/husarnet/esp32-internet-ota","commit_stats":null,"previous_names":[],"tags_count":0,"template":true,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/husarnet%2Fesp32-internet-ota","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/husarnet%2Fesp32-internet-ota/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/husarnet%2Fesp32-internet-ota/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/husarnet%2Fesp32-internet-ota/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/husarnet","download_url":"https://codeload.github.com/husarnet/esp32-internet-ota/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248750077,"owners_count":21155685,"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":["asyncwebserver","esp32","esp32-arduino","github-actions","husarnet","iot-device","iot-edge","nginx-proxy-manager","ota-updates","platformio"],"created_at":"2024-11-15T17:28:36.014Z","updated_at":"2025-04-13T17:01:33.592Z","avatar_url":"https://github.com/husarnet.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003e [!CAUTION]\n\u003e Husarnet for ESP32 has undergone a major refactor making it compatible with the latest upstream core codebase, latest ESP-IDF releases and newest Espressif microcontrollers. Because of that, code in **this repository is outdated** and it should not be used for new designs. It may or may not be updated to reflect the changes later in the future.\n\u003e \n\u003e [Learn more about our latest changes here!](https://husarnet.com/docs/esp32-idf/)\n\n---\n\n# esp32-internet-ota\n\nESP32 + GitHub Actions + Husarnet. \n\nA boilerplate project for ESP32 allowing in-field firmware update using GitHub Actions workflow.\n\n\u003e **Prerequisites** \n\u003e\n\u003e Install platformio CLI:\n\u003e\n\u003e ```bash\n\u003e pip3 install -U platformio\n\u003e ```\n\u003e\n\u003e If you are working in [Visual Studio Code](https://code.visualstudio.com/) the [PlatformIO extension](https://platformio.org/install/ide?install=vscode) will be helpful.\n\n## Quick start\n\n### First setup\n\n1. Click **[Use this template](https://github.com/husarnet/esp32-internet-ota/generate)** button to create your own copy of this repo. Clone the repo, and open it:\n\n    ```bash\n    git clone https://github.com/husarnet/esp32-internet-ota\n    cd esp32-internet-ota/\n    ```\n\n2. Erase the ESP32 flash\n\n    ```bash\n    pio run --target erase\n    # or \n    # esptool.py erase_flash\n    ```\n\n3. Prepare the `.env` file:\n\n    ```bash\n    cp .env.template .env\n    ```\n\n    And edit its content:\n\n    ```bash\n    export WIFI_SSID=\"\u003cplace-your-wifi-ssid-here\u003e\"\n    export WIFI_PASS=\"\u003cplace-a-password-to-your-wifi-here\u003e\"\n    export HUSARNET_JOINCODE=\"\u003cplace-your-husarnet-joincode-here\"\n    ```\n\n    \n\u003e **Tip** \n\u003e\n\u003e If your SSID or WLAN Password contains special characters (ex. ```$ \u0026 ( ) ? ; : , . \u003c \u003e | ` ```) you need to escape them like this::\n\u003e\n\u003e If WiFi password is ```$\u0026()?``` then:\n\u003e ```bash\n\u003e export WIFI_PASS=\"\\$\\\u0026\\(\\)\\?\"\n\u003e ```\n\u003e Some special characters (ex. ```' \" \\ ```) can't be escaped.\n\u003e We recommend to not use special characters and emojis in WiFi SSID/Password.\n\u003e\n\n3. The first time you need to upload the firmware over the USB cable:\n\n    ```bash\n    source .env\n    pio run -e serial_upload --target upload\n    ```\n\n4. Open the Platformio Device Monitor:\n\n    ```bash\n    pio device monitor\n    ```\n\n    If you will open a serial monitor you will see the similar output (the first time you may wait up to 2 minutes):\n\n    ```bash\n    **************************************\n    GitHub Actions OTA example\n    **************************************\n\n    📻 1. Connecting to: FreeWifi Wi-Fi network .. done\n\n    ⌛ 2. Waiting for Husarnet to be ready ... done\n\n    🚀 HTTP server started\n\n    Visit:\n    http://my-esp32:8080/\n\n    Known hosts:\n    my-laptop (fc94:a4c1:1f22:ab3b:b04a:1a3b:ba15:84bc)\n    my-esp32 (fc94:f632:c8d9:d2a6:ad18:ed16:ed7e:9f3f)\n    ```\n\n4. Visit http://my-esp32:8080/ from your laptop (that should be in the same Husarnet group) and if the website is avaialble you can test OTA upgrade from the level of your laptop:\n\n    ```bash\n    source .env\n    pio run -e ota_upload --target upload\n    ```\n\n5. If it works you can configure your GitHub repository.\n\n### Editing in Visual Studio Code with a PlatformIO extenstion\n\nSource environment variables from `.env` file before opening VS Code.\n\n```bash\ncd esp32-internet-ota/\nsource .env\ncode .\n```\n\n### Internet OTA with GitHub Actions\n\n\u003e **warning!**\n\u003e\n\u003e Before launching an Internet OTA, you need to upload the [initial firmware](#first-setup) at first to make your board accessible over the Husarnet VPN.\n\n1. Create the folowing GitHub repository secrets (`Settings` \u003e `Secrets` \u003e `New repository secret`):\n\n    | Secret | Sample Value | Desription |\n    | - | - | - |\n    | `WIFI_SSID` | FreeWifi | just your WiFi network name |\n    | `WIFI_PASS` | hardtoguess | ... and password |\n    | `HUSARNET_JOINCODE` | fc94:...:932a/xhfqwPxxxetyCExsSPRPn9 | find your own **secret** Join Code at your user account at https://app/husarnet.com \u003e `choosen network` \u003e  `add element` button. Anyone with this Join Code can connect to your Husarnet network |\n    | `HUSARNET_DASHBOARD_LOGIN` | me@acme.com | A login for your account at https://app.husarnet.com (needed by [Husarnet Action](https://github.com/husarnet/husarnet-action/)) |\n    | `HUSARNET_DASHBOARD_PASSWORD` | hardtoguess | A password for your account at https://app.husarnet.com (needed by [Husarnet Action](https://github.com/husarnet/husarnet-action/)) |    \n\n2. Push changes to your repo:\n\n    ```bash\n    git add *\n    git commit -m \"triggering the workflow\"\n    git push\n    ```\n\n    And trigger the workflow manually (`workflow_dispatch`) in your GitHub repository.\n\n3. In ~3 minutes the GitHub workflow should finish its job. Visit: `http://my-esp32:8080` URL with a sample \"Hello world\" website hosted by your ESP32.\n\n\n    Of course your laptop need to be connected to the same Husarnet network - you will find quick start guide showing how to do it here: https://husarnet.com/docs/\n\n\n## Tips\n\n### Monitoring network traffic on `hnet0` interface\n\n```bash\nsudo tcpflow -p -c -i hnet0\n```\n\n### Accesing a webserver hosted by ESP32 using a public domain\n\nHere is a blog post showing how to configure Nginx Proxy Manager to **provide a public access to web servers hosted by Husarnet connected devices**: https://husarnet.com/blog/reverse-proxy-gui\n\nIt can be also used  o provide the access to a web server hosted by ESP32 using a nice looking link like: `https://my-awesome-esp32.mydomain.com`.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhusarnet%2Fesp32-internet-ota","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhusarnet%2Fesp32-internet-ota","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhusarnet%2Fesp32-internet-ota/lists"}