Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/echo-lalia/microhydra
MicroHydra is a simple, 'OS-like', MicroPython based app switcher designed for ESP32 based devices.
https://github.com/echo-lalia/microhydra
cardputer cyberdeck esp32 launcher micropython os t-deck
Last synced: 1 day ago
JSON representation
MicroHydra is a simple, 'OS-like', MicroPython based app switcher designed for ESP32 based devices.
- Host: GitHub
- URL: https://github.com/echo-lalia/microhydra
- Owner: echo-lalia
- License: gpl-3.0
- Created: 2024-02-05T07:29:40.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2024-12-11T06:49:00.000Z (11 days ago)
- Last Synced: 2024-12-11T07:33:13.290Z (11 days ago)
- Topics: cardputer, cyberdeck, esp32, launcher, micropython, os, t-deck
- Language: Python
- Homepage:
- Size: 8.54 MB
- Stars: 170
- Watchers: 6
- Forks: 14
- Open Issues: 10
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# MicroHydra
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](https://github.com/echo-lalia/MicroHydra/wiki) for some basic guides to get you started with a MicroPython app.
And for a repository of community-made MicroHydra apps, see [here](https://github.com/echo-lalia/MicroHydra-Apps).
# how it works:
MicroHydra runs only a single "app" at a time, and switches between them by storing data in the RTC memory, and resetting MicroPython.
The launcher, `main.py`, and other built-in apps, import a `hydra.loader` module, to store or load strings in the RTC memory.
MicroPython automatically runs `main.py` when it starts, and `main.py` looks for a stored app path, and imports it if it exists. Otherwise, it starts the launcher 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 app, is the lightweight `hydra.loader` and `main.py` modules.
When MicroHydra is pre-compiled into .mpy files (and therefore doesn't need to compile anything before starting), this reset is fairly quick. And, when it's frozen into a MicroPython firmware, the reset is almost instantaneous.
Apps that need to pass information to eachother can use the same `hydra.loader` module to read/store additional arguments in the RTC.
For example, when you use the Files app to open a file in the text editor, the Files app adds both the path to the text editor, and the path to the text file into the RTC memory.
# Installing Apps:
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)
MicroHydra apps can be simple single-file scripts, or be contained in a folder with an `__init__.py`, just like a standard Python module. You can learn more about these specifics on the [app format](https://github.com/echo-lalia/MicroHydra/wiki/App-Format) section of the wiki.
Some community-made apps for MH can be found [here](https://github.com/echo-lalia/MicroHydra-Apps) (and this is where the "GetApps" built-in app find apps to download).
# Installing MicroHydra:
You can install MicroHydra a few different ways.
- [*Install on top of a normal MicroPython installation:*](#In-MicroPython)
Flash Micropython to your Cardputer, and copy the contents of the `DEVICENAME_compiled.zip` (or `DEVICENAME_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:*](#As-a-complete-firmware)
You can flash MicroHydra (along with MicroPython) directly to your device using the `DEVICENAME.bin` file 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](https://github.com/echo-lalia/MicroHydra/wiki/multi-platform) page in the wiki.*
-----
# In MicroPython
*This is a detailed guide for installing MicroHydra on a regular MicroPython installation, using Thonny.*
## Install 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.*
## Flash MicroPython
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 `G0` and 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 hold `g0` and 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.](https://micropython.org/download/ESP32_GENERIC_S3/)*
> *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!
## Install MicroHydra
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.
----
# As a complete firmware
*This is a detailed guide for flashing the MicroHydra firmware on your device, using Thonny.*
## Install 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.*
## Flash MicroHydra
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 `G0` and 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 hold `g0` and 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.
----
