ESP32 Shell (ESP32-OS V2.2.1)

A Linux-inspired shell for ESP32 with:

• Filesystem commands (ls, cat, cp, ...)
• Pipe support (|) for many text commands
• nano-like editor
• WiFi and network commands
• Digital/analog GPIO control
• Web terminal
• OTA updates (URL or upload webpage)
• Admin/sudo permissions with timeout

The shell runs over serial and optionally in the web terminal.

Feature Overview

• Filesystem on LittleFS
• Home directory for normal users: /home
• Admin areas: /autostart, /root, /system
• ANSI color output (serial + web terminal)
• Command history with arrow keys (up/down)
• Alias and variable system (alias, set, export)
• Script execution (run) and boot autostart (/autostart)
• OTA with dual partitions (app0, app1)

Project Files

• Main sketch: linux.ino
• Web terminal page: webterm_page.h
• OTA partition table: partitions.csv

Requirements

• ESP32 dev board
• Arduino IDE with ESP32 core
• Serial monitor baud rate: 115200

Optional for ping:

• ESP32Ping or ESPping (otherwise TCP fallback is used)

Build and Flash

1. Select your board in Arduino IDE (ESP32 Dev Module or matching board).
2. Set partition scheme to Custom (with partitions.csv in sketch folder).
3. Compile and flash via USB.
4. Open serial monitor at 115200.

Connect from Terminal (macOS, Linux, Windows)

Use 115200 baud for this shell.

macOS

Find the serial port:

ls /dev/cu.*

Common device names:

• /dev/cu.usbserial-*
• /dev/cu.usbmodem*

Connect with screen:

screen /dev/cu.usbserial-XXXX 115200

Exit screen:

• Ctrl + A, then K, then confirm with y

Linux

Find the serial port:

ls /dev/ttyUSB* /dev/ttyACM*

You can also check recent kernel logs:

dmesg | tail

Connect with screen:

screen /dev/ttyUSB0 115200

Alternatives:

picocom -b 115200 /dev/ttyUSB0

minicom -D /dev/ttyUSB0 -b 115200

Windows

Find the COM port:

• Device Manager -> Ports (COM & LPT) (for example COM3)

PowerShell option:

Get-CimInstance Win32_SerialPort | Select-Object DeviceID,Description

Connect options:

• Arduino IDE serial monitor at 115200
• PuTTY:
  • Connection type: Serial
  • Serial line: COMx
  • Speed: 115200

Partitions (OTA)

Included in partitions.csv:

• app0 OTA slot 0
• app1 OTA slot 1
• spiffs (LittleFS data)

df shows:

• FS Total/Used/Free
• APP0/APP1 Total/Used/Free/Valid
• Optional units with kb or mb

Login, Roles, and Permissions

First Boot

On first boot, an admin password is required:

• Prompt: password>
• Minimum length: 4 characters

User Roles

• Normal user:
  • Starts in /home
  • Can only write inside /home
  • Cannot read/list admin paths
• Admin (via sudo):
  • Full access including /, /autostart, /root, /system
  • Timeout session: 5 minutes

Sudo Behavior

• sudo <pass> enables admin session and switches to /.
• sudo <pass> <command> runs only that command as admin.
• sudo -k ends admin immediately and returns to /home.
• After timeout, admin is disabled and working directory returns to /home.

Paths and Navigation

• ~ means home directory (/home)
• ./ means current directory
• .. means parent directory
• cd without argument goes to /home

Examples:

• cd ~/test
• cat ./a.txt

Web Terminal

Admin command:

• webterm on
• webterm off

When WiFi is connected:

• URL is printed, for example http://192.168.178.187/

Web terminal supports:

• Colors
• Command history (up/down)
• Interactive input (for example nano)
• Local typing echo for fast input

OTA Update

Admin command:

• ota <http-url-to-bin>
• ota upload

OTA by URL

Example:

• ota http://192.168.178.10/linux.ino.bin

OTA via Upload Page

1. Run ota upload
2. Shell prints URL, for example http://<ip>/ota?token=<token>
3. Open in browser and upload linux.ino.bin
4. Progress bar shows upload status
5. Device reboots automatically after success

Important:

• Upload only linux.ino.bin
• Do not upload *.bootloader.bin
• Do not upload *.partitions.bin

Scripts and Autostart

Run a Script

• run <file>

Behavior:

• Executes each line as a shell command
• Empty lines and # comments are skipped
• Interactive commands stop script execution

Autostart

Admin area: /autostart

• On boot, files in /autostart are executed
• autostart runs the sequence manually

Nano Editor

Start:

• nano <file>

Editor commands (dot prefix):

• .list [from] [to]
• .set <line> <text>
• .ins <line> <text>
• .del <line>
• .save
• .exit
• .help

Pipes

Supported in pipelines:

• echo, cat, grep, head, tail, sort, uniq, wc, calc, curl, cut, tr, sed

Examples:

• cat /home/a.txt | grep -n test
• echo hello | wc
• cat /home/a.txt | sort | uniq -c

Variables and Aliases

Alias

• alias lists aliases
• alias ll=ls sets alias
• unalias ll removes alias

Variables

• set lists variables
• set NAME value sets variable
• set -u NAME unsets variable
• export is an alias of set

Usage:

• $NAME or ${NAME}

Full Command Reference

Notes:

• Admin-only: ota, webterm, format
• Some commands have additional path-based permission checks

System and Help

Command	Syntax	Description
help	help or help -full	Shows command list (admin commands included for admin sessions).
man	man <command>	Shows detailed help for one command.
clear	clear	Clears terminal screen.
uname	uname	Board/SDK/system info.
neofetch	neofetch	Linux-style system summary.
uptime	uptime	Time since boot.
date	date	Current time, or uptime fallback if time is not set.
mem	mem	Heap details (Heap size, Free, Min free).

Files and Directories

Command	Syntax	Description
ls	ls [path]	Lists directory contents.
pwd	pwd	Prints current working directory.
cd	cd [dir]	Changes directory, defaults to /home.
stat	stat <path>	Shows type and size of file/directory.
cat	cat <file>	Prints file content.
touch	touch <file>	Creates file if missing.
mkdir	mkdir <dir>	Creates directory.
rmdir	rmdir <dir>	Removes empty directory.
rm	rm <file>	Removes file.
cp	cp <src> <dst>	Copies file.
mv	mv <src> <dst>	Moves/renames file.
write	write <file> <text>	Overwrites file with one line.
append	append <file> <text>	Appends one line.
head	head <file> [n]	First n lines (default 10).
tail	tail <file> [n]	Last n lines (default 10).
find	find [path] [pattern]	Recursive name search.
tree	tree [path]	Directory tree view.
du	du [path]	Directory size in bytes.
df	df [kb|mb]	FS and OTA partition usage.

Text Processing

Command	Syntax	Description
grep	grep [-i] [-n] <pattern> <file>	Searches text in files.
sort	sort <file> [-r] [-f]	Sorts lines (-r reverse, -f case-insensitive).
uniq	uniq <file> [-c]	Removes adjacent duplicates (-c with counts).
wc	wc <file>	Counts lines/words/bytes.
cut	cut -f <n> [-d <delim>] [file]	Field extraction.
tr	tr <from> <to> [file]	Character translation/replacement.
sed	sed s/old/new/ [file]	Simple replace, use trailing g for global.

Shell and Automation

Command	Syntax	Description
run	run <file>	Executes script file line by line.
autostart	autostart	Runs all scripts in /autostart (admin).
history	history or history -c	Shows or clears history.
alias	alias or alias name=value	Creates/lists aliases.
unalias	unalias <name>	Removes alias.
set	set, set NAME value, set -u NAME	Lists/sets/unsets shell variables.
export	same as set	Same behavior as set.
echo	echo <text>	Prints text.
sleep	sleep <seconds>	Waits for seconds.
calc	calc <expr>	Evaluates expression (+ - * / ()).
libcall	libcall <module> <cmd> [args...]	Calls internal library module command.

Networking

Command	Syntax	Description
wifi	`wifi	`
wifi_disconnect	wifi_disconnect	Disconnects and turns WiFi off.
wifi_status	wifi_status	Shows status, SSID, IP, RSSI.
wifi_scan	wifi_scan	Scans nearby networks.
ip	ip	Prints local IP or 0.0.0.0.
nslookup	nslookup <host>	DNS lookup.
ping	ping <host> [count]	Ping (ICMP or TCP fallback).
wget	wget <url> [file]	HTTP download to output or file.
curl	curl <url> or curl -o <file> <url>	HTTP GET, optional file output via -o.

GPIO and Hardware

Command	Syntax	Description
pinmode	pinmode <pin> <in|out|pullup|pulldown>	Sets pin mode.
dread	dread <pin>	Reads digital input.
dwrite	dwrite <pin> <0|1>	Writes digital output.
aread	aread <pin>	Reads analog input (raw ADC).
awrite	awrite <pin> <0..255>	PWM output (8-bit).
pin_status	pin_status	Multi-pin status with mode/digital/analog values.

Admin and Security

Command	Syntax	Description
sudo	sudo <pass> / sudo <pass> <command> / sudo -k	Enables admin, runs one admin command, or logs out admin.
passwd	passwd <old> <new> or passwd <new> (admin)	Changes admin password.
format	format -y	Factory reset of filesystem (2nd confirmation with YES).
webterm	webterm [on|off]	Starts/stops web terminal.
ota	ota <url|upload>	OTA via HTTP URL or upload webpage.
reboot	reboot [seconds], reboot app0, reboot app1	Reboots, optional OTA slot switch (app0/app1 admin-only).

Write Permission Notes

Without admin rights, write operations are restricted to /home.

Affected commands include:

• mkdir, touch, write, append, nano
• cp (destination), mv (source/destination), rm, rmdir
• wget/curl -o when writing files

Known Messages

• No core dump partition found!
  • Informational only, not critical for normal usage.
• date: not set, uptime ...
  • Time source (NTP/RTC) is not configured, uptime fallback is used.

Quick Start Examples

# Help
help
man df

# File operations
pwd
ls
mkdir ~/test
write ~/test/a.txt hello
cat ~/test/a.txt

# Pipes
cat ~/test/a.txt | grep hello | wc

# WiFi
wifi FRITZ!Box 7490|yourpassword
wifi_status

# Web terminal (admin)
sudo yourpassword webterm on

# OTA upload page (admin)
sudo yourpassword ota upload

# Switch OTA slot (admin)
sudo yourpassword reboot app0

Security Notes

• Password is stored locally in /system/admin.pw.
• OTA upload webpage uses a token and limited validity window.
• sudo passwords are masked in command history.