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
• Generating Access Token
• Retrieving Runtime Information
• Resetting
• Lifecycle Management
• Working with an iOS Simulator

Prerequisites

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

• Attaching a real iOS device to the development Mac and selecting it as the build target. This won't work with the iOS simulator.

Starting mim OE Runtime

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

Think of mim OE as a host platform for deploying edge microservices. It also provides HTTP interfaces that allow the iOS application to perform various tasks.

Before deploying edge microservices, it's important to ensure that mim OE is running. The code example in Listing 1 demonstrates how to do this, followed by an explanation of the code.

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-MIM-OE-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, passing the startup parameters object.

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

Stopping mim OE Runtime

Sometimes, developers may need to manually shut down the mim OE Runtime. This might be necessary, for example, when opting out of automatic lifecycle management, or when a user wants to clear all their data after logging out. The code example below demonstrates how to perform this action.

To stop the mim OE Runtime, simply call the stop method from the mimik Client Library. No return values are provided, and no additional validation is required. Once the method completes, the mim OE Runtime will be shut down and its storage will be cleared.

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

Creating an Access Token

Most mim OE Runtime interface calls require an Access Token to perform their operations. This Access Token is generated from the Developer ID Token created in the mimik Developer Console. The code example in Listing 2 below demonstrates how to obtain and use the token.

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 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: Generating Access Token

First, obtain your Developer ID Token from the mimik Developer Console and set its value.

Next, we call the authorization method on the mimik Client Library, passing the developerIdToken as a parameter.

After the call is made, we retrieve the Access Token from the authorization response. Based on the result, we return either a success or failure.

Retrieving Runtime Information

Sometimes, developers need to retrieve detailed information about the mim OE Runtime system, such as its version, account details, or node information. The code example in Listing 3 demonstrates how to do this, followed by an explanation.

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 on the mimik Client Library.

Next, we validate the result. If successful, we print the information; if not, we return a failure.

The info object returns a JSON structure 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 clearing user data, developers may need to shut down the mim OE Runtime and erase all content stored in its working directory. The code example in Listing 4 demonstrates how to do this in a single call, followed by an explanation.

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 automatically opt in to the mim OE Runtime lifecycle management. This means the mimik Client Library will monitor the application's lifecycle events and respond to significant changes that could impact mim OE's ability to perform its functions.

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

Conversely, when the foreground system notification is received, mim OE start is called automatically.

Developers can opt out of automatic lifecycle management during mimik Client Library initialization by setting the manage parameter of the manage method to false. This is useful 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 mim OE 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:

 // 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
 case false:
     print("Lifecycle is not managed")
     // mim OE Runtime lifecycle is NOT being managed by the mimik Client Library
 }

Mac computers with Apple silicon

With the transition from Intel to Apple Silicon architecture in Mac desktop computers, it is now possible to run most iOS applications natively on desktop Macs without requiring any changes. This includes the mim OE Runtime binary.

The ability to run iPhone and iPad apps natively on Apple Silicon Macs opens up a whole new set of users. Apple has done much of the heavy lifting to make this seamless, so developers only need to make minimal adjustments.

The good news is that Xcode provides excellent support for debugging, testing, and profiling iPhone and iPad apps natively on a Mac, just as if they were running in a simulator or on an actual iOS device.

For more details, check out Apple's documentation.

Working with an iOS Simulator

Normally, developers intend to run their applications on iOS devices, where the mimik Client Library facilitates the integration of the mim OE Runtime binary directly within the iOS application sandbox. This is achieved by vendoring the mim OE binary inside the mim-OE-ai-SE-iOS-developer CocoaPod.

However, including the mim-OE-ai-SE-iOS-developer CocoaPod in an iOS project can affect the ability to compile the project for the iOS Simulator or Mac Catalyst environments. This occurs because the mim OE binary is compiled specifically for iOS devices and is not compatible with the processor architectures used by Mac Catalyst and simulated environments.

To address this, the mimik Client Library is split into two separate CocoaPods: EdgeCore and mim-OE-ai-SE-iOS-developer. This allows developers to choose between bundling the mim OE binary within the iOS application or running it externally on a platform of their choice (e.g., macOS, Linux, Windows, etc.).

Summary of the approach:

• For iOS devices: Include the mim-OE-ai-SE-iOS-developer and EdgeCore CocoaPods in your project. This will run the mim OE Runtime binary directly on the iOS device.
• For iOS Simulator or Mac Catalyst environments: Include only the EdgeCore CocoaPod. Then, host the mim OE Runtime on an external platform of your choice, and activate external mim OE support in the mimik Client Library.

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

 target 'internal-mim-OE-target' do
   pod 'EdgeCore'
   pod 'mim-OE-ai-SE-iOS-developer'
 end
 
 target 'external-mim-OE-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.