Master Lock

The Master Lock Plugin allows you to unlock and manage Master Lock Bluetooth® padlocks, lockboxes, and deadbolts by integrating with the Master Lock Mobile SDKs.

This guide provides step-by-step instructions to configure the plugin and use its features through the Median JavaScript Bridge. Features include scanning, unlocking, relocking (D1000), firmware updates, lock resets, and deadbolt configuration.

👍

Developer Demo

Test your setup during development by embedding the Master Lock demo page in your app.

Implementation Guide

Lock Provisioning (Activation, Setup and Access)

The lock setup and activation is handled using the Master Lock Connected Products Web API. For the latest details, always refer to the official API specification.

In general, you will need the following steps in order to provision a lock, retrieve it's information and provision a new access profile for your users.

Step 1 - API Authentication

Use the /authenticate endpoint to retrieve an API token by using your license and password.

Step 2 - Activate a Lock (Optional)

Use the /v2/device/activate endpoint to active a new lock. Skip this step if your locks are already provisioned.

Step 3 - Retrieve Lock Information

Use the /v2/device to obtain the Firmware Version of your lock(s). The Firmware Version is a required parameter to unlock the lock using the SDK.

Step 4 - Create an Access Profile

Use the /v2/device/accessprofile/create to create a new temporary access profile for your users. Please ensure the access profile has the Unlock permission otherwise the user won't be able to unlock the Bluetooth locks.

There are multiple API endpoints to create access profiles. The endpoint above creates a single profile for a single lock, but you can also create an access profile for multiple locks, or multiple access profiles for a single lock.

Note: Access Profile Permissions

Please always validate with the latest permissions outlined in the Master Lock Access Profile and Permissions documentation.

JavaScript Bridge Functions

Plugin Permissions

The Master Lock Plugin requires Bluetooth and Location permissions to scan for and interact with nearby locks. These permissions are requested automatically at runtime.

If you prefer to check and request permissions before initializing the plugin, see our Permissions Overview for implementation details.

Initialize Master Lock SDK

The SDK must be initialized before scanning or unlocking. This design supports multiple Master Lock licenses within the same app.

↔️Median JavaScript Bridge

JavaScript

median.masterlock.initialize({ license })

Scan for Locks

Discover nearby Master Lock devices. You are able to define a scanning timeout in milliseconds (otherwise a default value of 15s will be used) and can are able to define functions for each of the following events:

• onScanStart: App started scanning for nearby locks.
• onScanStop: App stopped scanning for nearby locks.
• onDeviceDiscover: App discovered locks.

↔️Median JavaScript Bridge

JavaScript

median.masterlock.scan({
  onScanStart: "onScanStart",
  onScanStop: "onScanStop",
  onDeviceDiscover: "onDeviceDiscover",
  timeout: timeout,
});

Unlock a Lock

Unlocking requires the Device ID, Access Profile, Firmware Version, and a timeout value (in milliseconds).

↔️Median JavaScript Bridge

JavaScript

median.masterlock.unlock({
  deviceId,
  accessProfile,
  firmwareVersion,
  mechanism: "primary" | "secondary"
  timeout: timeout
});

Parameters:

• deviceId: The lock's unique identifier - available during setup or Master Lock API.
• accessProfile: Profile generated via the Master Lock API.
• firmwareVersion: Lock firmware version.
• mechanism: Defines the primary or secondary lock mechanism.
• timeout: Time in ms before auto-relock.

Update Firmware

Initiate an OTA firmware update on a Master Lock device. The update process runs automatically once initiated.

↔️Median JavaScript Bridge

JavaScript

median.masterlock.updateFirmware({
  deviceId,
  accessProfile,
  currentFirmwareVersion,
  targetFirmwareVersion
});

Parameters:

• deviceId: The lock's unique identifier.
• accessProfile: Profile generated via the Master Lock API.
• currentFirmwareVersion: Current firmware version on the lock.
• targetFirmwareVersion: Target firmware version to update to (from Master Lock API).

⚠️

Important

• Ensure the device is awake and network connectivity is strong before starting.
• Updates can take up to 5 minutes.
• The lock will unlock automatically during update to ensure accessibility in case of failure.
• After completion, you must fetch a new access profile from the Master Lock API.

Firmware Update Listener

Subscribe to firmware update state changes and progress. Use this to display real-time progress to users.

↔️Median JavaScript Bridge

JavaScript

// Add listener
const listenerId = median.masterlock.firmwareUpdate.addListener((status) => {
  console.log(status.deviceId, status.state, status.percentage);
});

// Remove listener when done
median.masterlock.firmwareUpdate.removeListener(listenerId);

The callback receives a status object with:

• deviceId: The lock being updated.
• state: Current state - downloading, downloadComplete, applying, validating, done, or error.
• percentage: Progress percentage (0-100), only populated when state is applying.
• error: Error details when state is error.

Lock Reset

Perform a lock reset to invalidate all access profiles, temporary codes, and secondary codes. Use this when re-keying a lock or revoking all access. Please note that the Lock Reset is only available for the D1000 Deadbolt.

↔️Median JavaScript Bridge

JavaScript

median.masterlock.lockReset({
  deviceId,
  accessProfile,
  firmwareVersion
});

Parameters:

• deviceId: The lock's unique identifier.
• accessProfile: Profile generated via the Master Lock API.
• firmwareVersion: Lock firmware version.

Returns a promise that resolves with:

• success: Boolean indicating if reset completed.
• deviceId: The lock that was reset.
• accessProfilesInvalidated: Confirms access profiles are now invalid.
• temporaryCodesInvalidated: Confirms temporary codes are now invalid.
• secondaryCodesErased: Confirms secondary codes have been erased.

⚠️

Important

• Must be performed while online (API acknowledgement required).
• Takes 3-15 seconds to complete.
• Currently only D1000 Deadbolt model supports this operation.
• Cannot be performed if lock or phone battery is below 10%.
• After reset, all users must refresh their access profiles via the Master Lock API.

Lock Reset Error Codes

Get Deadbolt Handedness

Read the current bolt direction configuration from a D1000 Deadbolt. This is useful for displaying the current configuration in your app UI.

↔️Median JavaScript Bridge

JavaScript

median.masterlock.getDeadboltHandedness({
  deviceId,
  accessProfile,
  firmwareVersion
});

Parameters:

• deviceId: The lock's unique identifier.
• accessProfile: Profile generated via the Master Lock API.
• firmwareVersion: Lock firmware version.

Returns a promise that resolves with:

• success: Boolean indicating if read completed.
• deviceId: The lock that was queried.
• handedness: Current configuration - left or right.

Set Deadbolt Handedness

Configure the bolt direction on a D1000 Deadbolt. This must be set correctly for proper unlock/relock motor operation.

↔️Median JavaScript Bridge

JavaScript

median.masterlock.setDeadboltHandedness({
  deviceId,
  accessProfile,
  firmwareVersion,
  handedness: "left" | "right"
});

Parameters:

• deviceId: The lock's unique identifier.
• accessProfile: Profile generated via the Master Lock API.
• firmwareVersion: Lock firmware version.
• handedness: The desired bolt direction - left or right.

Returns a promise that resolves with:

• success: Boolean indicating if configuration was saved.
• handedness: The configured handedness.

💡

Determining Handedness

Stand inside the door looking at the thumbturn side of the deadbolt:

• If the bolt is on the left and extends left → use left
• If the bolt is on the right and extends right → use right

Relock (D1000 Deadbolt Only)

Manually relock a D1000 Deadbolt by extending the bolt to the locked position. This is required because the D1000 does not support automatic relocking like padlocks and lockboxes.

↔️Median JavaScript Bridge

JavaScript

median.masterlock.relock({
  deviceId,
  accessProfile,
  firmwareVersion
});

Parameters:

• deviceId: The lock's unique identifier.
• accessProfile: Profile generated via the Master Lock API.
• firmwareVersion: Lock firmware version.

Returns a promise that resolves with:

• success: Boolean indicating if relock completed.
• deviceId: The lock that was relocked.

⚠️

Important

• Only applicable to D1000 Deadbolt model.
• Lock must be awake and in Bluetooth range.
• Ensure deadbolt handedness is configured correctly before using this method.

Testing Your Integration

Hardware Testing

🔧

Test Environment

Hardware-dependent features cannot be tested using simulators. You'll need a physical Master Lock padlock or lockbox.

iOS testing requires a TestFlight or local build using XCode. For Android you can download the APK directly from App Studio.

Please follow the following steps for an end-to-end test

1. Activate and set up a lock using the Master Lock API.
2. Collect the Device ID and Firmware Version using the Master Lock API.
3. Create a new access profile via the API.
4. Switch to your mobile app and initialize the SDK by providing your license key.
5. Use the collected parameters to unlock the test lock.
6. The lock automatically re-locks after the configured timeout.

Frequently Asked Questions

Can I manually relock my padlock or lockbox?

No. Padlocks and lockboxes cannot be manually re-locked via the integration. They automatically lock after a preset timeout.

How do I relock my D1000 Deadbolt?

The D1000 Deadbolt does not support automatic relocking. Use the median.masterlock.relock() method to manually extend the bolt to the locked position. Ensure you have configured the correct handedness before calling this method.

Why am I receiving a "Not Permitted" error when unlocking?

This error indicates the access profile does not include the required permissions for the lock type. Confirm that the correct permissions (e.g. Unlock, UnlockDoor, or UnlockShackle) are assigned to the access profile.

Full Error Code:

{ 
  "success": false, 
  "error": "Error in response - Not Permitted)
}

What happens if a firmware update is interrupted?

If an update is interrupted or fails, the lock will remain in bootloader mode until the update is completed. You should retry the firmware update to restore normal lock operation.

Why do I need to set deadbolt handedness?

The D1000 Deadbolt needs to know which direction the bolt extends so the motor operates correctly during unlock and relock commands. Incorrect handedness configuration will cause the motor to turn the wrong direction.