{"schema":"libjg2-1", "vpath":"/git/", "avatar":"/git/avatar/", "alang":"", "gen_ut":1747979227, "reponame":"lws-esp32-factory", "desc":"ESP32 LWS factory image", "owner": { "name": "Andy Green", "email": "andy@warmcat.com", "md5": "c50933ca2aa61e0fe2c43d46bb6b59cb" },"url":"https://libwebsockets.org/repo/lws-esp32-factory", "f":3, "items": [ { "schema":"libjg2-1", "oid":{ "oid": "3034102c638930de2ca9df0bf81baab5fe681e44", "alias": [ "refs/heads/master"]},"tree": [ { "name": "components","mode": "16384", "size":0}, { "name": "main","mode": "16384", "size":0}, { "name": "romfs-files","mode": "16384", "size":0}, { "name": ".gitignore","mode": "33188", "size":91}, { "name": ".gitmodules","mode": "33188", "size":259}, { "name": "LICENSE","mode": "33188", "size":28281}, { "name": "Makefile","mode": "33188", "size":994}, { "name": "README.md","mode": "33188", "size":7256}, { "name": "partitions.csv","mode": "33188", "size":334}, { "name": "sdkconfig","mode": "33188", "size":14366}],"s":{"c":1747731634,"u": 2596}} ,{"schema":"libjg2-1", "cid":"437bfc3b5130624fbc53f9be17358e3d", "oid":{ "oid": "3034102c638930de2ca9df0bf81baab5fe681e44", "alias": [ "refs/heads/master"]},"blobname": "README.md", "blob": "lws-esp32-factory\n\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\n\nThis is a standalone \u003c1MB image intended for the 1MB \u0022factory\u0022 slot on ESP32.\n\nThis image is designed to look after \u0022generic device configuration\u0022... it means:\n\n - Automated generation of 2048-bit selfsigned certs on the device at first boot\n\n - Selecting up to 4 APs the device can connect to along with necessary passphrases\n\n - Updating the user application OTA\n\n - Automated Let's Encrypt certificate acquisition (requires external :443 forwarded\n to the device :443)\n\nYour actual \u0022OTA\u0022 application is something completely different, and has its own 2.9MB\nflash area. This -factory app is designed to take care of all common setup stuff and\nput it in nvs to be shared with the OTA app.\n\nThis now uses HTTP/2 serving from libwebsockets :-)\n\nIt also now supports ws-over-http2 tunelling, meaning all\nthe ws connections and the http actions share the same tls\ntunnel. This makes a massive improvement in speed and\nreduced memory consumption.\n\nAs of 2018-03-14 only Chrome Canary 67 supports this new\nmode, but support in other browsers is coming.\n\n\n\n\n\n\nIt has the following capabilities:\n\nThe first boot after flashing, the device will create its own selfsigned certificate and key.\n\nAfter generating the cert, if there is no AP information yet, the server up automatically at https://192.168.4.1 in AP mode.\n\nThe user can reach -factory subsequently programmatically or by grounding a GPIO (ie, by a button), the default GPIO is IO14.\n\n-factory allows you to select an AP from a scan list and give a passphrase. It supports four AP slots,\nfor, eg, home and work environments, and it handles the scan and acquire of the APs.\n\nOnce it connects, the DHCP information is shown, and it autonomously connects to a configurable server over https to check for updates. The user can select to have it autonomously download the update and restart.\n\nThe user can also upload images by hand. The factory image understands how to update both the 1MB factory slot itself and the single 2.9MB OTA slot using autonomous upload from a server or the browser based file upload.\n\n## Optional default peripherals\n\nIt's not required, but the default code expects\n\n - pushbutton to 0V connected on IO14, with pullup to 3.3V\n\nIf the pushbutton is held down at boot, the user is forced into the factory / Setup mode rather than the OTA application.\n\n**Note:** Default selection of GPIO14 should be changed to another value when [debugging with JTAG](http://esp-idf.readthedocs.io/en/latest/api-guides/jtag-debugging/index.html). Pins reserved for ESP32 JTAG: GPIO12, GPIO13, GPIO14 and GPIO15.\n\n - LED connected via, eg, 330R 3.3V ---|\u003e|-----/\u005c\u005c/\u005c\u005c/\u005c\u005c---- IO23\n\nWhile in factory / OTA mode, the LED flashes dows a PWM sine cycle at about 1Hz. When you press \u0022ID Device\u0022 button in the UI, the LED does the since cycle rapidly for 10s, so you can be sure which physical device you are talking to.\n\n\n## Building and using\n\n1) This was built and tested against esp-idf at 17ac4bad7381e579e5a7775755cc25480da47d97\nfrom Sept 11, 2018. You can force esp-idf to that commit by cloning / pulling / fetching\nthe latest esp-idf and then doing `git reset --hard 17ac4bad7381e579e5a7775755cc25480da47d97`\nin the esp-idf directory.\n\nEsp-idf is in constant flux you may be able to use the latest without problems but if not,\nrevert it to the above commit that has been tested before complaining.\n\n2) Esp-idf also has dependencies on toolchain, at the time of writing it recommends this toolchain version (for 64-bit linux)\n\n[1.22.0-75-gbaf03c2](https://dl.espressif.com/dl/xtensa-esp32-elf-linux64-1.22.0-75-gbaf03c2-5.2.0.tar.gz)\n\n3) Don't forget to do `git submodule init ; git submodule update --recursive` after fetching projects like esp-idf with submodules.\n\n4) After updating esp-idf, or this project or components, remove your old build dir with `rm -rf build` before rebuilding.\n\n### Step 0: Install prerequisites\n\n### 0.1: genromfs\n\nFor Ubuntu / Debian and Fedora at least, the distro package is called \u0022genromfs\u0022\n\nUnder Windows on MSYS2 environment you will need to separately build `genromfs` and add it to the path:\n\n```\ngit clone https://github.com/chexum/genromfs.git\nmake\ncp genromfs /mingw32/bin/\n```\n\n### 0.2: recent CMake\n\nCMake v2.8 is too old... v3.7+ are known to work OK and probably other intermediate versions are OK.\n\nUnder Windows on MSYS2 environment you will need to install cmake: `pacman -S mingw-w64-i686-cmake`\n\n### 0.3: OSX users: GNU stat\n\n```\n $ brew install coreutils\n```\n\n### Step 1: Clone and get lws submodule\n\n```\n $ git clone git@github.com:warmcat/lws-esp32-factory.git\n $ git submodule update --init --recursive\n```\n\n### Step 2: Erase the whole device\n\nClear down the partitioning since we write a custom table and the bootloader\nwill choke if the OTA parts are not initialized like this one time\n\n```\n $ make erase_flash\n```\n\n## Step 3: General build and flash\n\nFirst one time each session set an env var in your shell to override the tty port\n\n```\n $ export ESPPORT\u003d/dev/ttyUSB0\n```\n\nThen you can just do\n\n```\n $ make flash monitor\n```\n\n## First boot\n\nDuring the first boot, there will be a pause of a minute or so while the selfsigned\nTLS certificate is generated.\n\nAfterwards it continues boot normally.\n\n## Using the Setup app\n\n - connect your wifi to the ap \u0022ESP_....\u0022\n\n - In a browser, go to https://192.168.4.1\n\n - Click on the radio button for AP slot 1\n\n - Select your normal AP from the list\n\n - Give the AP password and click the button\n\n - Your ESP32 should associate with the AP without resetting\n\n## Using the lws test apps\n\nThis application is just the factory / setup application.\n\nThe end-user applications are separate projects, see eg\n\nhttps://github.com/warmcat/lws-esp32-test-server-demos\n\nThese are built and loaded slightly differently, ie\n\n```\n $ make lws_flash_ota monitor\n```\n\nThis is because they target the 2.9MB OTA flash area.\n\nThe `build/*.bin` file from the application build may also be uploaded in the setup page upload UI.\n\nNOTE: the first time you flash the OTA application, you need to do it using the\nupload file button or the autonomous update facility in the Factory App. The bootloader\nrequires it to not only be flashed, but marked as bootable.\n\nSubsequently you can just reflash the OTA partition with `make lws_flash_ota` or use the upload or autonomous update stuff in the -factory app.\n\n## Note for Firefox users\n\nFirefox has a longstanding, unfixed bug dealing with selfsigned certs. As you add more exceptions for them,\nfirefox bogs down processing the validity of the certs. Symptoms are slow (eventually very slow) browser\nperformance sending data on the accepted SSL connection.\n\nhttps://bugzilla.mozilla.org/show_bug.cgi?id\u003d1056341\n\nSymptom is your browser box's cpu burns while it sits there. Workaround is to delete the cert8.db file in\nyour firefox user config, on my box it was `~/.mozilla/firefox/blah.default/cert8.db`.\n\nThis isn't related to lws but affects all firefox usage with selfsigned certs...\n\n","s":{"c":1747731634,"u": 2085}} ],"g": 1265,"chitpc": 0,"ehitpc": 0,"indexed":0 , "ab": 0, "si": 0, "db":0, "di":0, "sat":0, "lfc": "7d0a"}