Skip to content

Command Reference

Jump to bottom
ppkantorski edited this page Oct 27, 2024 · 73 revisions

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

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

Ultrahand currently supports the following commands:

System Commands

  • reboot: Restarts the system. Can also be used to reboot into Hekate / UMS or Hekate ini boot entries by entry name.

    • Usage: reboot or reboot hekate or reboot ums or
      • reboot boot <NAME_OF_BOOT_ENTRY> (for entries within hekate_ipl.ini)
      • reboot ini <NAME_OF_INI_ENTRY> or reboot ini <NAME_OF_INI_ENTRY> <DUPLICATE_INDEX>

  • shutdown: Shuts down the system or all bluetooth controllers.

    • Usage: shutdown or shutdown controllers

  • backlight: Modify the current backlight value.

    • Usage: backlight on or backlight off or backlight <PERCENTAGE_INTEGER>

Filesystem Commands

  • make or mkdir: Creates a directory.

    • Usage: mkdir <directory_path>

  • copy or cp: Copies a file or diectory.

    • Usage: copy <source_file_path> <destination_file_path>

  • mirror_copy or mirror_cp: Mirrors the contents of a directory.

    • Usage: mirror_copy <source_file_path> <destination_file_path>

  • delete or del: Deletes a file or directory.

    • Usage: delete <file_path>

  • mirror_delete or mirror_del: Uses contents of a source directory as for files to remove within the destination path.

    • Usage: mirror_delete <source_file_path> <destination_file_path>

  • move or mv: Moves/renames a file/directory to a new location/label.

    • Usage: move <file_path> <destination_directory_path>

  • download: Downloads files from a specified URL to a local destination.

    • Usage: download <file_url> <destination_file_path>

  • unzip: Extracts files from a specified ZIP archive to a local destination.

    • Usage: unzip <zip_file_path> <destination_file_path>

INI Commands

  • set-ini-val or set-ini-value: Edits/makes an INI file by updating/adding a section with a desired key-value pair.

    • Usage: set-ini-val <file_to_edit> <desired_section> <desired_key> <desired_value>

  • set-ini-key: Edits an INI file by updating a section with a new key.

    • Usage: set-ini-key <file_to_edit> <desired_section> <desired_key> <desired_new_key>

  • remove-ini-key: Remove a key value pair from an INI file.

    • Usage: remove-ini-key <ini_file_path> <section_name> <desired_key>

  • remove-ini-section: Remove a section from an INI file.

    • Usage: remove-ini-section <ini_file_path> <section_name>

Hex Editing Commands

  • hex-by-offset

    • Description: Edits the contents of a file at a specified offset with the provided hex data.
    • Usage: hex-by-offset <file_path> <offset> <hex_data>

  • hex-by-custom-offset

    • Description: Edits the contents of a file at a specified custom pattern offset with the provided hex data.
    • Usage: hex-by-custom-offset <file_path> <custom_pattern> <offset> <hex_data>

  • hex-by-custom-decimal-offset

    • Description: Edits the contents of a file at a specified custom pattern offset with the provided decimal data, which is converted to hex.
    • Usage: hex-by-custom-decimal-offset <file_path> <custom_pattern> <offset> <decimal_data>

  • hex-by-custom-rdecimal-offset

    • Description: Edits the contents of a file at a specified custom pattern offset with the provided reverse decimal data, which is converted to reversed hex.
    • Usage: hex-by-custom-rdecimal-offset <file_path> <custom_pattern> <offset> <rdecimal_data>

  • hex-by-swap

    • Description: Edits the contents of a file by replacing a specified hex data with another. You can optionally specify an occurrence to replace.
    • Usage: hex-by-swap <file_path> <hex_data_to_replace> <hex_data_replacement> [occurrence]

  • hex-by-string

    • Description: Edits the contents of a file by replacing a specified string data with another. String data is automatically converted to hex.
    • Usage: hex-by-string <file_path> <string_data_to_replace> <string_data_replacement> [occurrence]

  • hex-by-decimal

    • Description: Edits the contents of a file by replacing a specified decimal data with another. Decimal data is converted to hex before replacement.
    • Usage: hex-by-decimal <file_path> <decimal_data_to_replace> <decimal_data_replacement> [occurrence]

  • hex-by-rdecimal

    • Description: Edits the contents of a file by replacing a specified reverse decimal data with another. Decimal data is converted to reversed hex before replacement.
    • Usage: hex-by-rdecimal <file_path> <decimal_data_to_replace> <decimal_data_replacement> [occurrence]

  • hex-by-pattern

    • Description: Edits the contents of a file by replacing data that matches a specific hex pattern.
    • Usage: hex-by-pattern <file_path> <hex_pattern_to_replace> <hex_data_replacement>

Notes

  • Occurrences: Some functions allow specifying an optional occurrence parameter, which defines which instance of the pattern or data will be replaced. If not specified, all occurrences will be replaced.
  • Hex Conversions: Functions like hex-by-decimal and hex-by-string automatically convert decimal and string data to hex format before applying the replacement in the file.

Mod Conversion Commands

  • pchtxt2ips: Converts a .pchtxt mod into a .ips.

    • Usage: pchtxt2ips <pchtxt_file_path> <output_file_path>

  • pchtxt2cheat: Converts and installs a .pchtxt mod into a cheat.

    • Usage: pchtxt2cheat <pchtxt_file_path>

Sourced Placeholder Functions

  • * (Asterisk):

    • The asterisk * is often used as a wildcard or placeholder, representing a value that will be dynamically filled in during execution. It's commonly used in contexts where specific values are expected, and the actual value will be determined at runtime.

  • package_source:

    • Package source allows users to forward one Ultrahand package ini from another. Can help users organize their code as well as chain up longer menus.
    • Used with ;mode=forwarder, called package_source /path/to/forwarder_package.ini.

  • list_source:

    • List source is a way to store variables for dropdown menus within the package.ini. It's used as a placeholder for the individual values within the list source variable. The code replaces list_source references with the corresponding value.

  • list_file_source:

    • Similar to list_source but utilizes a text file directory as input with the text file containing each entry separated by newlines.

  • file_source:

    • Representation of a source file or resource. It's a placeholder for the actual filename or source location. The code replaces source with the appropriate file path when executing certain commands.

      Here's a breakdown of the additional variables accessible by use of file_source:

      • file_name: The name of the individual file.
      • folder_name: The name of the parent folder for the file.

    • file_source in an on: section implies that a command or action should be executed when a specific source is "on" or enabled.

    • file_source in an off: section implies that a command or action should be executed when a specific source is "off" or disabled.

    • Evaluates the state of a toggle or a condition and then selects the appropriate command for execution based on whether the source is on or off.

    • For file_source function toggles, please refer to the Broomstick package example.

  • ini_file_source:

    • Similar to list_file_source but utilizes entry names from an ini file for its list value. It also retains other ini functions similar to ini_file.

  • json_file_source:

    • This command is used to define a JSON data source. It specifies a file path to a JSON file that contains data. This JSON data source is used for various purposes within the code.
    • The code reads data from the specified JSON file, and based on the context and logic in the code, it may perform actions or operations using this data.
    • In some cases, it might also accept an additional argument (e.g., jsonKey) to indicate a specific key or property within the JSON data to be used for display or processing.
    • This command is used to retrieve structured data from JSON files and incorporate it into the program's functionality.

    Here's a breakdown of the additional variables accessible by use of json_file_source:

    • jsonPath: The file path to the JSON data source.

    • jsonKey: An optional key within the JSON data for specific data retrieval.

    • For information on json_file_source function implementations, please refer to the Easy Installer package example.

Placeholder Functions

  • {ram_vendor}

    • Description: Returns the vendor of the device's RAM.
    • Example: Displays "Samsung" for a device with Samsung RAM.

  • {ram_model}

    • Description: Returns the model number of the RAM in the device.
    • Example: Displays "M471A1K43BB1-CTD" as the model number.

  • {ams_version}

    • Description: Returns the Atmosphere version installed on the device.
    • Example: Displays "1.7.1" for Atmosphere version 1.7.1.

  • {hos_version}

    • Description: Returns the Horizon OS version.
    • Example: Displays "18.1.0" for Horizon OS version 18.1.0.

  • {cpu_speedo}

    • Description: Returns the CPU speedo value of the device.
    • Example: Displays "1600" for the device's CPU speedo value.

  • {cpu_iddq}

    • Description: Returns the CPU IDDQ value of the device.
    • Example: Displays "60" for the device's CPU IDDQ value.

  • {gpu_speedo}

    • Description: Returns the GPU speedo value of the device.
    • Example: Displays "1600" for the device's GPU speedo value.

  • {gpu_iddq}

    • Description: Returns the GPU IDDQ value of the device.
    • Example: Displays "60" for the device's GPU IDDQ value.

  • {soc_speedo}

    • Description: Returns the SOC speedo value of the device.
    • Example: Displays "1600" for the device's SOC speedo value.

  • {soc_iddq}

    • Description: Returns the SOC IDDQ value of the device.
    • Example: Displays "60" for the device's SOC IDDQ value.

  • {slice(<STRING>,<START_INDEX>,<END_INDEX>)}

    • Description: Slices a string based on the provided start and end indices.
    • Parameters:
      • <STRING>: The string to be sliced.
      • <START_INDEX>: The starting index of the slice.
      • <END_INDEX>: The ending index of the slice.
    • Example: {slice("Test String", 0, 4)} returns "Test".

  • {decimal_to_hex(<DECIMAL>)}

    • Description: Converts a decimal number to a hexadecimal string.
    • Parameters:
      • <DECIMAL>: The decimal number to convert.
    • Example: {decimal_to_hex(255)} returns "FF".

  • {ascii_to_hex(<ASCII>)}

    • Description: Converts an ASCII string to its hexadecimal representation.
    • Parameters:
      • <ASCII>: The ASCII string to convert.
    • Example: {ascii_to_hex("Test")} returns "54657374".

  • {hex_to_rhex(<HEX>)}

    • Description: Converts a hexadecimal string to reverse-endian hexadecimal.
    • Parameters:
      • <HEX>: The hexadecimal string to convert.
    • Example: {hex_to_rhex("12345678")} returns "78563412".

  • {hex_to_decimal(<HEX>)}

    • Description: Converts a hexadecimal string to its decimal representation.
    • Parameters:
      • <HEX>: The hexadecimal string to convert.
    • Example: {hex_to_decimal("FF")} returns "255".

  • {split(<STRING>,<PATTERN>,<INDEX>)}

    • Description: Splits a string based on a pattern and returns a specific portion.
    • Parameters:
      • <STRING>: The string to split.
      • <PATTERN>: The pattern used to split the string.
      • <INDEX>: The index of the split portion to return.
    • Example: {split("Test - String", " - ", 0)} returns "Test".

  • {value}

    • Description: Returns the current value of a trackbar or slider.
    • Example: Used in trackbars to display the current selected value.

  • {index}

    • Description: Returns the current index of a selection or list.
    • Example: Used to indicate the position of an item in a list or dropdown.

  • {list_source(<INDEX>)}

    • Description: Fetches an item from a list defined earlier using list_source.
    • Parameters:
      • <INDEX>: Index of the item in the list.
    • Example: {list_source(0)} fetches the first item in the list.

  • {json_source(<KEY>)}

    • Description: Fetches a value from a JSON source based on the provided key.
    • Parameters:
      • <KEY>: The key to look up in the JSON object.
    • Example: {json_source("title")} fetches the value associated with the "title" key in a JSON object.

  • {ini_file(<SECTION>, <KEY>)}

    • Description: Returns the value of a key in a specific section of an INI file.
    • Parameters:
      • <SECTION>: The section in the INI file.
      • <KEY>: The key within the section.
    • Example: {ini_file("Settings", "Language")} returns the value for the "Language" key under the "Settings" section.

Command Modes

  • ;mode=default

    • Description: The default command mode that executes the command as is, without any special interaction or behavior. Used when no other mode is explicitly required.
    • Usage: When a command is executed in its standard form.
    • Example: 
      [Reboot]
;mode=default
reboot

  • ;mode=toggle

    • Description: A toggle command that switches between two states (on/off). The command will execute based on its current state and flip to the other state after execution.
    • Usage: Useful for settings or features that can be enabled/disabled.
    • Parameters:
      • toggle?on: Set the toggle to default to on.
      • toggle?off: Set the toggle to default to off.
    • Example: 
      [Backlight]
;mode=toggle?on
on:
backlight on
off:
backlight off

  • ;mode=option

    • Description: Displays a list of options for the user to choose from. This mode allows the user to pick one of several predefined options.
    • Usage: Useful for commands that need multiple options to be selected from, such as configurations or settings.
    • Example: 
      [Graphics Settings]
;mode=option
list_source '(Low, Medium, High)'

  • ;mode=trackbar

    • Description: Creates a standard trackbar (slider) allowing the user to adjust a value between a minimum and maximum range.
    • Usage: For numerical settings like volume, brightness, or performance adjustments.
    • Parameters:
      • min_value: The minimum integer value of the trackbar.
      • max_value: The maximum integer value of the trackbar.
      • units: Display units for the value.
      • unlocked: Optionally allows the trackbar to be unlocked for immediate interaction.
      • on_every_tick: Optionally execute the command at every trackbar tick (off by default).
    • Example: 
      [Volume]
;mode=trackbar
min_value=0
max_value=100
units=%

  • ;mode=step_trackbar

    • Description: Similar to the regular trackbar, but with fixed steps between values. Instead of freely adjusting the value, the user moves through predefined intervals.
    • Usage: Useful when you want a slider with distinct steps.
    • Parameters:
      • steps: Defines the number of steps the trackbar will have.
    • Example: 
      [Brightness]
;mode=step_trackbar
min_value=0
max_value=5
steps=6

  • ;mode=named_step_trackbar

    • Description: A step trackbar that uses predefined names for each step. The user selects a step from a list of named options.
    • Usage: Used when specific labels or named steps are required, such as quality settings (Low, Medium, High).
    • Parameters:
      • list_source: The source list of names for each step.
    • Example: 
      [Performance Mode]
;mode=named_step_trackbar
list_source '(Low, Medium, High, Ultra)'

  • ;mode=slot

    • Description: Slot mode allows the user to execute commands from a predefined set of options with custom labels and footers.
    • Usage: Used when commands need to be selected from a group, similar to option, but with more control over display elements.
    • Example: 
      [*Save Slot]
;mode=slot
list_source '(test a, test b, test c)'
set_footer list_source(*)

  • ;mode=forwarder

    • Description: A forwarder command that points to another package's .ini file. The user selects the forwarder and is taken to the forwarded package or executes commands from that package.
    • Usage: Useful for linking commands or packages in a modular fashion.
    • Parameters:
      • package_source: Points to the forwarded package .ini file.
    • Example: 
      [Performance Options]
;mode=forwarder
package_source '/switch/.packages/performance_config.ini'

  • ;mode=table

    • Description: A table display mode that allows rendering of structured information in a table-like format with rows and columns.
    • Usage: Useful for displaying organized data like system information, device specs, etc.
    • Parameters:
      • alignment: Aligns text within the table columns (left, center, right).
      • header: Draws a header for the table (true/false).
      • spacing: Sets the spacing between rows.
      • gap: Sets the gap after the table.
    • Example: 
      [System Info]
;mode=table
alignment=left
header=true

License

Larger License

This project is licensed and distributed under GPLv2 with CC-BY-4.0 material.

Copyright (c) 2024 ppkantorski

Notice: Advancements are faster than my ability to make clear documentation right now. Once things settle down, I'll work more on this wiki a bit. Lot's of new packages can be created with the improvements that have been added to v1.3.6+.

Clone this wiki locally