PyDOS

PyDOS, PyBASIC, edit... All the functionality of the 1981 IBM PC on a PI Pico?

MicroPython/CircuitPython DOS-like shell for microcontroller boards:
(RP2040, RP2350, ESP32, ESP32 PICO-D4, ESP32-S2/S3, nRF52840, SAMD51, stm32L4+, NXM ARM Cortex-M7, Lilygo T-Deck, M5Stack Cardputer, Cheap Yellow Display - esp32-2432s028)

Check out the demo video at https://www.youtube.com/watch?v=Az_oiq8GE4Y

Related Repositories:
PyDOS_virtkey - The modules needed to add virtual keyboard support to PyDOS
PyDOS_wifi - Generalized Python based microcontroller WiFi API

See the Installation section below to install all the external commands and customize the install for the particular microcontroller you are using. However, if you just want to launch the shell or have limited flash space, the PyDOS.py program will run standadlone so you can simply copy PyDOS.py to your microcontroller to begin.

To start the shell type import PyDOS at the REPL prompt.

At the PyDOS prompt a python program (.py) or batch (.bat) file can be run by simply entering the filename with or without the extension.

setup.bat in the root folder, will prompt the user to indicate the the type of board they are using. The setup batch file will then copy the programs and libraries appropriate for the user's platform to the root and /lib folders of the Microcontroller flash.

Implemented DOS Commands:

(syntax and descriptions taken from https://home.csulb.edu/~murdock/dosindex.html)

When run on an operating system that uses a forward slash as the Directory Seperator, PyDOS requires all switches to immediatly follow the command with no spaces between the command or switches. This is necessary becuase the forward slash directory seperator conflicts with the DOS switch seperator. If the PyDOS environement variable DIRSEP is set to \ (i.e. set DIRSEP=\) PyDOS will utilize the traditional backslash as the directory seperator and DOS switches can then be placed anywhere on the command line. Many of the messages displayed by PyDOS and virtually all external Python programs will not respect this environment variable so the *nix forward slash seperator may still be displayed or required when inputting path names to external programs.

If a command argument contains spaces the argument must be enclosed in quotes.

REM [comment] - Used in batch files to insert remarks (that will not be acted on).

DIR[/P][/W][/S] [path][filename] - Displays directory of files and directories stored on flash.

• /P Pauses after each screenful of information (Q or C to abort listing)
• /W Uses wide list format, displaying file/folder names only
• /S Displays files recursively, traversing any subdirectories

DATE - Displays the current date.

TIME - Displays the current time.

MEM[/D] - Displays available RAM and performs a garbage collection operation

• /D Include debug information when supported by microcontroller board

VER - Displays PyDOS version

ECHO [ON|OFF][message] - Displays messages or turns on or off the display of commands in a batch file.

PAUSE - Suspends execution until a key is pressed.

GOTO label Causes unconditional branch to the specified label. (labels are defined as :label in batch files)

IF [NOT] EXIST filename (command) [parameters]
IF [NOT] (string1)==(string2) (command) [parameters] - Allows for conditional operations in batch processing.
IF [NOT] ERRORLEVEL (number) (command) [parameters]

SET[/P][/A] (variable)=[(string|prompt)] - Inserts strings into the command environment. The set values can be used later by programs.

• /A specifies that the string to the right of the equal sign is a numerical expression that is evaluated
• /P displays the specified prompt string before setting the value of a variable to a line of input entered by the user
  DOS specific environment variables:
  • LIB - The Python search path for importing libraries (the current directory is always searched first but not included in the LIB variable)
  • PATH - The directory search list for executing python scripts and DOS batch files (the current directory is always searched first but not included in the PATH variable)
  • PROMPT - The DOS prompt string
  • _scrHeight - The number of lines on the terminal or screen
  • _scrWidth - The number of columns on the terminal or screen
  • _displayTerm - After running a python program PyDOS will make sure the terminal is restored to an attached displayio display unless _displayTerm is set to "N".
  • errorlevel - The result code from the previous BAT file or pexec command executed
  • DIRSEP - If set to a backslash (\) PyDOS will use a backslash as the directory seperator character regardless of the seperator used by the local filesystem (i.e. os.sep). If set to anything other than a backslash PyDOS will use a forward slash as the directory seperator character.

PROMPT [prompt text] - Changes or displays the DOS command prompt. Supported strings "$R,$D,$T,$P,$G,$L,$C,$F,$A,$B,$E,$H,$Q,$S,$V,$_,$$" and text literals
Example: prompt $e[44m$p$g sets the backgound blue (if the terminal supports vt100 escape sequences) and displays the current directory followed by a ">"

Character	Description
---------   -----------
$R          Available RAM
$D          Current date
$T          Current time
$P          Current path
$G          > (Greater than sign)
$L          < (Less than sign)
$C          ( (Left parenthesis)
$F          ) (Right parenthesis)
$A          & (Ampersand)
$B          | (Pipe symbol)
$E          ANSI escape code (code 27)
$H          Backspace (delete last character from displayed prompt)
$Q          = (Equal sign)
$S          Space
$V          Version number
$_          ENTER-LINEFEED
$$          $ (Dollar sign)

PATH [path1;path2;...] - Changes or displays the directory search list for executing python scripts and DOS batch files

RENAME (REN, MOVE, MV) [path]filename [path]filename - Changes the filename under which a file is stored.

DELETE (DEL)[/S] [path]filename - Deletes files from disk.

• /S Delete specified files from all subdirectories

TYPE (MORE)[/P] [path]filename - Displays the contents of a file.

• /P Pauses after each screenful of information (Q or C to abort listing)

CD [[d:]path] - Displays working (current) directory or changes to a different directory.
CD .. - Changes to parent directory of current directory.

MKDIR (MD) path - Creates a new subdirectory.

RMDIR (RD)[/S] path - Removes a subdirectory.

• /S Removes all directories and files in the specified directory and the directory itself

COPY[/Y] [path]filename [path][filename] - copies files.

• /Y Suppresses prompting to confirm you want to overwrite an existing destination file

EXIT - In a batch file returns to PyDOS, at PyDOS prompt terminates PyDOS and returns to REPL.

PEXEC[/Q] [python command] - Executes a single python command.

• /Q Supresses error message if error condition occurs (errorlevel variable is set)

An autoexec.bat batch file will automatically execute when PyDOS starts.

External programs included:

External programs may require one-time board configuration using setup.bat

pydospins.py - Displays the GPIO pins for sound output and I2C for the particular board PyDOS is running on.

PyBasic.py [[path]basic program file .py|.bas] - a Basic interpreter from https://github.com/richpl/PyBasic. Tweaked and modified to run on Micropython and Circuitpython. interpreter.py, basicparser.py, basictoken.py, flowsignal.py, lexer.py, program.py, basicdata.py

runasthread.py [[path]python program file[.py]] (Micropython only) - This program will attempt to launch a python program on the second RP2040 core. Threading is experimental on Micropython so it's not difficult to crash the microcontroller using this program. I have not found a way to kill a thread started on the second core so be sure any threads you launch will shutdown on their own or monitor a global variable or thread.lock to respond to a shutdown request (see the badblink.py for an example).

runvm.py [[path]python program file[.py]] - This program is used to launch Python programs that require more memory than is available while running PyDOS. runvm will write a code.py/main.py file which launches the specfied python program after the next soft reboot. The program then uses supervisor.reload() for CircuitPython or sys.exit for MicroPython to perform a reboot (sys.exit requires a Ctrl-D to complete the operation). The specified python program is "wrapped" in some code that passes any command line arguments and the PyDOS environment variables to the newly booted environment as well as code that restores the original code.py/main.py files and causes a second soft reboot returning control to PyDOS.

virtrepl.py - Launches a python REPL that can be run from PyDOS. Type "exit" to close and return to PyDOS.

edlin.py [[path]filename] - line editor inspired by DOS edlin. Intial program structure and functionality generated by MiniMax M2 https://agent.minimax.io/

edit.py [[path]filename] - shell to load full screen editor from https://github.com/robert-hh/Micropython-Editor

bounce.py - Terminal User Interface demo of a bouncing ball. Modified version of bounce by DuckyPolice

xcopy.py[/S][/Y][/V] [path]filename [path][filename] - a more robust version of the copy command

• /S Copies specified files from directories and subdirectories, except for empty ones
• /Y Suppresses prompting to confirm you want to overwrite an exi