# Lua Guide
Applicable to version 6.1.7 and above
What is AutoTouch?
- AutoTouch is a "Macro" tool used to record and playback human touching and pressing on the mobile device.
- It simulates touching and keys pressing.
- It runs Lua scripts.
- It provides several extended functions to achieve automation.
- It needs Jailbreak environment.
- It provides a Script Store to sell and buy scripts.
# Usage
# How to install?
- You can search and install AutoTouch in Cydia diredctly, it is released in BigBoss.
- You can also add the official repo: https://apt.autotouch.net (opens new window) to Cydia and install AutoTouch there.
- There is also a beta repo: https://beta.autotouch.net (opens new window) which contains more fresh but not so stable packages.
# How to use Activator?
- By default AutoTouch uses volume decrease button holding or pressing to control everything, untill you install Activator by hand.
- Add official repo:http://rpetri.ch/repo/ (opens new window) to Cydia.
- Install Activator form that repo.
- AutoTouch will automatically detect Activator and use it as the default control method.
- Customize the actions you want to use to control AutoTouch by Activator.
# How to record?
- At the interface where you want to start recording , hold volume decrease button (or other main control action set with Activator by youself, this point will not be repeated below) to call out the control panel.
- Press the "Record" button on the control panel to start recording.
- It will record all your touching and key pressing to a script until you stop it.
- Hold on volume decrease button (or other Activator action) again to stop the recording.
- Then, there will be a Lua script named with create time in the script list. You can edit, rename or playback it.
# How to play script?
- Hold on volume decrease button to call out the control panel.
- Click the script you want to run.
- There is a play options button on the control panel, it will ask for options if you turn on it.
- There is a H button means hold mode, it will enter hold mode if you turn on it. In hold mode, every time your tap the volume down button(or action you set in Activator) it will start playing.
- Hold volume decrease button to forcedly stop the playing, or quit the
Hold modestatus.- Long pressing volume down button will stop the playing forcely.
# How to take screenshot?
- Press "Snap" button on the control panel to take screenshot, or just use iOS's screenshot method with which you are able to edit it directly.
- The screenshot will be saved as PNG image into "AutoTouch" album of iOS Photo Library, then it might be used to speficy parameters of getColors, findColors or findImage.
# How to write a script?
- Press "+" button on top right of the local script list, choose “Create a script” to open the script editor.
- Write the code there.
- Press "save" button to save the script.
# How to use the "Function Helper" while script coding?
- There are "Extensions", "Indent" and "Statements" buttons on top of the keyboard in the script editor. You can conveniently insert extended functions, indent or common statement of Lua Language.
- Press the "Extension" button to present the extended functions list, click a function to insert into the script diretly.
- Press the "HELPER" button on the function list, it will help you to determine the coordinates, colors or key flags for the functions.
# How to write and manage scripts on the computer?
- Turn on Web Server at AutoTouch setting and visit the told URL from browser on computer. Manage scripts there.
- You can also turn on WebDAV Server and connect the told address with WebDAV client on computer.
# How to use Package to orgainize the script project?
- You can create a Package as script project to contain different scripts, files and images etc. Package must have a main.lua file as the entrance of the execution. A Package in fact is a directory named with .at extension such as xxx.at.
- Package can be encrypted to xxx.ate which is also execuate-able and can be released to Script Store.
# How to encrypt the scripts?
- Tap accessory button of a package or script in the local script list, choose "Encrypt".
- Input the encryption password. Or leave it blank if you don't want one.
- Press "Confirm" to complete the encryption. A encrypted file with the same name but ended with .lua.e or .ate will be generated in the script list then.
- You can play the encrypted scripts, or release them to Script Store.
# How to download and buy scripts from Script Store?
- You can directly download all scripts from the store.
- You need to contact the author to buy the decription password. Do be careful not to be cheated, AutoTouch can do nothing to protect your money provenly.
# How to buy AutoTouch license?
- Tap License on AutoTouch settings to enter the license management view.
- Read the Instructions and do be aware that AutoTouch license has ONE YEAR validity period!
- It will automatically activate current device after the payment if you use PayPal (If failed just follow the next step).
- You can query bought licenses with your PayPal ID email, or any activated device SN.
- You can activate another device with a license after you query it out.
- You can also "Activate Current Device" diretly with a license key bought from other devices.
- You should make sure it shows "License Downloaded" at top-right of the License view after it's activated.
- It allows only one time activation a day, you may do it again after 24 hours if you need.
# Script
# Basis
You can learn how to use Lua language from here:《Lua Official Reference Manual (opens new window)》
# Develop Tool
LuaStudio (opens new window) is aprofessional development environment for debugging Lua script in your applications. It's familiar and fast and you'll wonder how you ever worked without it.
# Coordinate, Size and Orientation System
AutoTouch uses pixel based Native Resolution as the coordinate and size system. Resolutions of different iOS devices are here (opens new window), for example, screen size of iPhone X is 1125 x 2436.
Origin point (0, 0) is alwasy at left-top of the Application Interface, regardless of the device orientation. Consider only the App interface while using these functions: touchDown,touchMove,touchUp,getColors,findColors,findImage.
# Extension Libraries
AutoTouch has some extension libraries built in, while you can also add extension libraries by yourself, just put
.sofiles at/usr/local/lib/lua/5.3and.luafiles at/var/mobile/Library/AutoTouch/Library/LuaLibraries.
ATTENSION: DO NOT use script filename same as the libraries' name, such aslcurl,lfs,lsqlite3.
# LuaCURL
curl is used in command lines or scripts to transfer data. It is also used in cars, television sets, routers, printers, audio equipment, mobile phones, tablets, settop boxes, media players and is the internet transfer backbone for thousands of software applications affecting billions of humans daily.
It supports DICT, FILE, FTP, FTPS, Gopher, HTTP, HTTPS, IMAP, IMAPS, LDAP, LDAPS, POP3, POP3S, RTMP, RTSP, SCP, SFTP, SMB, SMBS, SMTP, SMTPS, Telnet and TFTP. curl supports SSL certificates, HTTP POST, HTTP PUT, FTP uploading, HTTP form based upload, proxies, HTTP/2, cookies, user+password authentication (Basic, Plain, Digest, CRAM-MD5, NTLM, Negotiate and Kerberos), file transfer resume, proxy tunneling and more.
Learn More (opens new window)
Examples:
-- HTTP Get
local curl = require('lcurl')
curl.easy{
url = 'http://httpbin.org/get',
httpheader = {
"X-Test-Header1: Header-Data1",
"X-Test-Header2: Header-Data2",
},
writefunction = alert -- use io.stderr:write()
}
:perform()
:close()
-- HTTP Post
curl.easy()
:setopt_url('http://posttestserver.com/post.php')
:setopt_writefunction(io.write)
:setopt_httppost(curl.form() -- Lua-cURL guarantee that form will be alive
:add_content("test_content", "some data", {
"MyHeader: SomeValue"
})
:add_buffer("test_file", "filename", "text data", "text/plain", {
"Description: my file description"
})
:add_file("test_file2", "BuildLog.htm", "application/octet-stream", {
"Description: my file description"
})
)
:perform()
:close()
# LuaSocket
LuaSocket is a Lua extension library which supported TCP (opens new window), UDP (opens new window), SMTP (opens new window), HTTP (opens new window), FTP (opens new window) protocols. Learn how to use it from the Learn More (opens new window).
# LuaSec
LuaSec is a binding for OpenSSL library to provide TLS/SSL communication. It takes an already established TCP connection and creates a secure session between the peers.Learn More (opens new window)
# LuaSqlite3
LuaSQLite 3 is a thin wrapper around the public domain SQLite3 database engine. Learn More (opens new window)
# json.lua
json.lua provides operation methods on json. GitHub (opens new window)
LICENSE (opens new window)
Usage
local json = require "json"
local jsonString =json.encode({ 1, 2, 3, { x = 10 } }) -- Returns '[1,2,3,{"x":10}]'
local luaTable = json.decode('[1,2,3,{"x":10}]') -- Returns { 1, 2, 3, { x = 10 } }
# Plist
Plist library provides a batch of methods to operate on plist files.
Usage
local plist = require("plist")
-- Read a plist file, return it as a lua table, return nil if failed.
local luaTable = plist.read(plistFilePath);
-- Write a lua table as a plist into a file, the foramt parameter specifis "xml", "binary" you want to write with.
local done = plist.write(luaTable, plistFilePath, format);
-- Load a plist string to lua table.
local luaTable = plist.load(plistString);
-- Dump a lua table to plist data with format "xml" or "binary"
local plistData = plist.dump(luaTable, format);
# Penlight
A set of pure Lua libraries focusing on input data handling (such as reading configuration files), functional programming (such as map, reduce, placeholder expressions,etc), and OS path management.
GitHub (opens new window)
Document (opens new window)
LICENSE (opens new window)
It has plenty of modules:
Paths, Files and Directories
path: queries likeisdir,isfile,exists, splitting paths likedirnameandbasenamedir: listing files in directories (getfiles,getallfiles) and creating/removing directory pathsfile:copy,move; read/write contents withreadandwrite
Application Support
app:require_hereto rebaserequireto work with main script path; simple argument parsingparse_argslapp: sophisticated usage-text-driven argument parsing for applicationsconfig: flexibly read Unix config files and Windows INI filesstrict: check for undefined global variables - can usestrict.modulefor modulesutils,compat: Penlight support for unified Lua 5.1/5.2 codebasestypes: predicates likeis_callableandis_integer; extendedtypefunction.
Extra String Operations
utils: can split a string with a delimiter usingutils.splitstringx: extended string functions covering the Pythonstringtypestringio: open strings for reading, and creating strings using standard Lua IO methodslexer: lexical scanner for splitting text into tokens; special cases for Lua and Ctext: indenting and dedenting text, wrapping paragraphs; optionally make%work as in Pythontemplate: small but powerful template expansion enginesip: Simple Input Patterns - higher-level string patterns for parsing text
Extra Table Operations
tablex: copying, comparing and mapping overpretty: pretty-printing Lua tables, and various safe ways to load Lua as dataList: implementation of Python 'list' type - slices, concatenation and partitioningMap,Set,OrderedMap: classes for specialized kinds of tablesdata: reading tabular data into 2D arrays and efficient queriesarray2d: operations on 2D arrayspermute: generate permutations
Iterators, OOP and Functional
seq: working with iterator pipelines; collecting iterators as tablesclass: a simple reusable class frameworkfunc: symbolic manipulation of expressions and lambda expressionsutils:utils.string_lambdaconverts short strings like|x| x^2into functionscomprehension: list comprehensions:C'x for x=1,4'()=={1,2,3,4}
# LuaFileSystem
LuaFileSystem is a Lua library developed to complement the set of functions related to file systems offered by the standard Lua distribution.
LuaFileSystem offers a portable way to access the underlying directory structure and file attributes.Learn More (opens new window)
# WebSocket
This module provides Lua modules for Websocket Version 13 (opens new window) conformant clients and servers.
GitHub (opens new window)
LICENSE (opens new window)
Examples (opens new window)
Usage
-- Client
-- connects to a echo websocket server running a localhost:8080
-- sends a strong every second and prints the echoed messages
-- to stdout
local ev = require'ev'
local ws_client = require('websocket.client').ev()
ws_client:on_open(function()
print('connected')
end)
ws_client:connect('ws://echo.websocket.org','echo')
ws_client:on_message(function(ws, msg)
print('received',msg)
end)
local i = 0
ev.Timer.new(function()
i = i + 1
ws_client:send('hello '..i)
end,1,1):start(ev.Loop.default)
ev.Loop.default:loop()
# Extension Functions
Extension functions are used to extend Lua language. Thus, the device can simulate some human abilities of operating the mobile phone. Moreover, extension functions also support functions including: screenshot, color searching, color matching, and picture matching.
# touchDown(id, x, y)
Press the coordinate (x,y) on the screen.
Parameters
| Parameter | Type | Specification |
|---|---|---|
| id | Integer | Finger ID. is used to mark a finger in single-touch or multi-touch. |
| x | Float | x-coordinate on the screen |
| y | Float | y-coordinate on the screen |
Return
None
Examples
-- Press by one finger at coordinate (100,200).
touchDown(0, 100, 200);
-- Press by three fingers at three locations on the screen.
touchDown(0, 100, 200);
touchDown(1, 200, 300);
touchDown(2, 300, 400);
-- Implement a tap function
function tap(x, y)
touchDown(0, x, y);
usleep(16000);
touchUp(0, x, y);
end
-- Tap at (100, 200)
tap(100, 200);
# touchMove(id, x, y)
Move the finger to coordinate (x,y).
Parameters
| Parameter | Type | Specification |
|---|---|---|
| id | Integer | Finger ID. is used to mark a finger in single-touch or multi-touch. |
| x | Float | x-coordinate on the screen |
| y | Float | y-coordinate on the screen |
Return
None
Examples
-- Press by one finger at coordinate (100,200) and move the finger to coordinate (200,200).
touchDown(0, 100, 200);
usleep(16000);
touchMove(0, 200, 200);
-- Press by three fingers at three locations on the screen and move to new location.
touchDown(0, 100, 200);
touchDown(1, 200, 300);
touchDown(2, 300, 400);
usleep(16000);
touchMove(0, 150, 250);
touchMove(1, 250, 350);
touchMove(2, 350, 450);
# touchUp(id, x, y)
Lift the finger from coordinate (x,y)
Parameters
| Parameter | Type | Specification |
|---|---|---|
| id | Integer | Finger ID. is used to mark a finger in single-touch or multi-touch. |
| x | Float | x-coordinate on the screen |
| y | Float | y-coordinate on the screen |
Return
None
Examples
-- Click the screen once by one finger at coordinate (100,200).
touchDown(0, 100, 200);
usleep(16000);
touchUp(0, 100, 200);
-- Press by three fingers at three locations on the screen, move to new location, and then lift the finger.
touchDown(0, 100, 200);
touchDown(1, 200, 300);
touchDown(2, 300, 400);
usleep(16000);
touchMove(0, 150, 250);
touchMove(1, 250, 350);
touchMove(2, 350, 450);
usleep(16000);
touchUp(0, 150, 250);
touchUp(1, 250, 350);
touchUp(2, 350, 450);
# keyDown(keyType)
Simulate the pressing of physical key.
Parameters
| Parameter | Type | Specification |
|---|---|---|
| keyType | Integer | Physical key identification. Now you can use these physical keys. |
Return
None
Examples
-- Simulate the pressing of Home Key.
keyDown(KEY_TYPE.HOME_BUTTON);
-- How to simulate a key pressing?
function keyPress(keyType)
keyDown(keyType);
usleep(10000);
keyUp(keyType);
end
keyPress(KEY_TYPE.HOME_BUTTON);
-- How to simulate a screen lock function?
function lockScreen()
keyDown(KEY_TYPE.POWER_BUTTON);
keyUp(KEY_TYPE.POWER_BUTTON);
end
-- How to simulate a screen unlock function?
function unlockScreen()
keyDown(KEY_TYPE.POWER_BUTTON);
keyUp(KEY_TYPE.POWER_BUTTON);
usleep(1000000);
local w, h = getScreenResolution();
local x = 10;
local gap = 120;
touchDown(0, x, 200);
while x < w do
x = x + gap;
usleep(16000);
touchMove(0, x, 200);
end
touchUp(0, x, 200);
end
# keyUp(keyType)
Simulate the lifting of physical key.
Parameters
| Parameter | Type | Specification |
|---|---|---|
| keyType | Integer | Physical key identification. Now you can use these physical keys. |
Return
None
Examples
-- Simulate the action of pressing and lifting Home Key.
keyDown(KEY_TYPE.HOME_BUTTON);
usleep(10000);
keyUp(KEY_TYPE.HOME_BUTTON);
# getColor(x, y)
Get the color value of the pixel point of the specified coordinate on current screen.
Parameters
| Parameter | Type | Specification |
|---|---|---|
| x | Float | x-coordinate on the screen |
| y | Float | y-coordinate on the screen |
Return
| Return | Type | Specification |
|---|---|---|
| color | Integer | Integer color value of the pixel point |
Examples
local color = getColor(100, 200)
alert(string.format("Pixel color is :%d", color))
-- Pop up color: 16777215
-- Keep gettting color of a location until it matches a specify color
local color
repeat
color = getColor(100, 200)
usleep(50000) -- Wait a while
until( color == 123456 )
-- Continue to do what's next
# getColors(locations)
Get the color values of the pixel points of the specified coordinates on current screen.
Parameters
| Parameter | Type | Specification |
|---|---|---|
| locations | table | A grouo of coordinates, just as { {x1,y1}, {x2,y2}, {x3,y4} } |
Return
| Return | Type | Specification |
|---|---|---|
| colors | table | Colors gotten with corresponding order. |
Examples
local result = getColors({ {100, 200}, {200, 300}, {300, 400} });
for i, v in pairs(result) do
log(string.format("Gotten color:%d", v));
end
# findColor(color, count, region, debug, rightToLeft, bottomToTop)
Search the coordinates of the pixel points matching the specified color on current screen.
Parameters
| Parameter | Type | Specification | Optional | Default |
|---|---|---|---|---|
| color | Integer | Matched color value. | NO | |
| count | Integer | The number refers to how many matched pixel points is found at most. 0 is default setting, which shows all matching points are found. 1 refers to only the first matching pixel point is found. 2 refers to only the first two pixel points are found. The less the number is, the faster the speed is. | NO | 0 |
| region | table | You only search the result in the specified area. This area is the table type including four values {x, y, width, height}. The four values respectively represent the coordinate x, coordinate y, width, and height of the rectangular area. {100,100,200,200} is an example. If you do not want to specify the area, just input nil. | NO | nil |
| debug | boolean | If pass debug=true, it will produce a image ends with "-Debug.PNG" marked the matching areas. | YES | false |
| rightToLeft | boolean | Search direction, default is left to right. | YES | false |
| bottomToTop | boolean | Search direction, default is top to buttom. | YES | false |
Return
| Return | Type | Specification |
|---|---|---|
| locations | table | Coordinates of matched pixel points. For example: { {x1, y1}, {x2, y2}, ... } |
Examples
-- Example:
local result = findColor(0x0000ff, 2, nil);
for i, v in pairs(result) do
log(string.format("Found pixel: x:%f, y:%f", v[1], v[2]));
end
-- Example: Search from right to left, from bottom to top
local result = findColor(0x0000ff, 2, nil, nil, true, true);
for i, v in pairs(result) do
log(string.format("Found rect at: x:%f, y:%f", v[1], v[2]));
end
-- Example:
local result = findColor(0x00ddff, 0, {100, 50, 200, 200});
for i, v in pairs(result) do
log(string.format("Found pixel: x:%f, y:%f", v[1], v[2]));
end
-- Example:
local region = {100, 50, 200, 200};
local result = findColor(0x00ddff, 0, region);
for i, v in pairs(result) do
log(string.format("Found pixel: x:%f, y:%f", v[1], v[2]));
end
-- Example:
-- Keep finding a speficied color until it's found.
local locations
repeat
local locations = findColor(0x0000ff, 2, nil);
usleep(50000) -- Wait a while
until(#locations > 0)
-- Log the locations if found
for i, v in pairs(locations) do
log(string.format("Found pixel: x:%f, y:%f", v[1], v[2]));
end
Internal Implementation
function findColor(color, count, region, debug, rightToLeft, bottomToTop)
return findColors({{color,0,0}}, count, region, debug, rightToLeft, bottomToTop);
end
# findColors(colors, count, region, debug, rightToLeft, bottomToTop)
Search all rectangular areas matching “specified color and their corresponding location and return the coordinate of the pixel point matching the first color in the rectangular area. This function has the search efficiency and availability far beyond findImage. For example, you need not match the whole key picture, but only match the anchors’ color and their corresponding location on the key. You can specify the number of the results by count parameter. 0 refers to all, 1 refers to the first one, and 2 refers to the first tow. region parameter can specify the search area, which is the table type {x,y,width, height}. You only input nil if no data is specified.
This function can use the "HELPER" tool in the “Extension Function” of the script-editing interface to select the anchors’ colors from the screenshot and get their corresponding location to the function’s parameter automatically.
The coordinate of the pixel point pointed by the arrow is the coordinate of the return value.
Parameters
| Parameter | Type | Specification | Optional | Default |
|---|---|---|---|---|
| colors | table | Include some color and their corresponding location, such as:{ {0x00ddff,0,0}, {0x00eeff,10,10}, {0x0000ff,0,20} }. The small table in the big table includes 3 values: the first is the color value. The second and the third are the corresponding locations of the colors to the first color. The corresponding location of the first color’s table is always (0,0). {0x00ddff,0,0} is an example. The location values of the successive colors are their locations corresponding to the first color. The matched rectangular area can be found on the screen upon these colors and corresponding location relation. | NO | |
| count | Integer | The number refers to how many matched pixel points is found at most. 0 is default setting, which shows all matching points are found. 1 refers to only the first matching pixel point is found. 2 refers to only the first two pixel points are found. The less the number is, the faster the speed is. | NO | 0 |
| region | table | You only search the result in the specified area. This area is the table type including four values {x, y, width, height}. The four values respectively represent the coordinate x, coordinate y, width, and height of the rectangular area. {100,100,200,200} is an example. If you do not want to specify the area, just input nil. | NO | nil |
| debug | boolean | If pass debug=true, it will produce a image ends with "-Debug.PNG" marked the matching areas. | YES | false |
| rightToLeft | boolean | Search direction, default is left to right. | YES | false |
| bottomToTop | boolean | Search direction, default is top to buttom. | YES | false |
Return
| Return | Type | Specification |
|---|---|---|
| locations | table | The coordinate of the first color matched in the found rectangular area, including { {x1, y1}, {x2, y2}, ...} |
Examples
-- Example:
local result = findColors({ {0x00ddff,0,0}, {0x00eeff,10,10}, {0x0000ff,0,20} }, 2, nil, true);
for i, v in pairs(result) do
log(string.format("Found rect at: x:%f, y:%f", v[1], v[2]));
end
-- Example: Search from right to left, from bottom to top
local result = findColors({ {0x00ddff,0,0}, {0x00eeff,10,10}, {0x0000ff,0,20} }, 2, nil, true, true);
for i, v in pairs(result) do
log(string.format("Found rect at: x:%f, y:%f", v[1], v[2]));
end
-- Example:
local colors = { {0x00ddff,0,0}, {0x00eeff,10,10}, {0x0000ff,0,20} };
local result = findColors(colors, 0, nil, true);
for i, v in pairs(result) do
log(string.format("Found rect at: x:%f, y:%f", v[1], v[2]));
end
-- Example:
local colors = { {0x00ddff,0,0}, {0x00eeff,10,10}, {0x0000ff,0,20} };
local region = {100, 50, 200, 200};
local result = findColors(colors, 0, region);
for i, v in pairs(result) do
log(string.format("Found rect at: x:%f, y:%f", v[1], v[2]));
end
# findImage(targetImagePath, count, threshold, region, debug, method)
Search areas matching the specified image on current screen and return the center coordinates. It supports any format of target images. It also provides a debug mode which will produce an image marked the matching areas.
Parameters
| Parameter | Type | Specification | Optional | Default |
|---|---|---|---|---|
| targetImagePath | String | Path of the target image to match, for example: "images/gold.PNG". Any image with valid format are supported. If the path starts with character "/", it will be treated as absolute path, if not, it will be treated as relative path. Most of the time we use relative path, speficially for .ate package. | NO | |
| count | integer | How many areas to find. Pass 0 or nil if you don't want to speficy the count. | YES | 0 |
| threshold | float | Searching precision, maximum value is 1 means totally the same, minimum value is -1 means non same, default is 0.9, usually 0.99 is good. Pass nil if you just want to use the default value. | YES | 0.9 |
| region | table | Do searching in which region. Pass nil if you just want to use the default value. | YES | Whole screen |
| debug | boolean | If pass debug=true, it will produce a image ends with "-Debug.PNG" marked the matching areas. | YES | false |
| method | integer | Searching method, default is 1, pass 2 if you want to use the more intelligent method which is able to cover size scale, orientation, color changed, it will be a little slower than method 1. | YES | 1 |
Return
| Return | Type | Specification |
|---|---|---|
| center locations | table | Center coordinates of the matching areas. |
Examples
-- Example:
local result = findImage("images/Gold.PNG", 5, 0.99, nil, true)
for i, v in pairs(result) do
log(string.format("Found rect at: x:%f, y:%f", v[1], v[2]));
end
-- Example:
local result = findImage("images/Gold.PNG", nil, nil, nil, true)
for i, v in pairs(result) do
log(string.format("Found rect at: x:%f, y:%f", v[1], v[2]));
end
-- Example:
local result = findImage("images/Gold.PNG", 3)
for i, v in pairs(result) do
log(string.format("Found rect at: x:%f, y:%f", v[1], v[2]));
end
-- Example:
local imagePath = "images/spirit.PNG";
local region = {100, 100, 300, 300};
local result = findImage(imagePath, 2, 0.98, region, true)
for i, v in pairs(result) do
local x = v[1], y = v[2];
log(string.format("Found rect at: x:%f, y:%f", x, y));
-- Click the found location once.
tap(x, y);
usleep(16000);
end
-- Example:
local imagePath = "images/spirit.PNG";
local region = {100, 100, 300, 300};
-- Use method 2 to find image
local result = findImage(imagePath, 2, 0.98, region, true, 2)
# screenshot(filePath, region)
Take a screenshot for the whole screen or specified area.
It will save the screenshot image as an PNG into "AutoTouch" album of iOS Photo Library if the filePath parameter is nill, and will save the PNG to the speficied path if filePath is not nil.
If region parameter is nil, it will take shot of the whole screen.
By Clicking "+" button at top-right of AutoTouch view, then "Copy Image Here", you are able to copy an image from iOS Photo Library to AutoTouch scripts directory.
Parameters
| Parameter | Type | Specification | Optional | Default |
|---|---|---|---|---|
| filePath | string | Where to save the image. | YES | "AutoTouch" album of iOS Photo Library |
| region | table | You make a screenshot of the specified area. This area is the table type including four values {x, y, width, height}. The four values respectively represent the coordinate x, coordinate y, width, and height of the rectangular area. {100,100,200,200} is an example. If you do not want to specify the area, just input nil. | YES | nil |
Return
None
Examples
-- Take shot of the whole screen and save into "AutoTouch" album of iOS Photo Library.
screenshot();
-- Take a screenshot of the whole screen and save to the specified path, if no PNG as path extension, .PNG will automatically added.
screenshot ("images/screenshot1");
-- Take a screenshot of the specified area and save.
screenshot ("images/screenshot2.PNG", {100, 100, 200, 200});
-- Take a screenshot of the specified area and save into "AutoTouch" album of iOS Photo Library.
screenshot (nil, {100, 100, 200, 200});
# appRun(appIdentifier)
Run specified application.
Parameters
| Parameter | Type | Specification |
|---|---|---|
| appIdentifier | string | Application identifier, including "com.apple.mobilesafari". You can find the identifier from this service (opens new window) |
Return
None
Examples
-- Run Safari
appRun("com.apple.mobilesafari");
# appKill(appIdentifier)
Kill specified application.
Parameters
| Parameter | Type | Specification |
|---|---|---|
| appIdentifier | string | Application identifier, including "com.apple.mobilesafari". You can find the identifier from this service (opens new window) |
Return
None
Examples
-- Kill the running Safari
appKill("com.apple.mobilesafari");
# appState(appIdentifier)
Get the running state of the specified application
Parameters
| Parameter | Type | Specification |
|---|---|---|
| appIdentifier | string | Application identifier, including "com.apple.mobilesafari". You can find the identifier from this service (opens new window) |
Return
| Return | Type | Specification |
|---|---|---|
| state | string | State of Character string type: "NOT RUNNING", "ACTIVATED", "DEACTIVATED"。 |
Examples
-- Get the state of Safari.
local state = appState("com.apple.mobilesafari");
alert(string.format("State of Safari: %s", state));
-- Pop up the state of Safari: "ACTIVATED"
# rootDir()
Get the default directory address of the saved script. This is the default saving address of scripts and screenshots: "/var/mobile/Library/AutoTouch/Scripts/".
Parameters
None
Return
| Return | Type | Specification |
|---|---|---|
| dir | string | Default directory address of the saved script. |
Examples
local dirPath = rootDir();
alert(dirPath);
-- Popup "/var/mobile/Library/AutoTouch/Scripts/"
# currentDir()
Get directory of current executing script in runtime.
Parameters
None
Return
| Return | Type | Specification |
|---|---|---|
| dir | string | Directory of script in runtime. |
Examples
local dir = currentDir();
alert(dir);
-- "/var/mobile/Library/AutoTouch/Scripts"
-- Or maybe in tmp place for encrypted scripts: "/tmp/xxxxxxxxxxxx/"
# botPath()
Get original path of the bot, relative to the runtime path of encrypted scripts.
Parameters
None
Return
| Return | Type | Specification |
|---|---|---|
| path | string | Original path of the bot. |
Examples
local path = botPath();
alert(path);
-- "/var/mobile/Library/AutoTouch/Scripts/test.lua"
-- "/var/mobile/Library/AutoTouch/Scripts/test1.ate"
# usleep(microseconds)
Sleep several microseconds (1/1000000 second)
Parameters
| Parameter | Type | Specification |
|---|---|---|
| microseconds | Integer | The number of paused microseconds. |
Return
None
Examples
-- Sleep 1 second.
usleep(1000000);
# log(content)
Record log, can be seen in the log interface.
Parameters
| Parameter | Type | Specification |
|---|---|---|
| content | string | The log content to be recorded. |
Return
None
Examples
log("play here...");
# alert(message)
Pop up the dialog box to show specified content.
Parameters
| Parameter | Type | Specification |
|---|---|---|
| message | string | Content to be showed. |
Return
None
Examples
alert("Hello World!");
# toast(message, delay)
Show messages with Toast style and delay for some seconds.
Parameters
| Parameter | Type | Specification |
|---|---|---|
| message | string | Content to be showed. |
| delay | integer | How long time to keep showing, default is 2 seconds. |
Return
None
Examples
toast("Hello I'm a toast!", 5); -- Show message for 5 seconds.
toast("Hello again!"); -- Show message for 2 seconds.
# vibrate()
Vibrate once。
Parameters
None
Return
None
Examples
-- Vibrate once.
vibrate();
# playAudio(audioFile, times)
Play audio document at specified location.
Parameters
| Parameter | Type | Specification |
|---|---|---|
| audioFile | string | Absolute path of audio document. |
| times | integer | Number of repeated plays. 0 represents infinite repeat. |
Return
None
Examples
-- Play audio infinitely.
playAudio("/var/audio.mp3", 0);
# stopAudio()
Stop playing audio.
Parameters
None
Return
None
Examples
-- Stop playing audio.
stopAudio();
# getOrientation()
Get orientation of the screen. Return the integer value. Please refer to the “Orientation Type of Screen” for specific correspondence relation.
Parameters
None
Return
| Return | Type | Specification |
|---|---|---|
| orientation | Integer | Screen orientation may be these values |
Examples
local o = getOrientation();
alert(string.format("Screen orientation is : %d", 0))
-- Pop up the orientation 2 of the screen, and mark the reversed screen.
# getScreenResolution()
Get screen resolution bese on pixels.
Parameters
None
Return
| Return | Type | Specification |
|---|---|---|
| width | Integer | Width of screen resolution. |
| height | Integer | Height of screen resolution. |
Examples
local w, h = getScreenResolution();
alert(string.format("Resolution of iPhone 6 Plus: width:%d, height:%d", w, h));
-- iPhone 6 Plus’s resolution width is 1242 and resolution height is 2208.
# getSN()
Get Serial Number of the device.
Parameters
None
Return
| Return | Type | Specification |
|---|---|---|
| SN | string | Serial Number of the device. |
Examples
local sn = getSN();
alert(string.format("SN is : %s", sn));
-- Popup shows the SN of the device: C15NFK32TWD2
# getVersion()
Get version of AutoTouch.
Parameters
None
Return
| Return | Type | Specification |
|---|---|---|
| version | string | Version of AutoTouch. |
Examples
local version = getVersion();
alert(string.format("Current version of AutoTouch is : %s", version));
-- Pop up shows current version of AutoTouch: 3.5.3-4
# frontMostAppId()
Get identifier of current front most App.
Parameters
None
Return
| Return | Type | Specification |
|---|---|---|
| App Identifier | string | App Identifier of current front most App. |
Examples
local appId = frontMostAppId();
alert(string.format("Current front most App is : %s", appId));
# frontMostAppOrientation()
Get orientation of current front most App. See the Types of orientations
Parameters
None
Return
| Return | Type | Specification |
|---|---|---|
| Orientation | integer | Orientation of current front most App. |
Examples
local orientation = frontMostAppOrientation();
alert(string.format("Orientation of current front most App is : %d", orientation));
# intToRgb(intColor)
Transit integer color to independent values of R,G,B.
Parameters
| Parameter | Type | Specification |
|---|---|---|
| intColor | Integer | Integer color value |
Return
| Return | Type | Specification |
|---|---|---|
| R | Integer | Red color value. |
| G | Integer | Green color value. |
| B | Integer | Blue color value. |
Examples
local r, g, b = intToRgb(0x2b2b2b);
alert(string.format("R:%d, G:%d, B:%d", r, g, b));
# rgbToInt(r, g, b)
Transit values of R,G,B to integer color value.
Parameters
| Parameter | Type | Specification |
|---|---|---|
| R | Integer | Red color value. |
| G | Integer | Green color value. |
| B | Integer | Blue color value. |
Return
| Return | Type | Specification |
|---|---|---|
| intColor | Integer | Integer color value |
Examples
local intColor = rgbToInt(200, 255, 100);
alert(string.format("Int type color: %d", intColor));
# copyText(text)
Copy specified text to clipboard.
Parameters
| Parameter | Type | Specification |
|---|---|---|
| text | string | Text to be copied. |
Return
None
Examples
copyText("This is a copied text!");
# clipText()
Get the text in the clipboard.
Parameters
None
Return
| Return | Type | Specification |
|---|---|---|
| text | string | Text copied in the clipboard. |
Examples
local text = clipText();
alert(text);
-- Popup shows the text to be copied: "This is a copied text!";
# inputText(text)
Input text to the input box selected now. You can delete a character backspace by inputText("\b"). ATTENSION: Enable inoutText function at AutoTouch Settings > Features before using it.
Parameters
| Parameter | Type | Specification |
|---|---|---|
| text | string | Text to be input. |
Return
None
Examples
inputText("Let's input some text automatically without tapping the keyboard!");
-- Delete 3 character by inputing 3 backspaces.
inputText("\b\b\b");
# dialog(controls, orientations)
Pop up self-defined dialog box to accept the user input. Please refer to the example for specific usage.
Parameters
| Parameter | Type | Specification | Optional | Default |
|---|---|---|---|---|
| controls | table | Array of self-defined controls. You can now use these dialog box controls. | NO | |
| orientations | table | Orientations that dialog can be, see Types of orientations. | YES | auto |
Return
| Return | Type | Specification |
|---|---|---|
| Flag of tapped button | integer |
Examples
local label = {type=CONTROLLER_TYPE.LABEL, text="Would you mind to provide some personal informations?"}
local nameInput = {type=CONTROLLER_TYPE.INPUT, title="Name:", key="Name", value="Bob"}
local positionPicker = {type=CONTROLLER_TYPE.PICKER, title="Position:", key="Position", value="CEO", options={"CEO", "CTO", "CFO", "CXO"} }
local developerSwitch = {type=CONTROLLER_TYPE.SWITCH, title="A Developer:", key="ADeveloper", value=1}
-- It's an option for users to determine weather the inputs should be remembered, if you use this control in the dialog.
local remember = {type=CONTROLLER_TYPE.REMEMBER, on=false}
--[[ Define buttons:
type = CONTROLLER_TYPE.BUTTON
title = Button text
color = Button background color, it's optional, the default value is 0x428BCA
width = Button width upon percentage of the dialog width, it's optional, the default value is 0.5, max value is 1.0.
flag = Integer type of button flag for identifying which button is tapped.
collectInputs = Boolean type specifying wheather the dialog should collect the inputs while this button is tapped. ]]--
local btn1 = {type=CONTROLLER_TYPE.BUTTON, title="Button 1", color=0x71C69E, width=0.8, flag=1, collectInputs=false}
local btn2 = {type=CONTROLLER_TYPE.BUTTON, title="Button 2", color=0xFF5733, flag=2, collectInputs=true}
local btn3 = {type=CONTROLLER_TYPE.BUTTON, title="Button 3", color=0xFFB7D0, width=1.0, flag=3, collectInputs=false}
local btn4 = {type=CONTROLLER_TYPE.BUTTON, title="Button 4", width=1.0, flag=4, collectInputs=true}
local controls = {label, nameInput, positionPicker, developerSwitch, btn1, btn2, remember, btn3, btn4}
-- Pop up the dialog. After popping, the script will suspend waiting for user input until any button is tapped, then returns the flag of tapped button.
-- What orientations the dialog could be, it's optional
local orientations = { ORIENTATION_TYPE.LANDSCAPE_LEFT, ORIENTATION_TYPE.LANDSCAPE_RIGHT };
local result = dialog(controls, orientations);
if (result == 1) then
alert(string.format("name:%s, birthday:%s, gender:%d", nameInput.value, positionPicker.value, developerSwitch.value))
else
alert(string.format("Dialog returned: %s", result))
end
# clearDialogValues(script)
Clear the remembered values of the dialog created by the function dialog.
Parameters
| Parameter | Type | Specification |
|---|---|---|
| script | string | script path. eg. there is a dialog.lua script in the scripts list, use it like this: clearDialogValues("dialog.lua"); |
Return
None
Examples
-- There is a dialog.lua script in the scripts list
clearDialogValues("dialog.lua");
# openURL(urlString)
Open url, or open other apps' url scheme. Look at Always-Updated List of iOS App URL Scheme Names (opens new window) and example: Google Maps URL Scheme for iOS (opens new window)
Parameters
| Parameter | Type | Specification |
|---|---|---|
| urlString | string | Target to open. |
Return
None
Examples
openURL("https://autotouch.net")
openURL("prefs:root=General&path=About")
openURL("musics://")
openURL("itms-apps://itunes.apple.com")
openURL("tel://+1123456")
openURL("clashofclans://")
# isLicensed()
Check if the current device is running licensed AutoTouch
Parameters
None
Return
| Return | Type | Specification |
|---|---|---|
| licensed | boolean | If current device is licensed. |
Examples
if isLicensed() then
alert("Your device is licensed by AutoTouch!");
end
# setAutoLaunch(scriptPath, on)
Switch on/off a script as auto launch.
Parameters
| Parameter | Type | Specification |
|---|---|---|
| filePath | string | Path starts with "/" is a absolute path, otherwise it's a relative path. |
| on | boolean | Switch auto launch on or off, true means on, false means off. |
Return
None
Examples
setAutoLaunch("Records/test.lua", true);
# listAutoLaunch()
List all auto launch scripts
Parameters
None
Return
| Return | Type | Specification |
|---|---|---|
| scripts | table | Relative path List of auto launch scripts. |
Examples
local scripts = listAutoLaunch()
for i, v in pairs(scripts) do
alert(v);
end
# stop()
SStop the current script execution.
Parameters
None
Return
None
Examples
-- Exit execution
stop();
# ocr(options)
v8.0.10 and above
Text recognition from the screen
Parameters
| Parameter | Type | Specification | Optional | Default |
|---|---|---|---|---|
| options | table | look at the example code below | YES | Whole screen |
Return
| Return | Type | Specification |
|---|---|---|
| Recognized Texts | table | Look at the example code and output. |
Examples
-- Example:
-- Use remote AI service which bases on `TesseractOCR` at present.
local options = {
-- OPTIONAL, default is `OCR_METHOD.IOS_VISION`, `AI_CLOUD` means remote AI service which bases on `TesseractOCR`.
method = OCR_METHOD.AI_CLOUD,
-- OPTIONAL, image path (relative or absolute path), default is nil, nil means do ocr on the screen, otherwise do ocr on the provided image.
-- image = "./image.png",
-- OPTIONAL, specified the region to recognize text, default is nil which means the whole screen.
region = {100, 100, 500, 500},
-- OPTIONAL, you can find the options from https://github.com/tesseract-ocr/tessdata
lang = 'eng+fra',
-- OPTIONAL, what characters you want to recognize in the region, such as "0123456789" will find numbers only, default is nil.
whitelist = '1234567890',
-- OPTIONAL, default is 10 seconds
timeout = 10,
-- OPTIONAL, whether you want to produce debug image, default is false
debug = true,
}
local result = ocr(options)
local s = table.tostring(result)
alert(s)
-- Example:
-- Use iOS built-in `Vision.framework` to do ocr, it usually works better than others,
-- but might have issue on some devices or with some jailbreak tools.
local options = {
-- OPTIONAL, default is `OCR_METHOD.IOS_VISION`
method = OCR_METHOD.IOS_VISION,
-- OPTIONAL, image path (relative or absolute path), default is nil, nil means do ocr on the screen, otherwise do ocr on the provided image.
-- image = "./image.png",
-- OPTIONAL, specified the region to recognize text, default is nil which means the whole screen.
region = {100, 100, 500, 500},
-- OPTIONAL, an array of strings to supplement the recognized languages at the word recognition stage, default is nil.
-- customWords = {"Playing"},
-- OPTIONAL, the minimum height of the text expected to be recognized, relative to the region/screen height, default is 1/32.
-- minimumTextHeight = nil,
-- OPTIONAL, default is 0 which means accurate first, value 1 means speed first
-- level = 0,
-- OPTIONAL, an array of languages to detect, in priority order. ISO language codes: http://www.lingoes.net/en/translator/langcode.htm.
languages = {'en-US', "fr-FR"},
-- OPTIONAL, whether use language correction during the recognition process, default is false
correct = true,
-- OPTIONAL, default is 10 seconds
timeout = 10,
-- OPTIONAL, whether you want to produce debug image, default is false
debug = true,
}
local result = ocr(options)
local s = table.tostring(result)
alert(s)
-- Example
-- Got table(array) result with format:
-- {
-- {
-- "text": "Example",
-- "rectangle": {
-- "bottomRight": {
-- "x": 300.47,
-- "y": 177.78
-- },
-- "topRight": {
-- "x": 300.47,
-- "y": 237.52
-- },
-- "topLeft": {
-- "x": 33.51,
-- "y": 237.42
-- },
-- "bottomLeft": {
-- "x": 33.51,
-- "y": 177.68
-- }
-- }
-- }
-- }
# appInfo(appIdentifier)
Get the speficied App's displayName,executablePath,bundleContainerPath,dataContainerPath.
Parameters
| Parameter | Type | Specification |
|---|---|---|
| appIdentifier | String | App identifier，such as "com.apple.mobilesafari", Get identifiers from here (opens new window). |
Return
| Return | Type | Specification |
|---|---|---|
| info | table | App info table |
Examples
local result = appInfo("com.microsoft.Office.Outlook")
alert(table.tostring(result))
# setTimer(scriptPath, fireTime, repeat, interval)
Set timer for a script.
Parameters
| Parameter | Type | Specification | Optional | Default |
|---|---|---|---|---|
| filePath | string | Path starts with "/" is a absolute path, otherwise it's a relative path | NO | |
| fireTime | string or integer | When should the timer trigger. If this parameter is an integer, it means you want it trigger after n seconds from now on, if it is a string, it should be a datetime with format "2019-09-17 08:12:52" which means the timer will trigger at this time. | NO | |
| repeat | boolean | If the timer should run repleatly. | NO | |
| interval | integer | Repeat interval in seconds. | NO |
Return
| Return | Type | Specification |
|---|---|---|
| done | boolean | If it is successful. |
Examples
-- trigger after 1000 seconds
local done = setTimer("Records/test.lua", 1000, false, 0);
-- Equals to
const done = at.setTimer("/var/mobile/Library/AutoTouch/Scripts/Records/test.lua", 1000, false, 0)
-- trigger at 2019-09-17 08:12:52 and repeat every 10000 seconds
local done = setTimer("Records/test.lua", "2019-09-17 08:12:52", true, 10000);
# removeTimer(scriptPath)
Remove timer of a script.
Parameters
| Parameter | Type | Specification | Optional | Default |
|---|---|---|---|---|
| filePath | string | Relative path of a script inside script directory of AutoTouch, such as "/Records/test.lua". | NO |
Return
| Return | Type | Specification |
|---|---|---|
| done | boolean | If it is successful. |
Examples
local done = removeTimer("/Records/test.lua");
# keepAutoTouchAwake(keepAwake)
Keep AutoTouch awake aginst iOS idle sleep.
Parameters
| Parameter | Type | Specification | Optional | Default |
|---|---|---|---|---|
| keepAwake | boolean | Keep AutoTouch awake or not | NO |
Return
None
Examples
keepAutoTouchAwake(true);
# saveToSystemAlbum(filePath, albumName)
Save an image or video from specific path to system
Parameters
| Parameter | Type | Specification | Optional | Default |
|---|---|---|---|---|
| filePath | string | File relative path or absolute path | NO | |
| albumName | string | Album name | YES |
Return
None
Examples
saveToSystemAlbum("Examples/images/cat.png"); -- Save an image or video from specific path to system album without specifying the album name
saveToSystemAlbum("Examples/images/cat.png", "Test1"); -- Save an image or video from specific path to a specified system album
saveToSystemAlbum("test.mp4", "Test2"); -- Save an image or video from specific path to a specified system album
# clearSystemAlbum(albumName)
Clear all images and videos in system album
Parameters
| Parameter | Type | Specification | Optional | Default |
|---|---|---|---|---|
| albumName | string | Album name | YES |
Return
None
Examples
saveToSystemAlbum("test.mp4", "Test2"); -- Save an image or video from specific path to a specified system album
clearSystemAlbum("Test2"); -- Clear all images and videos in a specific system album
clearSystemAlbum(); -- Clear all images and videos in all system albums
# Constants
# Types of physical keys
| Value | Specification |
|---|---|
| KEY_TYPE.HOME_BUTTON | Home Button |
| KEY_TYPE.VOLUME_DOWN_BUTTON | Volume – Button |
| KEY_TYPE.VOLUME_UP_BUTTON | Volume + Button |
| KEY_TYPE.POWER_BUTTON | Power Button |
# Types of dialog controls
| Value | Specification |
|---|---|
| CONTROLLER_TYPE.LABEL | Text label |
| CONTROLLER_TYPE.INPUT | Input box |
| CONTROLLER_TYPE.PICKER | Picker |
| CONTROLLER_TYPE.SWITCH | Switch |
| CONTROLLER_TYPE.BUTTON | Button |
| CONTROLLER_TYPE.REMEMBER | Switch for remember user inputs |
# Types of screen orientations
| Value | Specification |
|---|---|
| ORIENTATION_TYPE.UNKNOWN | Unknown orientation. Practical value is 0. |
| ORIENTATION_TYPE.PORTRAIT | Portrait screen. Home button is at the bottom. Practical value is 1. |
| ORIENTATION_TYPE.PORTRAIT_UPSIDE_DOWN | Upside-down portrait screen. Home button on the top. Practical value is 2. |
| ORIENTATION_TYPE.LANDSCAPE_LEFT | Landscape left screen. Home Key is in the left. Practical value is 3. |
| ORIENTATION_TYPE.LANDSCAPE_RIGHT | Landscape right screen. Home key is in the right. Practical value is 4. |
# Types of ocr method
| Value | Specification |
|---|---|
| OCR_METHOD.IOS_VISION | Use iOS built-in Vision.framework to do ocr. |
| OCR_METHOD.AI_CLOUD | Use remote AI service bases on TesseractOCR to do ocr. |