Deployment Guide

In this document, we’ll discuss how to use the Mason platform to deploy builds, apps, and OS updates to your fleet of devices. We’ll also discuss best practices for testing updates and how to leverage Controller groups for development.

Deployment Overview

The Mason platform offers robust capabilities for deploying project builds, applications, and OS updates over-the-air (OTA) to a fleet of devices. These OTA updates are essential for keeping devices secure and functional, ensuring they run the latest versions of the OS and applications with minimal disruption. Deploying these updates correctly is vital to maintaining operational continuity while integrating new features and security enhancements.

Mason supports three types of deployments: project builds, applications, and MasonOS updates, each with its own considerations.

A properly configured fleet will survive factory resets- this is a core idea with the Mason platform. Once a project is deployed, your devices can be rebooted or factory reset and they will always return to the state defined in the project.

Project Builds

Builds include everything in a project like apps, start-up screens, animations, and settings. They're sent over-the-air and installed through the device's update system, which requires an automatic reboot. These builds are meant to stay, even after a factory reset. You can update them anytime. If you ever need to remove a build from a device, just follow the steps to move it to the unassigned group.

Applications

Mason's platform allows you to update individual apps without needing a full device reboot, ensuring your fleet can receive app updates without downtime. This feature supports fast development cycles with frequent updates.

When you deploy a new version of an app, existing data and permissions are retained. However, if a device undergoes a factory reset, these apps are automatically reinstalled over the network. To ensure devices are ready to use immediately, all necessary apps should be included in production builds.

*Note that removing an app from the project won't remove it from devices in the group.

MasonOS Updates

Mason periodically publishes new versions of MasonOS containing critical security updates, bug fixes, new features, and other changes. Unlike typical consumer OS updates, Mason gives you control over when these updates are applied. MasonOS updates are published by Mason and thoroughly tested, but the responsibility of testing and deploying these updates lies with our customers. This approach offers greater control and flexibility, catering to your specific needs and operational rhythms.

	Install time*	Requires reboot**	Survives factory reset	Data usage (per device)
Project Build	~5 minutes	Yes	Yes	Size of APKs + assets
Application	5-10 seconds	No	No	APK size only
OS Update	~15 minutes	Yes	Yes	Varies, usually < 100MB

• *Install time does not include time taken to download the payload, which can vary depending on network type and conditions.
• **Multiple reboots may be required depending on how many patches need to be installed, this may increase installation time

Deploying to your Fleet

For full documentation on managing and deploying projects using Controller and the CLI, please visit our projects guide.

Automatic Deployments

It’s important to understand that deployments are associated with a group. When a deployment is started, all devices in the group will be updated. The platform also does automatic deployment when a device is moved into a new group or initially provisioned. In these cases, the device will immediately install the build, apps, and OS updates. Installing these updates initially may take several reboots but the process is automated and does not require any intervention.

Certain types of operations will trigger an automatic factory reset of the device. This happens under several circumstances:

• Moving a device to the unassigned group
• Moving a device between groups with different configurations
• Downgrading a project

Factors Affecting Deployment

Mason deployments can be affected by configurations which alter the required on-device prerequisites and behavior.

Network Type and Availability

By default, OTAs are accepted regardless of whether the device is on the mobile network or on WiFi. It may be preferable to accept updates only when the device is on WiFi in order to avoid data overages. To change this from the default, add this snippet to your YAML:

configurations:
  mason-app-updater:
    config_allow_download_over_metered: false
  mason-fota:
    config_allow_download_over_metered: false

Battery Level

OTA on a device will not start unless the device is either charging and the minimum battery level is met. This is to avoid any issues with loss of power during the update process. This level can be configured by setting config_update_install_battery_threshold, the value is the percentage of full charge required before an update will begin (note: the system reserves 20% battery capacity as overhead).

configurations:
  mason-app-updater:
    config_update_install_battery_threshold: 30
  mason-fota:
    config_update_install_battery_threshold: 30

Push vs Pull

Devices can request updates from the platform by using either a push or pull strategy. With push, devices will immediately process the update command. Polling can also be used for update checks, in which case devices will check with the platform on a configurable interval once the prerequisites are met. Deployments started via Controller will always use the push strategy. When deploying using the CLI, add the “--push” flag to use the push strategy.

configurations:
  mason-fota:
    # Target 24-hour install time for OS updates that have been downloaded to the device. This must be in a 24-hour format, "hh:mm", where hh = 0-23 and mm = 0-60.
    # Passing a value of -1 (default) instructs the device to attempt a system update install as soon as it is downloaded. For example, if you want the device to attempt a system update install at 8:00 AM (device time), use config_update_install_time: 08:00.
    config_update_install_time: -1
    
    # The frequency for which to check for updates from boot, default is 24 hours
    config_update_check_frequency: 24

    # The network type required when checking for updates, integer constant
    # 1: NETWORK_TYPE_ANY The default update check network type, allows checks over any network
    # 2: NETWORK_TYPE_UNMETERED The update check requires network connectivity that is unmetered
    # 3: NETWORK_TYPE_NOT_ROAMING The update check requires network connectivity that is not roaming
    config_update_check_network_type: 1

    # When true, only performs update checks when the device is idle.
    config_update_check_when_idle: true

    # When true, only performs update checks when the device is charging
    config_update_check_when_charging: true

    # If true,the user will be prompted with a countdown dialog box prior to a system install. The timeout is defined by config_prompt_timeout_count (default 60 seconds). If False, the user will not be prompt with a countdown dialog box. System update installation will start immediately once available.
    config_update_prompt_prior_to_install: false

  # The time (in seconds) a user has before the pending update runs automatically from the update prompt.
    config_prompt_timeout_count: 60

  # The name of a package which will receive a broadcast message before any installation takes place. The application can make it's own determination of when to continue with the update. See the documentation for full syntax.
    config_install_prompt_package: ""

Behind the Scenes

The OTA process works as follows:

1. A deployment is started
   1. If it’s a push deployment, Mason pushes an update command to all devices in the group. Push is the default mode when a deployment is started via Controller. Use the –push flag when using the CLI.
   2. If polling is used, the update will start when the check interval has elapsed (see above)
2. Each device will check if prerequisites (connectivity, battery level, storage) are met, then requests to download the update payload from the platform. If prerequisites aren’t met, the update is queued and retried later based on config_update_check_frequency. Otherwise the device begins downloading the payload. If the download is interrupted for any reason (network disconnected, power loss, etc) it will be resumed as soon as the prerequisites are met again.
3. Once the payload is downloaded, it’s installed by the system. Application updates are installed immediately, while builds and OS updates require devices to reboot.

Monitoring a deployment

The progress of a deployment can be monitored in the devices view in Controller. Each device will show several status fields depending on the current state.

• Project Status: Whether the project build is up to date
• Apps Status: Whether all applications are up to date
• OS Status: Whether MasonOS is up to date

As devices are updated, these statuses will change from "Out of Date" to “Updated”. Depending on network conditions and other factors, deployments can take some time to complete. If devices are not showing as up to date, the next step is to understand what happened. Deployments can fail (or take a long time) for many reasons, most often due to poor network connectivity or low battery levels. See the troubleshooting section below for how to debug these issues.

Using Groups for Deployment Phases

Mason's platform facilitates the creation of specialized environments through the use of groups. Groups enable you to organize devices based on their operational purpose, location, or environment (such as production, staging, and development). This organization is essential for efficient management, testing, and deployment of builds, applications, and OS updates. Each group can have a different build deployed to it, and each build can contain different applications and resources. Groups must consist of devices with the model family and API level.

Example:

Your point-of-sale system project consists of thousands of handhelds at retail outlets. All of these devices are in production, and should only get the most stable software. A second group of devices are in the hands of application developers. A third group of devices are with your test team or early access group. Organize and maintain your project this way:

1. Create the groups: salesapp-prod, salesapp-test, salesapp-dev
2. Deploy your production project to salesapp-prod
3. Configure your CI system to upload new builds of your app in your development project to salesapp-dev using the Mason CLI
4. Periodically promote your development builds to salesapp-test as part of your release cycle
5. Deploy your new application to salesapp-prod when it’s ready!

Grow your test capabilities by setting up a group of devices for running automated tests. Your CI system can deploy new versions of your APK as well as associated instrumentation and test case APK(s). The test output can be collected using X-Ray and used to determine pass/fail status as part of your test pipeline.

Naming Conventions

Mason does not enforce any particular naming scheme for groups, but we recommend that you choose names which correspond to their function, location, and/or environment. A good example of a group name would be “salesapp-seattle-prod-1”- this name encapsulates the application id, the location, the environment, and a group id number which can be used for other purposes.

Troubleshooting Deployment Issues

Whether you're deploying builds, apps, or OS updates, various challenges can arise. Identifying and resolving these issues promptly is key to maintaining the integrity and performance of your device fleet. Devices may fail to update for many reasons including:

1. No network connectivity - Ensure that the device is online and can download files over HTTPS, and ensure that SIM is installed and activated if using mobile data.
2. WiFI required for update but not available - Ensure that WiFi is configured on the device or modify your configuration to allow updates on mobile networks.
3. Low battery - The device must have at least 20% charge (check this) or be charging for updates to install
4. Low storage - Ensure that applications on the device are not using up all available storage space

When deploying new versions of your application, especially to test or development environments, problems can become quickly apparent. If an application is not behaving appropriately or is crashing on startup, this will be very obvious in the logs. Use adb or X-Ray to monitor the device log and check for more information or stack traces. For deeper debugging, you can use X-Ray to connect your device to Android Studio and debug your application in real time.

If a device fails to update and is still showing “out of date” in Controller, the update will remain queued until the device is online and the above prerequisites are met. In this case we recommend physically inspecting any devices which are not updated after an hour to ensure they are operating correctly. Check our support site for additional information.

Checking for Pending Commands

Mason uses a push messaging system to send commands to devices, which relies on network connectivity. If your fleet isn’t updating or responding to other commands such as reboot or use of X-Ray, you can check if there are pending commands in Controller.

If you see outstanding commands in the list, it’s likely that the device has a connectivity issue. Verify that the device is powered up and connected to the network and try again. Commands in the queue will automatically be delivered when the device comes online.

Additionally, an update check can be forced from the device by clicking “Check for updates” under Settings -> System.

Updating MasonOS

Updating to new versions of MasonOS is a crucial process for maintaining the security, efficiency, and functionality of your fleet. These updates contain critical security patches, feature enhancements, and bug fixes essential for the optimal operation of the devices. MasonOS releases undergo extensive testing, but you should perform your own testing before deploying a new version to production. Here are some best practices to follow to ensure a smooth deployment:

1. Review Release Notes: Before initiating an update, review the latest Mason OS release notes. These notes provide vital information on new features, bug fixes, security enhancements, and any known issues.
2. Compatibility Checks: Perform thorough compatibility checks with your applications and configurations. This ensures that the new OS version will function seamlessly with your existing setup. You should also follow Android best practices for ensuring application compatibility across new OS versions.
3. Test in a Controlled Environment: Use a staging or development group of devices to test the new OS version before a widespread rollout. This helps in identifying any potential issues in a controlled environment without impacting your operation.

Compatibility Checklist

Mason recommends verifying each of the following items as part of your test process before deploying a project to your production environment:

• Correct splash screen is displayed at boot
• Boot animation is smooth and aesthetically pleasing on the device
• Mobile network is connected
• WiFI network is connected (if configured)
• Configuration and customizations are applied correctly
  • Status bar
  • Lock screen
  • Notification area
  • Quick settings
• Correct application versions are installed
• Direct boot package is automatically started (if enabled)
• Lockdown controls (kiosk mode, lock task mode) are correct (if enabled)
• Device performance is good, swiping the screen is snappy and smooth
• Verify correct device operation with network disconnected
• Ensure the appropriate update rules are selected to minimally impact operation
• Configured peripherals are connected
• Application specific testing

FAQ

1. What are the steps to only change the application (APK) for a device or device group without causing the device(s) to go through a reset? ( stef/Christopher/Brenda to discuss, the ways to install and uninstall APK( adb, Xary, Config, etc.) will get different results. Plan to get a table of what options and what are the results per, cons and pros, identify potential bugs.
2. User specified update behavior ( call back to app, and user can make decision what device shall do). Config_install_prompt_package without sample code(mason gitlab), how to create config or sample app ( tbd)
3. Try to ensure that your config does not allow your client to lock you out of your device with a lock screen code or block the network connection which would prevent you from getting device updates or sending factory reset and refurbish commands