2.2. ESP side installation

ESPresso works with an ESP8266 flashed with NodeMCU firmware (the newer the better). You need to run a ‘telnet’ script. You may use script from NodeMCU examples [https://github.com/nodemcu/nodemcu-firmware/tree/master/lua_examples/telnet] or use your own (it should simply redirect all serial output to TCP socket and grab all the data from the socket and send it to the NodeMCU interpreter).

Hint

NodeMCU commands issued by ESPresso do not produce excessive output so both simple and complex telnet scripts work fine.

Simple telnet script is also included in the ESPresso distribution package inside ESP folder.

Note

Simple telnet script from NodeMCU distribution contains a bug that closes connection when an empty string is about to be printed. The script from ESPresso distribution fixes that glitch. Since usual file operations should not produce an empty string output, usage of patched script is optional.

Warning

Telnet script from old NodeMCU docs which was copied to many websites is not working properly with recent NodeMCU versions. Use current one from Github or ESPresso package.

Depending on the way your ESP application is using TCP connection there are different ways to embed the telnet script in your software:

  1. Your app is not using any form of communication. In this case the only thing you need is to enable simple telnet script:

    dofile('simple_telnet.lua')
    

    or complex telnet server:

    local telnet=dofile('telnet.lc')
    telnet:open(nil, nil, 2323)
    

    somewhere in your init.lua file. Since there is no other communication it will not interfere with it.

  2. Your app acts as a client (it does NOT create a server) - it opens outgoing connections (i.e. using http or mqtt modules). Such a situation doesn’t require much attention. Tests showed that even when telnet session to ESP is active, outgoing connections are not interfered. However it may be good idea to disable your app normal operation (that involves using TCP connections) during ESPresso session. Good place to do this is the beginning of the callback function registered in:

    net.server:listen()
    

    in simple_telnet.lua. Regular operation mode of your app may be restored in callback for:

    socket:on("disconnection")
    

    Hint

    Simple telnet script from NodeMCU distribution contains placeholders for that purpose. Look for:

    -- put your device in service mode here (optional)
    

    and:

    -- restore normal operation here (optional)
    

    lines.

  3. Your app is a webserver. Unfortunately it’s not possible to start more than a single server in NodeMCU, therefore it’s not possible for an app to operate and wait for a telnet session simultaneously. However - it doesn’t mean that there is nothing you can do:

    1. You may design a ‘service mode’ of your ESP8266 device. It may be triggered by a special switch or combination of regular buttons. If in service mode your app would start telnet server instead of regular one.
    2. Another option is to develop a server that recognizes if a regular or telnet connection is coming by analyzing some of the very first characters received from socket. Depending of the content received it would pass the payload to the proper function.

    Both options require individual approach that fits to your application.

Warning

Since NodeMCU telnet scripts usually do not implement any authentication procedures (mainly due to platform limitations) you should be certain that your ESP device with telnet service enabled is in safe (i.e. home) network. You should never forward open telnet port of an ESP to a WAN network. If you need to access ESP from outside your network you should consider using VPN. ESPresso works flawlessly over VPN connection.

Note

telnet.lua needs to by uploaded to the ESP for the first time using other uploader (i.e. over serial port). Updating telnet script using ESPresso is however possible.

2.2.1. NodeMCU requirements

ESPresso uses basic set of NodeMCU commands to communicate with ESP. It doesn’t matter if firmware is integer or floating point.

Following modules must be present in the firmware for ESPresso to work:

  • node
  • file (with Object file model support - up-to-date firmware will have this)
  • wifi
  • net

Following modules are optional:

  • tmr (used by ESP restart function if reset delay is configured)
  • adc (used by ADC monitor)