FAQs

Welcome to the Mason docs knowledge base!

This is our collection of FAQ content, please reach out to us at support@bymason.com if you are unable to find answers to the questions you have.

FAQ Categories

Device FAQs
Controller FAQs
Networking FAQs
SDK FAQs
X-Ray FAQs
Debugging FAQs
Connectivity FAQs

Device FAQs

Setup and provisioning

If I have multiple devices, can I automatically set up the email, password, and timezone on them in bulk?

Yes, Mason supports auto-provisioning, a key feature for our production clients that need to work with devices in high volumes.

Devices are provisioned when they are linked to your platform account. We can automatically add your devices to your account in your production devices.

What metadata can be auto-provisioned to production devices?

Along with auto-provisioning your account information to your new devices, we can automatically add names and groups to the devices as you bring them online for your business needs.

When devices are auto-provisioned into groups, the devices will automatically download the project configuration currently deployed to that group the first time it is turned on, if one exists.

auto-provisioning devices into groups is an Enterprise-tier feature

Factory resets / refurbishes

How does a factory reset work?

Your project configurations are not stored in the user space on your device by design. As a result, a factory reset will clear out your application data and any device settings such as APNs, display, security, etc..., but not your device configuration itself.

When a factory reset is performed, the device will reboot with the latest project configuration that was deployed to the device.

What causes a factory reset?

A factory reset is triggered when one of the following events occur:

Sending a WIPE_DATA command from Controller will cause the device to perform a factory reset while retaining the latest project configuration that was deployed to the device. Note: The device will remain in its original group.
Sending a REFURBISH command from Controller will cause the device to perform a factory reset, but also wipe the project configuration that was deployed to the device. Note: The device will be moved to the unassigned group and will need to be provisioned into an account. The device will disappear from the original account's unassigned group once the device is provisioned to a different account.
Moving a device to the unassigned group.
Moving a device from one group to another group with a different project deployed to it. Example: Your device is currently in group_a running project_a and you move your device to group_b where project_b is deployed. When the device moves to group_b it will perform a factory reset and then install project_b.
Moving a device from one group to another group with zero deployments and then deploying a new project. Example: Your device is in group_a running project_a and you move your device to group_b where there are no projects deployed. When the device moves to group_b, a factory reset will not be performed, since there are zero deployments in group_b. Only when a new or different project is deployed to group_b will the device perform a factory reset and then install the deployed project.
Deploying an older project to a group of devices. Example: Your device is currently in group_a, running project_a version 2. If you deploy project_a version 1 to group_a then the device will perform a factory reset and then install project_a version 1.

How do I perform a Factory reset?

Performing a Factory Reset on a Mason device deletes the app-specific data and settings on the device, preserving the device's latest deployed Project configuration.

Visit our guide for manually perfoming a Factory reset on your device

Performing a Factory data reset is NOT the same thing as de-provisioning your device. See our guide for refurbishing your device if you'd like to disassociate the device with your Platform account

How do I unlink my device with my Platform account?

If you need to change the account a device is registered to, you need to refurbish the device.

Visit our guide for unlinking your device with your Platform account

Can I clear my Mason OS configuration without unlinking the device from my Platform account?

Yes! If you move your device to the unassigned group, the currently deployed Mason OS configuration will be wiped from your device, and your device will stay provisioned to your account.

This happens because you cannot deploy Projects to your unassigned group. Your device will need to be connected to the internet to correctly receive the notification from Mason's Platform to wipe.

Visit our guide for clearing your Project (Mason OS) configuration

Project Deployments

How can I tell what Project configuration has been deployed to my device?

Here are the steps to determine what the latest project config has been deployed to your device

Visit the device details page in Mason Controller
Visit the software tab in the device details page on Mason Controller
Your Project configuration should be shown in the Configuration section of the software tab
If you'd like to see the Project configuration, you can click on the Project name, which links to the Project page

App updates are not working as expected?

Ensure your APK version code was incremented and the new APK is signed with the same certificate as the old APK.

Can I downgrade the Project configuration on my device?

Yes, You can re-deploy any project version to a device group, as long as it built successfully.

If you are using the config config_install_prompt_package, the end-user for your device will see a prompt and need to accept the downgrade

Visit our guide for deploying Project configurations to your devices

How do I force update my devices if config_update_install_time is set?

Overriding the config_update_install_time is not currently possible as the feature is designed to prevent updates occurring during unscheduled times.

If you need to force an update to a device with the config_update_install_time config set out of band, wiping the Project Configuration is your only option. Doing this will remove the config_update_install_time config from the device, and then you can deploy an update immediately to update your device.

Visit our guide for wiping your Project configuration

Connectivity and Network configurations

Is there a way to programmatically configure WiFi?

Today, there is not a device configuration to allow this level of control, but there are Android APIs for this that will work with a Mason device.

Learn about Android WifiManager

Can I configure the bluetooth scanning frequency on my devie?

Today, there is not a device configuration to allow this level of control.

If this is something you would like to see in our platform, send us a note

Sleep and lock states

Is there a way to keep my device awake for a long time?

Using the config_minimumscreenofftimeout config will allow you to configure how long the device waits before falling asleep.

You can also use Android APIs for this, in certain cases. Learn more about Android wakelock

When I reboot my device, it goes to the initial lock screen instead of straight to my app?

Using the direct boot package and disable_keyboard configs will bypass the lock screen completely and boot into your application the device is woken up, or turned on.

Can I remove or disable the lock screen on my device?

Using the disable_keyboard config will get rid of the lock screen completely when the device is woken up.

Configuring default controls

Can I disable or modify the power buttons on my device?

Using the config_longpressonpowerbehavior config will disable the power button functions.

Alternatively, you can use the config_globalactionslist to configure the default behavior and see other options for handling this use case.

Can I disable the volume control buttons on my device?

Today, there is not a device configuration to allow this level of control, but there are Android APIs for this that will work with a Mason device.

Learn more about Volume controls in an Android application

Can I disable the 'recents' button on my device?

Using the config_shownavigationbar hides the full navigation menu on your device. Today, there is not a device configuration to just hide the 'recents' button.

If this is something you would like to see in our platform, send us a note

Controller FAQs

Mason Controller

What browsers are supported?

Our supported browsers are listed here

How long do user sessions last?

User sessions are valid for 10 hours at a time. Please remember to sign out of Controller when working on shared computers!

What is the `unassigned` group?

Devices which have finished provisioning, and have not yet been assigned to a group, sit in an Unassigned group that cannot be deployed to. You can move devices in an out of this group at will.

If a device has previously received a Mason OS deployment, moving it to the Unassigned group will automatically clear the Mason OS configuration on that device and does NOT perform a refurbish.

Visit our guide for clearing your Project (Mason OS) configuration

I can't click on a device to see device details, is it broken?

A new UUID column has been added to better align the identifiers we use in Controller with our Fleet API and the link to view the device details has been changed as such. Some users who have toggled or rearranged columns prior to the UUID column being added may not see this column. If your device list looks like this you may be impacted:

missing column

You can resolve this issue by clearing the localStorage in your browser.

In Firefox, localStorage is cleared when these three conditions are met: (a) user clears recent history, (b) cookies are selected to be cleared, (c) time range is "Everything"

In Chrome, localStorage is cleared when these conditions are met: (a) clear browsing data, (b) "cookies and other site data" is selected, (c) timeframe is "from beginning of time". In Chrome, it is also now possible to delete localStorage for one specific site.

In IE, to clear localStorage: (a) Tools--Internet Options, (b) General tab, (c) delete browsing history on exit, (d) ensure "Cookies and website data" (or "temporary internet files and website files") is selected, (e) consider unchecking "Preserve Favorites website data" at the top

In Safari: (a) Click Safari (b) Preferences (c) Select the Privacy tab (d) Click Remove all website data (e) Click Remove Now

Opera: Despite excellent articles on localStorage from the Opera site, I haven't yet found clear (non-programmatic) instructions to users on how to clear localStorage. If anyone finds, please leave a comment below this answer with reference link.

Why is my OS shown to be out-of-date?

At mason, a device's OS is marked as out-of-date when the version of Mason OS that is installed on the device doesn't match the version of Mason OS that is deployed to the rest of the group that the device is apart of. The device may have an older version of Mason OS or it may have a newer version. To check the versions of Mason OS, perform the following steps:

To check the version of Mason OS that is deployed to a device, select the device on the devices page and then navigate to the software tab at the top of the screen. There it will list the current Mason OS version.

To check the version of Mason OS deployed to a group, select the group from the groups page and click the most recent Mason OS deployment in the deployments section.

If the Mason OS version of the device is older than the one deployed to the group, then the device had an issue with its last deployed update. Verify it's connection is strong and have the device check for updates again. If there are still issues, contact Mason support for help.

If the Mason OS version is more recent on the device than in the group then the out-of-date message can most likely be safely ignored. Newer versions of Mason OS, especially ones that differ only by a minor versioning, are likely backwards compatible with the functionality of older versions of Mason OS. See the Mason OS versioning page for documentation. Mason devices are not able to downgrade their version of Mason OS without being reflashed so f you want to update the entire group to use the most recent version of Mason OS, you can run the following command using the Mason CLI:

mason deploy ota mason-os <OS version> <group name>

Networking FAQs

DNS Setup

IP allocations for cloud services are, by design, ephemeral. It is not recommended that whitelisting be performed by IP address range or CNAME but rather by domain name.

This ensures that any changes to IP addresses will allow the service to remain available without opening a large range of IP addresses needed for cloud-based environments.

App Name	Domain	Port
Mason Platform & API	platform.bymason.comapi.bymason.comlogin.bymason.com	443443443
AWS S3	mason-registry-production.s3.amazonaws.comd18atil0qfsuv.cloudfront.net	443
Auth0	bymason.auth0.com	443
Pushy	mqtt.pushy.me	1883
Firebase/Crashlytics	*.crashlytics.com e.crashlytics.com settings.crashlytics.com reports.crashlytics.com	443443443443
Android NTP server	2.android.pool.ntp.org	123

SDK FAQs

I'm getting a ClassNotFoundException when attempting to use Mason Framework

Ensure you have declared your usage of the library in your AndroidManifest.xml:

<uses-library android:name="masonamerica.platform" />

I'm getting a SecurityException when attempting to use Mason Framework

Ensure your application is declared in your Project Configuration and that the project has been deployed to your device.

For development you only need to deploy a configuration with your application declared once.

Then you can use install newer versions of your apk as usual using your development tools without needing to update your APK version in your project config.

How can I determine if my application is running on a Mason device

The simplest way to determine if your app is running on a Mason device is by checking Build.BRAND

if (Build.BRAND.equals("Mason")) {
  // running on a Mason device. use Mason Framework APIs
}

Learn more about the Android Build class here

How can I use the Mason Framework SDK with an app development framework like Xamarin

Integrating the Mason Framework stub jar in a Xamarin application requires:

Creating a wapper JAR around the masonstubs.jar
Creating an Android Bindings Project that includes your wrapper JAR as an EmbeddedJar
Adding the Android Bindings Project to your Xamarin application and updating your manifest as mentioned in the Setup instructions above

X-Ray FAQs

How do I disable X-Ray

By default, the X-Ray feature is enabled once you upgrade your devices to Mason OS 2.9.0+. To disable the X-Ray feature, add the config config_xray_enabled: false to any project config

os:
  configurations:
    mason-core:
      config_xray_enabled: false

When using X-Ray, I'm seeing an error message "No response from the device, it may not be connected to the network"

Your device may not be connected to the internet. Here are some steps you can take to solve this problem

Check the WiFi or cellular network connnections on the device
Check the device's ONLINE/OFFLINE status in the Mason Controller device info page. If Controller is reporting your device as OFFLINE, X-Ray will not work
Locate and try turning WiFi or cellular off and on again
Locate and reboot the device

When using X-Ray, I'm seeing an error message "The requested device was not found"

Ensure your Device ID matches what is reported in Mason Controller. Here are some steps you can take to solve this problem

Try visiting the device details page for your device inside Controller - ex: https://platform.bymason.com/controller/devices/[DEVICE_ID]
If you see an error message, the DEVICE_ID you are using does not map to a device in your Platform account
If you see the device details page, verify that the device information on the details page matches what you expect to see

When using X-Ray, I'm seeing an error message "Access to the requested device is denied"

When using X-Ray, you must supply an API key that has the right permissions associated with it.

Make sure your device is running Mason OS 2.9.0+
Make sure the API Key has the FLEET:ADMIN scope for Mason OS versoiun 2.9.0-6.0.6 and XRAY:ADMIN for 6.0.6+
Verify the latest project configuration deployed to the device does not have config_xray_enabled: false on it

Click here if you need help determining which project has been deployed to your device

Click here to learn more about using an API key with the Mason CLI

When using X-Ray, I'm seeing an error message "Connection was not accepted on the device within 30 seconds"

Every time X-Ray attempts to connect to a Mason device, the device user will see a prompt on their device screen. The user must accept the incoming X-Ray connection within 30 seconds for X-Ray to connect to the device, and the user can optionally deny the request.

If you are seeing this error consistently, you may need to get in touch with the end user of the device.

For Mason OS 6.0.6+, users only need to accept the connection when running you are adbproxy command from the Mason CLI on the device.

When using X-Ray, I'm seeing an error message "An X-Ray session is already active on this device"

Today, the Mason Platform only supports one X-Ray session per device at a time, and there is already an active X-Ray session on the device. The running session must be closed properly before a new session can be started.

If you are having problems with this, or would like to see Mason support multiple X-Ray connections to a single device, contact us at sales@bymason.com

Debugging FAQs

How can I collect logs from my device

You can use adb to collect logs from a device you have physical access to. Visit our guide for using adb to collect logs from your device

Alternatively, you can use X-Ray to remotely view logs. Visit our CLI documentation for the mason xray logcat command

Do Mason devices work with adb

Yes! Visit our guide for using adb to collect logs from your device

Connectivity FAQs

What happens if I need more data to test?

If you need more than 500mb of data in a 30 day period, or you require more than 90 days for testing connectivity on a Developer Kit, contact solutions@bymason.com or your dedicated account manager.

My SIM isn’t working - what’s wrong?

If your SIM is installed correctly, but your device is not receiving connectivity, please check the following:

Ensure the APN is set to super and correctly selected
Ensure that roaming is turned on
Ensure the SIM is installed correctly
Check the Mason Connectivity platform to see if you have reached your 500MB data cap for the period
Check if your SIM has been active for longer than 90 days

You can also contact support@bymason.com to help troubleshoot.

My SIM was working, but stopped - what’s wrong?

If your Mason Global SIM was working, but stopped unexpectedly, please check the following:

Check the Mason Connectivity platform to see if you have reached your 500MB data cap for the period
Check if your SIM has been active for longer than 90 days
Check if the APN is set correctly (occasionally, when switching towers, some devices may reset the APN).