Skip to content
BranchesTags

Repository files navigation

Lx Shell for M5Stack Cardputer ADV

Minimal Unix‑like shell optimized for the Cardputer ADV. Includes a terminal, a minimal vi (or nano) editor, core commands, and Lx script execution.

M5Stack Cardputer ADV

Features

  • Interactive terminal with history, autocompletion, and pager (more/less)
  • Minimal vi and nano editors (navigation, insertion, indentation, visual wrapping)
  • Core commands: battery, cat, cd, cp, find, ls, mount, mv, rm, slideshow, umount, view
  • Run Lx scripts (lx <script.lx>)
  • Output redirection (>, >>), pipes (|), and tee
  • Screensaver + display sleep
  • Keyboard with CP437 extended glyphs and optional debug
  • Audio playback via ESP8266Audio (streaming MP3/WAV)

Commands

  • battery - battery status
  • brightness - set display brightness
  • cat - print file contents
  • cd - change directory
  • clear - clear terminal
  • cp - copy file
  • find - search files
  • led - control the RGB LED
  • less - alias for more
  • ls - list directory contents
  • lx - run a Lx script
  • lxprofile - set Lx memory profile
  • man - command help
  • mkdir - create directory
  • more - pager for files and output
  • mount - mount SD card
  • mv - move/rename file
  • nano - minimal editor (nano-style)
  • play - audio player (WAV/MP3)
  • pwd - print working directory
  • reset - alias for clear
  • rm - remove file
  • rmdir - remove directory
  • slideshow - image slideshow (PNG/JPEG)
  • shutdown - halt or restart
  • tee - write piped output to a file
  • touch - create/update file
  • umount - unmount SD card
  • view - image viewer (PNG/JPEG)
  • vi - minimal editor

Preferences

When an SD card is mounted, LX shell stores preferences in /media/0/.lxshellrc. Without an SD card, preferences live in RAM and are lost on reboot.

Supported keys:

brightness=100
screensaver_minutes=2
screen_off_minutes=5

Target hardware

  • M5Stack Cardputer ADV (ESP32‑S3)
  • micro‑SD card for filesystem (/media/0)

Build and flash (PlatformIO)

This project is built with PlatformIO. Audio playback relies on the ESP8266Audio library.

  1. Initialize submodules:
git submodule update --init --recursive
  1. Build and upload:
pio run
pio run -t upload
  1. Open serial monitor:
pio device monitor

Quick usage

cd /media/0
ls
lx my_script.lx
lx scripts/lx_stress_test_progressive.lx > output.txt

Shell behavior

  • History lives in /sdcard/.lx_history on the SD card, loaded on boot and appended after each executed line. If the file is missing, history stays in memory only.
  • Autocomplete uses Tab on the current token. The first token searches /bin and the current directory, while path tokens list entries from that path. If multiple matches exist, they are printed space-separated and the input line is restored.
  • lxprofile is stored in RAM only; the default is balanced and it resets on reboot.

Virtual devices

LX shell exposes a few virtual device nodes under /dev:

  • /dev/console: writes to the UART/USB console (VSCode monitor).
  • /dev/stdout: writes to the on-screen terminal.
  • /dev/stderr: writes to the on-screen terminal using the error color.
  • /dev/tty: alias of /dev/stdout.
  • /dev/kmsg: alias of /dev/console.
  • /dev/full: always fails writes ("no space left").
  • /dev/zero: produces a short hex sample of zero bytes when read.
  • /dev/random and /dev/urandom: produce short hex samples of random bytes when read.
  • /dev/null: discards all output.

Lx profiles

The Lx runtime supports memory profiles:

lxprofile
lxprofile safe|balanced|power
lx --profile power /media/0/my_script.lx

Profiles reserve a minimum amount of free heap to avoid hard OOM crashes.

  • safe : highest reserve, most conservative
  • balanced: default reserve, good for most scripts
  • power: lowest reserve, maximum capacity (higher OOM risk)

Lx project (submodule)

The Lx engine is integrated as a submodule in lib/lx.

Upstream project: github.com/ppyne/lx

To update:

cd lib/lx
git fetch --tags
git checkout v1.3.0

Extended glyphs (Opt key)

Hold Opt and press a key to cycle through extra CP437 glyphs. Each press moves to the next glyph, and releasing Opt keeps the current one. UTF-8 input/output is supported, but only glyphs that map to CP437 are rendered.

Opt key mapping

KeyCycle sequenceKeyCycle sequenceKeyCycle sequence
,≤<◄←,_±+▬_mµm
.≥>▼↓•◘∙·■.aàâæÆáäÄåŪαanñÑⁿ∩n
/¿?►→/cçÇ¢coôöÖòóº°Ωo
0°○◙☺︎☻☼♂♀0dδdp₧π¶p
1¡‼½¼♪♫↕↨1eéÉèêëεesßσΣ§s
2²2fƒφΦftτΘt
8÷∞8gΓguùûüÜú∩u
;▲↑;iîïìí∞iv√♥♦♣♠v
=±≡≈÷=l£∟lyÿ¥y

UTF-8 to CP437 rendered glyphs

GlyphUTF-8CP437GlyphUTF-8CP437GlyphUTF-8CP437
☺U+263A0x01ûU+00FB0x96╠U+25600xCC
☻U+263B0x02ùU+00F90x97═U+25500xCD
♥U+26650x03ÿU+00FF0x98╬U+256C0xCE
♦U+26660x04ÖU+00D60x99╧U+25670xCF
♣U+26630x05ÜU+00DC0x9A╨U+25680xD0
♠U+26600x06¢U+00A20x9B╤U+25640xD1
•U+20220x07£U+00A30x9C╥U+25650xD2
◘U+25D80x08¥U+00A50x9D╙U+25590xD3
○U+25CB0x09₧U+20A70x9E╘U+25580xD4
◙U+25D90x0AƒU+01920x9F╒U+25520xD5
♂U+26420x0BáU+00E10xA0╓U+25530xD6
♀U+26400x0CíU+00ED0xA1╫U+256B0xD7
♪U+266A0x0DóU+00F30xA2╪U+256A0xD8
♫U+266B0x0EúU+00FA0xA3┘U+25180xD9
☼U+263C0x0FñU+00F10xA4┌U+250C0xDA
►U+25BA0x10ÑU+00D10xA5█U+25880xDB
◄U+25C40x11ªU+00AA0xA6▄U+25840xDC
↕U+21950x12ºU+00BA0xA7▌U+258C0xDD
‼U+203C0x13¿U+00BF0xA8▐U+25900xDE
U+00B60x14⌐U+23100xA9▀U+25800xDF
§U+00A70x15¬U+00AC0xAAαU+03B10xE0
▬U+25AC0x16½U+00BD0xABßU+00DF0xE1
↨U+21A80x17¼U+00BC0xACΓU+03930xE2
↑U+21910x18¡U+00A10xADπU+03C00xE3
↓U+21930x19«U+00AB0xAEΣU+03A30xE4
→U+21920x1A»U+00BB0xAFσU+03C30xE5
←U+21900x1B░U+25910xB0µU+00B50xE6
∟U+221F0x1C▒U+25920xB1τU+03C40xE7
↔U+21940x1D▓U+25930xB2ΦU+03A60xE8
▲U+25B20x1E│U+25020xB3ΘU+03980xE9
▼U+25BC0x1F┤U+25240xB4ΩU+03A90xEA
⌂U+23020x7F╡U+25610xB5ΩU+21260xEA
ÇU+00C70x80╢U+25620xB6δU+03B40xEB
üU+00FC0x81╖U+25560xB7∞U+221E0xEC
éU+00E90x82╕U+25550xB8φU+03C60xED
âU+00E20x83╣U+25630xB9εU+03B50xEE
äU+00E40x84║U+25510xBA∩U+22290xEF
àU+00E00x85╗U+25570xBB≡U+22610xF0
åU+00E50x86╝U+255D0xBC±U+00B10xF1
çU+00E70x87╜U+255C0xBD≥U+22650xF2
êU+00EA0x88╛U+255B0xBE≤U+22640xF3
ëU+00EB0x89┐U+25100xBF⌠U+23200xF4
èU+00E80x8A└U+25140xC0⌡U+23210xF5
ïU+00EF0x8B┴U+25340xC1÷U+00F70xF6
îU+00EE0x8C┬U+252C0xC2≈U+22480xF7
ìU+00EC0x8D├U+251C0xC3°U+00B00xF8
ÄU+00C40x8E─U+25000xC4∙U+22190xF9
ÅU+00C50x8F┼U+253C0xC5·U+00B70xFA
ÉU+00C90x90╞U+255E0xC6√U+221A0xFB
æU+00E60x91╟U+255F0xC7ⁿU+207F0xFC
ÆU+00C60x92╚U+255A0xC8²U+00B20xFD
ôU+00F40x93╔U+25540xC9■U+25A00xFE
öU+00F60x94╩U+25690xCAU+00A00xFF
òU+00F20x95╦U+25660xCB

License

BSD 3-Clause License. See LICENSE.

About

Minimal Unix-like shell for the M5Stack Cardputer ADV, with a tiny vi/nano editor, core commands, and Lx script support.

Topics

advcardputerembeddedesp32linuxlxlx-scriptm5stacknanoplatformiosdcardshellterminalunixvi

Resources

Readme
BSD-3-Clause license
Activity

Stars

10 stars

Watchers

1 watching

Forks

1 fork
Report repository

Releases

Packages

Contributors

Languages