Skip to main content

System Module

System Module - sys​

Functions marked with 🚥 will yield in the Thread Module. Before these function calls return, other threads may get a chance to run.

Display Toast Message (sys.toast)​

Declaration​

sys.toast(content[, orientation])

Parameters and Return Values​

  • content
    • string, the text to be displayed
  • orientation
    • integer, optional, screen orientation, defaults to the orientation set by the last call to screen.init
      • 0 indicates portrait mode with home button at the bottom
      • 1 indicates landscape mode with home button on the right
      • 2 indicates landscape mode with home button on the left
      • 3 indicates portrait mode with home button at the top
      • -1 hides the toast message immediately

Description​

Displays a toast message at the bottom of the screen in the current coordinate system.

info

Asynchronous operation. The toast message is displayed for approximately 2.8 seconds in total, which may affect color picking but does not intercept clicks.

Example 1​

sys.toast
-- Display a toast message
sys.toast("Decisively hello world")

Example 2​

sys.toast
-- Display the current date and time in real-time
while true do
sys.toast("Default: long press the volume key to stop the script\n\n"..os.date("%Y-%m-%d %H:%M:%S"), device.front_orien())
sys.msleep(1000)
end

Display System Alert (sys.alert)​

Declaration​

choice = sys.alert(content[, auto_dismiss_seconds, title, button0_title, button1_title, button2_title])

Parameters and Return Values​

  • content string
  • auto_dismiss_seconds
    • number, optional, in seconds, set 0 to not auto-dismiss, default is 0
  • title
    • string, optional, default title is "Script Alert"
  • button0_title
    • string, optional, default button title, default is "OK"
  • button1_title
    • string, optional, additional button 1 title, default is not displayed
  • button2_title
    • string, optional, additional button 2 title, default is not displayed
  • choice
    • integer
      • Returns 0 if button0_title is selected
      • Returns 1 if button1_title is selected
      • Returns 2 if button2_title is selected
      • Returns 3 if auto-dismissed due to timeout
      • Returns 71 if SpringBoard crashed

Description​

Displays a system alert dialog with up to 3 buttons, blocking all threads until a response is received.

The orientation of the alert defaults to the orientation set by the last call to screen.init.

Example​

sys.alert
local choice = sys.alert('What are you going to do now?', 10, 'Your Choice', 'Cancel', 'Eat', 'Sleep')
if choice == 0 then
sys.alert('You chose ‘Cancel’')
elseif choice == 1 then
sys.alert('You chose ‘Eat’')
elseif choice == 2 then
sys.alert('You chose ‘Sleep’')
elseif choice == 3 then
sys.alert('You did not choose, timed out')
else
sys.alert('SpringBoard crashed')
end

Display Input Prompt (sys.input_box)​

Description​

Displays a system input dialog with up to 3 buttons and 2 text boxes, blocking all threads until a response is received.
The default title is "Script Alert".

The orientation of the dialog defaults to the orientation set by the last call to screen.init.

Example​

sys.input_box
input_content = sys.input_box("Description")
--
input_content = sys.input_box("Title", "This is the description")
--
input_content = sys.input_box("Title", "This is the description", 0)
--
input_content = sys.input_box("Title", "Description", "TextBox Placeholder", 0)
--
input_content = sys.input_box("Title", "Description", "TextBox Placeholder", "TextBox Content", 0)
--
input_content = sys.input_box("Title", "Description", "TextBox Placeholder", "TextBox Content", "Default Button Title", 0)
--
input_content, choice = sys.input_box("Title", "Description", "TextBox Placeholder", "TextBox Content", "Default Button Title", "Button1 Title", 0)
--
input_content, choice = sys.input_box("Title", "Description", "TextBox Placeholder", "TextBox Content", "Default Button Title", "Button1 Title", "Button2 Title", 0)
--
input_content1, input_content2 = sys.input_box("Title", "Description", {"TextBox1 Placeholder", "TextBox2 Placeholder"}, 0)
--
input_content1, input_content2 = sys.input_box("Title", "Description", {"TextBox1 Placeholder", "TextBox2 Placeholder"}, {"TextBox1 Content", "TextBox2 Content"}, 0)
--
input_content1, input_content2, choice = sys.input_box("Title", "Description", {"TextBox1 Placeholder", "TextBox2 Placeholder"}, {"TextBox1 Content", "TextBox2 Content"}, "Default Button Title", "Button1 Title", "Button2 Title", 0)

Input Text (sys.input_text)​

Declaration​

sys.input_text(content[, press_enter_after_input])

Parameters and Return Values​

  • content
    • string, the text to be input, does not support "\b" (backspace)
  • press_enter_after_input
    • boolean, optional, whether to press the Enter key (send, search, etc.) after input, default is false

Description​

Inputs text in the foreground program’s text input area.

note

This function works by first writing the text to the clipboard and then pasting it using the paste shortcut (Command + V).

caution

Calling this function will overwrite the clipboard. Please back up any important data in the clipboard before calling this function.

Example​

sys.input_text
sys.input_text("I love you")  -- Inputs “I love you” in the current text box
--
sys.input_text("I love you", true) -- Inputs “I love you” in the chat interface and then presses Enter to send it

🚥 Second-Level Delay (sys.sleep)​

Declaration​

sys.sleep(seconds)

Parameters and Return Values​

  • seconds
    • number, the time to delay, in seconds

Description​

Blocks the current thread for a specified amount of time.

Example​

sys.sleep
sys.sleep(10)  -- Waits for 10 seconds

🚥 Millisecond-Level Delay (sys.msleep)​

Declaration​

sys.msleep(milliseconds)

Parameters and Return Values​

  • milliseconds
    • number, the time to delay, in milliseconds

Description​

Blocks the current thread for a specified amount of time.

Example​

sys.msleep
sys.msleep(1000)  -- Waits for 1000 milliseconds, i.e., 1 second

Get Current Millisecond-Level Timestamp (sys.mtime)​

Declaration​

timestamp = sys.mtime()

Parameters and Return Values​

  • timestamp
    • integer, millisecond-level UNIX timestamp

Example​

sys.mtime
local ms = sys.mtime()
screen.keep()
sys.alert('Time taken for one screen.keep: '..sys.mtime()-ms..' milliseconds')

Get Network Time (sys.net_time)​

Declaration​

timestamp, is_synced = sys.net_time()

Parameters and Return Values​

  • timestamp
    • integer, returns the current network time in seconds as a UNIX timestamp if successful, otherwise returns the current local time
  • is_synced
    • boolean, returns false if not yet successfully synced
note

This function call is non-blocking. After the first call, it will poll in the background and continuously keep in sync with the network time server.

Example​

sys.net_time
local nt, sync = sys.net_time()  -- Get network time
if not sync then
sys.alert('Network time not yet synced')
else
sys.alert(os.date('Current network time\n%Y-%m-%d %H:%M:%S', nt))
end

Generate a Random Number (sys.rnd)​

Declaration​

random_number = sys.rnd()

Parameters and Return Values​

  • random_number
    • integer, returns a random number in the range 0 ~ 4294967295

Description​

Generates a true random number.

info

The generated random number is a true random number, not a pseudo-random number.
Each time the script starts, the random number seed is automatically initialized with a true random number. Therefore, you usually do not need to explicitly call sys.rnd, and the random numbers generated by math.random are also safe.

Example​

sys.rnd
math.randomseed(sys.rnd())  -- Initialize the random seed with a true random number
local r = math.random(1, 100) -- Generate a random number in the range 1 ~ 100

Get Device’s Current Available Memory (sys.available_memory)​

Declaration​

available_memory = sys.available_memory()

Parameters and Return Values​

  • available_memory
    • number, returns the current available memory of the device, in MB

Example​

sys.available_memory
sys.alert('Current available memory: '..sys.available_memory()..'MB')

Get Device’s Current Total Memory (sys.total_memory)​

Declaration​

total_memory = sys.total_memory()

Parameters and Return Values​

  • total_memory
    • number, returns the current total memory of the device, in MB

Example​

sys.total_memory
sys.alert('Current total memory of the device: '..sys.total_memory()..'MB')

List Device Mount Points (sys.disks)​

Declaration​

mount_points = sys.disks()

Parameters and Return Values​

  • mount_points
    • table, returns a table where the keys are mount point paths and the values are the names of the mounted devices

Example​

sys.disks
local disks = sys.disks()  -- Get device mount point information
for k, v in pairs(disks) do
nLog(k..' -> '..v)
end

Example Output​

{
"/" = "/dev/disk0s1s1",
"/private/var" = "/dev/disk0s1s2",
"/Developer" = "/dev/disk2",
"/private/preboot" = "/dev/disk0s1s6",
"/private/var/hardware" = "/dev/disk0s1s7",
"/System/Library/Pearl/ReferenceFrames" = "/private/var/hardware/Pearl/System/Library/Pearl/ReferenceFrames",
"/private/var/wireless/baseband_data" = "/dev/disk0s1s3",
"/System/Library/Caches/com.apple.factorydata" = "/private/var/hardware/FactoryData/System/Library/Caches/com.apple.factorydata",
"/dev" = "devfs",
"/private/xarts" = "/dev/disk0s1s5",
"/private/var/MobileSoftwareUpdate" = "/dev/disk0s1s4",
}

Get Device’s Current Free Disk Space (sys.free_disk_space)​

Declaration​

free_space = sys.free_disk_space(mount_point)

Parameters and Return Values​

  • mount_point
    • string, valid values are "/var" or "/" by default, representing user space and system space respectively. Other values may be available if there is external storage such as a memory card
  • free_space
    • number, returns the current free disk space of the device, in MB

Example​

sys.free_disk_space
sys.alert(
'Current system space remaining\n'..sys.free_disk_space('/')..'MB\n\n'..
'Current user space remaining\n'..sys.free_disk_space('/var')..'MB'
)

Get Device’s Current Total Disk Space (sys.total_disk_space)​

Declaration​

total_space = sys.total_disk_space(mount_point)

Parameters and Return Values​

  • mount_point
    • string, valid values are "/var" or "/" by default, representing user space and system space respectively. Other values may be available if there is external storage such as a memory card
  • total_space
    • number, returns the current total disk space of the device, in MB

Example​

sys.total_disk_space
sys.alert(
'Current total system space\n'..sys.total_disk_space('/')..'MB\n\n'..
'Current total user space\n'..sys.total_disk_space('/var')..'MB'
)

Output Standard System Log (sys.log)​

Declaration​

sys.log([ param1, param2, ... ])

Parameters and Return Values​

  • param1, param2, ...
    • any, optional, variadic, will be converted to text and output, separated by "\t"

Description​

Outputs standard system log to standard output stdout and stores it in the log file.

note

Logs are automatically rolled and stored on the device at /var/mobile/Media/1ferver/log/sys.log, with each roll being 10 MB and up to 10 rolls.

info

Logs can be viewed in real-time using a computer browser by opening the remote interface http://<device IP address>:46952/log.html.

Example​

sys.log
sys.log("Of course, it’s Hello World")

Ask the System a Question (sys.mgcopyanswer)​

Declaration​

system_response = sys.mgcopyanswer(question_name)

Parameters and Return Values​

  • question_name
  • system_response
    • any, returns nil if the question is not supported

Description​

Gets some system information using MGCopyAnswer.

Keywords

Get system information Read system information Get device information Read device information Device identifier

Example​

sys.mgcopyanswer
sys.alert("The serial number of the device is: "..sys.mgcopyanswer("SerialNumber"))

Get System Version (sys.version)​

Declaration​

system_version = sys.version()

Parameters and Return Values​

  • system_version string

Example​

sys.version
sys.alert('Current system version: '..sys.version())

Get XXTouch Elite Version (sys.xtversion)​

Declaration​

version = sys.xtversion()

Parameters and Return Values​

  • version
    • string, XXTouch Elite version number

Example​

sys.xtversion
sys.alert('Current XXTouch Elite version: '..sys.xtversion())

Respring (sys.respring)​

Declaration​

sys.respring()

Description​

Resprings SpringBoard and backboardd, equivalent to the command line killall -9 SpringBoard backboardd.

caution

Many functions that depend on SpringBoard will fail until the respring is complete.
After calling this function, it is recommended to use app.front_bid to poll and check the status of SpringBoard. Once SpringBoard has restarted, proceed with other operations.

Example​

sys.respring
sys.respring()
sys.sleep(1)
while app.front_bid() ~= "com.apple.springboard" do
sys.sleep(1)
end
sys.alert("SpringBoard respring complete")

Reboot (sys.reboot)​

Declaration​

sys.reboot()

Description​

Reboots the device, equivalent to the command line reboot.

caution

Rebooting the device will force close all running applications and immediately end the script.
Requires re-jailbreaking.

Shutdown (sys.halt)​

Declaration​

sys.halt()

Description​

Shuts down the device, equivalent to the command line halt.

caution

Shutting down the device will force close all running applications and immediately end the script.
Requires re-jailbreaking.

User-Space Reboot (Soft Reboot) (sys.ldrestart)​

Declaration​

sys.ldrestart()

Description​

Performs a user-space reboot, retaining the jailbroken state. Equivalent to the command line ldrestart.

caution

A user-space reboot will force close all running applications and immediately end the script.
Does not require re-jailbreaking, but may fail and result in a hard reboot.

Get and Set Language (sys.language/sys.set_language)​

Declaration​

language_code = sys.language()   -- Get language
sys.set_language(language_code) -- Set language

Parameters and Return Values​

  • language_code
    • string, returns the current system language code, such as zh-Hans, en-US, etc.

Description​

Supports ISO 639-1 standard language codes.

caution

Setting the language will automatically respring.

Get and Set Locale (sys.locale/sys.set_locale)​

Declaration​

locale_code = sys.locale()   -- Get locale
sys.set_locale(locale_code) -- Set locale

Parameters and Return Values​

  • locale_code
    • string, returns the current system locale code, such as zh_CN, en_US, etc.

Description​

language + "_" + country + "_" + (variant + "_#" | "#") + script + "-" + extensions
caution

Setting the locale will automatically respring.

Get and Set Timezone (sys.timezone/sys.set_timezone)​

Declaration​

timezone_code = sys.timezone()   -- Get timezone
sys.set_timezone(timezone_code) -- Set timezone

Parameters and Return Values​

  • timezone_code
    • string, returns the current system timezone code, such as Asia/Shanghai, America/New_York, etc.

Description​

Supports IANA Time Zone Database timezone codes.

Get and Set Appearance (sys.appearance/sys.set_appearance)​

Declaration​

appearance_style = sys.appearance()   -- Get appearance style
sys.set_appearance(appearance_style) -- Set appearance style

Parameters and Return Values​

  • appearance_style enum
    • 1 for light mode
    • 2 for dark mode

Get and Set Text Size (sys.textsize/sys.set_textsize)​

Declaration​

text_size = sys.textsize()   -- Get text size
sys.set_textsize(text_size) -- Set text size

Parameters and Return Values​

  • text_size
    • enum, range 0 ~ 11, default is 3

Get and Set Bold Text (sys.is_boldtext_on/sys.boldtext_on,off)​

Declaration​

is_bold_text_on = sys.is_boldtext_on()  -- Get bold text status
sys.boldtext_on() -- Enable bold text
sys.boldtext_off() -- Disable bold text

Parameters and Return Values​

  • is_bold_text_on boolean

Get and Set Zoom Mode (sys.is_zoom_on/sys.zoom_on,off)​

Declaration​

is_zoom_on = sys.is_zoom_on()  -- Get zoom mode status
sys.zoom_on() -- Enable zoom mode
sys.zoom_off() -- Disable zoom mode

Parameters and Return Values​

  • is_zoom_on boolean

Description​

Enabling zoom mode will change the screen size obtained by screen.size, and the screen and simulated touch coordinate systems will also change accordingly.

caution
  • Enabling zoom mode will automatically respring.
  • Calling this function may cause subsequent script execution to fail. If the subsequent script requires the Screen Module or Simulated Touch Module, be sure to restart the script process using os.restart.

Set Wallpaper (sys.set_wallpaper)​

Deprecated

This function is deprecated and may be removed in future versions.

Declaration​

sys.set_wallpaper(light_image_path[, dark_image_path, effect_location, is_perspective])

Parameters and Return Values​

  • light_image_path
    • string, the path to the wallpaper image for light mode
  • dark_image_path
    • string, optional, the path to the wallpaper image for dark mode
  • effect_location
    • integer, optional, the location where the wallpaper takes effect, range 1 ~ 3, 1 for lock screen, 2 for home screen, 3 for both lock screen and home screen, default is 3
  • is_perspective
    • boolean, optional, whether to use a parallax effect, default is false

Description​

Supports jpg, jpeg, png, and heic formats.

Get and Set Icon Layout (sys.icon_state/sys.set_icon_state)​

Deprecated

These functions are deprecated and may be removed in future versions.

Declaration​

icon_layout = sys.icon_state()   -- Get icon layout
sys.set_icon_state(icon_layout) -- Set icon layout

Parameters and Return Values​

  • icon_layout table

Description​

You can arrange the icon layout on a development device, then use sys.icon_state to get the icon layout table, and use sys.set_icon_state to set it on other devices.

note

You do not need to worry about the specific format of the icon layout table. Just pass the return value of sys.icon_state to sys.set_icon_state.
The icon layout table can be safely serialized using the plist module.

Get and Set Assistive Touch (sys.is_assistive_touch_on/sys.assistive_touch_on,off)​

Declaration​

is_assistive_touch_on = sys.is_assistive_touch_on()  -- Get Assistive Touch status
sys.assistive_touch_on() -- Enable Assistive Touch
sys.assistive_touch_off() -- Disable Assistive Touch

Parameters and Return Values​

  • is_assistive_touch_on boolean

Get and Set Reduce Motion (sys.is_reduce_motion_on/sys.reduce_motion_on,off)​

Declaration​

is_reduce_motion_on = sys.is_reduce_motion_on()  -- Get reduce motion status
sys.reduce_motion_on() -- Enable reduce motion
sys.reduce_motion_off() -- Disable reduce motion

Parameters and Return Values​

  • is_reduce_motion_on boolean

Get and Set Location Services (sys.is_location_services_on/sys.location_services_on,off)​

Declaration​

is_location_services_on = sys.is_location_services_on()  -- Get location services status
sys.location_services_on() -- Enable location services
sys.location_services_off() -- Disable location services

Parameters and Return Values​

  • is_location_services_on boolean

Get and Set Allow App Tracking (sys.is_tracking_on/sys.tracking_on,off)​

Declaration​

is_tracking_on = sys.is_tracking_on()  -- Get allow app tracking status
sys.tracking_on() -- Allow app tracking
sys.tracking_off() -- Disallow app tracking

Parameters and Return Values​

  • is_tracking_on boolean

Get and Set Background App Refresh (sys.background_app_refresh_state/sys.set_background_app_refresh_state)​

Declaration​

state = sys.background_app_refresh_state()  -- Get background app refresh state
sys.set_background_app_refresh_state(state) -- Set background app refresh state

Parameters and Return Values​

  • state enum
    • 0: Off
    • 1: Wi-Fi only
    • 2: Wi-Fi and cellular

Reset (sys.reset)​

Deprecated

This function is deprecated and may be removed in future versions.

Declaration​

sys.reset(reset_type_name)

Parameters and Return Values​

  • reset_type_name
    • enum, the option name in Settings → General → Reset in English
      • "Reset All Settings": Reset all settings (device will reboot automatically)
      • "Erase All Content and Settings": Erase all content and settings (device will reboot automatically)
      • "Reset Network Settings": Reset network settings (device will reboot automatically)
      • "Reset Keyboard Dictionary": Reset keyboard dictionary
      • "Reset Home Screen Layout": Reset home screen layout
      • "Reset Location & Privacy": Reset location and privacy

Description​

Equivalent to manually resetting in settings, but without a confirmation dialog, it resets directly.