Overhaul flashing docs once again #1587

marcelstoer · 2016-11-09T21:05:42Z

pjsg · 2016-11-10T01:17:22Z

docs/en/flash.md

@@ -28,7 +28,9 @@ Run the following command to flash an *aggregated* binary as is produced for exa
 - `size` is given in bits. Specify `4m` for 512&nbsp;kByte and `32m` for 4&nbsp;MByte.  If unsure, try a smaller size;


Modern versions of the esptool.py actually auto-detect the flash size, so it is probably best to leave out the flash size. This functionality was added about a month ago. We may want to note the flash size issues in some notes somewhere.

Oh nice, just found the PR, thanks. Don't you think it'd make sense to mention that only for esptool.py >= 1.2 you can skip the flash size parameter?

I think that I would recommend leaving the parameter out. However, you should probably note that the esptool is under active development and that if it doesn't work, the first step should be to upgrade to the current version.

pjsg · 2016-11-10T01:18:40Z

docs/en/flash.md

@@ -41,6 +43,8 @@ Source: [https://github.com/nodemcu/nodemcu-flasher](https://github.com/nodemcu/

 Supported platforms: Windows

+Note that this tool was created by the initial developers of the NodeMCU firmware. It hasn't seen updates since September 2015 and is not maintained by the current NodeMCU *firmware* team. Be careful not to accidentally flash the very old default firmware the tool is shipped with.


This tool is actively maintained by espressif (I followed the link to it higher up in the document): https://github.com/espressif/esptool

Hhhuuu? That confuses me... "this tool" refers to the NodeMCU Flasher, it's in that chapter.

However, I didn't realize that esptool.py is now under the Espressif account on GitHub. I'll change https://github.com/themadinventor/esptool to https://github.com/espressif/esptool

pjsg · 2016-11-10T01:20:41Z

docs/en/flash.md


-* The NodeMCU flash filesystem may need to be reformatted, particularly if its address has changed because the new firmware has a much different size than the old firmware.  If it is not automatically formatted, then it should be valid and have the same contents as before the flash operation. You can still run [`file.format()`](modules/file.md#fileformat) to re-format your flash filesystem. You will know if you need to do this if your flash files exist but seem empty, or if data cannot be written to new files. However, this should be an exceptional case.
+* The NodeMCU flash file system may need to be reformatted, particularly if its address has changed because the new firmware is different in size from the old firmware.  If it is not automatically formatted then it should be valid and have the same contents as before the flash operation. You can still run [`file.format()`](modules/file.md#fileformat) manually to re-format your flash file system. You will know if you need to do this if your flash files exist but seem empty, or if data cannot be written to new files. However, this should be an exceptional case.


Can you add a note that says that formatting a file system on a large flash device (e.g. the 16MB parts) can take some time, and so, on the first boot, you shouldn't get worried if nothing appears to happen for a minute.

Ok, I can certainly do that.

marcelstoer · 2016-11-10T20:50:25Z

Philip, I processed your feedback and pushed a new version.

marcelstoer · 2016-11-12T19:20:33Z

I take your thumbs-up as a go for merging.

pjsg · 2016-11-12T22:27:35Z

Yes!

* add u8g.fb_rle display * move comm drivers to u8g_glue.c * disable fb_rle per default * implement file.size for spiffs (#1516) Another bug squashed! * Fix start-up race between UART & start_lua. (#1522) Input during startup (especially while doing initial filesystem format) ran the risk of filling up the task queue, preventing the start_lua task from being queued, and hence NodeMCU would not start up that time. * Reimplemented esp_init_data_default. To work around the pesky "rf_cal[0] !=0x05" hang when booting on a chip which doesn't have esp_init_data written to it. It is no longer possible to do the writing of the esp_init_data_default from within nodemcu_init(), as the SDK now hangs long before it gets there. As such, I've had to reimplement this in our user_start_trampoline and get it all done before the SDK has a chance to look for the init data. It's unfortunate that we have to spend IRAM on this, but I see no better alternative at this point. * Replace hardcoded init data with generated data from SDK The esp_init_data_default.bin is now extracted from the SDK (and its patch file, if present), and the contents are automatically embedded into user_main.o. * Rework flashing instructions Clarifies issues around SDK init data and hopefully clears up some confusion, when paired with the esp_init_data_default changes in NodeMCU. * Fix typo * Fixes the gpio.serout problem from #1534 (#1535) * Fix some issues in gpio.serout * Minor cleanup * fix dereferencing NULL pointer in vfs_errno() (#1539) * add map ids for flash sizes 32m-c2, 64m, 128m in user_rf_cal_sector_set() (#1529) * Somfy/TELIS driver (#1521) * Reduced LUAL_BUFFERSIZE to 256. Should free up some stack (#1530) * avoid task queue overrun for serial input (#1540) Thank you. * Increase irom0_0_seg size for PR build * Improve reliability of FS detection. (#1528) * Version to make filesystem detection more reliable * Improve bad fs detection * Version of printf that doesn't suffer from buffer overflows (#1564) * Small improvement to http client (#1558) * Remove luaL_buffer from file_g_read() (#1541) * remove luaL_buffer from file_g_read() - avoid memory leak when function gets terminated by lua_error - skip scanning for end_char when reading until EOF * attempt to free memory in any case * Change HTTP failures from debug to error messages (#1568) * Change HTTP failures from debug to error messages * Add tag to HTTP error messages * Create macro for error msg and improve dbg msg * Add ssd1306_128x32 for U8G (#1571) * Update CONTRIBUTING.md * Add support to mix ws2812.buffer objects. (#1575) * Add load/dump/mix/power operations on the buffer object * Calculate the pixel value in mix and then clip to the range. * Fixed the two wrong userdata types * Added a couple more useful methods * Add support for shifting a piece of the buffer. * Fix a minor bug with offset shifts * Update to the wifi module (#1497) * Removed inline documentation for several functions and update comments Since documentation is now part of the repository, the inline documentation just adds to the already huge wifi.c * Wifi module: add new functionality, update documentation Functions Added: wifi.getdefaultmode(): returns default wifi opmode wifi.sta.apchange(): select alternate cached AP wifi.sta.apinfo(): get cached AP list wifi.sta.aplimit(): set cached AP limit wifi.sta.getapindex(): get index of currently configured AP wifi.sta.getdefaultconfig(): get default station configuration wifi.ap.getdefaultconfig(): get default AP configuration functions modified: wifi.setmode: saving mode to flash is now optional wifi.sta.config: now accepts table as an argument and save config to flash is now optional wifi.sta.getconfig: added option to return table wifi.ap.config: save config to flash is now optional wifi.ap.getconfig: added option to return table Documentation changes: - Modified documentation to reflect above changes - Removed unnecessary inline documentation from `wifi.c` - Updated documentation for `wifi.sta.disconnect`to address issue #1480 - Fixed inaccurate documentation for function `wifi.sleeptype` - Added more details to `wifi.nullmodesleep()` * Move function `wifi.sleeptype()` to `wifi.sta.sleeptype()` * Fixed problem where wifi.x.getconfig() returned invalid strings when ssid or password were set to maximum length. * fix error in documentation for `wifi.sta.getapindex` * Renamed some wifi functions wifi.sta.apinfo -> getapinfo wifi.sta.aplimit -> setaplimit wifi.sta.apchange -> changeap also organized the wifi_station_map array * Make the MQTT PING functionality work better. (#1557) Deal with flow control stopped case * Implement object model for files (#1532) * Eus channelfix (#1583) Squashed commits included: Bug fixes and final implementation - Added Content-Length: 0 to all headers - Endpoint name checks not using trailing space so cache-busting techniques can be used (i.e., append a nonce to the URL) - Track when connecting so APList scan doesn't take place during (which changes the channel) - More debugging output added to assist in tracking down some issues Added /status.json endpoint for phone apps/XHR to get JSON response Station Status caching for wifi channel workaround + AJAX/CORS - During checkstation poll, cache the last station status - Shut down the station if status = 2,3,4 and channel is different than SoftAP - Add Access-Control-Allow-Origin: * to endpoint responses used by a service - Add a /setwifi GET endpoint for phone apps/XHR to use (same parameters as /update endpoint). Returns a JSON response containing chip id and status code. - Add handler for OPTIONS verb (needed for CORS support) Wi-Fi Channel Issue Workaround - Do a site survey upon startup, set SoftAP channel to the strongest rssi's channel - Compare successful station connect channel to SoftAP's. If different, then defer the Lua success callback to the end. Shut down Station and start the SoftAP back up with original channel. - After the 10 second shutdown timer fires, check to see if success callback was already called. If not, then call it while starting the Station back up. HTTP Response and DNS enhancements - If DNS's UDP buffer fills up, keep going as non-fatal. It's UDP and not guaranteed anyways. I've seen this occur when connecting a PC to the SoftAP and every open program tries to phone home at the same time, overwhelming the EUS DNS server. - Support for detecting/handling pre-gzipped `enduser_setup.html` (and `http_html_backup`) payload. Nice for keeping the size of the `state->http_payload_data` as small as possible (also makes minimization not as critical) - Corrected misuse of HTTP 401 response status (changed one occurrence to 400/Bad Request, and changed another to 405/Method Not Allowed) * Normalized formatting (tabs-to-spaces) * Added documentation * Corrected misuse of strlen for binary (gzip) data. * Added NULL check after malloc * fix vfs_lseek() result checking in enduser_setup and clarify SPIFFS_lseek() return value (#1570) * Fix link * Overhaul flashing docs once again (#1587) * Add chapter about determine flash size plus small fixes * Rewrite esptool.py chapter, move flash size chapter to end * i2c - allow slave stretching SCL (just loop and check) (#1589) * Add note on dev board usage of SPI bus 0 (#1591) * Turn SPI busses note to admonition note * support for custom websocket headers (#1573) Looks good to me. Thank you. Also: - allow for '\0's in received messages * add client:config for setting websocket headers Also: - headers are case-insensitive now * fix docs * fix typo * remove unnecessary luaL_argcheck calls * replace os_sprintf with simple string copy * Handle error condition in file.read() (#1599) * handle error condition in file.read() * simplify loop initialization * Fix macro as suggested in #1548 * Extract and hoist net receive callbacks This is done to avoid the accidental upval binding * Fix typo at rtctime.md rtctime.dsleep -> rtctime.dsleep_aligned

Add chapter about determine flash size plus small fixes

0032843

marcelstoer added this to the Post-1.5.4.1-II milestone Nov 9, 2016

pjsg reviewed Nov 10, 2016

View reviewed changes

Rewrite esptool.py chapter, move flash size chapter to end

bb0a707

marcelstoer merged commit a168449 into nodemcu:dev Nov 12, 2016

marcelstoer deleted the dev-flashing-docs branch November 12, 2016 19:21

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Overhaul flashing docs once again #1587

Overhaul flashing docs once again #1587

marcelstoer commented Nov 9, 2016

pjsg Nov 10, 2016

marcelstoer Nov 10, 2016

pjsg Nov 10, 2016

pjsg Nov 10, 2016

marcelstoer Nov 10, 2016

pjsg Nov 10, 2016

marcelstoer Nov 10, 2016

marcelstoer commented Nov 10, 2016

marcelstoer commented Nov 12, 2016

pjsg commented Nov 12, 2016

		@@ -28,7 +28,9 @@ Run the following command to flash an aggregated binary as is produced for exa
		- `size` is given in bits. Specify `4m` for 512 kByte and `32m` for 4 MByte. If unsure, try a smaller size;

		@@ -41,6 +43,8 @@ Source: [https://github.com/nodemcu/nodemcu-flasher](https://github.com/nodemcu/

		Supported platforms: Windows

		Note that this tool was created by the initial developers of the NodeMCU firmware. It hasn't seen updates since September 2015 and is not maintained by the current NodeMCU firmware team. Be careful not to accidentally flash the very old default firmware the tool is shipped with.


		* The NodeMCU flash filesystem may need to be reformatted, particularly if its address has changed because the new firmware has a much different size than the old firmware. If it is not automatically formatted, then it should be valid and have the same contents as before the flash operation. You can still run [`file.format()`](modules/file.md#fileformat) to re-format your flash filesystem. You will know if you need to do this if your flash files exist but seem empty, or if data cannot be written to new files. However, this should be an exceptional case.
		* The NodeMCU flash file system may need to be reformatted, particularly if its address has changed because the new firmware is different in size from the old firmware. If it is not automatically formatted then it should be valid and have the same contents as before the flash operation. You can still run [`file.format()`](modules/file.md#fileformat) manually to re-format your flash file system. You will know if you need to do this if your flash files exist but seem empty, or if data cannot be written to new files. However, this should be an exceptional case.

Overhaul flashing docs once again #1587

Overhaul flashing docs once again #1587

Conversation

marcelstoer commented Nov 9, 2016

pjsg Nov 10, 2016

Choose a reason for hiding this comment

marcelstoer Nov 10, 2016

Choose a reason for hiding this comment

pjsg Nov 10, 2016

Choose a reason for hiding this comment

pjsg Nov 10, 2016

Choose a reason for hiding this comment

marcelstoer Nov 10, 2016

Choose a reason for hiding this comment

pjsg Nov 10, 2016

Choose a reason for hiding this comment

marcelstoer Nov 10, 2016

Choose a reason for hiding this comment

marcelstoer commented Nov 10, 2016

marcelstoer commented Nov 12, 2016

pjsg commented Nov 12, 2016