Welcome to ESPresso’s documentation!

Project website: http://www.cielecki.pl

1. General

1.1. Introduction

ESPresso is an ESP8266/NodeMCU file manager and uploader with some distinct features:

  • It connects to ESP directly over TCP/IP port (in other words - over WiFi). It’s not using any serial port (physical nor virtual). No additional software on computer side is required. The only thing you need is to run the daemon script on the ESP side (standard script from NodeMCU docs that redirects serial output to TCP - see ESP side installation).
  • It represents a dual-pane filemanager approach. It’s designed to effectively send files to ESP, compile them and run.
  • It can ‘diet’ uploaded files using LuaSrcDiet on the fly.
  • It’s equipped with a built-in ADC monitor with a simple graph.
  • It’s possible to preview local source Lua files using built-in viewer (with Lua source highlighter), parse and compile them (using local lua compiler).

1.2. License information

ESPresso is a free software provided by Łukasz Cielecki which may be freely distributed, provided that no charge above the cost of distribution is levied, and that the disclaimer below is always attached to it.

The program is provided as is without any guarantees or warranty.

Although the author has attempted to find and correct any bugs in the free software program, the author is not responsible for any damage or losses of any kind caused by the use or misuse of the program.

The author is under no obligation to provide support, service, corrections, or upgrades to the free software programs.

ESPresso uses ueControls components which are distributed under Mozilla Public License Version 1.1 (MPL). You may obtain a copy of the MPL License at http://www.mozilla.org/MPL/MPL-1.1.html

ESPresso uses BGRABitmap library which is distributed under modified LGPL license. See https://sourceforge.net/projects/lazpaint/files/src/ for more details.

ESPresso uses Eye Candy Controls components which is distributed under modified LGPL license. See https://sourceforge.net/projects/eccontrols/ for more details.

ESPresso uses SynEdit component which is distributed under Mozilla Public License Version 1.1 (MPL). See https://sourceforge.net/projects/synedit/ for more details.

ESPresso uses Lua Script highlighter for SynEdit created by Zhou Kan which is distributed under Mozilla Public License Version 1.1 (MPL). You may obtain a copy of the MPL License at http://www.mozilla.org/MPL/MPL-1.1.html

ESPresso uses RichMemo component which is distributed under modified LGPL license. You may obtain a copy of the modfied LGPL License at http://wiki.lazarus.freepascal.org/FPC_modified_LGPL

This software package contains LuaSrcDiet which is distributed under MIT license. See lua subdirectory for details.

This software package contains Lua 5.1 which is distributed under MIT license. See lua subdirectory for details.

This software package contains ESP telnet script which is distributed under MIT license. See ESP subdirectory for details.

This software package contains NodeMCU Lua cross-compiler which is distributed under MIT license. See lua subdirectory for details.

1.3. Changelog

v.0.5.0.0 (2018-05-04)

  • Added possibility to transfer any file to ESP (no longer lua source files only)
  • Added lua source parse function of local files (requires luac compiler)
  • Added lua source compilation of local files (requires luac cross-compiler)
  • ESP Flash space usage indicator (inspired by Amiga Workbench 1.3 disk space usage indicator)
  • Local and ESP directories are now alphabetically sorted
  • NodeMCU version is now displayed upon connection
  • Redesigned output window, cleaned output messages
  • Fixed cursor position after file operations
  • Command buttons are now inactive during file operations
  • Fixed displaying timestamps for files created exactly at midnight
  • Redesigned ESP communication protocol handling
  • Directory sending attempt throws no errors anymore (but due to SPIFSS limitations is still not possible)

v.0.4.0.1 (2017-08-17)

  • Removed Del keyboard shortcut since it might have interfered with command line edit

v.0.4.0.0 (2017-08-14)

  • Fixed deleting of temporary files used by LuaSrcDiet
  • Automatic integer/float NodeMCU firmware recognition
  • Added distinct LuaSrcDiet options for integer and float NodeMCU firmwares
  • Extensive documentation created
  • Configurable ESP reset function
  • Connection timeouts and retries

v.0.3.0.0 (2017-02-05)

  • Fixed directory listing bug that might have caused some files to be missing on the first directory listing after connect
  • New rename dialog box that works under Linux
  • Some user interface bug fixes and improvements - more keyboard shortcuts
  • Added possibility to pass optional parameters to LuaSrcDiet

v.0.2.0.0 (2016-12-09)

  • New binary transfer mode that provides 100% carbon copy of source file on ESP side
  • Redesigned LuaSrcDiet compression. Now it uses interpreted script along with Lua interpreter
  • Source file preview with Lua syntax highlighting
  • Some user interface bug fixes and improvements

v.0.1.1.0 (2016-08-09)

  • Fixed some code portability issues
  • Initial Linux release

v.0.1.0.0 (2016-07-29)

  • Initial release

1.4. Feedback

This software was written as a commodity for my ESP projects. I’ve got some ideas for its further development so if you like ESPresso just let me know to encourage me to keep working on it.

ESPresso thread on esp8266.com: http://www.esp8266.com/viewtopic.php?f=22&t=11042

E-mail: lukasz@cielecki.pl

Wrocław, Poland, June 2016 - May 2018

####__     __ Łukasz "MrLuck"_Cielecki     __        __    _    ___  __ #
###/ /_ __/ /_____ _______ /  \ ____(_)__ / /__ ____/ /__ (_)  / _ \/ /##
##/ / // /  '_/ _ `(_-<_ /| (|// __/ / -_) / -_) __/  '_// /  / .__/ /###
#/_/\_,_/_/\_\\_,_/___/__/ \__ \__/_/\__/_/\__/\__/_/\_\/_(_)/_/  /_/####

2. Manual

2.1. Installation

ESPresso comes with binaries for Windows (both 32 or 64 bit) and Linux (i386, amd64 and armhf, all for gtk2 widgetset). Typically every second release contains binaries for Windows or Linux.

ESPresso doesn’t require installation. Simply unpack files (preserving directory structure) to the location you want and run the espresso.exe (win32, win64) or espresso (Linux version). If you don’t know which version to use - choose win32.

2.1.1. Windows specific requirements

ESPresso for Windows requires Visual C++ Redistributable for Visual Studio 2012 to be present on your system. It’s likely that it’s already been installed since many programs depend on it. If your system shows that MSVCR110.dll is missing when you start ESPresso then you might use the MSVCR110.dll file included in win32 version folder or install proper version of VCredist from: https://www.microsoft.com/en-au/download/details.aspx?id=30679

2.1.2. Firewall

ESPresso uses outgoing telnet connection to the address and port of your choice (NodeMCU telnet scripts usually listen on port 2323). Make sure that your firewall doesn’t block outgoing connections to this port.

2.1.3. Lua interpreter

ESPresso optionally uses Lua interpreter to run LuaSrcDiet script.

ESPresso package for Windows comes with Lua interpreter already included in lua subfolder so usually no further configuration is required.

ESPresso for Linux uses system Lua interpreter so you need to:

  1. Make sure it’s present in your system (lua command),
  2. Point [LUA]/path key in ESPresso.ini file to the correct Lua path.

2.1.4. Lua compiler

ESPresso is able to parse (syntax check) local *.lua source files when Lua compiler is installed on the system.

ESPresso package for Windows comes with Lua compiler already included in lua subfolder so usually no further configuration is required.

ESPresso for Linux uses system Lua compiler so you need to:

  1. Make sure it’s present in your system (luac command),
  2. Point [LUA]/compiler key in ESPresso.ini file to the correct Lua compiler path.
2.1.4.1. Lua cross-compiler

With local Lua cross-compiler it’s possible to compile Lua sources on your host machine and send binary *.lc files to ESP platform.

Lua cross-compiler may be prepared using instructions from: http://nodemcu.readthedocs.io/en/master/en/upload/#compiling-lua-on-your-pc-for-uploading

ESPresso package for Linux amd64 comes with already prepared cross-compiler in lua subfolder so usually no further configuration is required.

Note

Please note that standard Lua compiler from your host machine is not able to produce *.lc files compatible with NodeMCU and can be used only for syntax checking. To compile *.lc files usable on NodeMCU you must use special cross-compiler.

To enable local compile button you need to:

  1. Point [LUA]/compiler key in ESPresso.ini file to the correct Lua cross-compiler path.
  2. Set [LUA]/cross key in ESPresso.ini file to 1 to enable cross-compilation.

2.1.5. LuaSrcDiet

ESPresso uses LuaScrDiet to compress files you upload to ESP8266 on the fly.

ESPresso package (for both Windows and Linux) has LuaSrcDiet.lua already included in lua subfolder.

Note

Please note that included LuaScrDiet works with Lua 5.1.

If you’d like to use LuaScrDiet from another directory please update path in ESPresso.ini file under [DIET]/path key.

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 the one from NodeMCU examples [https://github.com/nodemcu/nodemcu-firmware/blob/master/lua_examples/telnet.lua] (also included in this distribution in ESP directory) 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).

Note

Telnet script from old NodeMCU docs which was copied to many websites is not working properly with recent NodeMCU versions. Use the 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 put:

    dofile('telnet.lua')
    

    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. 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 telnet.lua. Regular operation mode of your app may be restored in callback for:

    socket:on("disconnection")
    
  3. Your app is a webserver. Unfortunately it’s not possible to start more than a single server listening on a single port 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.lua using ESPresso is still possible.

2.3. ESPresso main window

ESPresso represents classic dual-pane filemanager approach.

_images/espresso_main_window.png

2.3.1. Connection parameters ①

Connection parameters need to be entered in the connection panel (see Connecting to ESP).

2.3.2. Status panel ②

Status panel shows connected NodeMCU version and firmware type (INT for integer and FLOAT for floating point firmware). Firmware version and type is determined immediately after connection is established. Diode image shows current status:

  • Gray diode - ESP disconnected
  • Green diode - ESP connected
  • Green / yellow blinking diode - operation in progress
  • Red diode - there was an error during last ESP operation

2.3.3. Main panels

Left panel ③ lists local (computer) directory of your choice (see Local operations (left panel)). Right panel ⑤ lists SPIFFS filesystem on ESP8266 flash chip (see ESP operations (right panel)).

You can upload files to your ESP using buttons from command panel in the middle ④ (see Transferring files).

2.3.4. Terminal window ⑥

Terminal window logs communications between ESPresso and ESP module and also acts as an output for commands launched locally within ESPresso (i.e. Lua parser and compiler, LuaSrcDiet). Different colors denote message source:

  • Black text denotes ESPresso messages and regular output from locally launched commands
  • Red text denotes error output from locally launched commands
  • Green text denotes commands sent from ESPresso to ESP module
  • Blue text denotes messages received by ESPresso from ESP module

Note

Please not that terminal windows doesn’t show commands send as a result of ESPresso graphical user interface operations. ESP output of these operations is also hidden. For debugging purposes it’s possible to trace all the communications in the session.txt file created automatically by ESPresso in its working folder.

2.3.5. Command prompt ⑦

Command prompt (see Command prompt) and progress bar are located at the bottom of the window. Progress bar indicates advances in file transfer.

2.4. Local operations (left panel)

Left panel allows you to browse through the local filesystem and choose a file for upload.

_images/left_panel.png

Top bar is used for directory selection. ESPresso remembers last directory path on exit.

Main area displays current directory listing. You can navigate through the files and directories using mouse or keyboard:

  • use cursor keys to move up and down the list,
  • press Enter key to enter a directory,
  • press Backspace key to move to the parent directory.

File size is given in bytes. Items are sorted alphabetically. Directories can be distinguished by the <DIR> label in the Size column. Entry .. represents parent directory and may be also used to move across the path.

Note

Inactive command button means that the operation is not applicable for selected file or configuration is incomplete (please refer Installation chapter).

2.4.1. Lua file preview

You can preview selected Lua file by pressing View button or F3 key. Preview uses Lua source highlighting.

_images/file_preview.png

Exit from preview by pressing Escape key or simply closing its window.

2.4.2. Lua file parse

Press Parse button to parse local *.lua source files. Parser output is printed in the terminal window (see Terminal window ⑥). This allows you to quickly check syntax of your files before uploading them to the ESP.

Note

Lua compiler has to be installed on the system for this function to work, however ESP8266 cross-compiler is not necessary. Please refer Lua compiler for more details on compiler configuration.

2.4.3. Lua local file cross-compile

Press Compile button in the left pane to cross-compile local *.lua source files. Cross-compiler output is printed in the terminal window (see Terminal window ⑥). This allows you to prepare *.lc files on your PC and send them to the ESP.

Note

This action is performed on your PC an therefore proper ESP8266 cross-compiler need to be present on your system. Please refer Lua cross-compiler for more details on cross-compiler configuration.

2.4.4. Lua / all files filter

Show all toggle switch changes display filter of the local (left) pane:

  • Show all - I (on): display all files present on the local filesystem.
  • Show all - O (off): filter local file list to the *.lua (Lua source) and *.lc (Lua compiled) files.

Note

When Show all is on you are able to send any file to the ESP.

2.5. ESP operations (right panel)

Remote (right) panel enables you to work on ESP filesystem (SPIFFS). Due to its limitations directories are not supported and files have no attributes (apart from their sizes).

_images/right_panel.png

2.5.1. ESP operations

ESP operations buttons execute special procedures directly on connected ESP module.

  • ADC button opens ADC Monitor.
  • Reset button performs ESP reset.
  • Refresh button reloads SPIFFS file list. Normally this is done automatically after each ESPresso operation that might have changed something in the filesystem (i.e. copy, compile, delete, rename). However it’s still possible to change files by entering commands in command line (see Command prompt) - that’s when manual refresh may be useful.

2.5.2. Remote commands buttons

Remote commands buttons perform operations on currently selected ESP file:

  • Do file executes lua or lc (compiled) file,
  • Compile compiles lua file to lc (compilation is done by NodeMCU on ESP); original file is kept,
  • Delete (shortcut [F8]) deletes file from SPIFFS (confirmation is required),
  • Rename (shortcut [F9]) opens rename dialog box.

2.5.3. Space usage indicator

Space usage indicator graphically represents usage of ESP flash memory (which is used by filesystem for file storage). It’s updated every time the directory listing is refreshed. Percentage of space usage is displayed in the middle of the indicator bar.

Tip

Hold mouse pointer over the vertical space usage bar for a tooltip with detailed remaining and used space readings (in Kilobytes). Hold mouse pointer over the F sign above the bar for tooltip with detailed total flash size (in Kilobytes and Megabytes).

2.5.4. Rename dialog box

_images/rename.png

Rename dialog box always displays original filename and allows you to enter a new one.

By default new name is split into two fields (name and extension) that can be edited separately. Since in most cases you do not need to change the extension this helps you to avoid mistakes.

Note

Dot between name and extension is not shown in new name / extension fields.

It’s possible to use standard single rename field by checking Use one field only box.

Finish editing filename by clicking Rename button or dismiss changes by clicking Cancel.

Rename (with corresponding .lc/.lua file) button is only visible when you have two files with filenames that differ only in extension (.lua and .lc). It allows you to rename both files with one click. Only New name field is used for both files. Extensions remain intact.

2.5.5. ESP reset

Basically this operation performs:

node.restart()

and reconnects but it can be customized in several ways:

  1. A delay may be added to allow graceful disconnect. ESPresso sets an ESP alarm up with restart command passed as a function. Delay (in milliseconds) is configured by reset_delay parameter in the [ESP] section of an INI file. If the delay is set to 0 then no alarm is activated and the restart functions is sent directly. In both scenarios ESPresso disconnects as soon as the command is sent to the ESP.
  2. If a delayed restart is configured you may choose which ESP alarm to use. By default ESPresso uses dynamic ESP timer (alarm) assignment (reset_alarm parameter in the [ESP] section of an INI file set to -1) but you may choose any valid value (0 - 6). If may be necessary if your NodeMCU doesn’t support dynamic timers (which means that it’s outdated) or your scripts interfere with them.
  3. A delay between an actual ESP reset (delayed or not) and reconnection attempt may be set using reset_reconnect_delay parameter in the [ESP] section of an INI file. ESPresso tries to reconnect restarted ESP until until a connection is reestablished or user cancels operation by pressing Disconnect button. Reconnection does not refresh file listing nor recognizes ESP firmware type again.

2.5.6. ADC Monitor

ESPresso allows you to remotely monitor ADC (analog input) of an ESP8266.

_images/adc.png

To start monitoring:

  1. When connected to ESP press ADC button above the remote (right) panel of the main window (see ESP operations (right panel)),
  2. In the new window enter sampling period (in milliseconds - sampling is maintained by computer side - no ESP timers are involved),
  3. Toggle Enable to start monitoring.

During ADC monitoring gage on the right shows last value read. All readings are plotted on the bottom chart. Please note that horizontal axis labels show reading indexes - not time.

ADC supports 10-bit resolution. Monitor shows raw values read from ESP. Min, Max and Last value read are shown in the ADC monitor window. These can be reseted using Clear button.

To stop monitoring:

  1. Toggle Enable button,
  2. Close ADC Monitor window.

2.6. Connecting to ESP

ESPresso uses direct TCP/IP connection to connect to an ESP. No additional software is required as system TCP stack is used.

Before connecting make sure that telnet.lua is running at ESP side (see ESP side installation).

  1. Enter Address and Port of your ESP. Port is determined in telnet.lua. 2323 is commonly used value.
  2. Toggle Connect button.

ESPresso uses following parameters from INI file when connecting to the ESP (all values are in milliseconds):

Section Key Description Default value
[CONN] timeout Connection attempt timeout 5000 [ms] (= 5 s)
[CONN] reconnect_delay Delay between timeout and reconnection attempt 3000 [ms] (= 3 s)

When connection attempt timeout occurs ESPresso tries to reconnect after reconnect_delay period. This happens until a connection is established or user cancels operation by pressing Disconnect button.

ESPresso remembers last connection details.

As soon as connection is established ESPresso:

  1. Checks for NodeMCU firmware type (integer or float - see Firmware dependent LuaSrcDiet parameters) and version,
  2. Retrieves ESP directory listing and storage space usage (see Space usage indicator).

To disconnect from ESP press Disconnect button when connected or close ESPresso.

2.7. Transferring files

Select file you want to send in the local (left) panel and hit:

  • Upload [F5] - to upload with original filename,
  • Upload as... [F6] - to upload with new filename. You may specify new filename of uploaded file in the dialog box. By default original filename with concatenated string _copy is suggested (i.e. init.luainit_copy.lua).

It’s possible to enable on-the-fly LuaSrcDiet source files compression using Diet switch. See LuaSrcDiet for more details.

Note

LuaSrcDiet processes only *.lua (Lua source) files. The Diet switch may stay on if you transfer other data (i.e. *.lc Lua compiled files). ESPresso simply won’t pass them through LuaSrcDiet during transfer.

Note

Inactive Diet switch after ESP connection is established means that configuration is incomplete (please refer LuaSrcDiet chapter).

ESPresso by default uses binary data transfer that creates 100% carbon copy of the file on the ESP side. It is however still possible to enable old deprecated ASCII transfer mode. Please see INI file entries for more details.

2.8. LuaSrcDiet

ESPresso uses LuaScrDiet to compress files you upload to ESP8266 on the fly.

Compressing Lua files is recommended since it saves limited ESP8266 resources. ESPresso on the fly compression is done right before file upload (system temp directory is used) so you can keep your source *.lua files intact.

2.8.1. Prerequisites

To start compressing files on the fly:

  1. Make sure you have correctly configured Lua interpreter (see Lua interpreter) and LuaScrDiet (see LuaSrcDiet),
  2. Toggle Diet switch on (located between local and remote panes). If diet switch is grayed out after ESP connection is established verify your configuration.

2.8.2. Extra LuaSrcDiet parameters

It’s possible to pass additional parameters to LuaSrcDiet by entering them under [DIET]/options section of ESPresso.ini.

2.8.3. Firmware dependent LuaSrcDiet parameters

By default LuaScrDiet compression changes large integers into its exponential representation (saving some bytes of source code, i.e.: 60000 becomes 6e4). This however is unreadable for NodeMCU integer firmware. Therefore if you have integer firmware installed on your ESP no integer optimizations should be done by LuaScrDiet.

ESPresso checks for firmware type every time a connection is established (it sends =1/3 command and reads the result - 0 is expected on integer firmware). According to this check, firmware dependent parameters may be passed to LuaScrDiet. These are configured in ESPresso.ini:

Section Key Description Default value
[DIET] options_int Options for integer firmware --noopt-numbers
[DIET] options_float Options for float firmware --opt-numbers

Default values simply turn off integer optimization for integer firmware so in most cases no configuration is necessary.

2.9. Command prompt

You can execute any command on the ESP by entering it in the command line at the bottom of the main window and hitting Enter key or pushing Send button.

Prompt line keeps history of all commands you entered since program start. Use Up and Down cursor keys (when command prompt has active focus) to navigate through them.

3. Extras

3.1. Keyboard shortcuts

Following keyboard shortcuts are available in ESPresso main window:

F1
Display help file.
F3
View local Lua source file.
F5
Upload local file to ESP.
F8
Delete remote (ESP) file from SPIFFS filesystem.
F9
Rename remote (ESP) file.
F10
Exit ESPresso.
TAB
Move cursor between local and remote (ESP) pane.
Up / down cursor keys
Navigate through filesystems.
Enter
Enter local directory.
Backspace
Go to parent directory on local filesystem.

3.2. INI file entries

Note

Please note that default values are used only when there is no corresponding entry in INI file. Values in a standard INI file from specific distribution package may differ from default values listed below.

Note

ESPresso updates INI file when exiting from application.

Section Key Description Default value
[CONN] timeout Connection attempt timeout 5000 [ms] (= 5 s)
[CONN] reconnect_delay Delay between timeout and reconnection attempt 3000 [ms] (= 3 s)
[LASTCONN] address Last connection IP address or host name  
[LASTCONN] port Last connection port 2323
[ESP] reset_alarm ESP alarm to use for reset delay -1 (= dynamic)
[ESP] reset_delay ESP reset delay 3000 [ms] (= 3 s)
[ESP] reset_reconnect_delay Delay between ESP reset and reconnection attempt 5000 [ms] (= 5 s)
[SRC] dir Last source directory (application working directory)
[SRC] show_all Show all files in the local panel 0 (= show lua source files only)
[LUA] path Lua interpreter path lua
[LUA] compiler Lua compiler path luac
[LUA] cross Compiler supports NodeMCU cross-compilation 0 (= no support)
[DIET] path LuaSrcDiet path LuaSrcDiet.lua
[DIET] enable Enable LuaSrcDiet 0 (= disable)
[DIET] options_int Options for integer firmware --noopt-numbers
[DIET] options_float Options for float firmware --opt-numbers
[DIET] options Additional options for LuaSrcDiet  
[TRANSFER] binary Enable binary transfer 1 (= enable)
[TRANSFER] showtransfermode Allow changing transfer mode from user interface 0 (= disable)

Warning

Binary transfer is enabled by default and default settings prevent disabling it from user interface. Obsolete ASCII transfer is deprecated.

Documentation tools