{"id":26501873,"url":"https://github.com/RetiredWizard/PyDOS","last_synced_at":"2025-03-20T17:03:36.116Z","repository":{"id":38041666,"uuid":"372102663","full_name":"RetiredWizard/PyDOS","owner":"RetiredWizard","description":"DOS-like OS for microcontroller boards running Micropython or Circuitpython","archived":false,"fork":false,"pushed_at":"2025-03-02T18:14:07.000Z","size":1206,"stargazers_count":145,"open_issues_count":0,"forks_count":18,"subscribers_count":9,"default_branch":"main","last_synced_at":"2025-03-08T14:43:17.734Z","etag":null,"topics":["basic","cardputer","cheap-yellow-display","circuitpython","cortex-m7","dos","esp32","esp32-2432s028","esp32s2","esp32s3","micropython","nrf52840","pico","python","raspberry","rp2040","rp2350","samd51","stm32","t-deck"],"latest_commit_sha":null,"homepage":"https://www.youtube.com/watch?v=Az_oiq8GE4Y","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/RetiredWizard.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-05-30T01:50:02.000Z","updated_at":"2025-03-05T02:50:55.000Z","dependencies_parsed_at":"2023-12-04T05:23:10.424Z","dependency_job_id":"250e0606-f969-44b3-aeea-0ced0fa8d249","html_url":"https://github.com/RetiredWizard/PyDOS","commit_stats":{"total_commits":492,"total_committers":1,"mean_commits":492.0,"dds":0.0,"last_synced_commit":"6e668b1180749252bc43b8c05979ba7b1f6dffae"},"previous_names":[],"tags_count":32,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RetiredWizard%2FPyDOS","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RetiredWizard%2FPyDOS/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RetiredWizard%2FPyDOS/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RetiredWizard%2FPyDOS/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/RetiredWizard","download_url":"https://codeload.github.com/RetiredWizard/PyDOS/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244656704,"owners_count":20488638,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["basic","cardputer","cheap-yellow-display","circuitpython","cortex-m7","dos","esp32","esp32-2432s028","esp32s2","esp32s3","micropython","nrf52840","pico","python","raspberry","rp2040","rp2350","samd51","stm32","t-deck"],"created_at":"2025-03-20T17:01:55.454Z","updated_at":"2025-03-20T17:03:36.109Z","avatar_url":"https://github.com/RetiredWizard.png","language":"Python","readme":"## PyDOS, PyBASIC, edit... All the functionality of the 1981 IBM PC on a PI Pico?\r\n\r\n**MicroPython/CircuitPython DOS-like shell for microcontroller boards:**  \r\n**(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)**  \r\n\r\n**Check out the demo video at https://www.youtube.com/watch?v=Az_oiq8GE4Y**\r\n\r\n*Related Repositories:*  \r\n[PyDOS_virtkey](https://github.com/RetiredWizard/PyDOS_virtkeyboard) - The modules needed to add virtual keyboard support to PyDOS  \r\n[PyDOS_wifi](https://github.com/RetiredWizard/PyDOS_wifi) - Generalized Python based microcontroller WiFi API\r\n\r\nSee 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.\r\n\r\nTo start the shell type **import PyDOS** at the REPL prompt.\r\n\r\nAt the PyDOS prompt a python program (.py) or batch (.bat) file can be run by simply entering the filename with or without\r\nthe extension.\r\n\r\n**setup.bat** in the root folder, will prompt the user to indicate the the type of board they are using.\r\nThe setup batch file will then copy the programs and libraries appropriate for the user's\r\n platform to the root and /lib folders of the Microcontroller flash.\r\n\r\n## Implemented DOS Commands:  \r\n(syntax and descriptions taken from https://home.csulb.edu/~murdock/dosindex.html)\r\n\r\nWhen 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 \r\nis 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.\r\nMany 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.\r\n\r\nIf a command argument contains spaces the argument must be enclosed in quotes.\r\n\r\n**REM [comment]** - Used in batch files to insert remarks (that will not be acted on).\r\n\r\n**DIR[/P][/W][/S] [path][filename]** - Displays directory of files and directories stored on flash.\r\n- /P Pauses after each screenful of information (Q or C to abort listing)  \r\n- /W Uses wide list format, displaying file/folder names only  \r\n- /S Displays files recursively, traversing any subdirectories  \r\n\r\n**DATE** - Displays the current date.\r\n\r\n**TIME** - Displays the current time.\r\n\r\n**MEM[/D]** - Displays available RAM and performs a garbage collection operation  \r\n- /D Include debug information when supported by microcontroller board\r\n\r\n**VER** - Displays PyDOS version\r\n\r\n**ECHO [ON|OFF][message]** - Displays messages or turns on or off the display of commands in a batch file.\r\n\r\n**PAUSE** - Suspends execution until a key is pressed.\r\n\r\n**GOTO label** Causes unconditional branch to the specified label. (labels are defined as :label in batch files)\r\n\r\n**IF [NOT] EXIST filename (command) [parameters]**  \r\n**IF [NOT] (string1)==(string2) (command) [parameters]** - Allows for conditional operations in batch processing.  \r\n**IF [NOT] ERRORLEVEL (number) (command) [parameters]**  \r\n\r\n**SET[/P][/A] (variable)=[(string|prompt)]** - Inserts strings into the command environment. The set values can be used later by programs.  \r\n- /A specifies that the string to the right of the equal sign is a numerical expression that is evaluated  \r\n- /P displays the specified prompt string before setting the value of a variable to a line of input entered by the user  \r\n*DOS specific environment variables:*\r\n    - LIB - The Python search path for importing libraries (the current directory is always searched first but not included in the LIB variable)  \r\n    - 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)\r\n    - PROMPT - The DOS prompt string\r\n    - _scrHeight - The number of lines on the terminal or screen\r\n    - _scrWidth - The number of columns on the terminal or screen\r\n    - errorlevel - The result code from the previous BAT file or pexec command executed\r\n    - 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.\r\n\r\n**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  \r\nExample: `prompt $e[44m$p$g` sets the backgound blue (if the terminal supports vt100 escape sequences) and displays the current directory followed by a \"\u003e\"\r\n\r\n```\r\nCharacter\tDescription\r\n---------   -----------\r\n$R          Available RAM\r\n$D          Current date\r\n$T          Current time\r\n$P          Current path\r\n$G          \u003e (Greater than sign)\r\n$L          \u003c (Less than sign)\r\n$C          ( (Left parenthesis)\r\n$F          ) (Right parenthesis)\r\n$A          \u0026 (Ampersand)\r\n$B          | (Pipe symbol)\r\n$E          ANSI escape code (code 27)\r\n$H          Backspace (delete last character from displayed prompt)\r\n$Q          = (Equal sign)\r\n$S          Space\r\n$V          Version number\r\n$_          ENTER-LINEFEED\r\n$$          $ (Dollar sign)\r\n```\r\n\r\n**PATH [path1;path2;...]** - Changes or displays the directory search list for executing python scripts and DOS batch files\r\n\r\n**RENAME (REN, MOVE, MV) [path]filename [path]filename** - Changes the filename under which a file is stored.\r\n\r\n**DELETE (DEL)[/S] [path]filename** - Deletes files from disk.  \r\n- /S Delete specified files from all subdirectories\r\n\r\n**TYPE (MORE)[/P] [path]filename** - Displays the contents of a file.  \r\n- /P Pauses after each screenful of information (Q or C to abort listing)\r\n\r\n**CD [[d:]path]** - Displays working (current) directory or changes to a different directory.  \r\n**CD ..** - Changes to parent directory of current directory.\r\n\r\n**MKDIR (MD) path** - Creates a new subdirectory.\r\n\r\n**RMDIR (RD)[/S] path** - Removes a subdirectory.  \r\n- /S Removes all directories and files in the specified directory and the directory itself\r\n\r\n**COPY[/Y] [path]filename [path][filename]** - copies files.  \r\n- /Y Suppresses prompting to confirm you want to overwrite an existing destination file\r\n\r\n**EXIT** - In a batch file returns to PyDOS, at PyDOS prompt terminates PyDOS and returns to REPL.\r\n\r\n**PEXEC[/Q] [python command]** - Executes a single python command.\r\n- /Q Supresses error message if error condition occurs (errorlevel variable is set)\r\n\r\nAn **autoexec.bat** batch file will automatically execute when PyDOS starts.\r\n\r\n### External programs included:\r\n*External programs may require one-time board configuration using setup.bat*\r\n\r\n**pydospins.py** - Displays the GPIO pins for sound output and I2C for the particular board PyDOS is running on.\r\n\r\n**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.\r\n\tinterpreter.py, basicparser.py, basictoken.py, flowsignal.py, lexer.py, program.py, basicdata.py\r\n\t\r\n**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\r\nexperimental on Micropython so it's not difficult to crash the microcontroller using this program. I have not found a way to kill\r\na thread started on the second core so be sure any threads you launch will shutdown on their own or monitor a global variable or\r\nthread.lock to respond to a shutdown request (see the badblink.py for an example).\r\n\r\n**runvm.py [[path]python program file[.py]]** - This program is used to launch Python programs that require more memory\r\nthan is available while running PyDOS. **runvm** will write a **code.py**/**main.py**\r\nfile which launches the specfied python program after the next soft reboot. The program then\r\nuses **supervisor.reload()** for CircuitPython or **sys.exit** for MicroPython to\r\nperform a reboot (sys.exit requires a Ctrl-D to complete the operation). The specified python\r\nprogram is \"wrapped\" in some code that passes any command line arguments and the PyDOS\r\nenvironment variables to the newly booted environment as well as code that restores the\r\noriginal **code.py**/**main.py** files and causes a second soft reboot returning control to\r\nPyDOS.\r\n\r\n**virtrepl.py** - Launches a python REPL that can be run from PyDOS. Type \"exit\" to close and return to PyDOS.\r\n\r\n**edlin.py [[path]filename]** - line editor inspired by DOS edlin. Intial program structure of line editor by Joesph Long\r\n    https://github.com/j-osephlong/Python-Text-Editor\r\n    \r\n**edit.py [[path]filename]** - shell to load full screen editor from https://github.com/robert-hh/Micropython-Editor\r\n\r\n**bounce.py** - Terminal User Interface demo of a bouncing ball. Modified version of bounce by [DuckyPolice](https://github.com/DuckyPolice)\r\n\r\n**xcopy.py[/S][/Y][/V] [path]filename [path][filename]** - a more robust version of the copy command  \r\n- /S Copies specified files from directories and subdirectories, except for empty ones  \r\n- /Y Suppresses prompting to confirm you want to overwrite an existing destination file\r\n- /V Performs a verification read of the copied file to ensure it matches the source\r\n\r\n**fileview.py [[path]filename]** - scrollable text file viewer\r\n\r\n**sdmount.py [[mount path][,pydos spi bus#]]** - mounts an sd card to the file system. If no SD card CS pins are defined or -1 is passed as the spi bus# the sd\r\ncard will be mounted using an SDIO bus rather than an SPI bus.    \r\n**sdumount.py [mount path]** - dismounts an sd card from the file system\r\n\r\n**setdate.py [mm-dd-yy]** - initalizes the real time clock to an entered date  \r\n**settime.py [hh:mm:ss]** - initalizes the real time clock to an entered time  \r\n**getdate.py [timzone offset]** (WiFi enabled boards) - sets the time and date from worldtimeapi.org and failing that, uses the Internet NTP protocol\r\n\r\n**diff.py [filename1,filename2]** - performs a file comparison\r\n\r\n**sound.py [Frequency,Duration(miliseconds),Volume]** - outputs a sound to a speaker cicruit connected to GPIO pin defined in lib/pydos_bcfg.py  \r\n**tsound.py** - test program that plays a short sound sequence  \r\n**piano.py** - emulates a small piano keyboard\r\n\r\n**i2cscan.py [bus number]** - scans the I2C bus and displays any found device addresses\r\n\r\nCircuitPython LCD libraries from https://github.com/dhylands/python_lcd  \r\n**lcdprint.py [text to display]** - displays text on an I2C LCD display  \r\n**lcdscroll.py [text to scroll]** - scrolls text on an I2C LCD display  \r\n**temperature.py** - displays temperature value from onboard temperature sensor to screen and I2C LCD display\r\n\r\n**basicpython.py** - Shell modeled after basic interpreter shell from https://github.com/tannewt/basicpython\r\n\r\n**blink.py [led pin number]** - program to blink onboard LED\r\n\r\n**rgbset.py [pin number,[size,[pixel]]]** - program to set the rgb color of an onboard neopixel or dotstar. The *size* and *pixel* arguments can be used to identify individual pixel in pixel array of more than 1 neopixel/dotstar.  \r\n\r\n**rgbblink.py [pin number]** - program to blink an onboard neopixel or dotstar  \r\n**rgbrainbow.py [pin number]** - program to color cycle an onboard neopixel or dotstar  \r\n\r\n**matrix.py [width,height,depth,across,down]** - (Circuitpython only) program to initalize connected HUB75 RGB Matrix Panels as a CircuitPython display. The display object is stored as a PyDOS environment variable (_display).  \r\n  \r\nParameters:  \r\nwidth - base width of a single RGB matrix tile  \r\nheight - base height of a single RGB matrix tile  \r\ndepth - the color depth of the matrix  \r\nacross - the number of tiles connected across the matrix display  \r\ndown - the number of tiles connected down the matrix display\r\n\r\nIf the parameters are omitted or not properly formatted, the program will prompt for each of the values.  \r\n\r\n**Playimage.py [filename[,filename2,filename3,etc[],seconds_to_display]]]** - (Circuitpython only, requires the adafruit_imageload library installed in the /lib folder) program to display .bmp, .jpg, .gif (incl animated) or .png image files. If multiple comma \r\nseperated files are entered a continous slide show is displayed with each image being \r\ndisplayed for `seconds_to_display` seconds. Wildcard's in the format of *.xxx can be used\r\nas an input filename. If the program is loaded from PyDOS it attempts to determine the appropriate display configuration from the PyDOS environment, otherwise several display options are supported and selected depending on the existence of BOARD.DISPLAY or locally installed display libraries.\r\n\r\n**reboot.py** - performs a soft reboot (Micropython requires a Ctrl-D to complete)\r\n\r\n**keys.bat** - (Keyboard Featherwing/BBQ Keyboard/LilyGo T-Deck only) Displays keyboard mappings for hidden keys and functions  \r\n**ui.bat [u/k]** - (Keyboard Featherwing/BBQ Keyboard only) Switches between using the Keyboard Featherwing and USB Serial port for PyDOS I/O\r\n\r\n**fs.py [ro/rw]** - (Circuitpython only) By selecting the \"RO\" option the flash mode is set such that when the microcontroller\r\nis power cycled or hard reset, the host computer will have read/write access to the flash and the microcontoller will be\r\nrestricted to read only access. To give PyDOS access to the flash after switching to this mode the boot.py file must be\r\nreplaced or modified from the host computer so that it contains the following instructions:\r\n\r\n    import storage\r\n    storage.remount(\"/\",False)\r\n    \r\nand then power cycled or hard reset.\r\n\r\n**setenv.py** - Helper program for adding the WiFi SSID and Password to settings.toml (used by setup.bat).\r\n\r\n*WiFi enabled boards only*  \r\n**wifi_finance [symbol]** - Displays the current Nasdaq prices by connecting to a financial website and scraping the information. If an optional symbol is supplied, the program will attempt to identify the symbol and scrap the corresponding price information.  \r\n**wifi_weather** - Displays the 7 day forcast from api.weather.gov\r\n\r\n## Hardware (Pin) customization file (pydos_bcfg.py)\r\n\r\n\r\nThe setup.bat file will identify the board being used from **board.board_id** or\r\n**sys.implementation._machine** and attempt to copy a customization file from the cpython or mpython /boardconfigs directory. If a matching config file is not found the default /lib/pydos_bcfg.py file will be used.\r\n\r\nThe pydos_bcfg.py file acts as a library which contains a single dictionary opject, Pydos_pins.\r\n\r\nThe recognized keys of the Pydos_pins dictionary are:  \r\n\r\n**TUPLES (pin number, Text description of identified pin)**  \r\nexample: `'led' : (25, \"GP25\")`  \r\n\r\n**led** - Micropython may use text identifer (i.e. \"led\") rather than pin number  \r\n**sndPin**  \r\n**neoPixel**  \r\n**neoPixel_Pow**  \r\n**dotStar_Clock**  \r\n**dotStar_Data**  \r\n**dotStar_Extra**  \r\n**dotStar_Pow**  \r\n**I2C_NUM** - MicroPython hardware I2C number  \r\n**SCL**  \r\n**SDA**  \r\n**SDIO_CLK**  \r\n**SDIO_CMD**  \r\n**SDIO_DPINS** - the \"pin number\" element for SDIO_DPINS is a list of pins  \r\n\r\n**LIST OF TUPLES**  \r\n*First tuple in list used for machine/board SD dedicated SPI (board.SD_SPI)*  \r\n*Last tuple in list used for machine/board general use SPI (board.SPI)*  \r\nexample: `'MISO' : [(43, \"DAT0 D43 Internal\"), (12, \"MISO D12\")]`\r\n\r\n**SPI_NUM** - MicroPython hardware SPI number  \r\n**SCK**  \r\n**MOSI**  \r\n**MISO**  \r\n**CS**  \r\n\r\n**CALCULATED DATA**\r\n\r\n**sndGPIO** - digitalio.DigitalInOut(sndPin)  \r\n**KFW** - Flag indicating use of Keyboard FeatherWing (True/False)  \r\n**I2CbbqDevice** - I2C device being used for the KFW keyboard  \r\n**SD** - list of sdcard objects  \r\n**SDdrive** - list of mount points for mounted SD cards\r\n\r\n\r\n## PyDOS Generalized Wifi API library (pydos_wifi.py)\r\n\r\nWhenever possible PyDOS and the bundled external programs work equally well on MicroPython or CircuitPython and on any of the supported micro controller chip families. To assist in reaching this goal PyDOS_wifi, a simplified Wifi library, is being developed which provides a unified Wifi API that works the same under both MicroPython and CircuitPython on ESP32xx, Pico W and Arduino Nano based Microcontrollers.\r\n\r\nFor PyDOS_wifi API documentation see https://github.com/RetiredWizard/PyDOS_wifi\r\n\r\n\r\n## Installation\r\n\r\n**Before copying PyDOS files**\r\n\r\nIf the board you're using has limited flash storage, as is the case with the Pico W, you can delete either the **cpython** (if you're not using CircuitPython) or **mpython**\r\n(if you're not using MicroPython) folder from the downloaded repository files. Within the remaining Python folder (**cpython** or **mpython**) are folders\r\nfor specific micro controller boards, you can free up further space by deleting anything other than the board you are using (the \"Pico W\" and \"Arduino Nano Connect\" boards use the ESP folder). For very limited Flash boards you may want to delete the **PyBasic** folder until after the **setup.bat** step is run. Once setup has ben run, delete the **cpython** and/or **mpython** folders from the microcontroller and copy as much of the **PyBasic** directory as space permits to the Microcontroller. Copying just the *.py files is all that's needed for PyBasic to run.\r\n\r\n**Circuitpython PYSTACK**\r\n\r\nThanks to the great work of **@bill88t**, starting with CircuitPython version 8.0.4, you no longer need to build custom CirucitPython firmware (ESP32 based boards are still being worked on but should have this feature in 8.0.6/8.1.0). PyDOS will run without issue on a standard downloaded CircuitPython image from https://circuitpython.org/downloads. \r\n\r\nWhen CircuitPython boots on a microcontroller the pystack size can be set by the **CIRCUITPY_PYSTACK_SIZE** value in the settings.toml file. PyDOS comes with this value set to 4000. PyDOS will derive a maximum wildcard length based on this value that should be adequate in most cases, however if you find yourself using particuarly long file names you can increase this parameter value as needed. As you increase the pystack size the memory available for PyDOS to run will decrease slightly.\r\n\r\n*By the way, if you like PyDOS you'll probably also enjoy Beryllium OS from https://github.com/beryllium-org/OS  \r\n\r\n**CircuitPython install**\r\n\r\nTo install the CircuitPython image, put your microcontroller board in \"bootloader\" mode and copy the .UF2 file to the USB mass storage device that shows up on your host computer. \r\n\r\nAfter the .UF2 file is copied to the microcontroller board it should re-boot and a new USB mass storage device should appear.\r\n\r\n**PyDOS install**\r\n\r\nTo copy PyDOS to the Microcontroller, simply drag the PyDOS directory structure\r\n(after removing the **mpython** folder if space is a concern) to the root directory of the device that appears on the host computer.\r\n\r\nIf the copy is interrupted for any reason you can delete the boot.py\r\nfile in the root of the microcontroller flash and try the copy again. \r\n\r\nIf the copy worked without any errors, you should power cycle the microcontroller board so that the file system is configured to allow the microcontroller to have Read/Write access. When you do this, the host computer will no longer be able to write to the microcontroller mounted drive (usually CIRCUITPY).\r\n\r\nIf you find yourself locked out of the flash from the host computer and PyDOS is not running, the easiest way to recover is to\r\nconnect to the REPL, remove the boot.py file and then power cycle the microcontroller board. \r\n\r\n        import os\r\n        os.remove(\"boot.py\")\r\n\r\nTo interact with the microcontroller you will need to connect using a terminal program. On a PC you can use putty and on linux, I would recommend [tio](https://github.com/tio/tio). To start tio on linux type the command:\r\n\r\n          tio /dev/ttyACM0\r\n\t  \r\nYou should be presented with either the REPL prompt (\u003e\u003e\u003e) or the PyDOS prompt (\\\u003e), if not, press return or Ctrl-C. *After using Thonny, you may need to press CTRL-B to exit the raw REPL mode that \r\nThonny uses to transfer and execute files.*\r\n\r\nAt the REPL prompt type \"**import PyDOS**\" to start PyDOS. From PyDOS type **setup** to run the customization script.\r\n\r\nOnce the **setup.bat** script has been run if you have more files to copy to the microcontroller (PyBasic for example) or you want to run **circup**, you will need to give the host computer read/write access to the mounted microcontroller drive. This is done by typing **\"fs ro\"** at the PyDOS prompt and then power cycling the board.\r\n\r\nAfter running **circup** or deleting/copying files using the Host computer, when you want to run PyDOS normally again, edit the **boot.py** file in the root folder of the mounted microcontroller drive (usually CIRCUITPY) and change the line that reads:  \r\n\r\n            storage.remount(\"/\",True)  \r\n\r\nto:  \r\n\r\n            storage.remount(\"/\",False)  \r\n\r\nand then powercycle the board once again.\r\n\r\nIt is recommended that once the **setup.bat** script has been run, **circup** be run on your host computer, in order to make sure the libraries are updated and in sync with the version of CircuitPython on your microcontroller board.\r\n\r\nInstructions on installing and using **circup** can be found [here](https://learn.adafruit.com/keep-your-circuitpython-libraries-on-devices-up-to-date-with-circup/overview)  \r\n\r\nOn your host PC, you should run:  \r\n**circup update**  (if you are conected to the board via a USB cable)  \r\n**circup --host *ip-address* --password *CIRCUITPY_WEB_API_PASSWORD* update** (for wifi enabled boards)  \r\n  \r\nOn your microcontroller, you can use the **setenv.py** PyDOS program to set or see your current CIRCUITPY_WEB_API_PASSWORD.  \r\n\r\nYou can also run commands like:\r\n**circup install adafruit_imageload** to install any adafruit libraries you need.  \r\n\r\n--------------------------------------------------------------------------------------------------------------------\r\n**Building custom Micropython firmware**\r\n\r\nAlthough you can use a standard Micropython image downloaded from Micropython.org to run PyDOS, there are two reasons you may want to build a custom\r\nMicropython firmware file. \r\n\r\nThe first is if you wan to connect up an old school serial terminal to the REPL rather than the standard serial over USB connection. Instructions for building \r\nMicropython with this modification can be found in section 2.2 of the Raspberry Pi Pico Python SDK at https://datasheets.raspberrypi.com/pico/raspberry-pi-pico-python-sdk.pdf.\r\n\r\nThe second is that PyDOS uses a recursive routine to process wildcard operations and the default stack in Micropython limits the recursion depth that can be obtained **(With more recent versions of Micropython this has become much less of an issue)**.\r\nThis means that PyDOS has to limit wildcard operations, one impact of this is that files with longer file names may not appear\r\nin directory listings when wildcards are used. To eliminate this issue a custom Micropython image can be built with the the MICROPY_STACKLESS parameter in **py/mpconfig.h**\r\nchanged from **0** to **1**.  \r\n**\\*\\*Note\\*\\* I haven't tested a MICROPY_STACKLESS build since ~1.19**\r\n\r\n**MicroPython Setup**\r\n\r\nOnce your microcontroller has Micropython installed and running the best way\r\nto copy the PyDOS files and interact with the repl is to use Thonny. Adafruit has a good learning guide for getting started with Thonny here:\r\nhttps://learn.adafruit.com/circuitpython-libraries-on-micropython-using-the-raspberry-pi-pico/micropython-installation. \r\n\r\nDownload PyDOS from the github repository and after deleting the **cpython** folder if space is an issue, use the Thonny upload command as described in the Adafruit \r\nlearning guide to copy the downloaded files to the microcontroller.\r\n\r\nTo interact with the microcontroller connect over the serial USB port (COMn: /dev/ttyACMx, etc) using a terminal program like puTTY or minicom. You can use the Thonny shell as well\r\nhowever, it does not support the basic ansi escape sequences used by some of the PyDOS functions.\r\nOne thing to note is that if you\r\nconnect to your microcontroller with a terminal program after using Thonny, you may need to press CTRL-B to exit the raw REPL mode that \r\nThonny uses to transfer and execute files.\r\n\r\nAnother option is to use MPRemote. Detailed documentation on installing and using MPRemote can be found \r\nat https://docs.micropython.org/en/latest/reference/mpremote.html.\r\n\r\nTo install PyDOS on the microcontroller board download PyDOS from the github repository and after deleting the **cpython** folder if space is an issue, set your current\r\ndirectory to the root folder of the downloaded PyDOS repository and use the following command:\r\n\r\n\tmpremote fs cp -r * :\r\n\t\r\nTo interact with the microcontroller you can connect to the REPL by simply typing **mpremote** and pressing return several times until the REPL prompt\r\n(\u003e\u003e\u003e) is displayed.\r\n\r\nAt the REPL prompt type \"**import PyDOS*** to start PyDOS and then type **setup** to run the customization script.\r\n\r\n**Note** If the board you're using has an onboard SD card slot, Micropython may not mount the flash at the root mount point. In this case copy the PyDOS files to the \"/Flash\" folder during the initial PyDOS setup. If you plan to boot your device with an SD card inserted you should install PyDOS and run setup before inserting the SD card, then copy boot.py to the SD card.\r\n\r\n**Note** To set up the Seeed (XIAO) nRF52840 board running MicroPython, copy the PyDOS /mpython folder to the /flash folder on the device and then copy the /mpython/boot.py file to /Flash/boot.py and reboot the microcontroller. You should then be able to install PyDOS as usual although the current version of Thonny has difficulty with this board so you should only copy a single folder (i.e. lib, mpython, PyBasic and then all the root files) at a time.\r\n\r\n## To Do  \r\n*Possible updates depending on RAM impact*\r\n\r\n- ~~integrate ConnectionManager into PyDOS_wifi~~\r\n- investigate porting micropython flash mount to circuitpython\r\n- investigate date/time stamp issue on seeed nrf52840 files\r\n- support for connected color displays  \r\n- ~~support for touch screens~~  \r\n- Rename should allow wildcards in filenames, i.e. \"rename *.bas *.txt\" or \"rename code.py *.sav\"  \r\n- Quiet, /Q switches to DEL, RMDIR, COPY, XCOPY commands\r\n- PgUp/PgDwn support in fileview.py\r\n- Properly implement edlin cursor position and append command","funding_links":[],"categories":["Python","Community Apps"],"sub_categories":["Launchers"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FRetiredWizard%2FPyDOS","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FRetiredWizard%2FPyDOS","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FRetiredWizard%2FPyDOS/lists"}