Ultrahand Overlay Switch

Ultrahand Overlay
General
Author	ppkantorski
Type	Overlays
Version	1.3.9
License	MIT License
Last Updated	2023/10/13
Links
Download
Website
Source

Ultrahand Overlay is a C++ program designed to provide a user-friendly main menu overlay for performing various file operations on different platforms, including the Nintendo Switch.

Inspired by the new Zelda feature, Ultrahand lets you unleash your creativity and shape your digital experiences like never before. It uses the Tesla library to create an interactive menu interface and allows you to perform actions such as creating directories, copying files, renaming files, moving directories, deleting files, and parsing INI files.

Note: Running homebrew software on your Nintendo Switch may void your warranty and carry certain risks. Ensure that you understand the implications and follow the appropriate guidelines and precautions when using homebrew software.

Features

• Create Directories - Simply specify the directory path, and Ultrahand will create directories for you.
• Copy Files or Directories - Just provide the source file or directory path and the destination file or directory path, and Ultrahand will handle the copying process seamlessly.
• Delete Files or Directories - By specifying the file or directory path, Ultrahand will promptly remove it for you, making the deletion process hassle-free.
• Move Files or Directories -Provide the source file or directory path and the destination directory path, and Ultrahand will take care of moving them, ensuring their seamless relocation.
• Modify INI Files - You can update existing key-value pairs, add new entries, or even create new sections within the INI file. Ultrahand makes it easy to customize and tailor the configurations of your INI files.
• Hex Edit Files - Edit the binary data directly, allowing for precise control over your data.
• Provide a convenient command-line interface to perform various file management functions.

Installation

In order to run the Ultrahand File Management System on the Nintendo Switch, you need to have the necessary homebrew environment set up on your console.

How to setup Ultrahand:

• Place the .ovl file into the /switch/.overlays/ directory on your Switch's SD card.
• Make sure you have nx-ovlloader and Tesla Menu installed.
• Create a directory named ultrahand in the config folder on your SD card.
• Place the config.ini file in the ultrahand directory (or sub-directory). This file contains the configuration options for Ultrahand.
• Your commands will show up on the Tesla Menu (L+D-Pad Down+Right Stick Button) within the Ultrahand overlay.

User guide

Configuration options

The config.ini file contains multiple sections, each defining a set of commands that can be executed. The sections are enclosed in square brackets [ ], and the commands are listed below each section.

Here's an example of the config.ini file:

[make directories]
mkdir /switch/.packages/example1/
mkdir /switch/.packages/example2/

[copy files]
copy /switch/.packages/config.ini /switch/.packages/example1/
copy /switch/.packages/config.ini /switch/.packages/example2/

[rename files]
move /switch/.packages/example1/config.ini /switch/.packages/example1/configX.ini
move /switch/.packages/example2/config.ini /switch/.packages/example2/configX.ini

[move directories]
move /switch/.packages/example1/ /switch/.packages/example3/
move /switch/.packages/example2/ /switch/.packages/example4/

[delete files]
delete /switch/.packages/example1/config.ini
delete /switch/.packages/example2/config.ini

[delete directories]
delete /switch/.packages/example1/
delete /switch/.packages/example2/
delete /switch/.packages/example3/
delete /switch/.packages/example4/

[modify ini file]
copy /bootloader/hekate_ipl.ini /switch/.packages/
set-ini-val /switch/.packages/hekate_ipl.ini 'Atmosphere' fss0 gonnawritesomethingelse
set-ini-val ​/switch/.packages/hekate_ipl.ini 'Atmosphere' booty true

You can add your own sections and commands to customize the actions performed by Ultrahand.

Note: The paths specified in the commands should be relative to the SD card root directory and should start with /.

Command reference

Ultrahand supports the following commands:

• mkdir <directory_path>: make or mkdir: Creates a directory.
• copy <source_file_path> <destination_file_path>: copy or cp: Copies a file or diectory.
• delete <file_path>: delete or del: Deletes a file or directory.
• move <file_path> <destination_directory_path>: move or mv: Moves/renames a file/directory to a new location/label.
• set-ini-val <file_to_edit> <desired_section> <desired_key> <desired_value>: set-ini-val or set-ini-value: Edits an INI file by updating a section with a desired key-value pair.
• set-ini-key <file_to_edit> <desired_section> <desired_key> <desired_new_key>: set-ini-key: Edits an INI file by updating a section with a new key.
• new-ini-entry <file_to_edit> <desired_section> <desired_key> <desired_value>: new-ini-entry: Edits an INI file by adding a new entry to a section.

Make sure to follow the correct syntax and provide the required arguments for each command.

You can configure these commands in the config.ini file by specifying them under the corresponding options. Be sure to provide the necessary arguments as described for each command.

Controls

A - Execute any command

X - View the individual command lines written in the ini for execution

Screenshots

Compatibility

HOS 16.0.0+.

Changelog

1.3.9

• Star-ing overlays is now done by pressing X instead of PLUS.
• Pressing PLUS on main menu now invokes the Ultrahand Settings menu (a page to control some settings in the config.ini).
• Pressing Y on top of an overlay / package pulls up the Menu settings for that particular item.
• New hidden overlays/packages page for storing hidden overlays/packages (will be drawn at the bottom when populated).
• New option clean_version_labels in /config/ultrahand/config.ini (can be set on Ultrahand Settings menu).
  • Clean versions restricts all displayed version labels into a X.X.X format.
• Various bug fixes.

1.3.8

• Introduction of Pages: Now, you can define pages using empty commands [@PAGE1] and [@PAGE2], where PAGE1 and PAGE2 are labels for the page. Note that only two of these empty @-commands can be referenced in a package. You can navigate between PAGE1 and PAGE2 using the left and right buttons on the DPAD.
• New Command remove-ini-section: I've added a new command called remove-ini-section <ini_file_path> <section_name>. This command allows you to quickly remove a section from an INI file.
• Package Info Section: You can now include a Package Info section within your package.ini file by using [Package Info] as an empty command. If there's no reference to [Package Info], the package info section will not be displayed.
• Package title colors now accept custom RGB888 hex representations (i.e. #FFFFFF for white).
• NOTE: RGB888 hex color format will be downscaled to RGB444 for libTesla compatibility.
  • Bug Fixes: Addressed various bug fixes, including a memory leak issue on the main menu.
• New updates to OC Toolkit.

1.3.7

• Hex offset caching has been implemented for faster hexing read/write calls.
• Various additional improvements to hex functions.
• New true/false property hide for packages.ini and overlays.ini to toggle visiblity.
• New command logging to enable/disable command logging (now off by default).
• New command clear for deleting Ultrahand relavent files (so far only clear log works).
• New ;color= header definition in package.ini for choosing colors for your package title.
  • Colors: red, green(default), blue, yellow, orange, purple, pink, white, ultra(wip)

1.3.6

• Added the ability to define functions in boot_package.ini other than boot.
• Enabled referencing and execution of global functions defined in boot_package.ini from your script using exec <COMMAND>.
• Introduced a new refresh command to redraw the current menu page.
• Various bug fixes as well as improvements to OC Toolkit.
• Menu related bug fix (memory leak). Opening and closing selection overlay with dictionaries was not unloading the dictionary. Issue has been resolved.
• If a command has the footer "Not available" it will no longer function.

1.3.5

• Introduction of boot_package.ini (commands that will run when your package is opened). This file is placed in the same folder as your package.ini file.
• Introduction of new hex_file advanced function for reading/parsing hex data from files.
• Introduction of command tags, i.e. [COMMAND?Tag]. Tags are not printed, but are helpful for making similar named commands unique (which is essential).
• New example package OC Toolkit for advanced modifications of kip files. (WIP)
• Update:
• Ive added a new function ini_file to read data from ini files.
  • ini_file <ini_file_path> is how it is defined.
  • {ini_file(section, key)} is how it will be called.

1.3.4

• List of changes:
  • Empty commands now define grouping sections.
  • Empty commands with a * at the start of them define group commands. Commands defined after will show up in a dropdown menu.
  • To end the identification of a group command, a group section must be defined.
  • New command set-footer.
  • Various bug fixes.
• Basic example:

[Section 1]
[*Test]
;mode=option
list_source '(test1, test2, test3)'
set-footer {list_source(*)}

[*Timings]
;mode=option
list_source '(1, 2, 3, 4, 5, 6)'
set-footer {list_source(*)}

[*Commands Group]
[*Test2]
json_source '[{"key_1":"entry 1", "key_2":"entry 2", "key_3":"entry 3"}, {"key_1":"entry a", "key_2":"entry b", "key_3":"entry c"}]' key_1

[Section 1]
[*Test3]
;mode=option
list_source '(test4, test5, test6)'
set-footer {list_source(*)}

• update:
  • Bug fix for selected footer after entering command groups. - 10/3/2023 4:48 PM

1.3.3

• List of changes:
  • Fixed dropdown toggles. (Setup double click prevention to ensure commands are properly parsed.)
  • New option command mode for selections. (useful for developing configurators scripts.)
  • New auto-generated config.ini for each package.ini within the package folder. Settings will be parsed from package.ini if provided as a comment.
    • mode: this can be set to default, option, or toggle.
    • grouping: this can be set to default or split (split splits commands into groups based upon subfolders)
    • footer: null by default. When used with option mode, it can be dynamically read on the menu.
  • DONE is now replaced by a checkmark.
• Basic Option Example:
  • Package: /switch/.packages/Test/package.ini

1.3.2

• Bug fixes with interpreter allocating too much memory.
  • This affected unzip and download in certain test cases, but is no longer an issue.
  • Easy Installer and other download packages should now work properly again.
• UPDATE: (stable)
  • Root menu commands (/switch/.packages/package.ini) now behave the same way as package menu commands.
  • Config menu has now been fixed. (09/26/23 11:21 PM)
  • Multiple menu related bug fixes. (09/27/23 2:25 AM)

1.3.1

• json_data (the non source version) is now json_file.
• json is now a new non-source version of json_source for storing data within the package.ini.
• list_source has been fixed. Items defined in list can be called by {list_source(<INDEX>)}.
• list is now a new non-source version of list_source. Items defined in list can be called by {list(<INDEX>)}.
• Re-built interpreter and SelectionMenu/SubMenu.
• Introduction of selection modes ;mode=.
• Drop of _on and _off functions.
  • Sections can be defined using ;mode=toggle and on: followed by the on commands and off: followed by the off commands.

1.3.0

• config.ini is now package.ini for Ultrahand packages.
• source is now file_source
• source_on is now file_source_on
• source_off is now file_source_off
• json_source is now json_file_source
• New function json_source for defining JSONs directly within the package.ini file.
  • Example: json_source '[{"key1":"value1"}, {"key1":"value2"}]' key1
• Menu item sorting are now implemented differently.
  • New files /config/ultrahand/overlays.ini and /config/ultrahand/packages.ini for manually specifying priority and storing information.
  • Priority value is a number from 0 to 9999

1.2.1

• hide_overlay_versions and hide_package_versions are now true or false options within /config/ultrahand/config.ini.
• hex-by-custom-offset is now a new command for using custom string pattern offsets for more advanced hex-editing scenarios.
• New wildcard source command type list_source implementation for specifying list variables within package inis.
• Several bug fixes.

1.2.0

• Commands now state "DONE" after pressed.
• Bug fix for "set-ini-value". Issue was that for a new entry, it would inject the new entry into every section.
• Simple fix, but since its bound to affect someone's project eventually, I'm updating the release.

1.1.9

• Bug Fixes: Static menu variable and rootFrame handling.
• These bug fixes potentially resolve the menu handling issue that occasionally can occur for some testers.
• Overall it should be more stable with static implementations of the particular variables I modified.

1.1.8

• Introduction of footers for commands.
• Testing potential bug fix for handling menu input.
• This issue is not very common, but occasionally the menu can get locked into a weird orientation, preventing you from moving to packages or overlays at times. Its hard to figure out the exact trigger, but I've attempted to address the issue here. Pre-release will be dropped after more testing. If you see this bug on this version, do let me know in issues.

1.1.7

• Download and unzip files implementation has been added.
• Command to download:
  • download <FILE_URL> <DESTINATION_FILE_OR_FOLDER>
• Command to unzip:
  • unzip <SOURCE_FILE> <DESTINATION_FOLDER>
• CURL has made it a bit beefier as you can tell, but the potential benefits are pretty great for having these commands handy. Lots of new packages can be made for updating and installing software.

• update: slight bug fix for handling more URLs (07/07/2023)
• update: bug fix for unzip and createDirectories (07/08/2023)

1.1.6

• Move commands now create directory if the directory does not exist.
• Bug fix for exiting main menu that can sometimes occur when exiting (locked users in the menu until an item is selected).
• Multiple filters are now implemented. filter, filter_on, filter_off calls will store your filter path into a list.

1.1.5

• Bug fix for those who specify their default menu mode instead of resorting to last_menu.
• Several cosmetic improvements.
• Easier transition from Tesla Menu by copying combo from sdmc:/config/tesla/config.ini if it exists and the combo is not within sdmc:/config/ultrahand/config.ini.

• update: more cosmetic improvements after initial release (only difference)

1.1.4

• Ultrahand is now a replacement for ovlmenu.ovl.
• Ultrahand packages are now relocated to sdmc:/switch/.packages/.
• Ultrahand specific settings are now stored in sdmc:/config/ultrahand/config.ini.
• Left on the menu takes you to your overlays.
• Right on the menu takes you to your packages and commands.
• More improvements to come.

1.1.3

• Introduction of more selection command features.
• Multi-wildcard statements.
• New functions 'mirror_copy' and 'mirror_delete' for implementing mirror functions on directory contents.
• All copy functions now create destination directories.

1.1.2

• Selection (wild card commands) toggles are now implemented.
• Simple one line filter added. (see updated examples).

1.1.1

• Introduction of wildcard commands (new command-type).

1.10.0

• Pre-release: Testing new hex editing functions.
• New commands "hex-by-offset", "hex-by-swap", "hex-by-decimal", "hex-by-rdecimal"
• Still needs more testing to confirm full functionality, but since it appears to be compiling properly ill leave it here for now for testing.

1.0.9

• Implemented safeguards so you don't delete or move your entire SD card or essential files. Still have more features to implement for this version, it should be better than using 1.0.8 but since I made changes that need review I am still calling it pre-release for now.
• Update: More advanced pattern searching. Multiple wildcards. 2:42 AM PST 06/08/2023
• Update: Updated safeguards for more advanced patterns. 3:16 AM PST 06/08/2023

1.0.8

• Added new feature "new-ini-entry" and restored original example config.ini generated if no config is present.

v1.0.7

• Improvements to menu. Version handling for user packages.

v1.6

• More improvements, "edit-ini" commands have now been labeled "set-ini". You can also press X on an individual command and see and execute individual lines within.
  • Update: Faster copying. - 05/31/23 4:19PM PST
  • Update: Even faster copying. - 05/31/23 4:35PM PST
  • Update: Slight size reduction. - 06/01/23 6:34PM PST

v1.0.5

• Too many bug fixes with statement logic.
• Ability to execute individual commands from a package have been added (press X on package).
• More slight tweaks and capabilities packed into the functions.
  • Update: Fixed editINI adding new lines by mistake. - 05/29/23 05:16 PM PST
  • Update: Fixed copy directory not copying subdirectories. - 05/29/23 05:59 PM PST
  • Update: Edit ini key or value now. - 05/29/23 09:40 PM PST

v1.0.4

• Slight tweaks to libtesla. This is pre-release, but it is still commits ahead of 1.0.3 and stable.
  • Update: Got new features as well as pattern searching implemented. New documentation coming soon. 05/29/23 9:11 AM PST

v1.0.3

• Improvements to code structure, menu layout, new commands (reset, shutdown), etc.
  • Update: Copy function now can rename to file as well as copy to directory. This makes it simulate "cp" a bit better. - 05/27/23 7:37 AM PST
  • Update: Fixed edit-ini bugs. - 05/27/23 2:21 PM PST
  • Update: Fixed even more edit-ini bugs. Should be working. - 05/27/23 3:27 PM PST
  • Update: Fixed one last edit-ini bug for handling command. Testing safer reboot method. - 05/27/23 9:40 PM PST

v1.0.2

• Folders have now been added.
• Future plans: cleaner UI, separation for "Packages" and "Commands" sections with titles.
  • Update: Fixed a bug that occurred with linking folders. - 05/28/23 05:59 PM

v1.0.1

• New feature 'parse-ini'.
• Update: Delete directory bug fix. - 05/28/23 8:11 AM PST

v1.0

• First Release.
  • Update: Improved structure and examples for testing. - 05/25/23 5:52 PM PST

External links

• GitHub - https://github.com/ppkantorski/Ultrahand-Overlay
• GBAtemp - https://gbatemp.net/threads/ultrahand-overlay-the-fully-craft-able-overlay-executor.633560/