Copied to clipboard

Mac setup and troubleshooting

Setup

Prepare Mac environment for Kobiton Desktop Application

This document describes how to setup Mac environment for the Kobiton Desktop App.

  1. (A) General setup
  2. (B) Setup Kobiton Desktop apps on Android devices: please skip this section if Android devices are disconnected from Mac
  3. (C) Setup Kobiton Desktop on iOS devices: please skip this section if iOS devices are disconnected from Mac

Pre-conditions:

  • Kobiton Desktop application requires macOS Sierra 10.12.6 or later
  • Please execute any command with non-root user
  • If you are having trouble during the setup, please check Troubleshooting steps for any solution

Note

Currently, the Kobiton desktop application doesn’t support Java JDK 9 but Java JDK 7 or 8 ONLY.

(A) General Setup

In order to reach maximum performance, the use of Ethernet cable is strongly recommended over Wifi on Mac devices

Increase the maximum number of open files. Please read increase number of open files document

(A.1) Disable Energy Saver in Mac

The Mac machine always acts as server. However, the Energy Saver on MacOS puts the machine into sleep mode after a period of inactivity. This step aims to keep the machine awake by disabling Energy Saver.

  • Launch System Preferences app

    launch-setting.png

  • Enter ‘Energy Saver’ into search field located at the top-right corner

    select-engery-saver.png

  • Switch to Power Adapter view, ensure that:

    • Prevent computer from sleeping ... is checked

    • Put hard disks to sleep when possible is unchecked

    put-os-sleep.png

  • Finish, close the window

(A.2) Set up time zone

By default, time zone set on Mac machine is as same as that of on mobile devices.

  • Launch System Preferences app

    launch-setting.png

  • Enter Date & Time into search field located at the top-right corner, select Date & Time

    select-date-time.jpg

  • Select Time Zone

    select-timezone.jpg

  • Click on lock icon located at the bottom-left corner, enter credential to change time zone setting

    unlock-timezone.jpg

  • Uncheck 'Set time zone automatically using current location'

    uncheck-set-timezone-automatically.jpg

  • Choose closest city

    set-closest-city.jpg

  • Finish, close the window

(A.3) Setup network interface and ports range for the Network Traffic Capturing feature

Note

All inbounce and outbounce network traffic from all devices will be going through Mac desktop application

  • Download and edit kobiton.proxy.plist file

  • KOBITON_PROXY_INTERFACE [Default: "en0"] : a network interface that is as same as the mobile devices’ network. In other words, the Mac machine and the mobile devices are reachable once they connect to the same wifi access point. Available network interface can be shown by using ifconfig command line

  • KOBITON_PROXY_PORT_RANGE [Default: "49000-49100"] : specific range of ports will be defined to enable mobile devices access the host machine

  • Copy ‘com.kobiton.proxy.plist’ to /Library/LaunchAgents/ folder and restart Mac desktop

Note

In case mobile device and Mac machine are already in same wifi access point, but they are not recognized each other, double check whether there is wifi router setting rule that blocks traffics on access point. If it is enabled need to disable it

inter-traffic-block.png

(A.4) Launch Kobiton Desktop app

  • Download Kobiton app from https://portal.kobiton.com/ with private account

  • Extract Kobiton.dmg and move to Applications folder

  • Open Kobiton app

(B) Setup Kobiton Desktop for hosting Android devices

Note

Kobiton supports Android with OS version from 4.2.2 to 8.1

The user needs to configure Android devices corresponding with the Kobiton Desktop Application. Please refer to the Setup Android Device document for more details

Kobiton Desktop requires Java JDK 8 and Android SDK available on Mac. They can be installed in two ways:

Manual

  • Install Java JDK 8

  • Install Android Studio

  • Go to Android Studio > Preferences > Appearance & Behavior > System Settings > Android SDK

  • Copy Android SDK path from Android Studio, paste it into Kobiton Android SDK path

    android-sdk-tools.png

  • Go to Setting tab (see below screenshot), enter the location to Java JDK and Android SDK

    SDK-location.png

Automated by Kobiton Desktop

  • Login to Kobiton Desktop, go to Setting tab. Below screenshot is how the tab looks like

  • Install Java JDK by clicking CLICK HERE on Java JDK part

    require-java-jdk.png

  • Install Android SDK by clicking CLICK HERE on Android SDK part

    require-android-sdk.png

(C) Setup Kobiton Desktop Application for hosting iOS devices

Summary

The setup process for hosting iOS devices on Mac is as follows:

Purchase an Apple Developer program.

In order to install iOS apps on your iOS devices, please enroll Apple Developer program to accquire a Developer or Organization account.

c.1. Setup Xcode and tools:  Kobiton Desktop uses Xcode and various tools to communicate with iOS devices. This section outlines the installation steps

c.2. Prepare iOS signing key files: Incorrect iOS signing keys are the main causes of failure iOS device initialization with Kobition Desktop Application. Please refer to the followings:

  • The subsection, stated in (C.3), shows the ways to configure Mac to generate iOS signing key files.
  • Note:
    • If you have multiple Mac machines to run Kobiton Desktop Application, you only need to perform (C.2) once and you can re-use the iOS signing keys for (C.3) in all of your Mac machines
    • When your Apple Developer account gets renewed, repeat step (C.2.1) to (C.2.5) and (C.3) in all the Mac machines
    • If a new iOS device is added, step (C.2.5) and (C.3) need to be done on the new hosting device

c.3. Add iOS signing key files to the Kobiton Desktop application: This step is to allow Kobiton Desktop Application to sign iOS apps and install to your devices

c.4. Create symbol files for first-plugged iOS device: Xcode requires extra configuration steps for any first-plugged iOS device to Mac machine. This step demonstrates the way to configure Xcode to recognise iOS devices plugged to machine

Note

Kobiton supports iOS with OS version from 9.0 to 11.3

The user needs to configure iOS devices corresponding with the Kobiton Desktop Application. Please refer to the Setup iOS Device document for more details

(C.1) Set up Xcode and tools

c.1.1. Setup Xcode

    sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
    xcode-select --install
  • Agree on xcodebuild license
    sudo xcodebuild -license accept

c.1.2. Setup tools

  • Upgrade iTunes app to latest version.
  • Upgrade iTunes app to the latest version.

(C.2) Preparing iOS signing key files

There are 2 types of iOS apps that will be installed in your devices:

  1. Kobiton apps: iOS apps developed by Kobiton and are required for Kobiton to do its work.
  2. Your apps: iOS apps that you want to run on the devices. Please notice that we currently don't support skipping signing even you have already signed your apps.

In order to install these apps in your iOS devices, Kobiton Desktop needs to sign them. To enable the signing process on Kobiton Desktop, you need to prepare iOS signing key files that will be used on Kobiton Desktop whenever it signs the iOS apps

iOS signing key files are:

  • Certificates.p12: A .p12 file is a specially-formatted and encrypted file that contains your distribution certificate.

  • kobiton.mobileprovision: this is the provisioning profile file downloaded from your Apple developer account. The device info will be listed here (e.g. list of device UDIDs).

Note

The provision's App ID is as same as Xcode iOS Wildcard App ID (TEAMID.*). This is required by Kobiton Desktop`

The iOS signing keys preparation is as below:

  • 1. Create and submit .certsigningrequest to Apple Developer site to create a .cer file

  • 2. Install the .cer to Mac and export the .p12 file

  • 3. Download kobiton.mobileprovision Provisioning Profile file

Tip

If you're setting up multiple Mac machines, make sure (C.2.1) and (C.2.2) steps to be done on the single Mac machine

After the above steps are done,the iOS signing keys (Certificates.p12 and kobiton.mobileprovision) will be available, you now can move to (C.3) sub-section

c.2.1. Create and submit .certsigningrequest to Apple Developer site to create a .cer file

  • Sign in to Apple Developer site with your Developer account

  • Go to Account, click CertificatesIdentifiers & Profiles.

  • From the drop-down menu located at the top-left corner, ensure that iOStvOS, and watchOS are selected.

  • On the left-hand sidebar, select Certificates > Development.

  • Click +.

  • Select iOS App Development click Continue.

  • Follow the instructions to create CSR (Certificate Signing Request), click Continue after finishing all steps.

Note

While following the instruction, please notice that the Common Name field is used to name the .cer file when it appears in other places such as Apple website or KeyChain Access app

  • On the Generate your certificate page, click Choose File.

  • Browse to the location where the CSR file for your certificate signing request is stored, select it and confirm the upload.

  • Click Continue.

  • Click Download to download your certificate.

The downloaded .cer file will be used in next step.

c.2.2. Install the .cer to Mac and export the .p12 file

  • In the Applications folder on your Mac, open the Utilities folder and launch Keychain Access.

  • Within the Keychain Access drop down menu, select File > Add Keychain...

  • Select the downloaded .cer file from previous step

  • On left panel, make sure login is selected under Keychains and Certificates is selected under Category

  • On the right panel, look for the imported certificate by using the Common Name applied in previous step. It usually looks like iPhone Developer:

  • Right click on the certificate, select Export "iPhone Developer: ...

  • Make sure the file with format is a “.p12” displays on next window, choose a filename and destination on your hard drive.

  • Click Save.

  • 'Set a password' window is prompted, leave both fields blank.

  • Click OK.

Help

The system might ask to enter the administrator password (possibly twice as there are two files to export). If so, enter the password and click OK.

The file with format .p12 should be available on chosen local drive. This file will be used in next step.

c.2.3. Download kobiton.mobileprovision Provisioning Profile file

  • Enter
    isign_export_creds.sh /path/to/your-exporting.p12 /path/to/output/folder

Note

When the isign tool is installed, the script isign_export_creds.sh is available on $PATH to allow you to execute the command from anywhere.

  • A password dialog is prompted, press Return.

  • Enter n when Done exporting .... Remove it? [Y/n], displays

  • Enter n when Find matching provisioning profile? [Y/n], displays

  • The result is as below:

    ls -l output/.isign
    -r--r--r--    1 alice  staff  2377 Sep  4 14:17 certificate.pem
    -r--------    1 alice  staff  1846 Sep  4 14:17 key.pem

certificate.pem and key.pem are now available

c.2.4. Download kobiton.mobileprovision Provisioning Profile file

c.2.4-1. Find Team ID

  • Login to Apple Developer site with your Developer account

  • Go to Account, click Membership.

  • Copy the Team ID that will required for later use

    find-team-id.png

C.2.3-2. Create Wildcard App ID with Team ID

  • Sign in to Apple Developer site with your Developer account

  • Go to Account, click CertificatesIdentifiers & Profiles.

  • From the drop-down menu located at the top-left corner, ensure that "iOStvOS, and watchOS" are selected.

  • Select App IDs under Identifiers

  • Click + 

    add-app-id.png

  • On Registering an App ID screen

    • On App ID Prefix, select the value matching with Team ID from the above step

    • On App ID Suffix, select Wildcard App ID and enter * on Bundle ID input

    • Other inputs are not required for Kobiton

    • Click Continue, click Register

C.2.3-3. Create Provisioning Profile

  • If iOS devices are not adding into Apple Developer account, please refer to Add iOS devices to add your devices first.

  • Sign in to  Apple Developer site with your Developer account

  • Go to Account, click CertificatesIdentifiers & Profiles.

  • From the drop-down menu located at the top-left corner, ensure that "iOStvOS, and watchOS" are selected.

  • Select Development under Provisioning Profiles

  • Click +

    add-pp.png

  • Select iOS App Development ratio option, click Continue

  • Select the App ID created from previous step__, click Continue__

  • Select the cert that you created from the guideline__, click Continue__

  • Select desired devices, click Continue

  • Enter provisioning profile name, click Continue

  • Download the file and click Done

The provisioning profile is now available on chosen location, assume its name is kobiton.mobileprovision.

Edit provisioning profile

New iOS devices need to be added as is its provisioning profile to be edited to include new UDID

  • To edit a provisioning profile, select Development under Provisioning Profiles

  • Click on the currently provisioning profile, click Edit button

    edit-pp.png

  • Add new devices

  • Click on Generate, download and click Done

(C.3) Add iOS signing key files to Kobiton Desktop app

  • Launch the Kobiton app.

  • Go to iOS tab as below picture:

    Select Development Certificate .p12 file

    add-iOS-singing-key.png

    Select Provisioning Profile kobiton.mobileprovision file

    add-iOS-singing-key.png

  • Select Update.

Now iOS apps can be installed in your devices.

(C.4) Create Symbol files for first-plugged iOS device

This step is performed once for a new first-plugged iOS device.

  • Plug in the iOS device.

  • Open Xcode, at Window > Devices and Simulators, select the device.

  • Move to the next iOS device after until Processing symbol files is finished.

    install_symbol_files.png

(C.5) Setup Apple Configurator 2

  • Download & install Apple Configurator 2 from App Store

  • Open Apple Configurator 2 & install cfgutil command

    cfgutil_01.jpg

    cfgutil_02.jpg

    • Enter your username and password into the form below

    cfgutil_03.jpg

FAQ and Troubleshooting

FAQ

1. How to find Kobiton's logs folder

  • Locates at /Users/$(whoami)/Library/Application\ Support/Kobiton/logs

2. How to download Kobiton debug build

Troubleshooting

1. Missing Command Line Tools

  • Execute the  command sudo xcodebuild -license and get the error as below:
    xcode-select: error: tool 'xcodebuild' requires Xcode, but active developer directory '/Library/Developer/CommandLineTools' is a command line tools instance xcode-select --install

Identify problem

  • Missing Command Line Tools

Action

  • Execute the command below on Terminal:
    xcode-select --install

Increase the maximum number of open files

You must increase the maximum number of open files to more than 2000. Complete the following steps to set up your computer:

Reference article

Check the current maximum number of open files as follows:

  $ ulimit -n

If the result is more than 2000, do not compete the rest of these steps. If the number is fewer than 2000, you must complete the rest of the steps.

  1. Copy limit.maxfiles.plist into /Library/LaunchDaemons/limit.maxfiles.plist as follows (or download here)
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>limit.maxfiles</string>
  <key>ProgramArguments</key>
  <array>
    <string>launchctl</string>
    <string>limit</string>
    <string>maxfiles</string>
    <string>65000</string>
    <string>65000</string>
  </array>
  <key>RunAtLoad</key>
  <true/>
  <key>ServiceIPC</key>
  <false/>
</dict>
</plist>
  1. Copy_ limit.maxproc.plist_ into /Library/LaunchDaemons/limit.maxproc.plist as follows (or download here)

html <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple/DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> <plist version="1.0"> <dict> <key>Label</key> <string>limit.maxproc</string> <key>ProgramArguments</key> <array> <string>launchctl</string> <string>limit</string> <string>maxproc</string> <string>2048</string> <string>2048</string> </array> <key>RunAtLoad</key> <true /> <key>ServiceIPC</key> <false /> </dict> </plist>

  1. Change ownership of the above files to _root:wheel_:
    sudo chown root:wheel /Library/LaunchDaemons/limit.maxfiles.plist  
    sudo chown root:wheel /Library/LaunchDaemons/limit.maxproc.plist
  • Apply them as follows:

    sudo launchctl load -w /Library/LaunchDaemons/limit.maxfiles.plist
    sudo launchctl load -w /Library/LaunchDaemons/limit.maxproc.plist
    
  • Reboot your computer.

  • Verify the new limit is applied as follows:

        ulimit -n
    

Plugging devices

How to arrange devices on the surface

  • Put the devices on shelves
  • The device’s back should be located on the shelf surface, with the screen facing upward, like the image below

phone-position.jpeg

Optimal configuration for plugging in devices

Warning

Notes about USB 2.0 speed limitation

In order to provide a reasonable frame per second rate on iOS devices, the captured screen is sent from the device in large raw format (500KB - 6MB per frame). Because the data will be transferred between the device and hosting machine at USB 2.0 speed, you should only connect a small number of devices to each USB port for streamlined efficiency.

Devices are categorized into the following groups:

Group A: To produce the maximum 5-10 fps (1MB/frame), the following iOS devices should be plugged into the USB hub at a maximum volume of 4 devices at a time:

  • iPhone 4S
  • iPhone 5 (model A1428, AT&T/Canada)
  • iPhone 5 (model A1429, everything else)
  • iPhone 5c (model A1456, A1532 | GSM)
  • iPhone 5c (model A1507, A1516, A1526 (China), A1529 | Global)
  • iPad 2
  • iPad Mini

Group B: To produce the maximum 5-6 fps (2MB/frame), the following iOS devices should be plugged into the USB hub at a maximum volume of 3 devices at a time:

  • 2nd Generation iPad Mini - Wifi
  • 2nd Generation iPad Mini - Cellular
  • 3rd Generation iPad Mini - Wifi (model A1599)

Group C: To produce the maximum 2 fps (5-8MB/frame), the following iOS devices should be plugged into the USB 1 at a time:

  • 3rd Generation iPad
  • 4th Generation iPad
  • 5th Generation iPad (iPad Air) - Wifi
  • 5th Generation iPad (iPad Air) - Cellular

Group D: Any devices that aren’t listed in groups A, B, or C

Plugging group devices into a Mac

  • General Rules:

    • 3 is the maximum number of tablet devices per USB hub that allows for sufficient charging power

    • 10 is the maximum number of Android devices that a Mac can recognize

    • 10 is the maximum number of iOS devices that a Mac can recognize

    • 15 is the maximum number of devices (despite OS) that can be plugged into a Mac

    • Below are sample scenarios of device grouping configurations using a 7-port USB hub. In the following scenarios, the 7-port hub is connected to a Mac machine via a single USB port. You can use multiple USB hubs as long as the general rules above are met.

    • 1 Group C device, plus 3 Group D devices

    • 3 Group B devices

    • 4 Group A devices

    • 7 Group D devices

Feedback

SELECTED

Tip

You can select a specific word, line of text, or one or more paragraphs to comment.

COMMENT

Please give us some feedback !
Thank you!
  • We are listening,
  • we will do our best to fix this soon