tipmao / stf_ios_support

Central repo to connect and document components/repos needed for IOS stf support

STF IOS Support

Build machine setup

1. Clone this repo down to your build machine

2. Install XCode

3. Add your developer Apple ID to XCode

   1. XCode -> XCode menu -> Preferences -> Accounts Tab
   2. + under Apple IDs list
   3. Choose Apple ID
   4. Login to your account so that dev certs can be downloaded

4. Run ./init.sh

Deploy server side:

1. On your STF server machine

   1. Pull STF server image docker pull openstf/stf

   2. Copy docker-compose.yml and .env from server/

   3. Generate certs for your system / domain

   4. Update docker-compose.yml cert paths and .env

   5. Start STF

      1. docker-compose up

Using a standard OpenSTF server:

1. Setup your server as normal following upstream instructions
2. Alter stf_ios_support/coordinator/proc_stf_provider --connect-sub and --connect-push lines to match your server config

Build provider files:

1. Update config.json

2. Run make then make dist

   1. dist.tgz will be created

Deploy provider setup:

1. Copy dist.tgz from build machine
2. Run tar -xf dist.tgz
3. Tweak config.json as desired

Starting provider

1. Register(provision) your IOS device to your developer account as a developer device

   1. Use the API?? https://developer.apple.com/documentation/appstoreconnectapi/devices
   2. Follow these instructions: https://www.telerik.com/blogs/how-to-add-ios-devices-to-your-developer-profile I couldn't find updated instructions on Apples website. If you find them please let me know so I can link to them.

2. Plug your IOS device in

3. Pair it with your system

4. Have Xcode setup the "developer image" on your IOS device:

   1. Open Xcode
   2. Go to Windows... Devices and Simulators
   3. Wait while Developer Image is installed to your phone

5. Run ./bin/ios_video_pull -devices -decimal to determine the PID ( product ID ) of your IOS device in decimal

6. Run ./bin/devreset [decimal product ID] 1452 to reset the video streaming status of your IOS device

7. Run ./run ( and leave it running )

8. Permissions dialog boxes appear for coordinator to listen on various ports; select accept for all of them

9. Device shows up in STF with video and can be controlled. Yay

Known Issues

1. libimobiledevice won't install properly right now

   1. The brew version cannot be used because it is both far out of date and broken
   2. The brew --HEAD version that is installed by init.sh does not build correctly right now because HEAD is broken, and additionally HEAD of libimobiledevice depends on HEAD of libplist which the init.sh script is not setup to build and install correctly.
   3. This all will be taken care of soon. For the time being; be aware that libimobiledevice won't install via init.sh so you'll need to figure out on your own somehow how to get it installed until this repo is updated to automate that process.
   4. It is possible to build current HEAD of libimobiledevice using --disable-openssl and by brew installing HEAD of libplist. You'll also need to brew install libgcrypt.

2. Video streaming will sometimes be left in a "stuck" state

   1. ios_video_pull sub-process of coordinator depends on quicktime_video_hack upstream repo/library. That library does not properly "stop" itself if you start and then stop reading video from an IOS device. As a result, if you run coordinator, stop it, then start it again, it won't be able to start up again correctly.
   2. To fix this you can use devreset. This is why the devreset command is mentioned above currently to run before starting coordinator. devreset effectively stops the video streaming entirely, resetting it so that it can be started up again.

3. The init.sh script does not created ~/Library/LaunchAgents folder; despite it needing to exist

   1. Your system may already have such a folder for your user, in which case everything will work fine.
   2. If it doesn't exist, coordinator will be unable to create the plist within it used to start WDA. You'll need to create the folder then to fix this. The error message in this case is somewhat obvious; but this issue will bite many users. Autocreation of this folder will be added soon.

Setting up with VPN

1. Install openvpn-server on your STF server machine
2. Create client certificate(s) using your favorite process...
3. Create ovpn file(s) with those client certs
4. Deploy those cert(s) to your provider machines; setting them up in Tunnelblick
5. Alter config.json on each provider to have the name of the cert setup in Tunnelblick
6. Start openvpn server on STF server
7. Start coordinator/provider on each provider machine

Handling video not working

1. Run ./view_log proc ios_video_pull to check for errors fetching h264 data from the IOS device

2. Run ./view_log -proc h264_to_jpeg to check for errors decoding h264 into jpegs

3. Run ./view_log -proc ios_video_stream to check for errors streaming jpegs via websocket to browser

4. Reboot your IOS device and try again

Increase clicking speed

1. Jailbreak your IOS device

2. Install Veency through Cydia

3. Configure a VNC password if desired

4. Alter config.json

   1. Set "use_vnc": true
   2. Set "vnc_scale": 2 ( or 3 depending on your device scale )
   3. If password used, set "vnc_password": "[your password]"

5. Start coordinator

6. Clicking is now nearly immediate!

Debugging

1. run ./view_log to see list of things that log
2. run ./view_log -proc [one from list]

FAQ

See https://github.com/tmobile/stf_ios_support/wiki/FAQ