Learn the Mason Platform in 10 Easy Steps!

The Mason Platform provides powerful tools to allow you to build, deploy, and manage your own Android-based custom devices. If you haven’t already read about the capabilities, we recommend reading the introduction first.

Introducing iHeartLives

Let’s pretend you’re in charge of software for iHeartLives, a company that builds heart rate monitoring wearables for patients in hospitals. These devices send data to an Android app running on a dedicated device which must be easy to use, always running, frequently updated, and resistant to tampering. The best way to create a great user experience and ensure unparalleled security and reliability is to run the app on a device where you have full control over the hardware and OS. Rather than tie your company’s core product to a consumer Android device, let’s walk through the process of prototyping our own solution using a Mason Developer Kit.

Check out this overview video of the iHeartLives use case

Before Your Start...

Before you get going, make sure to download or clone the Mason Starter Pack which will have all the resources you need to follow along in this demo including: iHeartLives demo app, Pre-Configured YML file for your OS, Custom iHeartLives boot-up animation

If you’d like to use your own app, you can either follow along and replace all references to the iHeartLives-Demo-V1.apk with your own APK, or you can skip the quick start and dive right into the full documentation.


A Rudimentary “Product Specification”

The goal of this demo is to build a purpose-built Android device dedicated to running our iHeartLives application. Below are the basic product specs we’ve outlined for the prototype:

  1. The app should run in a “kiosk mode” (sometimes called “single use” mode). This will create a better experience for the end-user and minimize the ability to tamper with the device.
  2. Limit the Settings menu so the user can only access wifi, cellular, bluetooth and get basic information about the device.
  3. Disable the Status bar so the user cannot accidentally turn wifi or cellular off.
  4. Disable the camera for privacy
  5. Add a boot-up animation to create a white-label experience

Our demo will also include a few more customizations and some rules around how OS and app updates should be deployed to the devices.

Before you begin…

In order to get started, we will need a few things to be ready.

  1. A Mason Developer Kit: You can order one by filling out our request form. See the introduction page for more info what a Developer Kit is.
  2. A Mason Platform Account: A Mason Platform account gives you access to Mason’s various tools and dashboards. Visit the Account Setup page to learn how to get setup.
  3. Software Setup: To use the Mason Platform, you will want the Mason CLI tools.
  4. Mason Starter Pack: Download the Mason Starter Pack, which includes resources for this demo including: iHeartLives Demo APK V1 and V2, a pre-configured YML file for your custom OS, and a custom boot-up animation.

Once we have these squared away, it’s time to get going!

1. Setup the developer device

With your developer device on hand, follow the instructions to setup the device. Upon completion, your device has been activated and we’re ready to start using the Mason developer tools!

2. Setup the Mason CLI and login

We need the Mason CLI up and running to begin developing our prototype device. To ensure it’s installed correctly, just type: mason

$ mason
Usage: mason [OPTIONS] COMMAND [ARGS]...

  mason-cli provides command line interfaces that allow you to register,
  query, build, and deploy your configurations and packages to your devices
  in the field.

  -d, --debug
  -v, --verbose        show verbose artifact and command details
  --access-token TEXT  optional access token if already available
  --id-token TEXT      optional id token if already available
  --no-color           turn off colorized output
  --help               Show this message and exit.

  build     Build a registered project.
  deploy    Deploy artifacts to groups.
  login     Authenticate via user/password.
  logout    Log out of current session.
  register  Register artifacts to the mason platform.
  stage     Stage a project.
  version   Display mason-cli version.

Once installed, let’s ensure we’re logged in using the credentials we set up earlier by running mason login.

$ mason login
User: demo@iheartlives.com
User authenticated.

We’re now ready to use the tools.


If your credentials have expired (typically after a day), your locally saved token becomes invalid and you will need to login again with the same mason login command via the CLI tool.

3. Create a project

The first step in creating our dedicated device is to create a project. You can read up on Mason Projects on this page. This allows us to associate a configuration (that you’ll create soon) describing our device’s included applications, media and behavior.

It’s now time to visit the Mason Platform website to get started with creating a project. We login using the Mason Platform account:

Login screen

Once we have successfully logged in, you can navigate to the Projects screen, where you should be able to see all projects we have that are currently active. Note that this will be empty to begin with as we have not created any projects yet.

Default Projects

Now lets create project by clicking on Actions > New Project and call it MonitoringAssistant. Notice that the identifier for the project has been converted into all lowercase. The Mason platform uses names that are not case sensitive. From now on we will refer to this project using its identifier monitoringassistant.

Create Project Action

Name Project

As an FYI, we chose the D450 device for this project, but you should pick whatever model Dev Kit you have ordered. Upon creation we should be able to see our newly created monitoringassistant project. For this demo, we will also select API Level 25, which corresponds with Android 7.1.X.

Next, we’ll create a a group for our device.

4. Create a group

Groups can be used to logically separate a collection of devices for different project configurations or targeted deployments. For more detailed information, read the page on Mason Groups.


Upon activation, a device is automatically placed in the unassigned group – a special group used to park devices that are in the process of being configured. Every device must live in a group before you can deploy a project’s configuration to it.

Let’s create a group named development to house our developer device. Navigate to the Groups page, select Action > Create Group > give our group a name and description > select Create.

Create Group Action

At this point, the Group page updates itself to show the new group.

Lastly, navigate to the Devices page, select the checkbox next to our device – the only one currently listed – and select Action > Move > development.

Move Device

On the Devices page, you will now see the device in the new group.

Device in Group

We’re now ready to upload our apps and start building out a configuration to meet our specifications.

5. Publish the app

To start, we need to make sure that we have published the app to the Mason Platform. Once published, the app can be included in a configuration and baked into the OS as a system app, or it can be deployed independently to a group of devices as a new app or app update. For the purposes of this walk through, you can use the iHeartLives-Demo-V1.apk found in the Mason Starter Pack.

From the Mason CLI, you’ll want to run mason register apk iHeartLives-Demo-V1.apk.

$ mason register apk $ mason register apk iHeartLives-Demo-V1.apk
------------ APK ------------
File Name: iHeartLives-Demo-V1.apk
File size: 7507136
Package: com.iheartlives.monitor
Version Name: 1.0.0
Version Code: 1
Continue register? (y)y <enter>
Connecting to server...
Uploading artifact...
100%|██████...███| 1.29M/1.29M [00:08<00:00, 156Kkb/s]
File upload complete.
Registering to mason services...
Artifact registered.

This publishes version 1 of our application to our Platform (see below on how to deploy the app to your Dev Kit). If you’re curious, once deployed, the app will look something like this:

Monitoring App Screenshot

Itching to Jump Ahead?

Once the APK is registered, you can deploy a stand-alone app install from the CLI by running mason deploy --push apk com.iheartlives.monitor 1 development. After a few seconds, you should see the app install in the background. Swipe up from the home screen to view your apps, and look for the app titled Monitor with a heart icon. Keep in mind, this is a demo app and is meant for a kiosk use case.

6. Publish your bootup animation

Android bootup animations are easy to make once you’ve learnt the basics. You can read up on how to make one here but we’ll just use one we already created, which is included in your Mason Starter Pack

Let’s publish the first version of this animation to the Mason registry to be able to refer to it from our configuration.

From the Mason CLI, run mason register media bootanimation.zip iheartlives-anim bootanimation 1

$ mason register media bootanimation.zip iheartlives-anim bootanimation 1
----------- MEDIA -----------
File Name: ./bootanimation.zip
File size: 721002
Name: iheartlives-anim
Version: 1
Type: bootanimation
Continue register? (y)
Connecting to server...
Uploading artifact...
100%|██████...███| 721K/721K [00:04<00:00, 156Kkb/s]
File upload complete.
Registering to mason services...
Artifact registered.

This publishes version 1 of our bootup animation for use with our device. If you’re curious, it looks like this:

Boot Animation

7. Create and register a configuration

We are now ready to build a configuration for the device. A configuration describes the exact behavior of the system software on the device such as OS features, included applications, etc. Read the Project Configuration page for more information.

For the purposes of this Quick Start, we’ve included a predefined configuration file in the Mason Starter Pack named monitoringassistant-v1.yml. You can find instructions for registering your configuration below, but as an FYI, when opened, it should look like this:

  - name: com.iheartlives.monitor
    package_name: com.iheartlives.monitor
    version_code: 1

  name: monitoringassistant #Project Name
  version: 1  #Project Version -- Increase every time you change a configuration
      direct_boot_package: "com.iheartlives.monitor" #Boots directly to specified app and locks it into kiosk mode
      disable_status_bar: true #disables the status bar for locked down experience
      disable_camera: true #Removes camera from the OS
      disable_screen_capture: true #Disables screen shots 

      config_default_tile_list: #List of settings made available on device
        - wifi
        - bluetooth
        - sim
        - about

    android: #Modifying basic features of Android
      config_lowBatteryWarningLevel: 25 #Shows low battery warning at 25%
      config_supportAutoRotation: false
      config_shortPressOnPowerBehavior: 1 #Sleeps device on single short press
      config_cameraDoubleTapPowerGestureEnabled: false #disables camera launch on double tap
    mason-fota: #Controls how the OS is updated
      config_allow_download_over_metered: true #Allows updates over cellular
      config_update_prompt_prior_to_install: false #Disable prompt so users cannot cancel an update
      config_show_download_in_downloads_ui: true 
    mason-app-updater: #Controls how apps are updated
      config_allow_download_over_metered: true #Allows updates over cellular

    name: iheartlives-anim
    version: 1

Let’s register the above configuration now using the Mason CLI by running mason register config monitoringassistant-v1.yml.

$ mason register config ./monitoringassistant-v1.yml
--------- OS Config ---------
File Name: monitoringassistant-v1.yml
File size: 494
Name: monitoringassistant
Version: 1
Continue register? (y)
Connecting to server...
Uploading artifact...
100%|██████...███| 494/494 [00:00<00:00, 654kb/s]
File upload complete.
Registering to mason services...
Artifact registered.

That’s it, and we’re now ready to build the first version of our dedicated device!


Note that since the version of the config is baked into the YML, we recommend putting the version name on the file as well to easily tell during development what version of the configuration you’re working with.


Note that you are allowed to re-publish configurations of the same version number for your project, causing the new version to override the previous one. However, we recommend bumping your configuration’s version each time any changes are made, as well as placing your configuration in a version control system such as git. Alternatively some prefer to put the version in the file name to easily tell during development what version of the configuration you’re working with.

8. Issue a build request

In order to deploy that new OS configuration onto a device, we need to initiate a build for it. A build is a process that compiles your configuration file, included apps and media into an OS update. When complete, that OS update can be deployed to a group of devices. Once you invoke a build, you can see the build status under the specific project (in this case monitoringassistant)in the Mason Projects Tab.

Let’s start a build for our configuration using the CLI mason build monitoringassistant 1

$ mason build monitoringassistant 1
Queueing build...
Build queued. You can see the status of your build at https://platform.bymason.com/controller/projects/monitoringassistant

Now let’s go check on the status of our build.

9. Check the Projects tab

Now we switch back to the Mason Platform Projects tab to check that this build task was actually queued. In the ‘monitoringassistant’ project, we should see the build in progress.

Build in progress

You may need to refresh the page occasionally to check if it has completed. Once the build completes (typically about 5 minutes), we should see the status updating to SUCCESS.

Build successful

Our build is ready and we can now deploy it to our device.

Streamlining the Process

In the future, you can run the mason stage command and include the name of your YML file, which will automatically register your project and then run a build for that project.

10. Deploy your configuration

This is the critical step that ensures our configuration makes it down to the device(s) in a group. For this, we go back to the CLI and deploy our config using mason deploy --push config monitoringassistant 1 development.

Breaking Down a Deploy Command

The deploy command can be used to deploy apps, configs, OS updates, or security patches using mason deploy TYPE [OPTIONS] NAME VERSION GROUP.

In our demo here, the --push option will send a notification to all of the devices in the development group, causing them to update immediately, overriding any existing update policies on the devices (except when a value is set for config_update_install_time).

$ mason deploy --push config monitoringassistant 1 development
---------- DEPLOY -----------
Name: monitoringassistant
Type: config
Version: 1
Group: development
Push: True
Continue deploy? (y)
Continuing deploy...
monitoringassistant:1 was successfully deployed to development

You should now see a popup on your device indicating that an update has been downloaded and ready to install. See our FAQ section if you don’t see the device updating after a few seconds. Note: This pop-up can be removed or customized for future updates. Check out the mason-fota Configurations under your devices to learn more.

Common Reasons You Might Not See An Update

If you don’t see an update start after a few seconds, here are a few things you may want to check:

  1. Is the battery over 20% charged? The default configs require the battery level be at least 20%.
  2. Are you connected to wifi? Downloads over cellular can take longer, so the OTA may be downloading but you haven’t seen the device reboot yet.
  3. Is the date/time correct? Check the Date & Time settings to make sure they are both correct.
  4. Is the device in the right group?

To check the progress of an OTA or see if a download is available, you can go to the Device settings menu > About > System Updates > Check for Updates.

FOTA popup

Once the update finishes installing, you should have our iHeartLives application running in a kiosk mode on a dedicated device!

And that’s it for our Quick Start Demo! There is much more to the Mason Platform, but this should provide a taste of what is possible. We invite you to read the docs to learn more about the real power of the Mason Platform, here are a few more things you can try out as you explore the Mason Platform:

Some things to try next…

Deploy an App Update

The Mason Platform gives you full control over app updates so you can make sure end-users always have the latest version of your app installed. This can drastically reduce support tickets and improves the overall user experience. To test an app update, register V2 of the iHeartLives app included in the Mason Starter Pack, and then deploy it to your development group.

mason register apk iHeartLives-Demo-V2.apk mason deploy --push apk com.iheartlives.monitor 2 development

You should see the app install silently in the background and refresh, updating the colors of the app.

Explore Remote Commands

The Mason Platform includes a number of remote commands that can be used by your team to help manage devices in the field. These actions include:

  1. Ping: Ping the device for the latest status update.
  2. Check for updates: Remotely force the device to check if there are updates available.
  3. Reboot: This action will reboot the device. The device will be offline and unreachable until it reboots.
  4. Shutdown: This action will power off the device. The device will be offline and unreachable until it is powered back on.
  5. Wipe data: This action will perform a factory data reset on the device. All user data will be removed. Configuration state will be retained.
  6. Refurbish: This action will fully reset the device. All configurations, login credentials, and group associations will be removed.

Try remotely rebooting your device. You will need to copy the device ID > go to Actions > select More actions > choose Reboot > paste the device ID > and select Send command

Reboot Device

Explore Configuration Options

There are over 500+ different configurations available. Check out our Configuration Glossary for your device type to start exploring.

Dive Into Our SDKs

We have two SDKs available in Beta that you can use in your application. Our Mason Framework SDK will give your app privileged abilities in the OS, and our Mason Platform SDK gives your app access to the Mason Platform, allowing you to retrieve information like device name, group, imei, serial, and more.

Test Our Management APIs

The Mason API lets you perform operations against your fleet of devices to help automate processes and connect Mason to your internal systems (e.g. inventory management). We’ve helped customers 30x their operational efficiency, check out the docs to learn more and start testing them out yourself!