Objective

The objective of this article is to demonstrate how to use the mimik Client Library interfaces when working with the mim OE Runtime in an iOS project.

Intended Readers

The intended readers of this document are iOS software developers, who want to familiarize themselves with the basics of the mimik Client Library interface, specifically methods for interfacing with the mim OE Runtime.

What You'll Be Doing

In this tutorial you'll be covering the following topics of working with the mim OE Runtime:

• Starting
• Stopping
• Creating an Access Token
• Retrieving Runtime Information
• Resetting
• Lifecycle Management
• Working with an iOS Simulator

Prerequisites

• Connecting a real iOS device to the development computer and selecting it as the target in Xcode. This tutorial will not work with an iOS Simulator.

• A familiarity of working with mimik Client Library components as described in this Key Concepts article.

• An understanding of the mimik Client Library components integration and initialization process as layed out in this article.

Starting mim OE Runtime

Once the mimik Client Library components have been integrated, initialized and imported into your project, you can get into the specifics of working with the mim OE Runtime.

You can think of mim OE as a host platform where edge microservices are deployed to. Also, mim OE provides http interfaces to the iOS application in order to do various tasks.

One prerequisite for being able to deploy the edge microservices is that the mim OE is in a running state. The code example below in Listing 1 shows you how to do this. An explanation of the code follows.

1: func start() async -> Result<Void, NSError> {
2:     // Developer mim OE license from mimik developer console at https://console.mimik.com
3:     let license = <DEVELOPER_MIMOE_LICENSE>
4: 
5:     // License parameter is the only parameter required for mim OE Runtime startup. There are other optional parameters also available.
6:     let startupParameters = EdgeClient.StartupParameters(license: license)
7: 
8:     // Using the mimik Client Library to start the mim OE Runtime
9:     switch await self.edgeClient.startEdgeEngine(parameters: startupParameters) {
10:     case .success:
11:         print("Success starting mim OE")
12:         // Returning a success for mim OE startup
13:         return .success(())
14:     case .failure(let error):
15:         print("Error starting mim OE", error.localizedDescription)
16:         // Returning a failure for mim OE startup
17:         return .failure(error)
18:     }
19: }

Listing 1: Starting mim OE

First, we get our developer mim OE (Edge) license from mimik Developer Console and set the value.

Next, we set the mim OE Runtime configuration object using the mim OE license. There are additional startup parameters available, but for the purpose of this article, only the license parameter will be used.

Then, we call the start method on the mimik Client Library, where we will pass our license parameter.

WHERE

parametersis the configuration object where we set our mim OE license

After the call, we validate the mim OE startup result. Returning either a success or a failure.

Stopping mim OE Runtime

Sometimes developers want to shut down the mim OE Runtime manually. For example, when opting-out from the automatic lifecycle management, or when the user wants to clear out all of their data after a logout. The code example below shows you how to do this.

We call the stop method on the mimik Client Library and that's it. There are no values returned, nor there is a need to do any validation. Once the client library method returns, mim OE Runtime will be stopped, with its storage erased.

1: func stopMimOE() {
2:     // Calling mimik Client Library method to stop mim OE synchronously.
3:     self.edgeClient.stopEdgeEngine()
4: }

Creating an Access Token

Most of the mim OE Runtime interface calls require an Access Token for their operations. The Access Token is based on the Developer ID Token generated at the mimik Developer Console. The code example below in Listing 2 shows you how to do this.

1: func authenticate() async -> Result<String, NSError> {
2:     // Using developer ID Token from mimik Developer Console
3:     let developerIdToken = <DEVELOPER_ID_TOKEN>
4:     
5:     // Calling mimik Client Library to generate the mim OE Access Token. Passing-in the Developer ID Token as the only parameter.
6:     switch await self.edgeClient.authorizeDeveloper(developerIdToken: developerIdToken) {
7:     case .success(let authorization):
8:         
9:         guard let accessToken = authorization.token?.accessToken else {
10:             // Authentication unsuccessful, returning a failure
11:             return .failure(NSError.init(domain: "Error", code: 500))
12:         }
13:         
14:         print("Success. Access Token:", accessToken)
15:         // We have the Access Token, return a success with the Access Token
16:         return .success(accessToken)
17:     case .failure(let error):
18:         print("Error", error.localizedDescription)
19:         /// We don't have the Access Token, returning a failure.
20:         return .failure(error)
21:     }
22: }

Listing 2: Authenticating for mim OE access

First, we get our Developer ID Token from mimik Developer Console and set the value.

Next, we call the authorization method of the mimik Client Library, which requires the developerIdToken parameter.

WHERE developerIdToken is the developer ID Token we set above.

After the call is made, we attempt to get the Access Token value from the authorization's token and return a success or a failure, depending on the result.

Retrieving Runtime Information

Sometimes developers need to find out more details about the mim OE Runtime system information, such as its version, account or node information. The code example in Listing 3 below shows you how to do this. An explanation follows.

1: func info() async -> Result<Any, NSError> {
2:     // Calling mimik Client Library method to get the mim OE Runtime information
3:     switch await self.edgeClient.edgeEngineInfo() {
4:     case .success(let info):
5:         print("Success", info)
6:         // Call successful, returning a success with the mim OE Runtime information JSON
7:         return .success(info)
8:     case .failure(let error):
9:         // Call unsuccessful, returning a failure
10:         print("Error", error.localizedDescription)
11:         return .failure(error)
12:     }
13: }

Listing 3: Getting information about mim OE Runtime

First, we call the info method of the mimik Client Library.

Then we validate and print the result if successful or return a failure.

The JSON information returned in the info object is similar to the following:

 {
   "supernodeTypeName" : "_mk-v15-4247._tcp",
   "nodeId" : "1234567890",
   "accountId" : "1234567890",
   "version" : "vX.Y.Z",
   "linkLocalIp" : "192.168.1.47"
 }

Resetting mim OE Runtime

When it comes to clearing out user data, developers might want to shut down the mim OE Runtime and erase all content stored in its working directory. The code example in Listing 4 below shows you how to do this with one call. An explanation follows.

1: func reset() async -> Result<Void, NSError> {
2:     // Calling mimik Client Library method to shut down and erase mim OE storage
3:     switch self.edgeClient.resetEdgeEngine() {
4:     case .success:
5:         print("Success")
6:         // Reset successful, returning a success
7:         return .success(())
8:     case .failure(let error):
9:         print("Error", error.localizedDescription)
10:         // Reset unsuccessful, returning a failure
11:         return .failure(error)
12:     }
13: }

Listing 4: Resetting mim OE

First, we call the reset method on the mimik Client Library.

Then we validate, returning a success or a failure, depending on the result.

Lifecycle Management

When developers initialize the mimik Client Library, they opt-in to an automatic mim OE Runtime Lifecycle management by default. This means that the mimik Client Library will be monitoring the application's lifecycle notifications, and reacting to any significant changes that affect mim OE's ability to perform its functions.

When the background system notification is received, mim OE stop is called automatically.

When the foreground system notification is received, mim OE start is called automatically as well.

Developers can opt-out of this automatic lifecycle management during the mimik Client Library initialization by setting the manage method manage parameter to false; for example, when they prefer to start and stop the mim OE Runtime manually.

The code example below shows you how to activate the automatic mim OE Runtime Lifecycle management:

 switch EdgeClient.manageEdgeEngineLifecycle(manage: true) {
 case .success():
     print("Success")
     // Lifecycle management activation successful
 case .failure(let error):
     print("Error", error.localizedDescription)
     // Lifecycle management activation unsuccessful
 }

This code example shows you how to deactivate the automatic edgeEngine Runtime Lifecycle management:

 switch EdgeClient.manageEdgeEngineLifecycle(manage: false) {
 case .success():
     print("Success")
     // Lifecycle management deactivation successful
 case .failure(let error):
     print("Error", error.localizedDescription)
     // Lifecycle management deactivation unsuccessful
 }

Finally, the following code example code shows you how to determine whether the current lifecycle management activation state:

 func lLifecycleIsManaged() -> Bool {
     // Calling mimik Client Library class method to determine the lifecycle management state
     switch self.edgeClient.edgeEngineLifecycleIsManaged() {
     case true:
         print("Lifecycle is Managed")
         // mim OE Runtime lifecycle is being managed by the mimik Client Library
         return true
     case false:
         print("Lifecycle is not managed")
         // mim OE Runtime lifecycle is NOT being managed by the mimik Client Library
         return false
     }
 }

Working with an iOS Simulator

Normally, developers intend to run their applications on iOS devices where the mimik Client Library is used to facilitate the integration of the mim OE Runtime binary directly within the iOS application sandbox. This is done by vendoring the mim OE binary inside the mimOE-SE-iOS-developer (or mimOE-SE-iOS) cocoapod.

The inclusion of mimOE-SE-iOS-developer cocoapod in the iOS project affects the ability to compile the project for the iOS Simulator or Mac Catalyst environments. This is because the mim OE binary is compiled specifically for iOS devices (and not the simulated environments that run on a different processor architecture).

In order to provide a functional workaround, the mimik Client Library is split into EdgeCore and mimOE-SE-iOS-developer cocoapods. This gives developers the choice of having the mim OE binary bundled within the iOS application or having it run externally on a host platform of their choice (e.g., macOS, Linux, Windows, etc...)

So to summarize. When compiling the project for an iOS device, include the mimOE-SE-iOS-developer cocoapod in your project. This would run the mim OE Runtime binary internally, on the iOS device.

When compiling for an iOS Simulator or Mac Catalyst environments, only include the EdgeCore cocoapod in your project. Then, host the mim OE Runtime on an external platform of your choice and activate the external mim OE support in the mimik Client Library.

The code example below shows you how to conditionally include (or not) the mimOE-SE-iOS-developer cocoapod, using two different targets.

 target 'internal-mimOE-target' do
   pod 'EdgeCore'
   pod 'mimOE-SE-iOS-developer'
 end
 
 target 'external-mimOE-target' do
   pod 'EdgeCore'
 end

The code example below shows you how to conditionally import EdgeEngine (mim OE) into your class using the EXTERNAL compiler flag.

 import EdgeCore
 #if !EXTERNAL
 import EdgeEngine
 #endif

Next, let's assume we want to have mim OE running externally, for example on a macOS host, with a 192.168.4.47 IP address and 8083 port number.

Once mim OE is running externally on a macOS host, we can activate the external mim OE support in the mimik Client Library, by calling the external support activation method.

The code example below shows you how to do this.

 func activateExternalSupport() -> Result<URLComponents, NSError> {
     // Calling mimik Client Library class method to activate the external mim OE support
     switch EdgeClient.activateExternalEdgeEngine(host: "192.168.4.47", port: 8083) {
     case .success(let urlComponents):
         print("Success", urlComponents)
         // External mim OE activation successful, returning a success
         return .success(urlComponents)
     case .failure(let error):
         print("Error", error.localizedDescription)
         // External mim OE activation unsuccessful, returning a failure
         return .failure(error)
     }
 }

You can then continue using the application and mimik Client Library normally, keeping in mind that with the mim OE Runtime running externally, the iOS application environment wouldn't have the ability to control its lifecycle directly.

Additional reading

In order to get more out of this article, the reader could further familiarize themselves with the following concepts and techniques:

• Understanding the mimik Client Library for iOS.
• Creating a Simple iOS Application that Uses an edge microservice.
• Integrating the mimik Client Library into an iOS project.
• Working with edge microservices in an iOS project.
• Working with AI language models in an iOS project.