|Ondřej Hruška e125aec459 Merge pull request #262 from schneemaier/patch-1||2 years ago|
|esp_iot_sdk_v1.5.2||3 years ago|
|front-end @ 9aae724df2||2 years ago|
|include||3 years ago|
|libesphttpd @ d6651ca0d1||3 years ago|
|rel-tpl||2 years ago|
|release||3 years ago|
|user||2 years ago|
|.gitignore||3 years ago|
|.gitmodules||3 years ago|
|CMakeLists.txt||3 years ago|
|LICENSE.txt||3 years ago|
|Makefile||3 years ago|
|Makefile.combined||5 years ago|
|Makefile.ota||5 years ago|
|Makefile.separate||5 years ago|
|README.md||3 years ago|
|build_parser.sh||3 years ago|
|build_web.sh||3 years ago|
|esphttpdconfig.mk.example||3 years ago|
|get_version.c||3 years ago|
|prepro.sh||3 years ago|
|ship.sh||3 years ago|
|showmem.php||3 years ago|
ESPTerm is a VT100-like terminal emulator running on the ESP8266 WiFi chip.
ESPTerm passes most of VTTEST test cases, making it functionally comparable to eg. gnome-terminal, terminator, konsole, GtkTerm or PuTTY. ESPTerm is capable of running Midnight Commander through agetty, including full mouse support, provided agetty is made to believe it's Xterm, which shows ESPTerm is compatible with ncurses.
In addition to control sequences that manipulate the terminal or user input, there is a set of simple networking commands for device-to-device message exchange and interacting with remote servers.
The terminal screen can be accessed using any web browser, even on a phone or tablet. It works with ESP-01, ESP-01S, ESP-12 and likely many other modules.
With ESPTerm, you can add remote access via WiFi to any embeded project, all you need is UART and some imagination!
You can try the web user interface here: espterm.github.io
The demo is almost identical to the real thing, except, of course, it doesn't do much without the emulator backend that runs on the ESP8266. The web version will be updated to match this repository after each minor release (and sometimes in between for testing; the version currently being show-cased can be read on the About page of the demo).
Use the above linked online demo to verify compatibility with your browser.
To our knowledge, ESPTerm works with:
It does not work with:
/api/v1/msg) for receiving messages sent e.g. from a script on PC, web browser or CURL
To ask any questions or discuss new features you'd like to see added, it's best to use the ESPTerm Dev mailing list
Subscribe to the mailing list to also receive new release announcements.
If you found a bug (that happens alot!), please submit it to our bug tracker. We also use it to track planned ideas. If you don't want to create a GitHub account for that, just send it to the mailing list.
To run ESPTerm on your ESP8266, either build it yourself from source using
(and the included Makefile), or download pre-built binaries from the GitHub releases section.
Flash the binaries using esptool.
MACADRbeing three unique bytes from the MAC address / Device ID as ASCII hex.
It can happen that some changes to the WiFi or network config make the module inaccessible.
ESPTerm has two config "files", one for defaults and one for the currently used settings. In the case of the terminal config, there is also a third, temporary file for changes done via ESC commands.
When you get your settings just right, you can store them as defaults, which can then be at any time restored by holding the BOOT (GPIO0) button. You can do this on the System Settings page. This asks for an "admin password", which can (and should!) be changed. This password can't be easily recovered when forgotten.
You can also restore everything (except the saved defaults) to "factory defaults", there is a button for this on the System Settings page. Those are the initial values you would get after a clean install.
Developing the terminal emulator was complicated by the information being scattered across many places and the existing implementations I used for reference often got some details wrong or didn't implement certain features at all. Xterm proved to be by far the most complete implementation.
A great tool for checking my code has proven to be VTTTEST. ESPTerm passes most of the tests on the main page and some additional Xterm specific ones, like Mouse Tracking.
Here is a list of useful VT100 emulation resources I've collected for reference.
ESPTerm's firmware is written in C and is based on SpriteTM's
libesphttpd http server library forked to
MightyPork/libesphttpd. This fork includes various improvements and changes required by the project.
--recursive, or afterwards run
git submodule initand
git submodule update.
make toolchain esptool libhal STANDALONE=n. Make sure the
xtensa-lx106-elf/binfolder is on $PATH.
KERNEL=="tty[A-Z]*[0-9]*", GROUP="uucp", MODE="0666"
.rlfile is the actual source, the
yarn installin the front-end folder, installed PHP)
esphttpdconfig.mkis set up properly - link to the SDK etc.
The IoT SDK is now included in the project due to problems with obtaining the correct version and patching it. It works with version 1.5.2, any newer seems to be incompatible. If you get it working with a newer SDK, a PR is more than welcome!
The web resources are in the
front-end git submodule. To prepare the web resources for a build,
make web. The resulting files are copied to
html/ folder is then embedded in the firmware image.
It's kind of tricky to develop the web resources locally; you might want to try the "split image"
Makefile option, then you can flash just the html portion with
make htmlflash. I haven't tried this.
For local development, use the
server.sh script in
html_orig (more details in the front-end repo's readme).
It's possible to talk to the API endpoints of a running ESP8266 from a page served by your local server
if you configure
_env.php with its IP.
The Makefile should automatically build the parser and web resources for you when you run
The web resources are normally no re-built, because the build process is quite slow. To manually rebuild them,
make web before
To flash, just run
make flash. It will use parameters you setup in the