MicroHydra is a simple MicroPython based app launcher with some OS-like features.
This code was built with MicroPython v1.23, for the ESP32-S3.
The main function of MicroHydra is to provide an interface to easily switch between MicroPython apps.
And to help lower the barriers to entry for anyone wanting to develop apps for their Cardputer (or other supported device!).
Python scripts can be placed in your device's /apps folder (on the flash), or in a /apps folder on a micro sd card. The launcher scans these two locations on startup.
Take a look at the wiki for some basic guides to get you started with a MicroPython app.
And for a repository of community-made MicroHydra apps, see here.
This program can be thought of as two main components; the launcher and the apploader.
The apploader is the "main.py" file in the root directory, and it's the first thing to run when the device is powered on.
The apploader reads the RTC memory to determine if it should load an app, otherwise, it loads the launcher.
The launcher is the main UI for the app switching functionality. Its primary responsibility is choosing an app, then storing its path in the RTC.memory. Once the app path is in the memory, it calls machine.reset() to refresh the system and return to the apploader, after which the apploader loads the target app.
This approach was chosen to help to prevent issues with memory managment or import conflicts between apps. Resetting the entire device means that the only thing thing loaded before the custom app, is the lightweight apploader.
Apps are designed to work very simply in this launcher. Any Python file placed in the "apps" folder on the flash, or the SD card, will be found and can be launched as an app. This works with .mpy files too, meaning machine code written in other languages can also be linked and run as an app (though I have not tested this yet)
This means that a simple app can be contained as one script, which will be executed when the app is selected from the launcher.
It also means more complicated apps can place a startup file in the apps directory, which imports anything it needs from another folder in the filesystem.
Some apps for MH can be found here, but there are other apps (especially work-in-progress apps) living in other locations, as well.
You can install MicroHydra a few different ways.
-
Install on top of a normal MicroPython installation:
Flash Micropython to your Cardputer, and copy the contents of theDEVICENAME_compiled.zip(orDEVICENAME_raw.zip) file from the "releases" section to the flash on your device.This is the most convenient way to install for development, because you can simply open up the MicroHydra files to see what's goin on. However, the
raw(as in, ending with ".py") form of the software is much more susceptible to memory issues than the other installation methods, so it's reccomended that you use the compiled (.mpy) version for any files that you aren't specifically working inside of. -
Flash MH as a compiled firmware:
You can flash MicroHydra (along with MicroPython) directly to your device using theDEVICENAME.binfile from the "Releases" section. (You can also usually find the most recent builds on M5Burner). This is the fastest and easiest to use form of MH!In this installation, the MicroHydra files have been 'frozen' into the MicroPython firmware. This makes the built-in files load much faster, and makes them all use less memory.
Make sure you erase the flash before installing, and put your device in download mode by holding G0 when plugging it in.
Note for developers: The contents of
src/must be processed in order to output device-specific MicroHydra builds. To learn more, take a look at this page in the wiki.
This is a detailed guide for installing MicroHydra on a regular MicroPython installation, using Thonny.
Thonny is a tool that provides a very easy way to flash MicroPython, edit code, and view/edit the files on the device.
You can follow the instructions here to install it: https://thonny.org/
Make sure to use a new version; older versions might fail to flash the ESP32-S3
Some sources of Thonny (such as with certain built-in package managers) can result in strange issues with permissions or missing dependencies. If you encounter an issue with thonny when setting it up, and there is no other clear solution to your problem, it might be a good idea to try installing from another source.
Next we need to flash MicroPython on your device
Open Thonny, click this button in the bottom right, and click "Configure interpreter":
It should open this menu:
click "install or update micropython", and you should see another window:
Now you need to put your device into bootloader mode, and connect it to your computer. To do this, simply hold the G0 button as you connect it to your PC.
You can also hold
G0and tap the reset button to get to bootloader mode.
If you are using a device like the TDeck, which doesn't power on when plugged in, you must holdg0and then flip the power switch on.
In "target port" you should now see a device with a name like "USB JTAG". Set the options as shown, and click "Install":
For a device with Octal-SPIRAM (like the TDeck), you will have to download a specific Octal-SPIRAM variant from the MicroPython website.
If installing didn't start, check that the correct device is selected, and it's in bootloader mode.
Once It has been flashed with MicroPython, unplug the device and plug it back in.
Thonny might not automatically detect it right away. If it doesn't, you can select it from the bottom right here:
And you might also need to click the red "stop/restart" button at the top to get it to appear.
If you see something like this in the bottom terminal, you've flashed it successfully!
Now you can download and install MicroHydra.
To get the apropriate files for your device, you should head to the "Releases" section of the GitHub page, and look for a DEVICENAME_compiled.zip or DEVICENAME_raw.zip file.
Extract the .zip file, and head back over to Thonny.
We need to use Thonnys file browser. If you don't see it to your left, you can bring it up by clicking view>Files in the top left.
On the top half of the file browser, navigate to the folder where you extracted the MicroHydra zip file.
Then, select all of the contents, and hit Upload to /
Once the files are transferred over, you can test it out by disconnecting it, and powering it on. If everything is working, you should see the main launcher open up!
If you have any issues, feel free to reach out. MH is still growing, and I'm interested to hear of any trouble it might be giving you.
This is a detailed guide for flashing the MicroHydra firmware on your device, using Thonny.
Thonny is a tool that provides a very easy way to flash MicroPython, edit code, and view/edit the files on the device.
You can follow the instructions here to install it: https://thonny.org/
Make sure to use a new version; older versions might fail to flash the ESP32-S3
Some sources of Thonny (such as with certain built-in package managers) can result in strange issues with permissions or missing dependencies. If you encounter an issue with thonny when setting it up, and there is no other clear solution to your problem, it might be a good idea to try installing from another source.
Now you can download and install MicroHydra.
To get the apropriate firmware for your device, you should head to the "Releases" section of the GitHub page, look for a DEVICENAME.bin file, and download it.
Open Thonny, click this button in the bottom right, and click "Configure interpreter":
It should open this menu:
click "install or update micropython", and you should see another window:
Now you need to put your device into bootloader mode, and connect it to your computer. To do this, simply hold the G0 button as you connect it to your PC.
You can also hold
G0and tap the reset button to get to bootloader mode.
If you are using a device like the TDeck, which doesn't power on when plugged in, you must holdg0and then flip the power switch on.
Next we will select the firmware .bin file we downloaded.
Click the little menu button and click Select local MicroPython image ...
Navigate to the .bin file you downloaded, and select it.
Make sure you also select your device in the "Target port" dropdown (it should have a name like "USB JTAG").
Your window should look something like this:
Click "Install", and let it do its thing!
If installing didn't start, check that the correct device is selected, and it's in bootloader mode.
Once it's flashed, you can test it out by disconnecting it, and powering it on. If everything is working, you should see the main launcher open up!
If you have any issues, feel free to reach out. MH is still growing, and I'm interested to hear of any trouble it might be giving you.
