3. Kobiton Cloud Installation Guide


This installation guide mentions two kinds of machines:

  • Local Machine: This is your local or personal computer that is used to ssh into the Target Machines.
  • Target Machines: The machines you will be setting up in this installation guide, including the GEM, deviceShare, and deviceConnect™.


Additional setup steps are required to support the following features:

  1. Image Injection
  2. virtualUSB
  3. Orion Board
  4. Network Payload Capture

Setup the GEM Server

What’s needed before you start

  1. GEM - Dell R740
  2. Power
  3. Monitor
  4. Keyboard
  5. Mac OS machine for building the USB boot disk.
  6. NVIDIA Quadro P2000 cards or NVIDIA Quadro P2200s
  7. GEM Firmware provided by Kobiton (*.img file)
  8. USB stick #1 (8GB or above): To build a bootable USB with the GEM Firmware.
  9. USB stick #2: To store automated installation scripts.

GEM Server Configuration

GEM Physical Setup

CAUTION: You need to plug network cable CORRECTLY into port 1 on the GEM.Screen_Shot_2022-09-06_at_3.22.58_PM.png

  1. Make sure the GEM is on a network and has an IP address.
  2. Ensure the RAID controller is set to HBA mode in the BIOS:
    1. Turn on the GEM
    2. At the server initiation sequence, press F2 to enter the BIOS settings
    3. Select Device Settings
    4. RAID Controller in Slot X
    5. Controller Management
    6. Advanced Controller Management
    7. Switch to HBAScreen_Shot_2022-09-06_at_3.25.06_PM.png
  3. In order to ensure that when the Dell starts, it boots to the correct boot disk, ensure the physical disk of Dell machine is a selected boot device
    1. Still in BIOS Settings
    2. Select Device Settings
    3. RAID Controller in Slot X
    4. Controller Management
    5. Select your hard disk as a Boot DeviceScreen_Shot_2022-09-06_at_3.28.07_PM.png
  4. Ensure the system is set to UEFI boot mode in BIOS:
    1. Still in BIOS Settings
    2. Select Boot Settings
    3. Boot Mode
    4. Select UEFIScreen_Shot_2022-09-06_at_3.28.43_PM.png
  5. After finishing all of the steps above, insert the bootable USB drive (USB Stick #1) and reboot the GEM. Do not insert USB #2.
  6. When the GEM reboots, press F11 to enter the Boot menu
    1. Select One-Shot UEFI Boot Menu
    2. Select the USB stick to boot from and wait for NixOS Boot sequence to completeScreen_Shot_2022-09-06_at_3.30.41_PM.png
  7. Login as root, no password is required
  8. Plug in USB Stick #2
    1. CAUTION: SSD on GEM must be identified at dev/sdb. Use the command:
      # lsblk
      to see if the SSD card is identified at dev/sdb. If it is not, unplug all USB sticks and reboot with the correct USB order. 
  9. From a terminal prompt, enter:
    # dmesg | tail
    to identify the USB Stick #2 mount point. In the following diagram, the line that reads sdc: sdc1 sdc2 displays the two mounted USB sticks.Screen_Shot_2022-09-06_at_3.31.37_PM.png
  10. Now mount USB Stick #2 by entering:
    # mount /dev/sdcx /tmp
    (make sure to select the correct sdcx for the USB Stick #2)
  11. Then run the script by enter the following commands:
    # cp -r /tmp/* ~/
    # cd ~/src/
    # chmod +x *
    # ./go.sh
  12. After the script runs to completion, remove the USB sticks.
  13. Then reboot the GEM by entering
    # reboot now
  14. The first time you boot the GEM, the login screen will appear as shown in this diagram.Screen_Shot_2022-09-06_at_3.32.58_PM.png
  15. Enter the user name "root"
  16. The password is "GoM*****!" (please contact us through support@kobiton.com to retrieve the full password.

Remotely setup deviceConnect™ - with or without GEM

By following these steps, you can install deviceConnect™ on multiple target machines at a time. Please perform these steps on the Local Machine

Step 1:

  • Download the latest automated deviceConnect™ installation package at this link: LINK
  • Download and unzip this file copy-ssh-key.zip.
  • Download Xcode 13.2.1 from here. The full list of Xcode Releases can be found here . Apple’s official link for the current version is here.
  • Download Java JDK here. The full version history from Oracle is here.
  • Download the deviceConnect installer from here
  • Prepare iOS cert files i.e. file extension .p12 and provisioning profile files. If you are not sure how to prepare those file, refer to our guide here: https://support.kobiton.com/hc/en-us/articles/9040671706765-Setup-provisioning-profile-and-certificate-files-for-iOS-devices

Step 2:

  • Unzip the automated deviceConnect™ installation package
  • Put the following files into the unzipped automated deviceConnect™ installation package folder:
    • .p12 files
    • One (or many) provisioning profiles .mobileprovision files are required for iOS devices. deviceConnect™ requires those files in order to build the agent app that can remotely control iOS devices. Those files can be generated under your Apple developer account. Make sure the profiles include all of your hosted iOS devices' UDIDs, and the certs files (*.p12) have no password.
    • deviceConnect™ installer file (filename like deviceConnect-...<git commit id>.pkg).
    • XCode installer file with.xip extension
    • Java JDK installer file with .pkg extension

Step 3: Copy your SSH public key from your Local Machine to the multiple Target Machines i.e. Mac Mini for deviceConnect

  • If you haven’t ever generated SSH key on your local machine, run this command in the local machine terminal:
    ssh-keygen -t rsa
  • Unzip the downloaded filecopy-ssh-key.zip
  • Then, within the unzipped folder is the file remote_mac-ip.txt. Input the information of target machines in the form of deviceconnect@<IP address>: e.g, deviceconnect@, where: deviceconnect is the username to login into the target machine and is the IP address of the target machine.
    • If you are installing deviceConnect™ for multiple target machines, input multiple deviceconnect@<IP address> and save the file (Cmd + S), for example:Screen_Shot_2022-09-06_at_3.34.58_PM.png
    • Within the unzipped folder, you can also find copy-ssh-key.sh. Open Terminal, change directory into the unzipped folder and run copy-ssh-key.shScreen_Shot_2022-09-06_at_3.36.15_PM.png

Step 4:

  • Input the information of the target machines into the file machines_info_samples.csv, located within the data folder, inside the automated deviceConnect installation package folder. (Note: each row in the .csv file contains information of one machine that we intend to install deviceConnect™ on. To install deviceConnect™ for multiple machines, input for multiple rows):
    • Username@<IP Address>:
      • Input deviceconnect@<IP Address> similar to the ones you input in step 3.
    • SSH Private file path: 
      • SSH file path to let the target machine (that will be installed the deviceConnect™) allow the commands from your local machine.
        • In step 3: If you choose the default location, your private key will be located in /Users/username/.ssh/id_rsa (username will be replaced by the username of the local machine).
    • GEM IP:
      • If the deviceConnect™ Mac mini will be connected to the GEM, input the IP address of the GEM. Otherwise, leave it blank. This is an example configuration:Screen_Shot_2022-09-06_at_3.39.26_PM.png

Step 5:

  • Open the Terminal (on the local machine) AND navigate to the unzipped automated deviceConnect™ installation package folder in step 1 (that contains automated deviceConnect™ installation package, p.12, .mobileprovision , deviceConnect™ installer - .pkg, machine info file - machines_info_samples.csv) (by using the cd command: e.g, cd Dowloads/latest-kobiton-installer-main/deviceConnect).
  • Input for each parameter in the script below AND run it on the terminal (there shouldn’t be spaces among below command lines):
./setup.sh \
   --dc-file ./assets/deviceConnect™-9.0.10518+0630.master.0d14a75.pkg \
   --java-sdk-installer-file ./assets/JDK-8-Update-301.pkg \
   --xcode-file ./assets/Xcode_14.2.1.xip \
   --kobiton-user-username kobitonusernam \
   --kobiton-user-api-key ***** \
   --kobiton-env-file ./scripts/kobiton-env/test \
   --data-file ./data/machines_info.csv \
    --ios-certs-folder ./assets
  • The input of each parameter:
    • dc-file: location of the deviceConnect™ installer.
    • java-sdk-installer-file (optional):
      • Location of java sdk installer file.
      • By default, the script still checks the compatibility between the current Java sdk version in the Mac machine and deviceConnect™. If the parameter is valid, the Mac machine will be updated with the Java sdk version in the parameter.
    • xcode-file (optional):
      • Location of xcode file.
      • By default, the script still checks the compatibility between the current xcode version in the Mac machine and deviceConnect™. If the parameter is valid, the Mac machine will be updated xcode version.
    • kobiton-user-username: username to login to the Kobiton.
    • kobiton-user-api-key: authentication information of the Portal environment (can be retrieved in Kobiton).
    • kobiton-env-file (optional):
      • Production environment: ./scripts/kobiton-env/production (by default, if you remove this row -> the installation will be on production environment).
    • data-file: location of the machine’s info file.
    • ios-certs-folder: location of the p.12 and provisioning file (best practice is keep these 2 files in the same folder). 

Step 6: Wait for and observe the result

  • If the installation has been run successfully: you will see INFO OK at the end of the terminal.
  • Example of a successful run:Screen_Shot_2022-09-06_at_3.44.05_PM.png

Connect deviceConnect™ with GEM machine

Note: Have a deviceConnect™ server which you want to connect to GEM. You will be required to perform a number of configuration steps on the deviceConnect™ server, as indicated below.

  •  Steps which must be performed on the deviceConnect™ server are prefixed "deviceConnect Server:
  •  Steps which must be performed on the GEM server are prefixed "GEM Server:" 
  1. deviceConnect Server: From deviceConnect™ Terminal, restart the services:
    # sudo sv restart /usr/local/var/service/*
  2. deviceConnect Server: From deviceConnect™ Terminal, generate an ssh key and leave passphrase blank:
    Restart the service:
    # sudo -i ssh-keygen
    Generate an ssh key and leave passphrase blank:
    # sudo -i ssh-keygen
  3. deviceConnect Server: From deviceConnect Terminal, preview the content of the generated key:
    # sudo cat /var/root/.ssh/id_rsa.pub
  4. GEM Server: Create log, configuration and data directories:
    # mkdir -p /ml/var/log /ml/var/gigacap /ml/var/config/ssh
  5. GEM Server: Create a self-signed SSL certificate for WebRTC streaming:
    # cd /ml/var/gigacap
    # openssl req -x509 -newkey rsa:4096 -keyout cert.key -out cert.pem -days 10950 -nodes -subj "/C=US/ST=Georgia/O=Mobile Labs LLC/"
  6. GEM Server: Create GEM options file, /ml/var/config/gigacap-options, which contains command line arguments for the GEM, as follows:
    --var-path /ml/var/gigacap
    --debug true
    --log-path /ml/var/log
    --cert-file /ml/var/gigacap/cert.pem
    --key-file /ml/var/gigacap/cert.key
    --public-address <ipaddress>
    Where <IP address> is the public IP address of the GEM.

  7. GEM Server: Create GEM pre-start hook script, /ml/var/config/gigacap-pre-start-hook, which is used to run additional commands before starting the GEM server, with the following content:
    #!/usr/bin/env bash
    Export LD_LIBRARY_PATH=/run/opengl-driver/lib:$LD_LIBRARY_PATH
    mkdir -p /ml/var/gigacap
    mkdir -p /root/.ssh
    chmod 0600 /root/.ssh
    echo "<SSH PUBLIC KEY FROM DC SERVER>" > /root/.ssh/authorized_keys
    cp /ml/var/config/ssh/*key* /etc/ssh/
    Where <SSH PUBLIC KEY FROM DC SERVER> is the value returned from Step 7.

  8. GEM Server: Make the pre-start hook script executable:
    # chmod +x /ml/var/config/gigacap-pre-start-hook
  9. GEM Server: Restart the GEM:
    # systemctl restart gigacap
  10. GEM Server: After performing all of the above actions, check the connection from deviceConnect™ to GEM, from deviceConnect™ Terminal ssh into the GEM
    # sudo ssh root@<ipaddress>
    Where <ipaddress> is the IP address of the GEM.
  11. GEM Server: Your devices should all be offline.
    You will still see your USB hub (at Gigafox UI > System > Device Gateway) with all your devices and you will only see the GEM hub once there are devices added to the GEM. The devices must be plugged into the GEM, instead of the deviceConnect Mac machine. If the device is plugged into the deviceConnect machine instead of GEM, the device won't display on gigafox.
  12. deviceConnect Server: Go to Gigafox Web UI (localhost on Mac mini) and login.
  13. deviceConnect Server: From the System -> Restart Services buttonScreen_Shot_2022-09-06_at_4.18.51_PM.png
  14. deviceConnect Server: generate an SSH key pair to be used to access the gigacap server:
    sudo -i ssh-keygen
  15. GEM Server: Create log, configuration and data directories
    mkdir -p /ml/var/log /ml/var/gigacap /ml/var/config/ssh
  16. GEM Server: Create an SSL certificate for WebRTC streaming (should be self signed)
    cd /ml/var/gigacap
    openssl req -x509 -newkey rsa:4096 -keyout cert.key -out cert.pem -days 10950 -nodes -subj "/C=US/ST=Georgia/O=Mobile Labs LLC/"
  17. GEM Server: Create gigacap options file, which contains command line arguments for Gigacap server:
    1. vim /ml/var/config/gigacap-options

      Add the following content (substituting in the actual public IP of your server, or its IP which is visible to users if it's not public):


      --var-path /ml/var/gigacap
      --debug true
      --log-path /ml/var/log
      --cert-file /ml/var/gigacap/cert.pem
      --key-file /ml/var/gigacap/cert.key
      --public-address <IP Address>

    Note: You can use ifconfig to determine the <IP Address>. By default, when you plug-in port 1 on GEM, the interface is eno1np0.

  18. GEM Server: Copy the SSH host key.
    cp /etc/ssh/*key* /ml/var/config/ssh
  19. GEM Server: Create Gigacap pre-start-hook script, which is used to run additional commands before starting Gigacap.
    vim /ml/var/config/gigacap-pre-start-hook
    #!/usr/bin/env bash
    export LD_LIBRARY_PATH=/run/opengl-driver/lib:$LD_LIBRARY_PATH
    mkdir -p /ml/var/gigacap
    mkdir -p /root/.ssh
    chmod 0600 /root/.ssh
    echo "<SSH PUBLIC KEY FROM DC SERVER>" > /root/.ssh/authorized_keys
    cp /ml/var/config/ssh/*key* /etc/ssh
  20. deviceConnect Server: enter:
    sudo cat /var/root/.ssh/id_rsa.pub
    and copy ssh key into clipboard

  21. GEM Server: replace it to <SSH PUBLIC KEY FROM DC SERVER>
    run chmod +x /ml/var/config/gigacap-pre-start-hook

  22. On GEM server,  run: systemctl restart gigacap

  23. On deviceConnect™ server, run: sudo sv status /usr/local/var/service/* 
    Verify that you are able to access the Gigacap server from the root account. Note that this must be done manually once to establish trust of the host key for the server.
    sudo su
    cd /var/root/.ssh
    ssh -i id_rsa root@<Gigacap server IP>
  24. When you can log in GEM without a password. type exit to log out GEM server and edit with this command.
    1. Edit vi /usr/local/deviceConnect™/dc.ini
    2. Under [set] section, add the following to enable Gigacap
    3. Stop local services. Do this with sudo sv stop /usr/local/var/service/*
  25. On deviceConnect™ server, edit 
    vi /usr/local/deviceConnect™/dc-services.conf
    Place the following contents into the file, filling in foregoing values accordingly.


  26. Update deviceConnect™_REDIRECT_HOST to the user@ip of your gigacap server (e.g. root@
  27. Restart local services, run: sudo sv start /usr/local/var/service/*

Checklist for deviceConnect™’s post-installation

  1. Count devices on Gigafox portal
  2. Check deviceConnect™ build:
  • Make sure the build in Gigafox portal is the same as the latest release build package. Please contact our support at support@kobiton.com to know about the latest release build package.
  • Make sure all configs in dc.ini file are correct (correct environment, port, host ID): sample file is below

# When adding or changing configuration, a # prefixed comment must be included

# prior to the configuration key. Explain why the key is being set and included

# a ML-### or ZD### for reference.


ConnectionString=Server=;Database=deviceConnect™_app;User Id=deviceConnect™_app;MaxPoolSize=100;Password=pass-56ffc8c3cd680bf96ba600943f149b92

# The IP which is reachable from AWS EC2 servers

PublicHubAddress=<your server IP address>




# don't turn this on, it'll be disabled by default eventually


# Enable cleanup policies


# required for streaming video



# Image Injection





# The Service ID on Consul for this deviceConnect™ instance

Kobiton.ServerId=device-connect-<your server IP address>

# DeviceAdmin gRPC service address (same server with Master Hub component)

Kobiton.DeviceAdminHost=hub.kobiton.<replace with 1 env: test/staging/prod>


# General gRPC service address (the AWS Internal Load Balancer which proxy to API instances)

Kobiton.GeneralHost=proxy-api-grpc.kobiton.<replace with 1 env: test/staging/prod>


# The Kobiton User ID who hosts plugged devices

Kobiton.TenantUserId=<userID of host>

  1. Count deviceConnect™ devices on Kobiton Portal on device listScreen_Shot_2022-09-06_at_4.40.16_PM.pngScreen_Shot_2022-09-06_at_4.40.40_PM.png
  2. Check and count the deviceConnect™ server on Device ManagementScreen_Shot_2022-09-06_at_4.41.05_PM.png
  3. Check GEM build:
  • Open a terminal
  • Execute this command: ssh root@<GEM IP>
  • Observe the GEM build and compare with the latest GEM build version. Please contact our support at support@kobiton.com to know about the latest GEM build version.Screen_Shot_2022-09-06_at_4.41.34_PM.png
  1. Ensure Kobiton Apple ID / Samsung account is signed-in on the mobile devices (smartphones, tablet).


Was this article helpful?
0 out of 0 found this helpful