Mac Setup and Troubleshooting

January 26, 2021 02:56

Setup

Prepare Mac environment for Kobiton Desktop Application

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

General setup
Setup Kobiton Desktop apps on Android devices: please skip this section if Android devices are disconnected from Mac
Setup Kobiton Desktop on iOS devices: please skip this section if iOS devices are disconnected from Mac

Prerequisites:

Before you start installing Kobiton, make sure you meet prerequisites shown in prerequisites.
Kobiton Desktop application requires macOS Catalina (v10.15.x) or Big Sur (v11.x.x). (Please note that Kobiton no longer supports macOS Mojave.) In case your macOS is older, please upgrade your OS by installing the OS from Apple site
Please execute any command with non-root user
If you are having trouble during the setup, please check Troubleshooting steps for a 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 an 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

(A.2) Increase the maximum number of open files

(A.3) Set up timezone

(A.4) Launch Kobiton Desktop app

(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
Enter ‘Energy Saver’ into search field located at the top-right corner
Switch to Power Adapter view, ensure that:
- Prevent computer from sleeping ... is checked
- Put hard disks to sleep when possible is unchecked
Finish, close the window

(A.2) Increase the maximum number of open files

Kobiton Desktop application required the maximum number of open files to more than 2000. If your computer has this is fewer than 2000 you can flow below steps to increase this.

- You can use this command to check the maximum number of open files in your computer: ulimit -n

- If the result is more than 2000, you can skip the below steps.

Disable System Integrity Protection (SIP), you can see here.
Configuring limit.maxfiles.plist.
- Open terminal and type with the command. sudo nano /Library/LaunchDaemons/limit.maxfiles.plist
- Copy and paste the below content into the text editor which is opened in your terminal. ```xml

Label limit.maxfiles ProgramArguments launchctl limit maxfiles 65000 65000 RunAtLoad ServiceIPC Note: Press Control-X to save and close the text editor.

Configuring limit.maxproc.plist.
- Open terminal and type with the command. sudo nano /Library/LaunchDaemons/limit.maxproc.plist
- Copy and paste the below content into the text editor which is opened in your terminal. ```xml

Label limit.maxproc ProgramArguments launchctl limit maxproc 2048 2048 RunAtLoad ServiceIPC ```

Reboot your computer.
Verify the new limit is applied as follows: ulimit -n

(A.3) Set up time zone

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

Launch System Preferences app
Enter Date & Time into search field located at the top-right corner, select Date & Time
Select Time Zone
Click on lock icon located at the bottom-left corner, enter credential to change time zone setting
Uncheck 'Set time zone automatically using current location'
Choose closest city
Finish, close the window

(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 10

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
Go to Setting tab (see below screenshot), enter the location to Java JDK and Android SDK

Automated by Kobiton Desktop (preferred)

Login to Kobiton Desktop, go to Settings tab. Below screenshot is how the tab looks
Install Java JDK by clicking Download & Install on Java JDK part
Install Android SDK by clicking Donwload & Install on Android SDK part

(C) Setup Kobiton Desktop Application for hosting iOS devices

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

Enroll in the Apple Developer program

In order to install iOS apps on your iOS devices, please enroll in the [Apple Developer program](https://developer.apple.com/programs/) to acquire 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 for iOS device initialization with the Kobition Desktop Application

Please refer to the following:

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 running the 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 the Kobiton Desktop Application to sign iOS apps and install to your devices c.4. Create symbol files for first plugged in iOS device: Xcode requires extra configuration steps for any first plugged in iOS device to the Mac machine. This step demonstrates the way to configure Xcode to recognize iOS devices plugged in to a machine

The user needs to configure iOS devices to correspond 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

Download Xcode version 11.3.1 Beta in:

After downloading Xcode_11.3.1_beta.xip (above step)
- Double click on it to extract a new app called Xcode.app
- Move Xcode.app to /Applications/ folder
Install command-line tools
- 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 the latest version.

(C.2) Preparing iOS signing key files

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

Kobiton apps: iOS apps developed by Kobiton and are required for Kobiton to do its work.
Your apps: iOS apps that you want to run on the device.

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 (com.*). This is required by Kobiton Desktop`

The iOS signing keys steps are 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 are done on a 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

Here is a tutorial video on how to accomplish this task.
Sign in to Apple Developer site with your Developer account
Go to Account, click Certificates, Identifiers & Profiles.
From the drop-down menu located at the top-left corner, ensure that iOS, tvOS, 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 instructions, 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

Here is a tutorial video on how to accomplish this task
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

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

*____Here is a tutorial video on how to accomplish this task__

Sign in to Apple Developer site with your Developer account
Go to Account, click Certificates, Identifiers & Profiles.
From the drop-down menu located at the top-left corner, ensure that "iOS, tvOS, and watchOS" are selected.
Select App IDs under Identifiers
Click +
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

Here is a video follow along video to use as a tutorial
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 Certificates, Identifiers & Profiles.
From the drop-down menu located at the top-left corner, ensure that "iOS, tvOS, and watchOS" are selected.
Select Development under Provisioning Profiles
Click +
Select iOS App Development radio 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
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.
Select the iOS tab, select Development Certificate .p12 file

Select Provisioning Profile kobiton.mobileprovision file
Select Update.

Now, iOS apps can be installed on 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.

(C.5) Setup Apple Configurator 2

Download & install Apple Configurator 2 from App Store
Open Apple Configurator 2 & install cfgutil command
- Enter your username and password into the form below

(D) (Optional) Customize behavior of Kobiton Desktop application

Kobiton Desktop application respects several configurations provided at launching time that you can use to customize the application behaviors on special situations or needs

Below are steps for appling the configuration and the documentation for them

Disable System Integrity Protection (SIP), you can see here.
Create file (say com.kobiton.variables.plist) in folder /Library/LaunchAgents/ with content as below

```xml

Label com.kobiton.variables ProgramArguments launchctl setenv

  <!--
    A string to define maximum size a debug log file could be.
    Default value is 10m
  -->
  <string>KOBITON_DEBUG_LOG_MAX_SIZE</string>
  <string>10m</string>

  <!--
    A string to define maximum size an error log file could be.
    Default value is 10m
  -->
  <string>KOBITON_ERROR_LOG_MAX_SIZE</string>
  <string>10m</string>

  <!--
    An integer to define maximum amount of debug log files to keep (retention).
    Default value is 20
  -->
  <string>KOBITON_DEBUG_LOG_FILE_KEEP</string>
  <string>20</string>

  <!--
    An integer to define maximum amount of error log files to keep (retention).
    Default value is 20
  -->
  <string>KOBITON_ERROR_LOG_FILE_KEEP</string>
  <string>20</string>

  <!--
    A string to specify the geolocation that the Desktop app will set into
    the device for some features like setting fake location.
    This configuration is used only when KOBITON_AUTO_DETECT_GEO_LOCATION_ENABLED is FALSE.

    The value is a string of lat and lon like "10.8087713,106.6628823"

    To find the lat and lon for a location, perform as below

    1. Access page https://www.google.com/maps
    2. Enter the location name like Atlanta US
    3. Wait for the website to update
    4. Copy the lat,lon at the URL, it should be like "@33.7678358,-84.4906437,12z" but we only keep the number part e.g. "33.7678358,-84.4906437,12"

    Default value is 10.8087713,106.6628823 (Atlanta, Georgia US)
  -->
  <string>KOBITON_DEFAULT_GEO_LOCATION</string>
  <string>10.8087713,106.6628823</string>

  <!--
    A lowercase string of "true" or "false" to specify that whether the
    Desktop app should auto find the geolocation of current machine is
    Default value is false (not auto find geolocation)
  -->
  <string>KOBITON_AUTO_DETECT_GEO_LOCATION_ENABLED</string>
  <string>false</string>

  <!--
    See section A.3 (Network Traffic Capturing feature) for
    documentation of 02 below configuration
  -->
  <!--string>KOBITON_PROXY_INTERFACE</string>
  <string>en0</string>
  <string>KOBITON_PROXY_PORT_RANGE</string>
  <string>49000-49100</string-->
</array>
<key>RunAtLoad</key>
<true/>
<key>ServiceIPC</key>
<false/>

```

Tell MacOS to load it

bash chmod 644 /Library/LaunchAgents/com.kobiton.variables.plist launchctl load /Library/LaunchAgents/com.kobiton.variables.plist

Restart the Kobiton Desktop application
Verify that Kobiton Desktop application reads updated configuration by looking at file out.log in Kobiton log folder (see below FAQ section)
In case not effect, please restart your computer and start Desktop app again

FAQ and Troubleshooting

FAQ

1. How to find Kobiton's logs folder

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

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

2. Devices are stuck at Register to Cloud state

Identify problem

The current network is blocking some ports

Action

Ask IT team to bypass those ports below:
- hub.kobiton.com port 443
- portal.kobiton.com port 443
- api.kobiton.com port 443
- hub.kobiton.com port 4001

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

Optimal configuration for plugging in devices

!!! warning Notes about USB 3.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 3.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 5
iPhone 5
iPhone 5c
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)
iPhone 6
iPhone 6s
iPhone 7
iPhone 7 Plus
iPhone 8
iPhone 8 plus
iPhone x
iPhone XR
iPhone XS
iPhone XS Max
iPhone 11 series
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 10-port USB hub. In the following scenarios, the 10-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

Recommended hardware devices

USB Hub with separated power supply: AmazonBasics USB-A 3.1 10-Port Hub with Power Adapter - 65W Powered
USB cables
- For Android
- For iOS
  - Lightning to USB