Skip to main content

Remotely debug devices with X-Ray

What is Mason X-Ray?​

X-Ray is a tool and a workflow within the Mason platform that allows you to debug and diagnose your devices from anywhere in the world. With X-Ray, you can remotely view and control your device, and stream device logs.

X-Ray is built on top of adb, the Android Debug Bridge. This suite of tools provides powerful access to any provisioned Mason device, giving you remote access to the device and the power of the tooling adb provides.

One of the most commonly used tools in adb is called logcat, which provides a steam of global logs across the entire device.

Where do I find X-Ray in the Mason platform?​

The Mason CLI​

Mason X-Ray wraps adb functionality in easy-to-use REST APIs available to use from the Mason CLI. See command references for X-Ray within the Mason CLI here.

The Mason Controller​

You can also stream device logs or start an interactive remote control session with the device right from your Mason Controller account. Within Controller, the functionality of X-Ray is a workflow accessible via the device details tab. See our X-Ray feature walkthrough here.

X-Ray setup​

Select your device version below for instructions on how to set up X-Ray.

Devices running Mason OS version 6.0.5+ can be accessed via X-Ray in Controller and in the CLI, version 2.0 or higher.

To use X-Ray in Controller, you can navigate to the device's details section in your Controller account. If the Connectivity Status is Online, you can use desktop mode with your device or stream device logs. To use desktop mode (vnc) with your device to view the device's screen and interact with and control the device remotely, click “Launch Remote Session” at the bottom of the device details tab. To view and filter your device's logs, click “View Device Logs” at the bottom of the device details tab.

In order to use X-Ray in the CLI, follow the steps below:

  1. Download the latest Mason CLI
  2. Ensure your device is running version 6.0.5+

To check which Mason OS version your device is running, log into Controller and navigate to your Device Details. In the Device Details section, click the Software tab and under the OS section, verify that the Mason OS Version is 6.0.5 or higher.

If your device is not running Mason OS 6.0.5+, use Controller to deploy a mason-os update to your device. You can do this by navigating to the device Group's detail view and selecting "Mason OS update" from the 'Deploy to group' dropdown in the upper right.

For using X-Ray on the CLI, create a Mason API with XRAY:ADMIN scope. Once the API key is created, you will need to pass it along with the mason xray commands.

Stream device logs with X-Ray logcat​

Mason X-Ray logcat wraps adb logcat so that you can remotely access your devices, giving you the power of adb across your entire fleet of devices.

Using Mason X-Ray logcat on a Mason device can give you insights into CPU power states, network changes, and other details that are relevant to application performance and stability.

The logs provided by Mason X-Ray logcat also include logs from the applications you've deployed to your devices, helping you debug repeated crash loops or unexpected behavior.

Select your device version below for instructions on how to stream device logs with X-Ray. In order to use X-Ray, your device must be turned on and connected to Wi-Fi or cellular data.

You can access X-Ray logcat from the Mason Controller or using the CLI v2.0+. Refer to the CLI documentation to learn about how to use X-Ray in the CLI, with commands like mason xray logcat and mason xray get-bug-report command.

To stream logs from Controller, follow the instructions below.

  1. Navigate to the Devices tab and select your device. A device details tab will appear on the right side of your screen.
  2. At the bottom of the device details tab, select “View Device Logs.”

Stream device logs with ADB​

If your device is unable to connect to Wi-Fi or cellular data, you can stream device logs using Android Debug Bridge. You must have your device physically present, and USB debugging must be enabled on your device. To enable USB debugging, follow the steps below.

  1. You need to access the Developer Options screen, which is hidden by default. To make it visible, on your device go to Settings > About phone and tap Build number 7 times or until you see a prompt that says “You're now a developer!”
  2. Press the Back button until you exit the Settings app completely.
  3. Re-enter Settings, and scroll down to Developer options.
  4. Turn on USB debugging.

A common use of adb is working with the Android file system. Being based on Linux, Android follows its conventions. For example, / is the root of the file system, similar to C:/ in Windows.

You can use the Mason CLI command mason xray adbproxy to start a remote ADB session where you can start an interactive shell on the device. On devices running Mason OS version 6.0.5+, you can use the command mason xray list-files to navigate the directories on a production device.

Important directories to note

The /sdcard directory is where user-accessible files are stored:

  • If an app takes a picture, it will be saved to /sdcard/DCIM
  • If a user downloads a file, it will be saved to /sdcard/Download

The /data directory is where apps store their private data:

  • Authentication credentials and database configs live here
  • On a production Mason device, you will not have access to /data, even for your own app, for security reasons

Interacting with files on a device​

This functionality is only available on devices running Mason OS v6.0.5+.

X-Ray gives you the ability to put files on your devices using the CLI, with the mason xray put-file command or download files with the mason xray get-file command.

Using put-file allows you to move files onto your production device.

Using get-file allows you to copy files from your production device.

X-Ray feature walkthrough​

This walkthrough only applies to devices running Mason OS v6.0.5+. Devices must be turned on and connected to Wi-Fi or cellular data.

For any of the below X-Ray features, a prompt will appear on the device when you initially establish a connection. This prompt needs to be accepted within 30 seconds in order for the device to successfully establish a connection to the Mason Platform. If the prompt is rejected, then the X-Ray command will fail.

Using X-Ray remote control (AKA desktop mode or VNC)​

Select your device in Controller. A device details tab will appear. Click “Launch Remote Session” at the bottom of the device details tab. This will allow you to remotely view and control your device screen. You can click the “Take Screenshot” button to capture a screenshot of what you're viewing.

View and filter your device's logs inside your Mason Controller account​

Select your device in Controller. A device details tab will appear. Click “View Device Logs” at the bottom of the device details tab.

Push or Pull a file to your remote device​

To do this, you'll need to have the Mason CLI installed on your computer.

To pull a file from the device, run:

mason --api-key <YOUR_API_KEY> xray get-file -p /sdcard/DCIM/Camera/superCoolPhoto.jpg -d <YOUR_DEVICE_ID>

And similarly, to put a file on the device, run

mason --api-key <YOUR_API_KEY> put-file -p "/sdcard/Download/superCoolFile.jpg" -f superCoolPhoto.jpg -d <YOUR_DEVICE_ID>

Use ADB to debug and interact with your device​

To do this, you will need to have the Mason CLI installed on your computer. Additionally, you'll need to have ADB installed locally. See this guide on how to set up ADB.

Run:

mason --api-key <YOUR_API_KEY> xray adbproxy -d <YOUR_DEVICE_ID>

This will prompt you to connect ADB locally on the port of your choice. You can do this by running adb connect localhost:5558 on your computer with ADB installed. After this is successful, you can interact with the device using ADB. An example would be running adb shell to bring up the shell interface on the device.