ZEBRA Mobile Parcel Dimensioning User Guide

How Big Is It?
Daniel Neamtu
EMEA Developer
Advocate

Mobile Parcel Dimensioning

Agenda

• ToF Sensor
  – What it is and how it works
  – Android APIs
  – Use Cases

• Mobile Parcel Dimensioning
  – Key Features
  – Architecture
  – Versioning / Installation
  – API

ToF Sensor

ToF Sensor
What is it?

• Sensor with a 3D imaging system

• Composed of:
  – Emitter
  – Detector
  – Support Circuitry

• Can be integrated into a mobile device/smartphone without affecting the overall shape and size of the device

• Zebra ToF solution does not require recalibration

ToF Sensor
How does it work?

• When activated, the ToF sensor will illuminate the scene with a modulated light source.
• Once the signal is emitted, it will travel through space until it encounters an object or a surface.
• The sensor will then detect the time delay or phase shift of the reflected light relative to the emitted signal to travel from the sensor to the object and back again.
• Given that the sensor knows the original speed of the signal, it can accurately calculate the distance of the object based on the time delay or phase shift

Using Android Camera2 API

Getting Started

• Must use the Camera2 API because the CameraX API does not support ToF
• Support for both Java & Kotlin
• To get started, first thing to do is adding the appropriate permissions in the Android Manifest of the project

Using Android Camera2 API
Check if the device supports ToF sensor

Using Android Camera2 API
Determine maximum resolution of the ToF sensor

Using ToF with NDK Android Native Camera API
Overview

• The ToF Sensor also supports Android NDK Development
  – The Android NDK is a toolset that lets you implement parts of your app in native code, using languages such as C and C++

• To communicate with the ToF sensor, you will need to use the native camera API: https://developer.android.com/ndk/reference/group/camera

• Better option for developers experienced with C or C++

• Provides improved performance since depth-processing algorithms are usually written in C or C++ (including ours)

ToF Sensor
Use Cases

• AR & VR – ToF sensors can be used to map the user’s surroundings and create realistic and immersive virtual experiences so that the device can understand the environment and recognize objects
• Facial Recognition and Biometric Security – ToF sensors can enable the recognition of faces by capturing facial features in 3D, making it more secure compared to the old 2D based methods. This is similar to how Face ID works on Apple devices
• Distance Measurement and Object Detection – ToF sensors can be used to gather distance measurements (which also involves detecting the presence and position of objects). This is similar to how the dimensioning algorithm works on our Zebra devices
• ….and more

Mobile Parcel Dimensioning

Mobile Parcel Dimensioning

Overview

• Fast and accurate Weights & Measure certified Mobile Dimensioning of parcels
• Solution offered on Premium TC73/TC78 Mobile Computer with Time of Flight (ToF) Sensor
• Solution offered as Certified and Non-Certified SKU
• Solution to be certified at following OIML, NTEP, MC, NMI regulatory agencies

Note: Metric to imperial mapping: (1 cm) → (0.5”), (2 cm) → (1”), (5 cm) → (2”) for rounding

Key Features

• Supports dimensioning of Cuboidal Parcels
• Supports top down and isometric (top and front face of parcel) dimensioning approaches
• Supports both certified and non-certified solutions
• Initial software is pre-installed from factory
• Demo application also pre-installed for demonstration & testing purpose
• Software persists across factory and enterprise reset
• Software is updatable independent of OS image via stagenow/EMM
• Supports all regulatory requirements for certified solutions, such as: event log, information screen, rounding rules, software sealing, etc…
• SDK / APIs available to integrate dimensioning into line of business applications
• Supports diagnostic capability (image dumping, log capture, etc.)

Software Architecture

• MDClient
  – Mobile Dimensioning Client demo application pre-installed on the mobile computer
  – Application uses Mobile Parcel Dimensioning API (Intent)
  – Application is delivered as part of software bundle along with Dimensioning Framework

• Dimensioning Framework
  – Dimensioning Framework is the core software component of the dimensioning solution and comes pre-installed on the mobile computer
  – Dimensioning Framework is a foreground service, which has a notification icon which shows “Dimensioning is running”
  – Framework handles all incoming intents from the API and delivers dimension data to applications once successfully dimensioned
  – Framework is signed by a special Zebra key and protected to meet regulatory software sealing requirements

• ToF Sensor
  – Dimensioning Framework uses input from ToF sensor to perform measurement

Android

Line of Business
(LOB)| MDClient
Intent API
(https://techdocs.zebra.com/mobile-parcel/1-0/guide/api)
Dimensioning Framework
ToF Sensor

Software Versioning Scheme

• Sample Version Format
  – MP_NONCERTIFIED_1_0_0_0_20220730.zip – Software Version 1 for Non-Certified Solution
  – CMP_US_1_0_0_0_20220730.zip – Software Version 1 for NTEP (metrological)
  – CMP_US_1_1_0_0_20220830.zip – Software Version 1.1 for NTEP (non- metrological)
  – CMP_EU_1_0_0_0_20220830.zip – Software Version 1 for OIML (metrological)
  – CMP_US_1_1_1_0_20220930.zip – Non-Metrological Custom Changes for a specific custom request (internal modules will have patch version bumped if they are modified)

• Software Versioning Format
  – CMP / MP: Certified Mobile Parcel for certified solution & Mobile Parcel for non-certified solution
  – Regulatory Region: Tracks the software for specific regulatory region
  – Major Version (aa): Major version (aa) tracks any Metrological changes
  – Minor Version (bb): Minor version (bb) tracks any nonMetrological changes
  – Patch(cc): Tracks any non-Metrological point fixes to specific customers

Software Installation Procedure

Software can be installed one of two ways:

1. Using StageNow
   • Installation using OS update Feature
   • Installation using Xpert Mode

2. Using an Enterprise Mobility Management (EMM) Client
   • Airwatch
   • SOTI

Note: Dimensioning Software (MDClient and Dimensioning Framework) will persist across Factory and Enterprise reset
https://www.zebra.com/content/dam/zebra_new_ia/en-us/manuals/software/mobile- parcel/mobileparcel-ig-en.pdf

Dimensioning API

Overview – Sequence Diagram

• Enable Dimension
• Disable Dimension
• Get Dimension Parameter
• Set Dimension Parameter
• Get Dimension

See https://techdocs.zebra.com/mobile-parcel/1-0/guide/api/

Security

• Zebra requires developers use an access control method through MX Access Manager (https://techdocs.zebra.com/mx/accessmgr/)
• Only trusted applications can communicate with the Mobile Parcel API
• All application packages must be placed on the allow list
• Line of Business (LOB) application must generate API token using MX Access Manager
• API requires LOB application to pass API token and package name in each API for authentication

Security – Allow listing procedure

• Extract LOB App Certificate
  – This is a pre-requisite to create the StageNow profile that places the app in the allow list
  – Steps to extract the LOB app certificate:

• Download SigTools.jar from Zebra’s App Signature Tools (https://techdocs.zebra.com/emdk-for-android/latest/samples/sigtools/)

• Follow the instructions provided from the link to extract the certificate from the LOB app APK file using command (where [filename.apk] is the full path and file name of the LOB app APK file and [filename.crt] is the designated certificate file name):

Security – Allow listing procedure

• Create StageNow Profile to place the LOB app in the allow list
• Download and install StageNow on a host computer
• Open StageNow. In the StageNow home screen, click Create New Profile from the left menu
• Ensure MX version 11.1 or higher is selected at the top drop-down selector. The MX version on the device should match this or higher. See MX documentation for instructions how to check the version
• Select Xpert Mode from the list and click Create

Security – Allow listing procedure

• Enter the profile name. Click Start
• Scroll to AccessMgr and click the plus (+) sign to add AccessMgr to the Config tab on the right side
• Click Add

Security – Allow listing procedure

• Enter the appropriate information as prompted:
  – Service Access Action: Allow Caller to Call Service
  – Service Identifier: delegation-zebra-com.zebra.mobiledimensioning-Enable
  – Caller Package Name: [Enter package name of the LOB app.] – Caller Signature: [Browse to the app certificate generated from Extract LOB App Certificate.]

• Click Continue

• Click Complete Profiles. Profile creation is complete

• 10. Perform one of the following steps based on the staging method. Ensure devices are connected to the network during the staging process:
  – StageNow: Generate the barcode. Open StageNow on the device and scan the barcode to place the app in the allow list
  – EMM: Click on Export the XML for MDM. Send the XML using either OEMConfig or MX to place the app in the allow list

Security – Token Generation

• The application must use Access Manager to dynamically generate an API token
• The API token is one of the parameters that must be sent with each API request for authentication
• Mobile Dimensioning sample code demonstrates how to talk to the Device Manager through the ZDM Content Provider
  – See https://techdocs.zebra.com/flux/query/

Add Queries tag
This is required to allow the application to communicate with Dimensioning and Device Manager for generating the token.

Specify Permission
This is also needed to communicate with the Device Manager.

Security – Token Generation

Note – The API token expires after 24 hours and must be regenerated.

Overview – Common Intent Extras

• Request
  – Intent.putExtra(String name, String value)

response

• Response
  – Intent.getStringExtra(String name)

Overview – Results

• Response RESULT_MESSAGE values

• Dimension Complete
1: Failure| • Dimensioning In Use by Another App
• Dimensioning Already In Use
• Dimensioning Not Supported
• Failed to Open Camera
• Failed to Enable
• Framework Not Installed
• Failed Integrity Check| • Integrity Check Fault
• Insufficient Permissions
• Failed to Disable
• Failed to Get Dimension
• Failed to Get Parameters
• Failed to Set Parameter
2: Error| • Access Denied
• Invalid Module Parameter
• Already Dimensioning
• Invalid State
• Invalid Value
• Invalid Parameter
3: Cancelled| • User Cancelled
• User Inactivity

Enable Dimension

• Enable Dimension
  – ENABLE_DIMENSION starts the Dimensioning service, enables and configures the time-of-flight (ToF) camera for the app to be ready for dimensioning. This must be called before any other API to ensure the Mobile Parcel API is enabled, allowing communication with the app
  – NOTE: ENABLE_DIMENSION prevents other apps from accessing the ToF camera until DISABLE_DIMENSION is called. To save battery and reduce resource conflicts, Zebra recommends calling DISABLE_DIMENSION when dimensioning is not in use or when the app is running in the background
  • Request
  – Use the following action to call ENABLE_DIMENSION:
  com.zebra.dimensioning.ENABLE_DIMENSION

• Response
  – Standard RESULT extras

Disable Dimension

• Disable Dimension
  – DISABLE_DIMENSION releases the ToF camera and any other Dimensioning service resources allocated during ENABLE_DIMENSION. To save battery, call DISABLE_DIMENSION when dimensioning is not in use or when the app is running in the background

• Request
  – Use the following action to call DISABLE_DIMENSION: com.zebra.dimensioning.DISABLE_DIMENSION

• Response
  – Standard RESULT extras

Get Dimension Parameter – Request

• Get Dimension Parameter
  – GET_DIMENSION_PARAMETER returns the values for all Mobile Parcel API parameters. Only call this API after ENABLE_DIMENSION is successfully called

• Request
  – Use the following action to call GET_DIMENSION_PARAMETER:
  com.zebra.dimensioning.GET_DIMENSION_PARAMETER

Get Dimension Parameter – Response

• Response
  – Standard RESULT extras plus:

READY_LENGTH / READY_WIDTH /
READY_HEIGHT| BigDecimal| Length / width / height value to display in app when ready to dimension
DIMENSION_UNIT| String| • Inch
• CM
FRAMEWORK_VERSION| String| Framework version
SERVICE_VERSION| String| Service version
PACKAGE_VERSION| String| Parcel dimensioning software package version
REGULATORY_APPROVAL| String| For Certified Solution: “OIML1234”
For Non-Certified Solution: “”
SUPPORTED_UNITS| StringArray| • (“Inch”,“CM”)
• (“CM”)
REPORT_IMAGE| Boolean| Enable reporting proof of dimension image with
dimension response
• True
• False

Set Dimension Parameter

• Set Dimension Parameter
  – SET_DIMENSION_PARAMETER configures the parameters supported by the Mobile Parcel API. Set any number of parameters through a single call by adding them as intent extras
  – ENABLE_DIMENSION must be called before calling SET_DIMENSION_PARAMETER
  – Supported values for DIMENSIONING_UNIT are reported by the SUPPORTED_UNITS value in GET_DIMENSION_PARAMETER
  – NOTE: Changing DIMENSIONING_UNIT will change the ready value

• Request
  – Use the following action to call SET_DIMENSION_PARAMETER:
  com.zebra.dimensioning.SET_DIMENSION_PARAMETER Key| Type| Required
  ---|---|---
  DIMENSIONING_UNIT| String| No
  REPORT_IMAGE| Boolean| No

• Response
  – Standard RESULT extras

Get Dimension – Request

• Get Dimension
  – GET_DIMENSION returns the values of the parcel measurements when an end-user dimensions a parcel.
  When this API is called, the Mobile Parcel API renders its user interface (UI) on top of the application, allowing the user to aim the camera at the parcel and begin dimensioning. Upon successful dimensioning and confirmation from the user, the results are sent back to the application through an intent response. If dimensioning fails, the result message contains details about the cause of failure
  – NOTE: When calling GET_DIMENSION, the Mobile Parcel UI controls are overlaid on top of the application. This prevents the user from accessing the application until the dimensioning is complete or the user exits the dimensioning session by tapping the back button

• Request
  – Use the following action to call GET_DIMENSION:
  com.zebra.dimensioning.GET_DIMENSION

Get Dimension – Response

• Response
  – Standard RESULT extras plus:

No dimension result is provided
• BelowRange     – Dimension result is below the certified range
• InRange.           – Dimension result is within the certified range
• AboveRange.    – Dimension result is above the certified range
DIMENSIONING_UNIT| String| • Inch
• CM
TIMESTAMP| Instant| Time when dimension took place
IMAGE| Bitmap| Bitmap Image (only reported if REPORTIMAGE parameter is
enabled)
PARCEL I D| String| Parcel ID set by the app
Key| Type| Description/Value

References

• TechDocs Documentation
• Sample Application

Questions

Thank You

ZEBRA and the stylized Zebra head are trademarks of Zebra Technologies Corp., registered in many jurisdictions worldwide. All other trademarks are the property of their respective owners.
©2023 Zebra Technologies Corp. and/or its affiliates.
All rights reserved.

References

• Camera  |  Android NDK  |  Android Developers
• App Signature Tool - TechDocs
• Using ZDM Queries - TechDocs
• Mobile Parcel API - TechDocs
• Access Manager - TechDocs

Read User Manual Online (PDF format)

Download This Manual (PDF format)

Download this manual  >>