View source for Electronics project notes/ESP notes

{{#addbodyclass:tag_tech}}
{{electronics notes}}


See also [[Electronics project notes/Microcontroller and computer platforms]]


<!--
==Software==


The IDE (such as it is) is closed-source, though the [https://github.com/espressif/esp-idf ESP-IDF] for ESP32 is open sourced 


Espressif provide a closed-source SDK with an API.
-->

==Hardware, and the minimal boards==

WiFi-capable microcontrollers.

You can run code on the microconroller, alongside the wifi code.

It is also sometimes used standalone, with another microcontroller using it for the wifi.


See [[Electronics_project_notes/Microcontroller_and_computer_platforms#ESP_series]] for wider context.


===ESP8266===

ESP8266
* Based on Xtensa LX106 microprocessor (a 32-bit RISC CPU)
* ~160KB SRAM
: often at 80 MHz {{comment|(can be run faster at 160MHz though people report this breaks code that didn't expect that)}}
* WiFi b/g/n (no bluetooth) 
:: apparently people have got it to send on the order of ~10mbit/s but don't count on that
:: The given SDK effectively shares the CPU cooperative-multitasking style, and you must yield time to the wifi code at least every few hundred ms and preferably more often{{verify}}
* 17 GPIO, 2 SPI, 2 I2S, 2 UART, 1 I2C, and a 10-bit ADC (pin overlap)
* no hardware PWM (though you get a decent rate out of via timers)



ESP8266 itself is a SMD IC and you ''probably'' want to get it on a board helping you along, (see e.g. http://esp8266.net/ for details), because at the least you'll want it connected to flash.
It's hard to get it without unless you buy just the chip in bulk, though.


{{zzz|many boards|
There were a whole slew of different boards, popular at different times. At first we had

Initially from espressif, who had board variants called ESP-WROOM-''something''.

More common are the Ai-Thinker ones, and derivatives, often one of:
* {{imagesearch|ESP-01}} - exposes little useful IO, used mostly as a "add WiFi to existing project" board
* {{imagesearch|ESP-05}} - also exposes little IO. Allows better antenna than 01. Discontinued?{{verify}}
* {{imagesearch|ESP-12}} - exposes more things, making it more useful as a standalone uC
:: though physically it's not so easy to use ''by itself'', it is the core of various larger PCBs
* {{imagesearch|ESP-201}} - easier to use on a breadboard
: ...and yeah, a bunch more of these exist.}}


You now may prefer more complete prototyping boards, such as the NodeMCU or WeMOS or HUZZAH 

Most build on the ESP-12, and add things like USB-to-serial and voltage regulation. (see below)

The size of flash will vary.

===ESP8285===

Compatible with ESP8266, but smaller because it has flash integrated (1MiB for ESP8285N08, 2MiB for ESP8285H16).

There seem to be some variant boards here too, at least:{{verify}}
: {{imagesearch|ESP-M1 board|ESP-M1}} - antenna connector
: {{imagesearch|ESP-M2 board|ESP-M2}} - onboard antenna
: {{imagesearch|ESP-M3 board|ESP-M3}} - onboard antenna
: {{imagesearch|ESP-01M board|ESP-01M}}


https://www.espressif.com/sites/default/files/documentation/0a-esp8285_datasheet_en.pdf

===ESP32===
{{stub}}

'''The earlier variants''' we saw (no particular signifier{{verify}})
* CPU: dual or single-core Tensilica Xtensa LX6 {{verify}} 
* [[WiFi]]
* [[Bluetooth 5 LE]]
* often at 160MHz (can be run faster), ~20% CPU used for wireless {{verify}}
* https://www.espressif.com/en/products/hardware/esp32/overview
* https://www.espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf
* ~520K SRAM
* Four timers
* more IO than a ESP8266: thirty-six GPIO, four SPI, two I2S, 3 UART{{verify}}, 2 I2C, a 12-bit ADC, two 8-bit DACs 
:: but note: pin overlap, and boards may not break out everything 
::: because they use things internally, like GPIO used to access flash
::: because they are smaller
::: because there are just a bunch of boards out there. Also makes finding pinouts slightly interesting.


<!--
Even for just the first few, there seem to be various different boards
: a 30-pin variant 
: a 32-pin variant, e.g. [https://circuits4you.com/2018/12/31/esp32-devkit-esp32-wroom-gpio-pinout/]
: a 36-pin variant, e.g. 
: a 38-pin variant, e.g. [https://randomnerdtutorials.com/esp32-pinout-reference-gpios/]
: a 42-pin variant, e.g. [https://docs.espressif.com/projects/esp-idf/en/latest/esp32s2/hw-reference/esp32s2/user-guide-saola-1-v1.2.html]

ESP-WROOM-32

-->


'''ESP32-S2'''
: CPU: single-core Tensilica Xtensa LX7, up to 240MHz
: 320 KB [[SRAM]]
: [[WiFi]]
: (no Bluetooth {{verify}})
: USB OTG
: some variants have 2MByte{{verify}} embedded [[PSRAM]] (R2 in ESP32 model name, e.g. ESP32-S2R2, ESP32-S2FN4R2, but it's less obvious to tell by the board)
: https://www.espressif.com/en/products/socs/esp32-s2
: https://www.espressif.com/sites/default/files/documentation/esp32-s2_datasheet_en.pdf


'''ESP32-C3'''
: CPU: single-core RISC-V, up to 160 MHz
: [[Bluetooth 5 LE]]
: [[WiFi]]
: 400KB SRAM
: https://www.espressif.com/en/products/socs/esp32-c3
: https://www.espressif.com/sites/default/files/documentation/esp32-c3_datasheet_en.pdf


'''ESP32-S3'''
: CPU: dual-core Tensilica Xtensa LX7, up to 240MHz
: [[Bluetooth 5 LE]]
: [[WiFi]] (b/g/n)
: variants with 2, 8, or 16MB internal '''PSRAM''' <!-- (but not a lot of internal flash at the same time?{{verify}}) -->
: USB OTG {{verify}}
: 512KB SRAM
: https://www.espressif.com/en/products/socs/esp32-s3
: https://www.espressif.com/sites/default/files/documentation/esp32-s3_datasheet_en.pdf



'''ESP32-C6'''
: [[Bluetooth 5 LE]]
: [[WiFi]] 802.11ax (also b/g/n support)
: [[802.15.4]]
: CPU: RISC-V core (up to 160MHz) and low-power RISC-V core (up to 20MHz)
: 512KB SRAM
: https://www.espressif.com/en/products/socs/esp32-c6
: https://www.espressif.com/sites/default/files/documentation/esp32-c6_datasheet_en.pdf


'''ESP32-H2'''
: [[Bluetooth 5 LE]]
: [[802.15.4]] (zigbee)
: (no wifi)
: CPU: RISC-V, up to 96MHz
: 320KB SRAM 
: https://www.espressif.com/en/products/socs/esp32-h2
: https://www.espressif.com/sites/default/files/documentation/esp32-h2_datasheet_en.pdf


<!--
'''ESP32-P4'''
: https://www.espressif.com/en/news/ESP32-P4


A bunch have secure boot, 
and a trusted execution environment.


ESP-IDF rather than ESP-SDK?

-->

<!--

Of the above, only S2 and S3 speak USB natively  {{comment|(other boards will likely have a USB-serial IC)}}
: USB serial (S3, fixed to CDC-ACM) and 
: USB OTG (S2, S3)

USB 2.0 specification (S2 not at 480 Mbit/s)


The [https://docs.espressif.com/projects/esp-idf/en/latest/esp32s2/api-reference/peripherals/usb_device.html S2] and [https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/api-reference/peripherals/usb_device.html S3] stack seem to be identical


-->


See also:
* https://en.wikipedia.org/wiki/ESP32
* http://esp32.net/
* https://www.espressif.com/en/products/hardware/esp32/overview
* https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf

* https://hackaday.com/2021/02/08/hands-on-the-risc-v-esp32-c3-will-be-your-new-esp8266/

===see also===
<!--


https://blog.squix.org/2015/03/esp8266-module-comparison-esp-01-esp-05.html


-->

==Some DIYer-geared ESP8266 boards==

May add
* breakout into something easier to solder

* USB-to-serial, often one of [[CH340]], [[CP2101]], [[PL2303]]
: exceptions include the Huzzah

* Regulator from 5V input --  particularly if it has USB, to be powered off it

* Reset button, GPIO (boot related) button


===Huzzah===
[[File:Huzzah.jpg|thumb|right|170px|A Huzzah, and some poor soldering skills]]
Adafruit huzzah:

Based on ESP-12 

Power:
* The board has a 500mA LDO regulator that you should feed 4-6V
:: V+ and Vbat both go to this LDO, separated via Schottky diodes
:: and V+ is also on FTDI header, so that you stably can power the chip while programming it (...from a powered hub / port)
:: if you have your own regulation, you can bypass the LDO regulator by connecting the LDO pin to ground


IO:
* TX and RX are used for bootloading, and for serial control (exposed in two places on this board, to make FTDI plug easier) 
: RX is 5V safe (and Vcc goes to the regulator) so you can use a generic 5V serial cable

Note: no USB

<!--
64 KiB of instruction RAM
96 KiB of data RAM
4 MB of QIO FLASH (32 Megabits)
-->

* https://www.adafruit.com/product/2471
* https://learn.adafruit.com/adafruit-huzzah-esp8266-breakout?view=all

===WeMOS ESP8266===

[[File:Wemos.jpg|thumb|220px|right|Wemos D1 {{comment|(where I removed the barrel jack for some reason)}}<br/>and size of the D1 mini (this might be a non-WeMOS copy?)]]

'''WeMos D1''' is a Arduino-sized board, partially compatible
: and a revision "D1 R2", with minor difference in pins between the two.
: https://wiki.wemos.cc/products:d1:d1



<br/>

'''Wemos D1 Mini''' are smaller boards, specifically:
: '''D1 Mini Lite'''
:: ESP-8285 based, 
:: 1MB Flash
:: PCB antenna
:: https://www.wemos.cc/en/latest/d1/d1_mini_lite.html

: '''D1 Mini'''
:: ESP-8266EX based
:: 4MB Flash
:: PCB antenna
:: https://www.wemos.cc/en/latest/d1/d1_mini.html

: '''D1 Mini Pro'''
:: ESP-8266EX based
:: 16MB Flash
:: Lithium battery pin, charger chip
:: PCB antenna + Antenna connector
:: https://www.wemos.cc/en/latest/d1/d1_mini_pro.html


'''Power'''

<!--
D1 has a 0.5A 3.3V LDO regulator and some comparison/switching, 
: If no Vin < 3.3V, it switches VUSB to 5V

Meaning it deals with 
: ? on the bus socket
: 5V from USB
: ~4.5 to 5.5V from the 5V pin (possibly not at the same time as 5V?)


Keep in mind that variants that can power Vusb from Vin tend to have a protection diode that lowers that voltage.{{verify}}


Mini has a different but similarly-specced regulator
[https://wiki.wemos.cc/_media/products:d1:mini_new_v2_2_0.pdf]



-->

===NodeMCU devkit===

NodeMCU itself refers to the firmware.
It'll run on any ESP based board, really.

[[File:nodemcu.png|thumb|right|555px]]

For clarification, there is also a breadboardable piece of hardware called the 
The 'NodeMCU Devkit' is the name of a specific board [https://github.com/nodemcu/nodemcu-devkit],


There seem to be three board that carry this name. Image on the right from this post:
[https://www.reddit.com/r/esp8266/comments/9q3314/nodemcu_v1_v2_v3_size_and_pinout_comparison/].{{verify}}

===Other===


==Some DIYer-geared ESP32 boards==


===Wemos ESP32===


D32, based on [[ESP32]]
: '''D32''' 
:: Lithium battery pin, charger chip
:: https://www.wemos.cc/en/latest/d32/d32.html

: '''D32 Pro'''
:: Lithium battery pin, charger chip
:: MicroSD socket
:: 4MB PSRAM
:: https://www.wemos.cc/en/latest/d32/d32_pro.html

(with some revisions)


===Huzzah32===
https://www.adafruit.com/product/3405


===ESP32 DevKit-C===
https://www.espressif.com/en/products/devkits/esp32-devkitc/overview


===No-name===

There's a bunch of ebay/aliexpress boards that are perhaps best distinguished by some physical things like
pin count, (lack of) antenna overhang, and such 

Consider e.g. these: https://www.studiopieters.nl/esp32-pinout/

<!--
https://aliexpress.com/item/4000093185394.html
-->

===LOLIN32 ESP32===
https://www.tinytronics.nl/shop/en/development-boards/microcontroller-boards/with-wi-fi/wemos-lolin32-esp32-cp2104

===D1 Mini ESP32===
https://www.az-delivery.de/products/esp32-d1-mini

===M5Stamp===
https://shop.m5stack.com/products/m5stamp-pico-diy-kit

=On firmware=
==Flashing new firmware==
{{stub}}


'''nodemcu pyflasher'''
: basic GUI that is a wrapper around esptool.py
: easier to use
: you need to install wxpython and pyserial (e.g. through {{inlinecode|pip install wxpython pyserial}})
: https://github.com/marcelstoer/nodemcu-pyflasher


'''esptool.py'''
: came from the community, now also adopted by espressif
: you need to install python


'''ESP Flash Download tool'''
: in theory more flexible, but the interface is hard to understand
: https://www.espressif.com/en/support/download/other-tools



See also:
* https://nodemcu.readthedocs.io/en/master/flash/


====On flash mode====

Apparently [https://github.com/espressif/esptool/#flash-modes]
: ESP8266 ESP-12 boards uses DIO
: most other ESP8266 board (e.g. ESP-01 and ESP-07) use QIO
: ESP8285 uses DOUT
: ESP32 uses DIO

Since this is about wiring, you can't be ''entirely'' use until something fails to flash.

Is this just about upload speed or also about execution speed?{{verify}}



On some bare-bones boards you may need to manually get it into programming mode.

e.g. on ESP8266-01 you need to tie GPIO0 to Gnd {{verify}} at reset time.
Various boards will have two buttons to make this easier.

====What's this address stuff?====

In basic cases you put the firmware at the start of flash (0x0),

If you have distinct blocks to go to specific addresses, you'll probably get instructions for it.

==Firmware alternatives==
{{stub}}


Everything shares the same SDK underneath, 
but what is added on top, and the thing you interact with, varies.


===AT commands firmware===

The '''AT commands firmware''' (Espressif?) is useful if you want to use the ESP as a separate board that does WiFi for you.

You communicate over it via serial (RX and TX serial pins), and controlling how it communicates. 

You'll still need to manage how it connects to access points, and set up TCP and UDP connection.

<!--
You can update firmware through the network - but do have a backup plan for when that breaks things
-->


https://room-15.github.io/blog/2015/03/26/esp8266-at-command-reference/

https://www.electrodragon.com/w/ESP8266_AT-Command_firmware

https://bbs.espressif.com/viewtopic.php?f=10&t=362 - for espressif firmware?


https://tttapa.github.io/ESP8266/Chap07%20-%20Wi-Fi%20Connections.html

===NodeMCU firmware (Lua)===

The '''NodeMCU firmware''' wraps Espressif's SDK (and primarily for the ESP8266) with a Lua interpreter, which hooks into a bunch of C libraries and pure-lua libraries.

There is now also an RTOS variant for the ESP32 (and not ESP8266, because of the higher memory use) which 


There are a whole bunch of C libraries you can add.
: A little more controlled, but more work, is https://github.com/nodemcu/nodemcu-firmware
: The easier way for tinkerers is to use the online build service: https://nodemcu-build.com/

Including more modules will increase the flash size (you usually don't care) but often also the RAM size



'''Lua coding for that firmware'''

You can use one of various tools to upload lua files, which itself is (relatively basic) serial-port stuff. Options include:

ESPlorer
: java based IDE, fiddly but it works
: https://esp8266.ru/esplorer/
: https://github.com/4refr0nt/ESPlorer

luatool [https://github.com/4refr0nt/luatool]
: CLI
: uploads Lua files to ESP8266 modules running nodemcu firmware

nodemcu-tool
: CLI
: up/down lua files, manage filesystem

esp8266 lualoader [http://benlo.com/esp8266/]

...and various other tools people have built.


See also:
* https://nodemcu.readthedocs.io/en/master/en/modules/net/
* https://github.com/nodemcu/nodemcu-firmware
* https://nodemcu.readthedocs.io/en/master/
* https://nodemcu.readthedocs.io/en/dev/lua-developer-faq/


===Other interpreters people have built onto the SDK===

[http://esp8266.net/ this page] lists variants on idea of the interpreting firmware but for other languages, 
like python, JS, Basic, Forth, Lisp, and support from some other embedded platforms.


The idea ends up being the same - flash its firmware, later upload code via the serial port (and possibly over the air)


===Arduino===

<!--
The Arduino IDE can be told to deal with ESP8266. 

It too builds on the SDK, but exposes things in C, with the Arduino names you may be more comfortable with,
and is a compile-binary-firmware-and-upload deal you're used to.


There are some footnotes, e.g. 
more considered care keeping the WiFi sable, 
some timing details for libraries that assume classic 16MHz AVR boards).
Some higher-level functionality is more work than it is in Lua firmware.


Yet if you're used to Arduino IDE, or have some arduino libraries you want to use without figuring out how to bolt them into lua, 
then this can be preferable.

Which one is easier depends on what you're doing, and what code you already have.





See the documentation "Flash layout", but basically it contains:
* bootloader {{verify}}
* Sketch 
* (OTA update sketch)
* File system (SPIFFS)
* EEPROM storage
* wifi config (SDK)

including espressif SDK?{{verify}}


Your sketch can either be flashed as part of it, alongside it, or you can use SPIFFS.


SPIFFS (SPI Flash File System)[https://github.com/pellepl/spiffs] uses part of the flash to store data via a simple file-like API. The Arduino IDE asks you how large your flash chip is, and how much to assign to SPIFFS.


Over-The-Air sketch updates are possible. 
Has a few added requirements, like that the flash should be able to store the old and new sketch;
the new one needs to be verified, and the old one will be overwritten after reboot {{verify}}


See also:
* https://arduino-esp8266.readthedocs.io/en/latest/

* https://nodemcu.readthedocs.io/en/master/en/getting-started/

* https://github.com/esp8266/Arduino
-->

===PlatformIO===
<!--
PlatformIO[https://platformio.org/] aims to unify different boards (currently mostly PIC, AVR, ESP8266, STM32 and other ARM Cortex.

Has an IDE[https://platformio.org/platformio-ide] built on top of VS code, so inherits a bunch of nice tools (and a good editor - Esplorer and Arduino's are sort of shitty).

See [[PlatformIO]]
-->



==Lua firmware notes==

===Some lowish level notes===

Keep in mind that some standard Lua modules (e.g. {{inlinecode|io}}, {{inlinecode|os}}, {{inlinecode|debug}}) are removed, and others provide ''similar'' function (e.g. {{inlinecode|[https://nodemcu.readthedocs.io/en/release/modules/node/node node]}}, {{inlinecode|[https://nodemcu.readthedocs.io/en/release/modules/file/ file]}}).

: So ''some'' Lua code you find around (e.g. for raspberry Pi) will need changes, with some specific knowledge of the argument differences.

: And since {{inlinecode|debug}} is missing, debug mostly consists of print statements.
: There are other practical differences, like that {{inlinecode|print(string)}} is mainly just {{inlinecode|uart.write(0, string)}}


Running code off flash is done with cached memory mapping, which is basically why there is one SPI interface ''you'' cannot use


The '''event/tasking system''' is roughly three queues, a high priority one (for hardware related tasks), medium (for timer and event stuff), and low (everything else)
: no task can pre-empt others (priority isn't relevant once it's started), 
:: so ideally no task should run longer than a dozen milliseconds 
::: ''if'' you want things like wifi (or any other code-mediated hardware) to work smoothly
::: and sometimes less so that your ''own'' tasks work smoothly but this can be less critical
: if a task takes over 500ms it'll trigger the watchdog (unless you explicitly feed it, but in most cases that is bad design)
{{comment|(there are also ISRs in C for time-critical stuff but you probably don't want to touch that. They can interrupt tasks, but only up to ~10usec)}}


Calling various functions in net, tmr, wifi, and some others will (in part because they are C) amount to queueing their code as tasks. So
: They will not run until after the current lua task is done. 
L They will not ''necessarily'' be the next task (but many will be high priority so this is ''moderately'' likely) 
: being in that queue uses a little RAM until they actually execute
:: (which is one of a few reasons why event/callback style coding is recommended)


Errors will trigger a panic, which then leads to triggering the watchdog, and a reboot
: this is useful for recovery
: but not always for debugging because even just a typo may cause a reboot before any error gets printed


Flash not used for firmware is provided via {{inlinecode|file}}
: classically SPIFFS, now moving to LittleFS
: (Confusingly, LFS, Lua Flash System, is a different thing https://nodemcu.readthedocs.io/en/release/lfs/ )
: note that {{inlinecode|file}} can also be used to read/write SD cards
: https://arduino-esp8266.readthedocs.io/en/latest/filesystem.html



The float versus int builds:
: working in float is more to specs, and generally recommended
: working in integers is faster but breaks the specs a little, so also some code.



The SDK triggers startup code, 
: which initializes lua, 
: runs init.lua
: listens interactively to UART0
:: defaults to 9600 baud. ESPlorer changes speed by sending a uart.setup() command, then attempting to reconnect {{verify}}


====Coding using events, timers, and coroutines====
{{stub}}


Tasks run to completion and cannot be [[pre-empting|pre-empted]]. 

Running too long will trigger the watchdog, and before that will make wifi code break or be choppier.

So it's suggested to try keeping tasks under 10ms, also for the responsiveness of responding to events. 


In general, try to do things event-based, using callbacks.

It's generally useful to put code in a timer, or use a timer as an event loop checker

Note that since timers and callbacks are tasks that don't pre-empt (and that timers are software timers), they may get scheduled later than you think. 
Also, don't set timers faster than they'll take.
<!--
(apparently timers have higher scheduling priority?)
-->

Longer calculations are probably best done in smaller chunks


Can you use coroutines?{{verify}}


Keep ISRs under 10us, or wifi will break.

I2S canbe DMA'd, no other peripherals can{{verify}}

==="Waiting answer from ESP - Timeout reached. Command aborted"===

(in ESPlorer)

This can be 
* a bug related to use of CR-style newlines[https://github.com/nodemcu/nodemcu-firmware/issues/784] (where the firmware expects CRLF{{verify}}), but only on specific commands.
: It's particularly file transfers that will be broken.
: This could be fixed on both sides, but the easier may be to get a newer firmware build {{verify}}
: https://github.com/nodemcu/nodemcu-firmware/issues/784


* the serial connection crapping out for some reason {{verify}}
: I seemed to have it one one board, possibly power problems?

===modules, packages, and compilation===
<!--
Compilation is useful in that interpreting every time takes noticeable RAM. 

In lua in general, 
* '''dofile('name.lua')''' loads and executes.

* '''require('name')''' caches results so will only do so once.
: also returns the handle, which makes sense when these things are modules.
: based on name, so picking a name of an existing module makes (consider in particular internal names and C modules) is not going to work


dofile can be useful when reloading live,
but require is cleaner in general,
and lets you assign 



In nodemcu
* node.compile("thing") takes thing.lua and saves compiled bytecode into thing.lc
: which is mostly a comibination of string.dump(function) and writing that to a file{{verify}}
: keep in mind that while running an lc saves some ram, compilation itself also needs RAM
:: so either do it once, interactively, or do it before anything loads?
:: You ''can'' also cross-compile it, then upload that instead, but this may be more work than is worth it.


* nodemcu's implementation of require means require("thing") will look for thing.lc before thing.lua

* or you could do dofile("thing.lc")




https://nodemcu.readthedocs.io/en/release/compiling/





'''Modules and packages''' are more a basic Lua thing.

lua does not provide packages, in the sense of namespacing.


We can do it ourselves with tables, though. Say we create a lua file containing
 ourmod = {}

 ourmod.pi = 4
 
 function ourmod.addpi(a)
   return ourmod.pi+a
 end

 return ourmod


There's some further habits. You can e.g. do 
 local P = {}
 ourmod = P

 P.pi = 4

 function P.addpi(a)
   return P.pi+a
 end

 return ourmod
...to save a little typing and space.

We can fake private functions by declaring them local in the file (and not assigning them to P/that global).

A slightly more explicit variant of that is to forget this P business, declare everything local, and explicitly list everything you want public, e.g. finishing with
 ourmod = { addpi=addpi,   pi= pi, }


Notes:
* That final return isn't strictly necessary because we assigned 'ourmod' as a global,


You will also see the fragment
 local P = {}
 if _REQUIREDNAME == nil then
   complex = P
 else
   _G[_REQUIREDNAME] = P
 end
Or, since 5.1 this can be done slightly cleaner, start with
 local P = {}   -- package
 modname = ...       
 _G[modname] = P
(where {{inlinecode|...}} is passed in by 


TODO: figure out environments

https://www.lua.org/manual/5.3/manual.html

http://www.inf.puc-rio.br/~roberto/pil2/chapter15.pdf



-->

===On reboots===

====boot/reset cause====
{{stub}}


If you catch enough of the next boot's output, you'll see something like:
 rst cause:2, boot mode:(3,6)


'''boot mode'''

The last part, the boot mode is rarely very interesting.  It indicates 
* where we booted from (which is based on GPIO pin state at boot), and
* how exactly. 

ESP8266: 
: In most cases this will be 3 (Flash), (rather than SD or UART)[https://github.com/esp8266/esp8266-wiki/wiki/Boot-Process#esp-boot-modes]
: ...and if it's not, and not booting as expected, chances are the relevant GPIO pins (GPIO15, GPIO0, GPIO2{{verify}}) are not in the state they should be.  (If you put hardware on these pins, this needs extra care to not affect boot)
: ...or it's the first watchdog reset after a firmware download and soft reboot{{verify}}, which can trigger it trying to do a firmware download ''again'' (e.g. 1,7) {{verify}}, once.{{verify}}

ESP32:
: 0x13 seems to mean SPI_FAST_FLASH_BOOT, which seems typical
: 0x03 seems to mean programming mode (specific variant?)<!--DOWNLOAD_BOOT(UART0/UART1/SDIO_REI_REO_V2)-->





'''rst cause'''

{{warning|I've seen some conflicting lists - TODO: figure out}}


While the '''rst cause''' seems to be the list from 
 0  unknown reason
 1  'Reset due to power-on event', which is effectively normal boot
 2  External reset using reset pin (not for ESP8266?)
 3  Software reset (esp_restart?)
 4  Hardware watchdog (WDT) reset / 



...there is a slightly more informative value you get via [https://nodemcu.readthedocs.io/en/master/modules/node/#nodebootreason node.bootreason()]. It returns 
 rawcode, reason [, exccause, epc1, epc2, epc3, excvaddr, depc ]

That is, it ''usually'' returns two values:
* the first as above{{verify}}  <!--"raw code, not the new "reset info" code which was introduced in recent SDKs"-->

* the second is the extended reset cause, which is one of:
 0  power-on
 1  hardware watchdog reset
 2  exception reset
 3  software watchdog reset
 4  software restart
 5  wake from deep sleep
 6  external reset

..but in the case of exception reset, it also returns more exception information, 
the first of which is tells you [https://arduino-esp8266.readthedocs.io/en/latest/exception_causes.html exception cause] and the rest of which may be useful to for an actual debugger (if you built the image yourself).


<!--
{{search|esp_system.h}}
 0 ESP_RST_UNKNOWN = 0,    //!< Reset reason can not be determined
 1   ESP_RST_POWERON,        //!< Reset due to power-on event
 2   ESP_RST_EXT,            //!< Reset by external pin (not applicable for ESP8266)
 3   ESP_RST_SW,             //!< Software reset via esp_restart
 4   ESP_RST_PANIC,          //!< Software reset due to exception/panic / watchdog?
 5   ESP_RST_INT_WDT,        //!< Reset (software or hardware) due to interrupt watchdog
 6   ESP_RST_TASK_WDT,       //!< Reset due to task watchdog
 7   ESP_RST_WDT,            //!< Reset due to other watchdogs
 8   ESP_RST_DEEPSLEEP,      //!< Reset after exiting deep sleep mode
 9   ESP_RST_BROWNOUT,       //!< Brownout reset (software or hardware)
 10   ESP_RST_SDIO,           //!< Reset over SDIO
-->


I mostly run into {{inlinecode|2 4}} where 4, software reset, which seems to include the ''software'' watchdog{{verify}} (confusingly enough).

{{inlinecode|4 1}} is the hardware watchdog{{verify}}




https://riktronics.wordpress.com/2017/10/02/esp8266-error-messages-and-exceptions-explained/

====Solving and avoiding reboot loops====
{{stub}}

If you manage to get an exception in early code, or trigger the hardware watchdog fairly early, then you may not be able to get the control you need to fix that.

There's always flashing the firmware again, and then wiping the flash.
But that's a bunch of work, annoying during coding/debugging.


One way around that I like is to have init.lua contain something like:
<syntaxhighlight lang="lua">
abort = 0
function load_main()
   if abort ~= 0 then
      print("aborting startup")
   else
      if file.exists('main.lua') then
        print("startup")
        dofile('main.lua')
      else
        print("main.lua does not exist")
      end 
   end
end
print("send  abort=1  to stop boot")
_start_timer = tmr.create()
_start_timer:register(1500, tmr.ALARM_SINGLE, load_main)
_start_timer:start()
</syntaxhighlight>

...and put your real code in main.lua. 

That way, you have a little over a second before anything happens, in which time you can stop startup by sending {{inlinecode|<nowiki>abort=1</nowiki>}} via serial

<!--
I'd previously gotten similar results by putting {{inlinecode|tmr.delay(2000000)}} on top of <tt>init.lua</tt>, but it seems that that doesn't guarantee it will accept input{{verify}}

{{comment|(and don't have to do <tt>file.remove("main.lua")</tt> works too)}}

-->


https://bigdanzblog.wordpress.com/2015/04/24/esp8266-nodemcu-interrupting-init-lua-during-boot/

====On watchdogs====
{{stub}}

There is both a 
* '''hardware watchdog'''
: on by default,  ''can'' be disabled (but there is ''rarely'' good reason to disable it)
: part of the ESP's hardware
: configured at approximately 6 seconds{{verify}}
<!--: basically a fallback for when the higher level code poops itself.
-->



* '''software watchdog'''
: on by default
: C code that digs into the SDK, and amounts to a timer that decrements a counter and, if that counter reaches zero, calls <tt>system_restart()</tt>
: accessible in Lua via tmr.softwd() to set a time, and tmr.wdclr() to feed it
: apparently a value like 0.5 sec [https://nodemcu.readthedocs.io/en/release/lua-developer-faq/], 1.5 sec, or 3.2 sec (reports are mixed; TODO: figure out)


It seems that the SDK's <tt>system_soft_wdt_feed()</tt> feeds ''both''.
: tmr.wdclr() in Lua, and ESP.wdtFeed() in arduino{{verify}}, mostly call system_soft_wdt_feed()
: tmr.delay calls system_soft_wdt_feed while it is counting down (but is otherwise a wait loop, so long ones will mess with wifi{{verify||)
: some libraries will also reset the watchdog in some places <!--
You may run into watchdog issues via libraries too, e.g. [See also https://nodemcu.readthedocs.io/en/master/modules/pwm2/#troubleshooting-watchdog-timeouts pwm2 has a note about it] -->


The short version is that if code does not
: call tmr.wdclr(), OR
: call something that implies tmr.wdclr(), OR
: returns to let the ESP idle
...for a significant time {{comment|(between 0.5 or 6 seconds, see above)}}, it will cause a reset.

Which makes sense.
If you have code that takes more than 500ms without yielding in any way, you are likely breaking other things, not least of which the WiFi code, which can stutter (in smaller ways) if any task takes longer than approx 15ms.


If you do need to do a lot of processing, just make sure you yield occasionally so that that housekeeping can happen.
This may mean rewriting to do small chunks at a time.

In Lua this is sometimes simple, because when you code in an event/callback style the idle task gets control regularly (and its feeds the dog{{verify}} and does the necessary housekeeping{{verify}}).


Keep in mind that it's not too hard to defeated the watchdog (e.g. feed it each loop but get into your own infinite loop) and can make things hang forever, and/or break wifi and other library code.




'''The likeliest problems that trigger the watchdog''' seem to be
* an exception in the code
: if you're me, largely variable typos and nil values you should be checking
: presumably stops the current task so the watchdog 
: to avoid hanging forever, this is cause for reset (via watchdog?)

* triggering a watchdog by having code hang, or take too long to complete

* running out of heap space






<!--
* internally
: tmr.softwd sets soft_watchdog, which is a counter
: a timer callback decrements that counter each 1ms{{verify}}, and calls system_restart() if it reaches 0
: tmr.wdclr does nothing but call system_soft_wdt_feed 
: system_soft_wdt_feed presumably just sets the counter back to the value you gave to softwd()
-->


<!--
https://www.esp8266.com/viewtopic.php?f=13&t=20206

https://www.sigmdel.ca/michel/program/esp8266/arduino/watchdogs_en.html

https://mongoose-os.com/blog/esp8266-watchdog-timer/
-->

====Your own watchdogs====

I have found reasons to have code like "if we didn't manage to do a HTTP fetch in a minute, for ''any'' reason, we probably want to reset" 

...just because there are more reasons for that (that I can't easily check), and most of them will be rare enough that a reset is the easiest clean slate.


You will want to decide which method of [[#manual reset|reset]] you prefer.

===manual reset===

If you have an ESP with USB, it probably has its DTR/RTS wired to GPIO0 and RST, there so you can get it into flash programming mode. [https://tttapa.github.io/ESP8266/Chap06%20-%20Uploading.html], but you ''could'' also self-reset by wiring a GPIO pin to RST and do the same.

In some ways it's the cleanest, because apparently there are a few issues around some internal registers not being reset unless it's a hardware reset.{{verify}}. 
But check that you don't get stray signals.


If you're not bothered by said register problems, then software resets probably using node.restart() is also an option.
<!--(node.restart and and tmr's watchdog call the same underlying C function (<tt>system_restart()</tt>)-->

===Networking===

====TCP server====
<!--
netserver = net.createServer(net.TCP, 10) -- 10 second timeout to disconnect inactive clients
  netserver:listen(8888,function(conn)
      conn:on("receive",function(conn,payload)
        -- receive is triggered for every frame, so with a little buffering
        -- we can effectively stream 
        --print(payload)
      end)
    end)


-->

====UDP server====


====HTTP requests====
{{stub}}

The [https://nodemcu.readthedocs.io/en/release/modules/http/ http] module is quite convenient.

Example:
 http.get(posturl,
           "", -- headers
           function(code, data)
             if (code < 0) then
               print("HTTP request failed")
             else
               print(code, data)
             end
           end
         )

Note that concurrent requests are not supported.

(I think an issue of mine (reported as HTTP client: DNS error code -1, I think) was that I was effectively doing this.)




'''On HTTPS'''

The http module can use the [https://nodemcu.readthedocs.io/en/release/modules/tls/ tls module] which is basically [https://tls.mbed.org/ mbed TLS].

That means you can give it https links and it'll do the TLS part too.
{{comment|(Alternatively, you can do a TLS connection, and e.g. do a bare HTTP 1.0 request over it. See examples using tls.createConnection())}}



'''However''', you basically don't have enough RAM to guarantee that large certificates, or large chains, can be processed properly - the process may easily need 30KByte or 40KByte of heap, which is usually most of what you have.
Also, there is no real [https://en.wikipedia.org/wiki/Server_Name_Indication SNI] support.

So you cannot guarantee all HTTPS requests to arbitrary servers will work, and the best workaround is to only ever send to a server you have precise control over the certificates being send, and possibly self-sign.

==Arduino firmware notes==
<!--


-->
=Some notes=

==Current draw and sleep==
{{stub}}

{{comment|(this is ''broadly'' true for ESP8266, ESP32, just get get a sense of the ballpark. When specifics matter, look them up for a specific board)}}


Estimates:
: Startup might be up to ~400mA for ~40ms[https://www.ondrovo.com/a/20170207-esp-consumption/] (RF calibration maybe?)
: just once and short

: ~200mA actively transmitting radio (though Tx power can be lowered)

: <100mA actively receiving radio  (it helps that it tries to be smart with [[DTIM]]{{verify}})

: CPU but no RF on (i.e. '''modem sleep''')
: 15mA to 70mA, depending on core frequency, amount of cores, ESP variant, readymade board you bought (often on the lower, 25mA end of that?{{verify}})

: ~1mA with '''light-sleep''' (varying a little with DTIM interval)
:: wakeup takes a few milliseconds

: ~0.1mA with '''deep-sleep''', which roughly amounts to 'everything off, waiting to be rebooted from a pulse on RST pin'
:: takes regular boot time, and note that a cold connect to wifi tends to take a few seconds


Note that the ESP32 variants vary on CPU use and sleep details, 
but RF power is basically just determined by range.



On the sleep modes:
* no sleep / active mode
:: ESP32: ~200mA if transmitting, ~100mA if not

* modem sleep
: keeps the CPU on, keeps the wifi on but only listening, and can be woken by [[DTIM]]
: since it times the sleep between AP beacons, this applies only once connected to an AP
: should average maybe ~20mA when not transmitting
: going to modem sleep is automatic once set (and possible), so firmware seems to enable this by default{{verify}}
: NodeMCU: seems to apply automatically once we're connected to an AP{{verify}}

* light sleep - pauses modem, system clock, CPU
: ~1mA ? {{verify}}
: cannot enter light sleep if wifi suspended
: woken via configured GPIO or timer{{verify}}
:: ESP32 can wake up via touch sensitive GPIO{{verify}}
: modem ''and CPU'' are sleeping but can be woken by GPIO, or DTIM{{verify}} 
: wakeup takes ~3ms
: NodeMCU: [https://nodemcu.readthedocs.io/en/master/modules/node/#nodesleep node.sleep()]

* deep sleep leaves on the RTC and almost nothing else
: ~0.01mA or 0.2mA ? {{verify}}
: can apply when not maintaining a WiFi connection.
: you can only explicitly tell it to go to deep sleep (not an automatic thing)
: only the RTC is still powered (and can be used to wake up), 
: woken up a pulse on RST, which can come from our own RTC (if GPIO16/WAKE/D0 is wired to RST)
:: so the call is "deep sleep for this many microseconds" (in an uint32, which implies a 71 minute maximum [https://thingpulse.com/max-deep-sleep-for-esp8266/]
: there are flags controlling 
:: whether wifi will be initialised after such a sleep (you can avoid a current spike if you don't need it)
:: whether a calibration will be done (which you want after longer sleeps{{verify}})
: NodeMCU: [https://nodemcu.readthedocs.io/en/master/modules/node/#nodedsleep node.dsleep()]

* hibernation (ESP32)
: ~3uA ? {{verify}}
: deep sleep on the ESP32 leaves on a low-power coprocessor and the oscillator it needs, hibernation does not. {{verify}}


Note that 
* I need to look up the difference between ESP8266, ESP32

* these currents are the ratings of the ESP itself, things like regulators will add to this.

* These figures are often the use of the raw circuit. If powered via a linear regulator, your will waste more energy. Battery users will care.




https://bbs.espressif.com/viewtopic.php?t=133

https://www.espressif.com/sites/default/files/9b-esp8266-low_power_solutions_en_0.pdf

https://lastminuteengineers.com/esp32-sleep-modes-power-consumption/

<!--
The DTIM stuff is Delivery Traffic Indication Message,
essentially an AP-controlled 
sent within a beacon
-->

==Voltage and damage==
{{stub}}

Power should be 3.3V. {{comment|(Powering from 5V power won't fry it immediately, but is likely to shorten lifespan, some people report sooner rather than later (and seemingly it's the flash that often fails first)}}


The '''ADC''' gets damaged by voltages above 1V, so you probably always want a voltage divider. And possibly a diode to protect it.



"Are ESPs [[5V tolerant]]?"

Officially, no. 


Can you get away with it?

Probably?


There is ''transient'' higher-voltage detection - basically ESD above 6V - quoth the datasheet" ''"All digital IO pins are protected from over-voltage with a [[snap-back]] circuit connected between the pad and ground. The snap back voltage is typically about 6V, and the holding voltage is 5.8V. This provides protection from over-voltages and ESD. The output devices are also protected from reversed voltages with diodes."''

However, 5V tolerance is more about ''continuous'' current/heat the entire structure can deal with. 
There's no mention of it, so the short answer is no.


The ESD protection diodes will probably help a little, and people have experimentally determined that putting 5V on these inputs only sinks a few microamps,

Perhaps the simplest halfway-decent solution is a voltage divider.
Though it comes with 'assuming it does not affect your use' footnote. Particularly high-speed communication often needs a little more care,
so when you're prepared to throw some components at it, there are also other options - see [[level shifting]].


Note that using our 3.3V GPIO to ''output'' to things expecting 5V levels can be safe -- but note it's not great if the 5V side engages a pullups (rather than pulldown).
{{comment|(As in general, it may not always ''work'' due to voltage levels -- 5V TTL is high is above 2V so fine. 5V CMOS is high above 3.7V so won't work. Thresholds can vary a little per device anyway, so check datasheets.)}}.

==On WiFi==
{{stub}}

'''Having it be stable'''

For wifi to be stable, task should yield after ~15ms or so (quoth the SDK{{verify}}).

More may still work because it'll recover, but wifi will be choppier.

When you think tasks may take longer, think some more about event, timer, and corouting style programming.




I also tend to add a "can I DNS-resolve things" test, so that it can reconnect, or switch APs, when one does not work for some reason.

(...which I can still mess up by spamming the ESP with UDP packets)


<!--
It helps to understand task scheduling, and that some SDK calls are asynchronous, meaning they are queued to run after the calling task is finished.  This can make ordering and timing interesting. 

This includes various SDK calls, e.g. wifi.suspend.
-->

<!--

* writing it as a "do a few loops" way, 

* coroutines

* [https://nodemcu.readthedocs.io/en/release/modules/wifi/#wifisuspend suspending wifi] during them, if you don't need it
-->



'''How to tell it about APs'''

The basic way to do credentials is hardcoding one, or maybe a few that code loops through a few stored APs.
This works until you move it, or replace your AP, at which point you have to put in new credentials, probably via usb-serial.


The fancier thing to do is a wifi manager that, if it can't find one of the previously configured AP's, puts the ESP into soft AP mode with a webserver, and lets you set AP via a simple web interface.

For NodeMCU: https://github.com/gfnord/lua_wifimanager

For arduino: https://github.com/tzapu/WiFiManager (slightly nicer)


'''Wifi current draw'''

https://nodemcu.readthedocs.io/en/release/modules/wifi/#wifisetphymode

==On PWM==
<!--


The [https://nodemcu.readthedocs.io/en/release/modules/pwm/ lua pwm module] 
seems to be a 10 bit counter run up to 1000Hz.

The way it's described suggests it's the interrupt-based implementation of PWM (updating pins from the timer interrupt), not hardware PWM.

Which is a little higher CPU at higher rates, and a little jittery, but otherwise quite serviceable.

Note that it does basically means all PWM outputs need to run at the same rate (or a divisor of that rate).


{{comment|(What's confusing is that the datasheet mentions the ESP8266 has four PWM pins, MTDI, MTDO, MTMS, and GPIO4.  If that describes hardware PWM, it seems this is ''not'' used)}}




[https://nodemcu.readthedocs.io/en/release/modules/pwm2/ pwm2] seems similar with lifted limits, meaning it can go up to perhaps 125kHz but CPU (and presumably jitter) use is significant by then.


-->

==On SPI==
<!--
ESPs have multiple SPI buses

ESP8266 seem to have two:
SPI0 CSPI
SPI1 HSPI_HOST


ESP32 seem to have four:
SPI0 - used by the flash cache
SPI1 - used for programming flash (same bus?)
HSPI - free
VSPI - free

No idea what the C, H, and V stand for.


{{search|ESP8266 SPI Overlap & Display Application Guide}}
-->

==Errors==

===serial.serialutil.SerialException: Cannot configure port, something went wrong. Original message: PermissionError(13, 'A device attached to the system is not functioning.', None, 31)===

...when uploading a sketch.

For me this seemed caused by esptool not finding the device in the right state - presumably because I had selected the wrong board variant?

I did get it to work by holding the boot button. 

Which is a problem and solution possibly very specific to my case.