Add ability to enable/disable AssistiveTouch soft "home" button. iOS 11+ (danielpaulus#148)

* Add ability to enable/disable AssistiveTouch soft "home" button. iOS 11+

Using the same technique already used for querying and setting the device language and locale, go-ios can now enable and disable AssistiveTouch using the the magic boolean com.apple.Accessibility.AssistiveTouchEnabledByiTunes

This commit slightly modifies the existing SetValueForDomain() and related methods and structs to take an interface{} value (rather than a string) in order to pass a raw bool to lockdown.

This commit also replaces a few inconsistently used tabs in the verbose command-line "help" output.

Thank you to the team at alibaba/taobao-iphone-device (tidevice) for sharing the magic word to make this happen.

Validated on iPhone 5s, 6, 6s, 6s plus, 7, 8, se 1st gen, se 2nd gen, and 11 pro max.  iOS 11.4.1, 12.1, 12.5.5, 13.4, 13.6, 14.0.1, 14.7, 15.0, 15.3, and 16.0.1 beta.

Failed on an iPhone 6+ running iOS 10.2.1 (Exits with error including hint: “Is this device running iOS 11+?”)

* Add iOS11+ version check to "assistivetouch" command, with --force override to attempt anyway.

Having tested on a grand total of 1 iOS10.x device (an iPhone 6s plus), we speculate that the technique used to enable/disable assistive touch does not work on devices older than iOS 11.  This commit adds a fail-fast check for versions older than iOS 11.

However, since only 1 device has been tested, (and older iPad OS has not been tested at all), I have also added a "--force" override so that the end-user can still give it a try.

The "--force" option also forces SetValue() to be called even if it would not cause an apparent change. (By default, if assistive touch is already disabled, and the user asks to disable it, nothing happens).

"--force" is mostly meant as a way to continue testing older device functionality without having to have a custom debug build of go-ios.  If we can definitively prove that iOS12 is the minimum, the --force option can be removed.

Co-authored-by: danielpaulus <[email protected]>

Author: briankrznarich

ios/lockdown_assistivetouch.go

@@ -0,0 +1,53 @@
+package ios
+
+import log "github.com/sirupsen/logrus"
+import "fmt"
+
+const accessibilityDomain = "com.apple.Accessibility"
+const assistiveTouchKey  = "AssistiveTouchEnabledByiTunes"
+
+// EnableAssistiveTouch creates a new lockdown session for the device and enables or disables
+// AssistiveTouch (the on-screen software home button), by using the special key AssistiveTouchEnabledByiTunes.
+// Setting to true will enable AssistiveTouch
+// Setting to false will disable AssistiveTouch, regardless of whether it was previously-enabled through
+// a non-iTunes-related method.
+func SetAssistiveTouch(device DeviceEntry, enabled bool) error {
+	lockDownConn, err := ConnectLockdownWithSession(device)
+	if err != nil {
+		return err
+	}
+	log.Debugf("Setting %s: %t", assistiveTouchKey, enabled)
+	defer lockDownConn.Close()
+	err = lockDownConn.SetValueForDomain(assistiveTouchKey, accessibilityDomain, enabled)
+	return err
+}
+func GetAssistiveTouch(device DeviceEntry) (bool, error) {
+	lockDownConn, err := ConnectLockdownWithSession(device)
+
+	if err != nil {
+		return false, err
+	}
+	defer lockDownConn.Close()
+
+	enabledIntf, err := lockDownConn.GetValueForDomain(assistiveTouchKey, accessibilityDomain)
+
+	if err != nil {
+		return false, err
+	}
+	if enabledIntf == nil{
+		// In testing, nil was returned in only one case, on an iOS 14.7 device that should already have been paired.
+		// Calling SetAssistiveTouch() directly returned the somewhat more useful error: SetProhibited
+		// After re-running "go-ios pair", full functionality returned.
+		return false, fmt.Errorf("Received null response when querying %s.%s. Try re-pairing the device.", accessibilityDomain, assistiveTouchKey)
+	}
+	enabledUint64, ok := enabledIntf.(uint64)
+	if !ok {
+		// On iOS 10.x at least, "false" is returned, perhaps for any key at all.  Attempting to manipulate AssistiveTouchEnabledByiTunes had no effect
+		return false, fmt.Errorf("Expected unit64 0 or 1 when querying %s.%s, but received %T:%+v. Is this device running iOS 11+?", accessibilityDomain, assistiveTouchKey, enabledIntf, enabledIntf)
+	} else if enabledUint64 != 0 && enabledUint64 != 1{
+		// So far this has never happened
+		return false, fmt.Errorf("Expected a value of 0 or 1 for %s.%s, received %d instead!", accessibilityDomain, assistiveTouchKey, enabledUint64)
+	}
+
+	return enabledUint64 == 1, nil
+}

ios/lockdown_value.go

@@ -114,7 +114,7 @@ type valueRequest struct {
 	Key     string `plist:"Key,omitempty"`
 	Request string
 	Domain  string `plist:"Domain,omitempty"`
-	Value   string `plist:"Value,omitempty"`
+	Value   interface{} `plist:"Value,omitempty"`
 }
 
 func newGetValue(key string) valueRequest {
@@ -126,7 +126,7 @@ func newGetValue(key string) valueRequest {
 	return data
 }
 
-func newSetValue(key string, domain string, value string) valueRequest {
+func newSetValue(key string, domain string, value interface{}) valueRequest {
 	data := valueRequest{
 		Label:   "go.ios.control",
 		Key:     key,
@@ -215,7 +215,7 @@ func (lockDownConn *LockDownConnection) GetValueForDomain(key string, domain str
 }
 
 //SetValueForDomain sets the string value for the lockdown key and domain. If the device returns an error it will be returned as a go error.
-func (lockDownConn *LockDownConnection) SetValueForDomain(key string, domain string, value string) error {
+func (lockDownConn *LockDownConnection) SetValueForDomain(key string, domain string, value interface{}) error {
 	gv := newSetValue(key, domain, value)
 	lockDownConn.Send(gv)
 	resp, err := lockDownConn.ReadMessage()

ios/utils.go

@@ -94,16 +94,18 @@ func PathExists(path string) (bool, error) {
 	return false, err
 }
 
-//IOS14 semver.MustParse("14.0")
 func IOS14() *semver.Version {
 	return semver.MustParse("14.0")
 }
 
-//IOS12 semver.MustParse("12.0")
 func IOS12() *semver.Version {
 	return semver.MustParse("12.0")
 }
 
+func IOS11() *semver.Version {
+	return semver.MustParse("11.0")
+}
+
 //FixWindowsPaths replaces backslashes with forward slashes and removes the X: style
 //windows drive letters
 func FixWindowsPaths(path string) string {

main.go

@@ -106,6 +106,7 @@ Usage:
   ios setlocation [options] [--lat=<lat>] [--lon=<lon>]
   ios setlocationgpx [options] [--gpxfilepath=<gpxfilepath>]
   ios resetlocation [options]
+  ios assistivetouch (enable | disable | toggle | get) [--force] [options]
 
 Options:
   -v --verbose   Enable Debug Logging.
@@ -186,9 +187,10 @@ The commands work as following:
    ios reboot [options]                                               Reboot the given device
    ios -h | --help                                                    Prints this screen.
    ios --version | version [options]                                  Prints the version
-   ios setlocation [options] [--lat=<lat>] [--lon=<lon>]			  Updates the location of the device to the provided by latitude and longitude coordinates. Example: setlocation --lat=40.730610 --lon=-73.935242
-   ios setlocationgpx [options] [--gpxfilepath=<gpxfilepath>]		  Updates the location of the device based on the data in a GPX file. Example: setlocationgpx --gpxfilepath=/home/username/location.gpx
-   ios resetlocation [options]										  Resets the location of the device to the actual one
+   ios setlocation [options] [--lat=<lat>] [--lon=<lon>]              Updates the location of the device to the provided by latitude and longitude coordinates. Example: setlocation --lat=40.730610 --lon=-73.935242
+   ios setlocationgpx [options] [--gpxfilepath=<gpxfilepath>]         Updates the location of the device based on the data in a GPX file. Example: setlocationgpx --gpxfilepath=/home/username/location.gpx
+   ios resetlocation [options]                                        Resets the location of the device to the actual one
+   ios assistivetouch (enable | disable | toggle | get) [--force] [options] Enables, disables, toggles, or returns the state of the "AssistiveTouch" software home-screen button. iOS 11+ only (Use --force to try on older versions).
 
   `, version)
 	arguments, err := docopt.ParseDoc(usage)
@@ -328,6 +330,29 @@ The commands work as following:
 		return
 	}
 
+	b, _ = arguments.Bool("assistivetouch")
+	if b {
+		force, _ := arguments.Bool("--force")
+		b, _ = arguments.Bool("enable")
+		if b {
+			assistiveTouch(device, "enable", force)
+		}
+		b, _ = arguments.Bool("disable")
+		if b {
+			assistiveTouch(device, "disable", force)
+		}
+		b, _ = arguments.Bool("toggle")
+		if b {
+			assistiveTouch(device, "toggle" , force)
+		}
+		b, _ = arguments.Bool("get")
+		if b {
+			assistiveTouch(device, "get", force)
+		}
+	}
+
+
+
 	b, _ = arguments.Bool("dproxy")
 	if b {
 		log.SetFormatter(&log.TextFormatter{})
@@ -920,6 +945,52 @@ func language(device ios.DeviceEntry, locale string, language string) {
 	fmt.Println(convertToJSONString(lang))
 }
 
+func assistiveTouch(device ios.DeviceEntry, operation string, force bool) {
+	var enable bool
+
+	if !force {
+		version, err := ios.GetProductVersion(device)
+		exitIfError("failed getting device product version", err)
+
+		if version.LessThan(ios.IOS11()) {
+			log.Errorf("iOS Version 11.0+ required to manipulate AssistiveTouch.  iOS version: %s detected. Use --force to override.", version)
+			os.Exit(1)
+		}
+	}
+
+	wasEnabled, err := ios.GetAssistiveTouch(device)
+
+	if err != nil{
+		if force && ( operation == "enable" || operation == "disable" ) {
+			log.WithFields(log.Fields{"error": err}).Warn("Failed getting current AssistiveTouch status. Continuing anyway.")
+		} else{
+			exitIfError("failed getting current AssistiveTouch status", err)
+		}
+	}
+
+	switch {
+	case operation == "enable":
+		enable = true
+	case operation == "disable":
+		enable = false
+	case operation == "toggle": 
+		enable = !wasEnabled
+	default: // get
+		enable = wasEnabled
+	}
+	if operation != "get" && ( force || wasEnabled != enable ) {
+		err = ios.SetAssistiveTouch(device, enable)
+		exitIfError("failed setting AssistiveTouch", err)
+	}
+	if operation == "get" {
+		if JSONdisabled {
+			fmt.Printf("%t\n", enable)
+		} else {
+			fmt.Println(convertToJSONString(map[string]bool{"AssistiveTouchEnabled":enable}))
+		}
+	}
+}
+
 func startAx(device ios.DeviceEntry) {
 	go func() {
 		deviceList, err := ios.ListDevices()