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 first.

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:

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

Download the Mason Starter Pack

To complete this step, you will need a Mason Dev Kit and a Mason Account. You can request a Dev Kit here, and create an account 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, and manually set the appropriate settings. Once done, make sure to toggle the Automatic date & time or the Automatic time zone 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.

Check for update Home screen

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.

Log in to Mason

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

Login screen

Create Your First Project

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.

Now let's create a 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.

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.

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.

Create Your Development Group

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.

Move Your Device

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.

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

We're ready to start the fun stuff! To kick things off, we need to make sure that we have published the app to the Mason Platform. Once published, the app can be:

For the purposes of this walk through, you can use the iHeartLives-Demo-V1.apk found in the Mason Starter Pack.

Download the Mason Starter Pack

From the Mason CLI, you'll start by running mason login, and log in using your Mason Account credentials. Once logged in, you'll want to run mason register apk iHeartLives-Demo-V1.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 the 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:

Android bootup animations are easy to make once you've learned 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.

Publish Your Animation

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 iheartlives-anim bootanimation 1.

$ mason register media iheartlives-anim bootanimation 1
----------- MEDIA -----------
File Name: ./
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.

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

Registering Your Configuration File

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, and we recommend opening and exploring the configuration file to get more familiar with the layout.

To register your custom OS configuration, you simply use the Mason CLI and run mason register config monitoringassistant-v1.yml

That's it! It's now registered with the Mason platform, and we're now ready to build the first version of our dedicated device!

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.

Issue a Build Request

Let's start a build for our configuration using the CLI run mason build --turbo monitoringassistant 1.

$ mason build --turbo monitoringassistant 1
Queueing build...
Build queued. You can see the status of your build at

Check Your Build Status

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.

If you used the --turbo flag, the build should be completed almost instantly. If you did not use that flag, 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.

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

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.

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

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:

How helpful was this guide?

Very helpful - "I have a great understanding on the Mason platform" Somewhat helpful - "I got through it, but still lots to learn" Neutral - "Meh" Unhelpful - "It was hard to follow" Very unhelpful - "I'm more confused than ever"

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

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!