diff --git a/wiki/Home.md b/wiki/Home.md index 9611bfb..1d967ed 100644 --- a/wiki/Home.md +++ b/wiki/Home.md @@ -5,7 +5,8 @@
## Multiplatform support -MicroHydra uses a few different ideas in order to output code for multiple devices. You can learn about this [here](https://github.com/echo-lalia/MicroHydra/wiki/multi-platform) +MicroHydra uses a few different ideas in order to output code for multiple devices. You can learn about this [here](https://github.com/echo-lalia/MicroHydra/wiki/multi-platform). +You can also learn more about the supported devices [here](https://github.com/echo-lalia/MicroHydra/wiki/Supported-Devices). ## Making Apps For a basic overview of how MicroHydra apps work, see the [App Format](https://github.com/echo-lalia/MicroHydra/wiki/App-Format) section. @@ -40,13 +41,15 @@ MicroHydra includes a built-in library, intended to help you easily make apps. C │       │       ├── [beeper](https://github.com/echo-lalia/MicroHydra/wiki/Playing-Sound#beeper) │       │       ├── [color](https://github.com/echo-lalia/MicroHydra/wiki/color) │       │       ├── [config](https://github.com/echo-lalia/MicroHydra/wiki/Accessing-config-files) +│       │       ├── i18n │       │       ├── [menu](https://github.com/echo-lalia/MicroHydra/wiki/HydraMenu) -│       │       └── [popup](https://github.com/echo-lalia/MicroHydra/wiki/popup) +│       │       ├── [popup](https://github.com/echo-lalia/MicroHydra/wiki/popup) +│       │       └── simpleterminal │       │ │       ├── [userinput](https://github.com/echo-lalia/MicroHydra/wiki/userinput) │       ├── battlevel │       ├── [device](https://github.com/echo-lalia/MicroHydra/wiki/Device) -│       ├── kanji -│       └── sdcard +│       ├── sdcard +│       └── zipextractor │ └── main diff --git a/wiki/MH-Origins.md b/wiki/MH-Origins.md new file mode 100644 index 0000000..bd50760 --- /dev/null +++ b/wiki/MH-Origins.md @@ -0,0 +1,63 @@ +## The Origins of MicroHydra: +> *This is a rambling recount on the origins of MicroHydra, by echo-lalia (me)* +> *You probably don't need to know any of this to use or contribute to MicroHydra, but I just wanted to write it down somewhere for myself, and anyone who is curious.* + +
+ +### Cardputer-MicroHydra + +When I got my Cardputer in the mail, there was very little software or documentation available for it, +and M5Burner didn't even have a dedicated section for the Cardputer yet. +(In fact, I don't think the *demo firmware, or UIFlow*, for the Cardputer were made public yet). +I started by installing MicroPython on it just to play around, and tried figuring out how to get each peripheral working. + +The demo firmware that came on the device got a lot of people (myself included) excited about the possibilities. +However, there was no way to easily extend the demo firmware, and I preferred working in MicroPython, anyways. +I had previous experience with MicroPython on the RP2040, and hit a lot of roadblocks regarding memory usage. +So, I knew that if I wanted to support a lot of different kinds of features in my program, I'd need to find a way to load only what was needed at any given time. + +I came up with the idea of resetting the device between every app, to allow the RAM to be fully cleared each time. +To do this, there would need to be some way to maintain some memory of what we were doing between resets. +Thankfully, the ESP32-S3 has a built-in RTC with it's own memory that doesn't reset when the main CPU does, +and MicroPython provides a really easy way to read/write from it. + +So, I designed a really simple `main.py` script that would read the RTC memory, and import whatever file it pointed to. +And, I also designed a barebones `launcher.py` that would scan for `.py` files in the `apps/` directory, and allow you to pick one. +Once an app was picked, its path would be loaded into the RTC memory, and the device would reset. + +
+ +Initial impressions of the software were really positve, and people in the Cardputer Discord were super enthusiastic about the possibilities. +People in the community were talking about what a potential 'ideal' software/operating system for the Cardputer might have in it. +MicroPython is a really awesome and feature-rich project, and it made it really easy and quick to add a lot of the requested 'OS-like' features to MH. +And so I read all of the community suggestions, and just kept adding new features into the program. + +The more I added the more enthusiasticly people responded to it, and so I was motivated to just keep adding more. +Eventually, community members even started making pull requests with their own enhancements, and the software grew rapidly. + +
+ +### Supporting more devices + +The project was named "Cardputer-MicroHydra" because it was intended to be the version of MicroHydra specific to the Cardputer. +Eventually I thought I might fork the project and modify it for other devices. +But, as the project got bigger, I realized this would take an increasingly huge amount of work, and that once I did that, +it would become very difficult to extend community contributions to each completely separate version of MicroHydra. + +This kinda bummed me out as it seemed like once I got bored of working on the Cardputer (or M5Stack stopped selling them), +the software would almost certainly be useless. Or at the very least, the community would be fragmented. + +*So*, I basically tried to polish up and 'officially' release a complete version with all of the features currently in MH (v1.0), +and got to work trying to restructure the program so that it could potentially support multiple devices. + +This sucked 😅 + +Working on MicroHydra is really fun for me, and I could practically spend all day doing it. +However, the original code was so specific to the Cardputer that I had to almost completely rewrite a lot of the modules and built-in apps for MH2.0. +I also had to restructure the repository and write scripts for automating the process of assembling/exporting the device-specific builds of MH. +For the majority of the process, I wasn't even certain that my changes would ever be finished/released. + +Once I was able to get the same launcher to start up on both the TDeck and the Cardputer, though, things became fun again, and all that work was very much worth it! +At the time of writing, MH2.0 has been released, and I am again excited about the potential of this project. +When time comes to support another new device there will probably be new challenges, but I hopefully I will not have to rewrite it again. + diff --git a/wiki/Supported-Devices.md b/wiki/Supported-Devices.md new file mode 100644 index 0000000..c6e37fb --- /dev/null +++ b/wiki/Supported-Devices.md @@ -0,0 +1,43 @@ +Currently, MicroHydra supports 2 devices (the Cardputer and the TDeck), with the intention to add more in the future. + +
+ + + +# Cardputer +The M5Stack Cardputer is the device MicroHydra was [first designed](https://github.com/echo-lalia/MicroHydra/wiki/MH-Origins) for. + +### Pros: +* Because it was the first device supported by MicroHydra, most of the features are heavily geared towards this form-factor, + and feel very comfortable on the Cardputer, specifically. + +### Cons: +* The 512kb of RAM on the Cardputer can sometimes feel very limiting in MicroHydra. + +
+ + + +# TDeck +> ***Important note:** The keyboard that comes with the TDeck has a separate ESP32-C3 which communicates with the main ESP32-S3 through I²C.* +> *The firmware that comes on the keyboard does not allow many features MicroHydra requires, +> (Keys can't be held, modifier keys do nothing, not many symbols can be typed etc). +> *I have made an [updated firmware](https://github.com/echo-lalia/t-deck-keyboard-hydra), which adds several key features, +> including the ability to enable a 'raw' output to the main MCU, while maintaining backwards-compatibility with the old firmware.* +> *In order to flash this firmware, you must solder pins, and connect a **USB to TTL converter** onto the TDeck, which I found very annoying to do.* +> +> *The `_keys` module for the TDeck does also have a backwards-compatibility mode for when it doesn't detect the new firmware. However, the experience is sub-par.* + +The Lilygo T-Deck was chosen as the second device to support because it had the same ESP32-S3 MCU, and ST7789 display as the Cardputer. +*(Also, I just thought it looked neat.)* + +### Pros: +* The 8MB of octal SPI-RAM means you practically never have to worry about memory usage in TDeck apps. +* Touch support for the built-in apps was added for the T-Deck, and works fairly well. + +### Cons: +* The trackball on the T-Deck is not very accurate, and is slightly hard to control on some menus. +* The default keyboard firmware is bad, and must be updated to get all the features. This involves soldering and using a USB to TTL adapter. +* The keyboard has fewer keys than the Cardputer, and the legend on the keyboard varies randomly between units, + so you need to memorize certain key-combos to get full use out of it. +