Functionalities

The main features of the MX Connect application are:

• Display basic information about the connected MX Mobile Terminal, for example MX-1502.
• Receive and display the configuration from the MDM server, for example JAMF.
• Perform necessary updates according to configuration received from the MDM server.
• Lock the application via Single App Mode during updates and display update status (active / inactive).
• Log and display events sorted by date.

Updating Process

In the UPDATES section of the main screen the app shows the configured firmware and MX configuration. If these configurations are installed properly, a checkmark is displayed in the rows, respectively. Although the configuration XML sent by the MDM contains URLs, MX Connect only displays the last component of these URLs. Use file names in the URLs that reflect the version of their content.

Browsing the Log

Check the log to review the history of the attached MX mobile terminal. You can check what configuration the app received, and if the updating processes were successful.

Tap the row in the history list and check the disclosed page for more detailed information on a particular event.

Terminology and Definitions

The following terms are used throughout this document:

• MX Mobile Terminal: The MX barcode reader device, for example, MX-1502.
• iOS device: iPhone or iPod Touch built into an MX Mobile Terminal.
• Firmware: The firmware of the MX Mobile Terminal.
• MX configuration: The configuration of the MX Mobile Terminal.
• App Configuration XML: An XML formatted text containing the URLs of the update files.
• MDM: Mobile Device Management referring to an MDM solution, for example, Jamf.

Preparation Steps

1. Configure Apple Push Notification Service on your MDM

   Follow the instructions to enable your MDM to communicate with mobile phones via Apple's Push Notification Service.

   • JAMF
   • SOTI
   • MobileIron
   • WorkSpace ONE

   Push Certificates

   Enable the required URLs during enrollment. 

   Apple Configurator Enrollment Settings

   

   

   Using the Apple Push Notification Service

   

   

2. Make your iOS device supervised

   Make your iOS device supervised by using the Apple Configurator desktop application on a Mac or by using Apple's DEP program. This is a precondition so that MDM can have more control over the mobile phone (e.g. launch and application in single app mode which is required for MX Connect updating workflow).

3. Enroll the mobile phone to the MDM.

   • JAMF
   • SOTI
   • MobileIron
   •  
   • Workspace ONE

   User-Initiated Enrollment for Mobile Devices

   You can combine supervising and enrolling by using a supervising identity.

   Supervision Identities

   For more information about device enrollment, refer to Enrollment of Mobile Devices.

   Adding iOS Devices

   You can use the enrollment URL of your "Add Devices" rule.

   

   There are multiple ways to enroll a device in MobileIron. You can read two examples below (for more options please check MobileIron's User's manual).

   • Enrolling via invitation:

   

   

    

   • Enrolling via Apple Business Manager:

   

   There are multiple ways to enroll a device in Worspace ONE. Check the following description:

   iOS Device Enrollment Overview

4. Install MX Connect app with your MDM system from the App Store.

   • JAMF
   • SOTI
   • MobileIron
   •  
   • Workspace ONE

   Add MX Connect to JAMF by an App Store URL.

   

   Set the distribution method to "Install Automatically" to let JAMF deploy it without user interaction.

   

   To learn more about app distribution in JAMF, read the App Distribution document. 

   To install MX Connect app first you have to create an Application Catalog Rule.

   

   In the app catalog rule you have to add MX Connect app by any of the possible options. Most likely you will select the App Store Applications option.

   

   To force installing to devices set the Application Type field to Mandatory.

   

   To install MX Connect application via MobileIron first you have to add it on the MDM admin site.

   

   Click Add button.

   

   Navigate to publicly available native apps and select "Add application":

   

   Fill out the form properly:

   

   Select MX Connect published by Cognex Corporation:

   

   Save and assign to user group where MX mobile terminals are used. Set all other assignment properties according to your need and finally publish your changes.

    

5. Create a Single App Mode Configuration Profile for MX Connect.

   Launch the application by putting it to Single App Mode (SAM). To let your MDM put the application to SAM, create a configuration profile in your MDM that is sent out to devices in the right time. If a device receives a Single-App-Mode configuration profile for MX Connect app, the iOS device launches the app and keeps it on screen until the MDM system revokes the configuration profile.

   • JAMF
   • SOTI
   • MobileIron
   •  
   • Workspace ONE

   You can create a Single-App-Mode configuration profile at Mobile Devices or Configuration Profiles.

   

   You can create a Single-App-Mode configuration profile at Profiles / Add.

   

   You can create a Single-App-Mode configuration profile at Configurations.

   

   Create a new configuration and select the Single App Mode type.

   

   To associate the MX Connect app configure the restriction by selection your hosted MX Connect app.

   

   Please note that this is only a preparation step so please leave "Enable this configuration" option unchecked:

   

   Select "Add profile" for devices from the drop-down list:

   

   Select  for Platform and  for Context.

   Fill out General tab according to your needs (use Manual for Deployment) but leave Smart Group assignment empty for now. Select Single App Mode tab and enter the following data and then Publish it:

   

    

6. Create an Autonomous Single App Mode Configuration Profile for MX Connect.

   Autonomous Single App Mode (ASAM) is a very similar functionality to Single-App-Mode. ASAM lets the MX Connect app to lock to the iOS device's screen and unlock when it is no longer needed. 

   Note that while the user of the MDM system manually issues and revokes Single-App-Mode, the Autonomous Single App Mode is activated and deactivated by MX Connect app.

   MX Connect needs this to autonomously lock to the screen during downloading and installing update files to prevent the phone's user to navigate away during installation.
   To let MX Connect use ASAM, create a configuration profile with MX Connect app's bundle ID, com.cognex.MXConnect, in your MDM and issue it to all your iOS devices.

   Sending out ASAM configuration profile for MX Connect does not put the app on the screen, it only gives permission to the app to do so. Issuing an ASAM configuration profile has to be done only once for an iOS device and it must not be revoked.
   • JAMF
   • SOTI
   • MobileIron
   •  
   • Workspace ONE

   Select Restrictions to create an Autonomous Single App Mode configuration profile.

   

   Select the Applications tab and MX Connect's bundle ID: com.cognex.MXConnect

   

   Select Restrictions to create an Autonomous Single App Mode configuration profile.

   

   

   Select the Applications tab and add MX Connect's bundle ID (com.cognex.MXConnect) to the list.

   

   To create an iOS restriction for ASAM mode for MX Connect app you have to select "iOS restriction" at type selection.

   

   In the configuration section you have to add MX Connect to the appropriate field.

   

   To send ASAM configuration to a particular device click on Push button on the device's Configuration tab.

   

   This option is not available on Workspace ONE for apps available in App Store.

    

   What does it mean?

   MX Connect cannot keep up single application mode during firmware upgrade roll-out if Single App Mode was turned off/deactivated too early (e.g. the update was still ongoing).

    

   How can I avoid issues?

   Inform your users not to navigate away from MX Connect if an upgrade operations has been started.

    

   How shall I use Single App Mode?

   You have to make sure that you do not disable Single App Mode until the installation of the firmware is finished on the MX mobile terminals. We would suggest to communicate a slot to your users when you plan to upgrade firmware on MX mobile terminals. 15 minutes slot should be enough to do the firmware upgrade but this may vary according to your network speed.

    

   What happens if I disable Single App Mode when the upgrade process has not been finished?

   If the user does not navigate away from MX Connect during the update process, then the operation will be finished and firmware/configuration file is rolled out to mx mobile terminal.

   I the user navigates away (as MX Connect is not in single app mode user is not prevented to do this) then Firmware upgrade and configuration update may be interrupted and not processed until you start Single App Mode again.

7. Prepare a server to access firmware and configuration update files by URL.

   During a firmware or configuration update MDM sends only the URLs of the update files to the MX Connect app, which downloads the update files using these URLs. Make sure that your update files are accessible by a URL, and set up a server to accomplish this requirement, if necessary. You can use Cognex' firmware storage to distribute upgrades. For more detail, refer to the FAQ

Update Firmware and Configuration on MX Mobile Terminal

1. Install MX Connect app (with your MDM system) on mobile devices.

   If the MX Connect app is already installed on all iOS devices managed, skip this step (otherwise check Preparation step 4).

   • JAMF
   • SOTI
   • MobileIron
   • Workspace ONE

   Once you have added MX Connect to your JAMF instance, apply two settings to automatically install to you device.

   App install is automatic:

   

   Add your iOS device to the app's scope:

   

   Once you have added MX Connect to your SOTI instance, apply two settings to automatically install to you device.

   Installing the app is automatic:

   

   Add your iOS device to the app's scope:

   

   To install MX Connect app on your device(s) you have to configure its Distribution settings in App Catalog.

   

   To install MX Connect app on your device(s) you have to configure its Assignment settings.

   

2. Launch MX Connect. To launch MX Connect, send a Single App Mode configuration profile to the iOS devices.

   Revoke this profile manually to let the user of the iOS device switch to another application. Make sure to revoke SAM configuration profile, otherwise the company's daily workflow will be blocked because the designated application is not able to use the MX devices.
   • JAMF
   • SOTI
   • MobileIron
   • Workspace ONE

   To launch MX Connect, put it to Single-App-Mode by adding your device to the SAM configuration profile's scope.

   

   To launch MX Connect, put your device to Single-App-Mode by adding it to the SAM configuration profile's scope.

   

   You have prepared a Single App Mode configuration. Edit this configuration and enable it by checking the appropriate option.

   

   Please note that you have to uncheck this option after the installation process to terminate the Single App Mode.

   Open the profile (that was created at Preparation step 5) and assign it to mobile phones (use smart group) where the MX terminal update is necessary.

   

   If you revoke the Single App Mode configuration during an upgrade process, the app keeps the SAM until the installation is done. Exception is Workspace ONE as there is no Autonomous single app mode configuration for App store apps 

3. Send updates to the MX mobile terminal.

   To send firmware or MX configuration updates, compose an XML text containing the URLs of the update files. The XML has to be provided to your MDM, which sends it to each MX Connect instance. MX Connect starts the update process upon receiving the XML configuration.

   The XML composed is not a command but a configuration. The XML resides at MX Connect until the next XML configuration overwrites it. MX Connect will try to install the firmware and configuration using the defined URLs each time when the application starts. Firmware update is performed once and MX Connect checks whether the installed firmware matches with the firmware available on the MX mobile terminal. MX configuration update is performed multiple times when the application is opened, which takes only a few seconds.

   • JAMF
   • SOTI
   • MobileIron
   • Workspace ONE

   To send new updates to MX Connect, edit the App Configuration text at MX Connect's page. Use the proper form of the XML to perform a successful update.

   

   To send new updates to MX Connect, edit the App Configuration text at MX Connect app's "Application Catalog Rule". Use the proper form of the XML to perform a successful update.

   

   

   To create and send a Managed App Config go to MX Connect app's App Configuration tab and select iOS Managed App Configuration section.

   

   Click on Add button and create a new configuration as indicated below.

   

   Open Application settings for MX Connect app and select Assign.

   

   Select the actual MX Connect assignment and edit Application configuration. Turn on Send configuration setting.

   

    

   Depending from MDM you have to enter an XML as configuration or you can add key-value pairs as a configuration or you can pick your preferred method. 

   • Use the following template to compose a configuration XML:

   			<dict>
   				<key>firmwareURL</key>
   				<string>https://myserver.com/firmwares/firmware_file_name</string>
   				<key>configurationURL</key>
   				<string>https://myserver.com/configs/config_file_name</string>
   			</dict>

   • Define the following key value pairs:

   Key	Type	Value
   firmwareURL	string	https://myserver.com/firmwares/firmware_file_name
   configurationURL	string	https://myserver.com/firmwares/firmware_file_name

   Note that all key-string pairs are optional. MX Connect does not perform any update or check for a missing field, and does not restore any kind of default value for a missing field. If you configure both the firmwareURL and the configurationalURL with new values, MX Connect first installs the firmware rebooting the MX mobile terminal, then processes the configuration file.

4. Revoke Single App Mode from MX Connect to remove devices from SAM.

A company owning and operating many Cognex Mobile Terminals may want to remotely collect up-to-date information about battery level, battery health, installed firmware, etc. An iOS application using the cmbSDK framework can report status information of the attached Mobile Terminal to an MDM instance. Cognex mobile apps (MX Connect, Cognex Quick Setup...) can be also configured to report MX data.

Preparing your iOS application for reporting data about MX mobile terminal

Any iOS application is capable of reporting Mobile Terminal status information if it embeds and uses the cmbSDK framework.

1. Update cmbSDK framework in your app to use at least 2.4.0 version. 

2. Configure reporting for the app in your MDM.

Configuring the reporting functionality from MDM

Reporting is done by an iOS application towards an MDM instance. The app has to be managed by the MDM instance and can only report to that MDM instance. There are a few configuration options the MDM administrator has to properly set to let the reporting feature work for a certain application. These settings are done by creating a proper Managed App Configuration including key-value pairs as the configuration of reporting. Please refer to your MDM's administration guide to learn how to edit Managed App Configuration of a managed mobile app.

Mandatory configuration fields

As described above the MDM's administrator has to compose a Managed App Configuration to define settings of the reporting. This Managed App Configuration is sent to the mobile app by the MDM to let the app process it and behave accordingly. Please note that providing a proper Managed App Configuration is mandatory to enable the reporting. Without that the cmbSDK (in the app) won't start reporting.

The mandatory configuration fields are the following.

Authentication fields

For cmbSDK connecting to your MDM instance will most likely require authentication credentials. Beside the mandatory configuration fields you also have to provide these in the Managed App Configuration as indicated in the following table.

Please note that you have to provide a registered user's credentials that has the right to use the MDM's API for reporting. Refer to your MDM's administrator guide to learn more.

var authCredentials: MDMAuthCredentials = MDMAuthCredentials()
authCredentials.username = "usr"
authCredentials.password = "pwd"
authCredentials.clientID = "myClientID"
authCredentials.clientSecret = "myClientSecret"
self.dataManSystem.defaultMDMAuthCredentials = authCredentials
self.dataManSystem.MDMReportingEnabled = true // if you want to start reporting

MDMAuthCredentials *authCredentials = [MDMAuthCredentials new];
authCredentials.username = "usr";
authCredentials.password = "pwd";
authCredentials.clientID = "myClientID";
authCredentials.clientSecret = "myClientSecret";
self.dataManSystem.defaultMDMAuthCredentials = authCredentials;
self.dataManSystem.MDMReportingEnabled = true; // if you want to start reporting

Reported information

The following data of the attached Mobile Terminal is collected:

Custom attributes in MDM

The reported data fields appear as custom/extension attributes in MDM.

Jamf, SOTI, and Workspace ONE / Airwatch

These custom attributes are global attributes. These are assigned to all enrolled devices in case of Jamf and SOTI and are assigned only to the devices that have reported data in the case of Airwatch. By default the custom attributes are not present in an MDM instance, the properly configured mobile app creates the custom attributes automatically via the MDM's API and neither the app developer nor the MDM administrator has to take care of it.

MobileIron Cloud

Preparing custom/extension attributes to require two steps:

• First custom attributes have to be defined at Admin/System/Attributes. MDM admin has to add manually all relevant attributes that you want to check. Use the names from the table above but replace spaces with an underline (e.g.: MX_Pistol_Grip_Battery_Level)
• The second step is assigning these attributes to the device(s). This second step is automatically performed the apps that includes cmbSDK, you don't have to do it manually. So please be sure to first define the custom attributes before using cmbSDK for reporting.

Summary of all requirements

• It is possible to use your own app for reporting, but Cognex mobile apps can be also configured to send data to MDM.
• Your app has to use the cmbSDK framework (2.4.0 version or later) and has to be managed by your MDM.
• The app has to be in the foreground and has to connect to the attached Mobile Terminal via cmbSDK.
• If you are using multiple apps during your work and you want to make sure of the continuity in reporting, we suggest configuring both apps in MDM.
• The mobile phone has to have a proper network connection to reach your MDM instance.
• It is mandatory to have a proper Managed App Configuration sent to your app by your MDM to enable reporting.
• Authentication credentials have to be complete and valid for the usage of your MDM API.
• Do not modify or delete manually the created custom attributes on your MDM instance.
• In the case of MobileIron Cloud, you have to first define the custom attributes manually on the admin site.
• MX data reporting is available in Cognex apps from the following versions:
  • Cognex Quick Setup (available from version 2.4.2)
  • MX Browser (available from version 2.0.2)
  • MX Connect (available from version 1.0.2)
  • MX Keyboard (not available yet)