tales from an old nibble
Zebra's EMDK Async Profile Manager APIs
Note: the accompanying code is available on github.
Summer is the perfect time for some cleanup, and I’ve some older content laying around my laptop that is about time I publish!
I’m planning to cover some long-standing argument that I’ve touched over the last few years as Zebra’s EMEA Software Consultant.
Years ago we had some posts on the EMDK discussion forum about some instability seen if an application tries to apply a profile just after device boot.
This blog wants to be an in deep discussion about what is going on in these cases and what is the best approach to adopt in these cases.
EMDK’s Profile Manager API
This was the first API introduced in the EMDK v2.0 back in 2014. A little-known fact is that Zebra introduced an Async version of this API to cover a couple of use cases:
- Complex profiles that can lock take few seconds to be applied by Mx locking the calling task
- Need to apply the profile immediately after booting the device
Fast forwarding to 2016, Zebra released EMDK v4.0 where we can find as a new feature the Async version of the
Added new method
getInstanceAsync()to EMDKManager. The EMDK Feature Manager object returned by this method is guaranteed to be usable immediately. The feature manager object returned by the existing method
getInstance(), may not be ready to be used immediately, especially after a device reboot.
This, together with the
ProcessProfileAsync() method allows building an application that process a profile asynchronously as soon as the Mx framework is available.
Setting the stage for the problem
As of today, the latest available Zebra’s EMDK for Android is v6.9 I’m going to use this version for this tutorial, together with AndroidStudio v3.1.3 on a Nougat TC56 with BSP 01.01.49 and LifeGuard patch 7.
The first step is to create a working application using the Synchronous version of the Profile Manager API to apply a simple profile, in this case, we can use the Clock profile, with this sample EMDKConfig.xml:
You can find the demo at this stage of the github project looking for the
This version of the application works as expected, you launch it, and it changes the date and time of the device.
If you run this application just after the device finish to boot you can get some strange errors:
Because the error is time-dependent you can be lucky and see a message that provides a bit more insight into what is going on here:
That’s exactly the point, the Mx framework is not immediately ready after boot!
Enter the Async version of the APIs
As we wrote, there’s a version of these API that works asynchronously providing two huge benefits:
- The profile is processed on a different thread than the main (UI) thread. This avoid to freeze the app UI
- It is executed as soon as the Mx framework is available
The first benefit can be achieved even with the synchronous APIs as shown in the EMDK sample ProfileClockSample1 running the ProcessProfile method on a thread different than the UI one. Note that the synchronous version of the sample implemented for this blog instead runs this method on the UI thread, potentially freezing the UI.
The second benefit is quite unique and, if you need to process a profile as soon as the device has booted, it could be a deal breaker.
Which are the async APIs?
Let’s see which are the APis we’re talking about:
void getInstanceAsync(EMDKManager.FEATURE_TYPE featureType, EMDKManager.StatusListener statusListener)
This method is an asynchronous call and requests object instance for the specified feature type and object is returned through the status listener callback when the feature is initialized and ready to use.
EMDKResults processProfileAsync(String profileName, ProfileManager.PROFILE_FLAG profileFlag, String extraData)
Processes the given profile based on the data provided and the flag and return status of the request. This is an asynchronous method and result will be returned through the registered callback.
To use the
getInstanceAsync we need to implement the
EMDKManager.StatusListener interface, with an
onStatus method is called when the EMDK is able to provide an instance of the object requested. In our case, a ProfileManager object. So, the first thing we can do is to check that we got the right object:
Keep in mind that this code is not run on the UI Thread, this is why to change an element of the UI, we need to create a runnable on the right thread.
After having checked that everything is OK, we can start to use our
Now, before actually being able to process a profile asynchronously, we have to register a DataListener that is going to evaluate the result of the
Keep in mind that this is a
ProfileManager.DataListener, different from the DataListener used in the barcode API.
Once we have the DataListener in place, we can process the profile checking that the XML is going to be processed by Mx:
Putting all the pieces together
In the end, putting all the pieces together, this is the code for the onStatus callback:
Now, if run this version of the application just after a device boot you’ll see that the profile is correctly applied as soon as Mx is ready.
This is a sample application that wants to show how to use these APIs with the minimum amount of ceremony, there’s little or no error control and there’s no management of configuration changes that could destroy and recreate the activity spawning a new call to process the profile!
The sample project can be downloaded from github, this version is associated with the