Wireless Developer Service APIs

Wireless Workstation Connect 2.1

Overview

The Zebra Wireless Developer Service (ZWDS) allows custom Android apps to share content over the air to a monitor connected to a wireless receiving device such as the Zebra ZEC500. The APIs provided with the service include the ability to scan for available receivers, connect and disconnect, set a proximity threshold for making and breaking connections and to switch between Mirror and Desktop display modes.

By default, ZWDS uses secure tokens for all intent API transactions. Before first using the APIs, a token must be generated through Zebra Access Manager and passed as a parameter with API calls. Though not recommended by Zebra, this security measure also can be disabled. See the Secure Mode section below for details.

Best Practices

Zebra engineers recommend the following practices for apps using the wireless-service APIs to achieve optimal performance and avoid unpredictable behavior.

  • First use of ZWDS requires generating a secure token. Go to the Secure Mode section to learn more.
  • Before calling CONNECT_WIRELESS_DISPLAY:
    • a. First call START_WIRELESS_DISPLAY_SCAN to identify a receiving device (e.g. ZEC500) with which to connect.
    • b. Then check the display properties of the intended receiver to confirm that CanConnect and IsAvailable properties are both true.
  • After establishing a connection, call STOP_WIRELESS_DISPLAY_SCAN to minimize the resource usage on the device.
  • Before exiting the app:
    • a. Call DISCONNECT_WIRELESS _DISPLAY first.
    • b. Then call DEINIT_DEV_SERVICE to clear the service. This enables subsequent INIT_DEV_SERVICE calls to succeed.
  • When a connection is active, calling CONNECT_WIRELESS_DISPLAY disconnects the session.
  • If a connection remain idle for more than 60 minutes, reset the connection to avoid unresponsiveness or erratic behavior.

APIs

Start Service

Starts the developer service for wireless communications with a ZEC500-type receiver. This API must be called before any other API calls are made.

Request

  • Intent Action: com.zebra.wirelessdeveloperservice.action.INIT_DEV_SERVICE
  • Supports the key(s) shown below.
Key Type Description
CALLBACK_RESPONSE PendingIntent Object that receives the response
STATE_CHANGE_RCV_PKG String Package name to receive broadcast for state change

Response

Sends the following response(s) to the app:

Key Type Description
RESULT_CODE Integer 1: Success
0: Failure
RESULT_MESSAGE String Success: "Success"
Failure: "[Error message]"

Stop Service

Stops the developer service for wireless communications with a ZEC500-type receiver. This API must be called after any communications session before exiting the app.

Request

  • Intent Action: com.zebra.wirelessdeveloperservice.action.DEINIT_DEV_SERVICE
  • Supports the key(s) shown below.
Key Type Description
CALLBACK_RESPONSE PendingIntent Object that receives the response

Response

Sends the following response(s) to the app:

Key Type Description
RESULT_CODE Integer 1: Success
0: Failure
RESULT_MESSAGE String Success: "Success"
Failure: "[Error message]"

Start Display Scan

Starts scanning for available ZEC500-type receivers with which to connect. This API must be called before calling CONNECT_WIRLESS_DISPLAY.

Request

  • Intent Action: com.zebra.wirelessdeveloperservice.action.START_WIRELESS_DISPLAY_SCAN
  • Supports the key(s) shown below.
Key Type Description
CALLBACK_RESPONSE PendingIntent Object that receives the response

Response

Sends the following response(s) to the app:

Key Type Description
RESULT_CODE Integer 1: Success
0: Failure
RESULT_MESSAGE String Success: "Success"
Failure: "[Error message]"

Stop Display Scan

Stops scanning for available ZEC500-type receivers with which to connect. Zebra recommends calling this API after any successful connection to preserve device resources.

Request

  • Intent Action: com.zebra.wirelessdeveloperservice.action.STOP_WIRELESS_DISPLAY_SCAN
  • Supports the key(s) shown below.
Key Type Description
CALLBACK_RESPONSE PendingIntent Object that receives the response

Response

Sends the following response(s) to the app:

Key Type Description
RESULT_CODE Integer 1: Success
0: Failure
RESULT_MESSAGE String Success: "Success"
Failure: "[Error message]"

Connect Display

Connects with an available ZEC500-type receiver after passing its MAC address or device name. Calling this API during an active connection disconnects the session.

Request

  • Intent Action: com.zebra.wirelessdeveloperservice.action.CONNECT_WIRELESS_DISPLAY
  • Supports the key(s) shown below.
Key Type Description
CALLBACK_RESPONSE PendingIntent Object that receives the response
DEVICE_ID String MAC address or Device Name of receiving device

Response

Sends the following response(s) to the app:

Key Type Description
RESULT_CODE Integer 1: Success
0: Failure
RESULT_MESSAGE String Success: "Success"
Failure: "[Error message]"

Disconnect Display

Disconnects from the ZEC500-type receiver, ending the session. Zebra recommends calling DEINIT_DEV_SERVICE before exiting the app to stop the developer service and enable subsequent connections.

Request

  • Intent Action: com.zebra.wirelessdeveloperservice.action.DISCONNECT_WIRELESS_DISPLAY
  • Supports the key(s) shown below.
Key Type Description
CALLBACK_RESPONSE PendingIntent Object that receives the response

Response

Sends the following response(s) to the app:

Key Type Description
RESULT_CODE Integer 1: Success
0: Failure
RESULT_MESSAGE String Success: "Success"
Failure: "[Error message]"

Register Proximity

Initializes the Bluetooth service and registers the Bluetooth client to get proximity callbacks. Must be called before SET_PROXIMITY_CONNECT.

Request

  • Intent Action: com.zebra.wirelessdeveloperservice.action.REGISTER_PROXIMITY_CONNECTION
  • Supports the key(s) shown below.
Key Type Description
CALLBACK_RESPONSE PendingIntent Object that receives the response

Response

Sends the following response(s) to the app:

Key Type Description
RESULT_CODE Integer 1: Success
0: Failure
RESULT_MESSAGE String Success: "Success" + "[Client ID]"
Failure: "[Error message]" + "[Error Code]"

Unregister Proximity

"Unregisters" the Bluetooth client and stops the Bluetooth service. Call when proximity broadcast callbacks are no longer needed.

Request

  • Intent Action: com.zebra.wirelessdeveloperservice.action.UNREGISTER_PROXIMITY_CONNECTION
  • Supports the key(s) shown below.
Key Type Description
CALLBACK_RESPONSE PendingIntent Object that receives the response

Response

Sends the following response(s) to the app:

Key Type Description
RESULT_CODE Integer 1: Success
0: Failure
RESULT_MESSAGE String Success: "Success"
Failure: "[Error message]"

Set Proximity

Turns on/off the proximity dis/connection broadcast threshold. Once a receiving device crosses the proximity threshold, an intent is sent to connect the device to (or disconnect it from) that receiver.

Request

  • Intent Action: com.zebra.wirelessdeveloperservice.action.SET_PROXIMITY_CONNECTION
  • Supports the key(s) shown below.
Key Type Description
CALLBACK_RESPONSE PendingIntent Object that receives the response
PROXIMITY_CONNECT String ON – Proximity connection broadcast
OFF – Proximity connection broadcast
PROXIMITY_DISCONNECT String ON – Proximity disconnection broadcast
OFF – Proximity disconnection broadcast
CONNECT_THRESHOLD Integer Distance in feet
(max=30)
DISCONNECT_THRESHOLD Integer Distance in feet
(max=30)

Response

Sends the following response(s) to the app:

Key Type Description
RESULT_CODE Integer 1: Success
0: Failure
RESULT_MESSAGE String Success: "Success"
Failure: "[Error message]"

Get Status

Obtains the current status of the developer service on a connected, disconnected or state-unknown ZEC500 device.

Request

  • Intent Action: com.zebra.wirelessdeveloperservice.action.GET_STATUS
  • Supports the key(s) shown below.
Key Type Description
CALLBACK_RESPONSE PendingIntent Object that receives the response

Response

Sends the following response(s) to the app:

Key Type Description
RESULT_CODE Integer 1: Success
0: Failure
RESULT_MESSAGE String Success: "Success"
Failure: "[Error message]"
STATUS String Device in connected state:
{"device_status":{"device_address":"ZEC500"," connection_status":1}}
Device in disconnected state:
{"device_status":{"device_address":"ZEC500"," connection_status":0}}
Device in unknown state:
{"device_status":{"device_address":" "," connection_status":-1}}

Switch Display Mode

Toggles Desktop Mode on the device, effectively switching between Desktop Mode and Mirror Mode (which is "on" whenever Desktop Mode is "off"). Mirror Mode duplicates the contents of the device screen on the external monitor. Desktop Mode displays content independent of the device.

Request

  • Intent Action: com.zebra.wirelessdeveloperservice.action.SWITCH_DESKTOP_MODE
  • Supports the key(s) shown below.
Key Type Description
CALLBACK_RESPONSE PendingIntent Object that receives the response
DESKTOP_MODE String ON – Switch to Desktop Mode
OFF – Switch to Mirror Mode

Response

Sends the following response(s) to the app:

Key Type Description
RESULT_CODE Integer 1: Success
0: Failure
RESULT_MESSAGE String Success: "Success"
Failure: "[Error message]"

Get Available Displays

Fetches a list of available receivers in the vicinity with which to connect.

Request

  • Intent Action: com.zebra.wirelessdeveloperservice.action.GET_AVAILABLE_DISPLAYS
  • Supports the key(s) shown below.
Key Type Description
CALLBACK_RESPONSE PendingIntent Object that receives the response

Response

Sends the following response(s) to the app:

Key Type Description
RESULT_CODE Integer 1: Success
0: Failure
RESULT_MESSAGE String Success: "Success"
Failure: "[Error message]"
AVAILABLE_DISPLAYS String List of available receivers as a .json array with the following fields:
canConnect
deviceAddress
deviceName
isAvailable
isRemembered
Example:
[{"canConnect":false,"deviceAddress":"4b:e0:20:5e:0f:88","deviceName":"ZEC500","isAvailable":false,"isRemembered":true}]

Enable Display

Enables a wireless receiver to accept a remote display connection.

Request

  • Intent Action: com.zebra.wirelessdeveloperservice.action.ENABLE_WIRELESS_DISPLAY
  • Supports the key(s) shown below.
Key Type Description
CALLBACK_RESPONSE PendingIntent Object that receives the response
DESKTOP_MODE String ON – Enables the wireless display
OFF – Disables the wireless display

Response

Sends the following response(s) to the app:

Key Type Description
RESULT_CODE Integer 1: Success
0: Failure
RESULT_MESSAGE String Success: "Success"
Failure: "[Error message]"

Display Callback

Register or unregister to receive notifications via broadcast of changes to the properties of connected or unconnected receivers in range of the device.

Request

  • Intent Action: com.zebra.wirelessdeveloperservice.action.WIRELESS_DISPLAY_CALLBACK
  • Supports the key(s) shown below.
Key Type Description
CALLBACK_RESPONSE PendingIntent Object that receives the response
REGISTER_CALLBACK String ON – Register for wireless display change callback broadcast
OFF – Unregister for wireless display change callback broadcast

Response

Sends the following response(s) to the app:

Key Type Description
RESULT_CODE Integer 1: Success
0: Failure
RESULT_MESSAGE String Success: "Success"
Failure: "[Error message]"

State Change Callbacks

The Zebra Wireless Developer Service sends three types of broadcasts for updating apps about the current status. To receive ZWDS broadcasts, the app must first add the permission shown below in its manifest.xml file.

Grant ZDWS broadcast permission in app manifest:


<uses-permission android:name="com.zebra.permission.ZWDS_BROADCAST" />

Proximity Change

Notifies the app of a change in Bluetooth proximity state. Broadcast to apps when a device crosses the value in the SET_PROXIMITY_CONNECTION parameter.

Intent Action

  • com.zebra.wirelessdeveloperservice.action.BT_PROXIMITY_STATE_CHANGE
  • Supports the key(s) shown below.
Key Type Description
STATE_TYPE String BT_PROXIMITY_STATE
STATE_CHANGE String .json string describing the change, as in examples below.
Connected state:
{"proximity_monitor_status":{"connection_status":2,"p2p_friendly_name":"ZEC500"}}
Disconnected state:
{"proximity_monitor_status":{"connection_status":4,"p2p_friendly_name":"ZEC500"}}

Connection Change

Notifies the app of a change in the peer-to-peer connection state. Broadcast to apps when a connection state changes as a result of the value in the SET_PROXIMITY_CONNECTION parameter being crossed.

Intent Action

  • com.zebra.wirelessdeveloperservice.action.CONNECTION_STATE_CHANGE
  • Supports the key(s) shown below.
Key Type Description
STATE_TYPE String CONNECTION_STATE
STATE_CHANGE String .json string describing the peer-to-peer change, as in examples below.
Connected state:
{"p2p_connection_status":{"connection_status":1}}
Disconnected state:
{"p2p_connection_status":{"connection_status":0}

Receiver Info Change

Notifies the app of a change in the information about the connected receiver. Broadcast to apps when changes occur to the information relating the ZEC500-type device hosting the connection to its display.

Intent Action

  • com.zebra.wirelessdeveloperservice.action.DISPLAY_DETAILS_CHANGE
  • Supports the key(s) shown below.
Key Type Description
STATE_TYPE String DISPLAY_DETAILS_CHANGE
STATE_CHANGE String .json string describing the data newly stored in the following fields:
canConnect
deviceAddress
deviceName
isAvailable
isRemembered
Example:
[{"canConnect":false,"deviceAddress":"4b:e0:20:5e:0f:88","deviceName":"ZEC500","isAvailable":false,"isRemembered":true}]

Secure Mode

Grant Token Permission

Before using the Zebra Wireless Developer Service in its default secure mode, a token must be generated and passed as a parameter using an intent. A token is generated by "whitelisting" the app using the ZWDS delegation scope shown below and options of Zebra Access Manager and its Service Access Action parameter (values shown below). ZWDS processes only API calls containing the validated token. Calls not containing the token generate an error to the app.

  • ZWDS delegation scope: delegation-zebra-zwds-api-secure-access-config
Action Function
AllowCaller Allows an app to request a token
DisallowCaller Prohibits an app from generating a token

Generate Token

Customer app should generate the token using existing Access Manager using Action in below and send that with ZWDS Intent APIs.

Action Function
AquireToken Acquires a token for sending

Send Token

Send the token using the intent EXTRA parameter.

Key Type Description
TOKEN String Secure token generated by the user for the app

Sample Code

The code below is an example for generating a secure token for use with ZDWS intent APIs.

Code not for use in production environments. 


public class GetIntentSecureToken {
 static final Uri AUTHORITY_URI = Uri.parse("content://com.zebra.devicemanager.zdmcontentprovider");
 static Uri ACQUIRE_TOKEN_URI = Uri.withAppendedPath(AUTHORITY_URI, "AcquireToken");
 public static final String COLUMN_QUERY_RESULT = "query_result";
 private static final String TAG = "GetIntentSecureToken";
 @SuppressLint("Range")
 public static String acquireToken(String delegation_scope, Context mContext) {
   String token = "";
   try {
     Cursor cursor = mContext.getContentResolver().query(ACQUIRE_TOKEN_URI, (String[])null,
      "delegation_scope=?", new String[]{delegation_scope}, (String)null);
    if (cursor != null && cursor.getCount() > 0) {
       cursor.moveToFirst();
        token = cursor.getString(cursor.getColumnIndex(COLUMN_QUERY_RESULT));
        Log.e(TAG, token);
        cursor.close();
      }
    } catch (Exception var3) {
      if (var3 instanceof SecurityException) {
        Log.e(TAG, "Invalid Token/Caller");
      } else {
        Log.e(TAG, "Unknown Caller to acquire token");
      }
    }
  return token;
 }
}

Secure Mode Enable/Disable

The values below are options of Zebra Access Manager and its Service Access Action parameter. Use this to control and check status of ZWDS secure mode with the delegation scope: delegation-zebra-zwds-api-secure-access-config.

Action Function
AllowBinding Disable secure mode
DisallowBinding Enable secure mode
(default setting)
VerifyBinding Check the status of secure mode