{"id":21424959,"url":"https://github.com/arkhipenko/espcoldboot","last_synced_at":"2025-04-19T14:45:33.537Z","repository":{"id":187971208,"uuid":"263674278","full_name":"arkhipenko/EspColdBoot","owner":"arkhipenko","description":"Flexible ESP8266 and ESP32 initial device provisioning","archived":false,"fork":false,"pushed_at":"2020-06-03T17:53:39.000Z","size":1433,"stargazers_count":8,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-29T08:51:10.721Z","etag":null,"topics":["arduino","boot","coldboot","esp32","esp8266","provisioning"],"latest_commit_sha":null,"homepage":null,"language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/arkhipenko.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2020-05-13T15:46:56.000Z","updated_at":"2025-02-03T08:24:11.000Z","dependencies_parsed_at":"2023-08-13T03:06:01.452Z","dependency_job_id":null,"html_url":"https://github.com/arkhipenko/EspColdBoot","commit_stats":null,"previous_names":["arkhipenko/espcoldboot"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arkhipenko%2FEspColdBoot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arkhipenko%2FEspColdBoot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arkhipenko%2FEspColdBoot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arkhipenko%2FEspColdBoot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/arkhipenko","download_url":"https://codeload.github.com/arkhipenko/EspColdBoot/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249716928,"owners_count":21315068,"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":["arduino","boot","coldboot","esp32","esp8266","provisioning"],"created_at":"2024-11-22T21:25:55.790Z","updated_at":"2025-04-19T14:45:33.517Z","avatar_url":"https://github.com/arkhipenko.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ESP ColdBoot v1.0\n\n## Flexible ESP8266 and ESP32 initial device provisioning\n\n \n\n### Background\n\nWhen you deploy hundreds of devices as part of the IoT project, the question is: how to get them on customer's network and provision the latest specific firmware to the device. \n\nThe issue is that you do not know where and when the device will be first booted up. \n\nThe device would not know the WiFi parameters and its firmware may be outdated.\n\nThis is where **ColdBoot** comes to help. \n\n \n\n\n### What is ColdBoot?\n\nColdBoot is a pre-compiled firmware for ESP8266 or ESP32 microcontroller that is capable of quickly collecting:\n\n- WiFi parameters (SSID and password) \n- URL of the latest configuration file\n- URL of the OTA update server\n\nfrom the end-user via a simple web-form. \n\n**ColdBoot's main objective** is to get to Wifi and provision the latest firmware for a particular device as quickly and easily as possible. \n\nColdBoot provides step-by-step instructions via terminal window connected to USB or Serial port \n(115200 bps setting)\n\n\n\n\n### How to use:\n\nOption 1: Upload pre-compiled binaries directly to the chip\n\nOption 2: Compile and upload provided sketch.\n\nOptionally: edit *data/config.json* file and upload to SPIFFS using upload tool\n\n \n\n### Process flow\n\n#### STEP 1:  READ COFIGURATION FROM SPIFFS\n\nColdBoot tries to read a configuration file from the SPIFFS file system of the device. \n\nThe configuration file should be named '*config.json*' and should reside in the root folder.\n\nThe config file is a simple JSON array and could define the following parameters:\n\n- \"Title\" - title of the web form for collecting parameters from the user\n- \"SSID\" - WiFi network SSID\n- \"Password\" - WiFi password\n- \"Config\" - URL to the configuration file if parameters are to be sourced from the web\n- \"OTA\" - URL to the OTA firmware provisioning HTTP server\n- \"fields\" - number of fields to be shown on the web form   \n\nAll or a subset of fields could be defined. Subsequent process flow could be influenced by this file.\n\n##### An example use case: \n\nConfiguration file provides a Title for the web-form, a URL for latest configuration, and limits number of web-form fields to 2 (SSID and password)\n\n```json\n{\n  \"Title\"    : \"My Amazing IoT device\",\n  \"Config\"   : \"http://ota.home.lan/esp/config/\",\n  \"fields\"   : \"2\"\n}\n```\n\n**Note**: To use SPIFFS configuration capability - edit the provided *data/config.json* file to your needs and upload SPIFFS image to the device using ESP8266 SPIFFS Upload Tool in the Arduino IDE. \n\n \n\n#### STEP 2:  CONNECT TO WIFI BASED ON SPIFFS CONFIGURATION\n\nIf reading configuration from the SPIFFS was successful, there is a chance an SSID and password were provided there, so ColdBoot attempts to connect to WiFi. \n\nIf SPIFFS was not available **or** *config.json* file was not available, the step 2 is skipped. \n\n \n\n#### STEP 3:  PROVISION CONFIGURATION FROM THE USER\n\nIf device was able to get onto the WiFi network as part of step 2, this step is skipped. \n\nAs this point, device creates a WiFi AP point and creates a simple web-form in order to collect configuration parameters from the user.  AP SSID is **ESP8266-\\\u003cdevice-id\\\u003e** or**ESP32-\\\u003cdevice-id\\\u003e**. \n(Example: ESP8266-dac26e)\n\nEnd user needs to connect to the AP and navigate to http://10.1.1.1\n\n![Windows 10 Network Connect Example](https://github.com/arkhipenko/EspColdBoot/blob/master/pictures/ap.png)\n\n \n\nA full web-form would look like this:\n\n![](https://github.com/arkhipenko/EspColdBoot/blob/master/pictures/form.png)\n\nA reduced web-form based on the step 1 example *config.json* file would look like this:\n\n![](https://github.com/arkhipenko/EspColdBoot/blob/master/pictures/form-reduced.png)\n\n\n\nOnce user hits Submit button, device attempts to connect to WiFi again and again until successful. \n\nDevice will reboot after 10 minutes of inactivity.\n\n  \n\n#### STEP 4:  READ CONFIGURATION FROM HTTP SERVER\n\nIn case a configuration URL is provided, device will attempt to read and parse configuration parameters from the http server. \n\nThere are two choices here:\n\n- You can provide a path to the server where specific configuration files are stored per each device, or\n- you can provide a path to a configuration file directly (in this case a multiple devices could read the same file) \n\nIf only a folder path is provided, **ColdBoot** will add device ID and version, so configuration requested is presumed to be unique. E.g., for device id ESP8266-dac26e, the URL will look like:\n\n​\t\thttp://ota.home.lan/esp/config/coldboot-dac26e-1.0.0.json\n\n(provided http://ota.home.lan/esp/config/ is your configuration server)\n\nAlternatively, you can specify a direct file URL like:\n\n​\t\thttp://ota.home.lan/esp/config/iotdevice.json\n\nIf **ColdBoot** determines that a valid URL was not provided, this step is skipped as **optional**. \n\n \n\n#### STEP 5: UPDATE FIRMWARE FROM AN OTA SERVER\n\nAt this point ColdBoot assumes there is a valid URL to an OTA update server available. \n\nDevice will attempt to perform OTA firmware update based on the provided URL. \n\nThere are two choices here:\n\n- You can provide a path to the server where specific binary files are stored per each device, or\n- you can provide a path to a binary file directly (in this case a multiple devices could update based on the same file) \n\nIf only a folder path is provided, **ColdBoot** will add device ID and version, so OTA requested is presumed to be unique. E.g., for device id ESP8266-dac26e, the URL will look like:\n\n​\t\thttp://ota.home.lan/esp/bin/coldboot-dac26e-1.0.0.bin\n\n(provided http://ota.home.lan/esp/bin/ is your OTA server URL)\n\nAlternatively, you can specify a direct file URL like:\n\n​\t\thttp://ota.home.lan/esp/bin/iotdevice.bin\n\n\n \n#### STEP 6: REBOOT\n\nIf everything goes well, step 6 should not be reached as device will reboot at the end of successful OTA update at step 5. \n\nHowever, if OTA update fails, device will wait for 10 seconds and reboot.\n\n \n\n### FOLDERS:\n\n**data** - SPIFFS image to be uploaded to the device if provisioning via SPIFFS is desired. Must contain a JSON file called *config.json* in the root folder. \n\n**binary** - a pre-compiled esp8266 binary (assuming 4Mb Flash size, 2Mb SPIFFS size, 1Mb OTA size) which could be flashed directly to the chip as part of the manufacturing process\n\n\n \n### EXAMPLE:\n\nBelow is a terminal output of the real device being provisioned via ColdBoot.\n\nPlease note the application ID changes to **success-...** after OTA is done. \n\n```\nESP8266 ColdBoot v1.0.0\n\nESP8266 ID: ESP8266-dac26e\n\nFull Application Version: coldboot-dac26e-1.0.0\n---------------------------------------------\n\nSTEP 1:\n\n \u003e Reading configuration file from SPIFFS if present\n \u003e SUCCESS.\n\nSTEP 2:\n\n \u003e Configuration read from SPIFFS:\n \u003e Title\t:\tColdBoot Initial Config\n \u003e SSID\t:\t\u003cyour wifi ssid\u003e\n \u003e Password\t:\t\u003cyour wifi password\u003e\n \u003e Config\t:\thttp://ota.home.lan/esp/config/\n \u003e OTA\t:\t\u003cpath to OTA firmware\u003e\n \u003e fields\t:\t2\n \u003e Current count = 6\n \u003e Current size  = 157\n\n \u003e Attempting WiFi connection ............................................................ WiFi connection timeout\n \u003e WiFi connection unsuccessful.\n\n\nSTEP 3:\n\n \u003e Provisioning configuration from the user\n\n\tNavigate to  http://10.1.1.1  and fill out the form\n\tProvide WiFi SSID and password\n\tas well as URLs for Configuration and/or OTA\n\n \u003e Bootstrapping SUCCESS.\n \u003e Configuration after Bootstrap:\n \u003e Title\t:\tColdBoot Initial Config\n \u003e SSID\t:\tdevices\n \u003e Password\t:\t********\n \u003e Config\t:\thttp://ota.home.lan/esp/config/\n \u003e OTA\t:\t\u003cpath to OTA firmware\u003e\n \u003e fields\t:\t2\n \u003e Current count = 6\n \u003e Current size  = 142\n\n \u003e Attempting WiFi connection .............\tWiFi connected\n \u003e IP address: 192.168.122.65\n \u003e SSID: devices\n \u003e mac: 98:F4:AB:DA:C2:6E\n\nSTEP 4:\n\n \u003e Checking if configuration should be read from an HTTP server\n \u003e Attempting to read config from this URL:\n   http://ota.home.lan/esp/config/coldboot-dac26e-1.0.0.json\n \u003e SUCCESS.\n \u003e Dictionary after HTTP config:\n \u003e Title\t:\tColdBoot Initial Config\n \u003e SSID\t:\tdevices\n \u003e Password\t:\t********\n \u003e Config\t:\thttp://ota.home.lan/esp/config/\n \u003e OTA\t:\thttp://ota.home.lan/esp/bin/\n \u003e fields\t:\t2\n \u003e Current count = 6\n \u003e Current size  = 148\n\n\nSTEP 5:\n\n \u003e Checking for the OTA provisioning URL\n \u003e Attempting OTA Update from this URL:\n   http://ota.home.lan/esp/bin/coldboot-dac26e-1.0.0.bin\n\n ets Jan  8 2013,rst cause:2, boot mode:(3,7)\n\nload 0x4010f000, len 3456, room 16 \ntail 0\nchksum 0x84\ncsum 0x84\nva5432625\n@cp:0\nld\nColdBoot v1.0.0\n\nESP8266 ID: ESP8266-dac26e\nAppVersion: success-dac26e-1.0.0\n```\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farkhipenko%2Fespcoldboot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Farkhipenko%2Fespcoldboot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farkhipenko%2Fespcoldboot/lists"}