Mason Docs


The Mason Platform provides powerful tools that allow you to build a single-use device dedicated to your application. We give you full control over the hardware, OS, updates, and supporting services so all you need to worry about is building great software. If you haven't already read about the capabilities, feel free to take a look at the introduction to the Mason Platform first. In this guide, we'll cover how to build a custom Android OS with an app in kiosk mode, custom settings menu, disabled status bar, disabled camera, and more!

What you'll learn

Introducing iHeartLives

For the purposes of this demo, we’ll pretend you’re in charge of software at our fictional company, iHeartLives. At iHeartLives, we produce a heart-rate monitor that is paired with an Android device dedicated to running our application. The use case is simple: send data via Bluetooth from the heart rate monitor to our app running on the device, which can then relay that data to our backend systems in the cloud. For our use case, it’s important that:

  • We have a simple user experience for an elderly demographic
  • The device is completely locked down to only our app
  • The app is always up-to-date, and the device can’t be tampered with

For a bit more background info, check out this video about iHeartLives:

Getting Started

In order to get started, we’ll need a few things:

  1. A Mason Platform Account: Visit our Sign Up page to create an account.
  2. A Mason Developer Kit: You can order one from our store. If you'd like to chat with us before you buy you can do so by filling out a request form.
  3. CLI Version 1.5+ Installed: Visit our setup instructions to learn how to install it.
  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.

Setup Your Dev Kit

To complete this step, you will need a Mason Account and a Developer Kit. You can create an account here. Once you sign up you should see an Order a Dev Kit button or you can access the page directly here.

Power On and Connect

The first thing you’ll need to do before registering your device is make sure you have a stable wifi or cellular connection. If you don’t have a SIM card inserted, you’ll also need to make sure that the time and date are set correctly before connecting to wifi. To manually set the time and/or date, you’ll need to toggle off the Automatic date & time or the Automatic time zone options, and manually set the appropriate settings. Once done, make sure to toggle the Automatic date & time or the Automatic time zone options back on.

Log In with Mason Account Credentials

Once you are connected, you can move forward by clicking SETUP YOUR DEVICE, and logging in with your Mason Platform account credentials.

If you sign in successfully, you may see the device checking for and downloading any available updates. After that has succeeded, you will be left with the default home screen which we will be customizing in the next steps.

Create a Project

The first step in creating our dedicated device is to create a project. Projects allows us to associate a configuration (that you'll create soon) describing our device's operating system, included applications, media, and behavior. You can read up on Mason Projects on this page. First, log into the Mason Platform using your credentials created in the Getting Started section. Navigate to the Projects screen, where you can see all active projects. Note that this will be empty to begin with as we have not created any projects yet.

Now let’s create a project by clicking the Create project button and calling it monitoringassistant. The name of the project is used both in the CLI commands below, as well as being referenced in the mason.yml file in the Starter Pack that you downloaded. Upon creation we should be able to see our newly created monitoringassistant project.


We chose the D450 device for this project, but you should pick whatever model Dev Kit you have ordered. For this demo, we will also select API Level 25, which corresponds to Android 7.1.X.

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, you can visit our docs to read up on Mason Groups.

The Unassigned Group

Upon activation, a device is automatically placed into 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.

Create Your Development Group

Let's create a group named development to house our developer device. Navigate to the Groups page, click the Create group button, then give it a name and description. The CLI commands below reference this group name.


Move Your Device

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

We can now move your device to this group by navigating to the Devices page, selecting the checkbox next to the device—the only one currently listed—and clicking Move, then choosing the development group.

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

Register the Project

We’re ready to start the fun stuff! To kick things off, we’ll upload all the different artifacts needed to create a customized OS. These include an OS config, Android app, and boot animation.

An OS configuration describes the exact behavior of the system software on the device, such as OS features, included applications, etc. Check out the Project configuration guide for more information. A boot animation describes the different still frames to run in a loop while the device is booting. You can read up on how to make one here.

Once an OS config is registered, it can be deployed to different groups, thereby updating the devices in those groups to match your OS configuration. Similarly, a registered app can be deployed directly to a group (removing the need to go through a full OS update), or included in an OS config as a system app. In a terminal, navigate to the Mason-Starter-Pack directory that you downloaded earlier. (You may need to unzip the folder first). Then, run mason login to allow the CLI to access your account.

You’ll need to make sure you have the CLI installed to continue. Read up on installing the CLI here

Once logged in, you can run mason register project to upload the artifacts we discussed above. The output will look something like this:

$ mason register project
------------ APK ------------
File Name: /home/mason/Desktop/Mason-Starter-Pack/apps/iHeartLives-Demo-V1.apk
File size: 7507136
Package: com.iheartlives.monitor
Version Name: 1.0.0
Version Code: 1
Continue register? [Y/n]:
Apk 'com.iheartlives.monitor' already registered, ignoring.

----------- MEDIA -----------
File Name: /home/mason/Desktop/Mason-Starter-Pack/media/
File size: 3156136
Name: iheartlives-anim
Version: 1
Type: bootanimation
Continue register? [Y/n]:

--------- OS Config ---------
File Name: /home/mason/Desktop/Mason-Starter-Pack/mason.yml
File size: 917
Name: monitoringassistant
Version: 2
Continue register? [Y/n]:
100%|███████████| 917/917 [00:00<00:00, 5314.23kb/s]
Config 'monitoringassistant' registered.
Build queued.
You can see the status of your build at

Waiting for build to complete...
Build completed.

Itching to jump ahead?

Now that the iHeartLives app is registered, you can deploy a standalone app install from the CLI by running mason deploy --push apk com.iheartlives.monitor latest development.

Visit our CLI documentation on the mason deploy command

After a few seconds, you should see the app install itself in the background on your device. 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.

What just happened?

The mason register project command used the .masonrc file to know where to find our apps and media. We didn’t have to tell it where to find the OS config because it looks for a mason.yml file by default.

We registered an OS config (the mason.yml file), a boot animation (the media/ file), and an APK (the apps/iHeartLives-Demo-V1.apk file). By registering these artifacts, we can now deploy them to devices using the Mason Platform.

Deploy Your Custom OS

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 latest 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 GROUPS.

Visit our CLI documentation on the mason deploy command

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 latest development
---------- DEPLOY -----------
Name: monitoringassistant
Type: config
Version: 1
Group: development
Push: True
Continue deploy? [Y/n]:
Config 'monitoringassistant' deployed.

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 device type to learn more.

Example: see the mason-fota configurations available for our G450 tablet here

Not Seeing 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.

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 Getting Started 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

Get in touch with us

Want to keep exploring?

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 apps-v2/iHeartLives-Demo-V2.apk
mason deploy --push apk com.iheartlives.monitor latest 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:

  • Ping: Ping the device for the latest status update.
  • Check for updates: Remotely force the device to check if there are updates available.
  • Reboot: This action will reboot the device. The device will be offline and unreachable until it reboots.
  • Shutdown: This action will power off the device. The device will be offline and unreachable until it is powered back on.
  • Wipe data: This action will perform a factory data reset on the device. All user data will be removed. Configuration state will be retained.
  • 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 > type Reboot into the confirmation box > and select Send command

Explore Configuration Options

There are over 500+ different configurations available. Visit the documentation for your devkit device to see the configurations available.

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 Android SDK gives your app access to the Mason Platform, allowing you to retrieve information like device name, group, imei, serial, and more.

Visit the documentation for our device SDKs

Try our Platform APIs

The Mason Platform 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).

Visit our documentation on Mason Platform APIs