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 digital heart rate monitoring wearables for patients in hospitals. These devices send data to an Android app on a user’s device, and it must be easy to use, always running, frequently updated, and resistant to tampering. This means it must run on a device that you can control. Rather than tie your company’s core product to a COTS Android device, let’s walk through the process of prototyping our own solution using a Mason Developer Kit.

A Rudimentary “Product Specification”

What we want is a purpose-built Android device to pair with these monitors that we can give your customers. The app will run in a “kiosk mode” (sometimes called “single use” mode) so there is never any user confusion for the user, and no way to jump out of it. While we’re at it, we’ll add a touch of personalization with an iheartlives custom boot-time animation.

Let’s go!

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 emailing solutions@bymason.com. See the introduction page for more info what a Developer Kit is.
  2. A Mason Platform Account: As part of procuring a Developer Kit, you will also be invited to setup a Mason Platform account. An account gives you access to Mason Platform’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 which are built using the popular Python toolset. Please visit the Mason CLI page to learn how to install it. The Software Prerequisites page will show you how to install the requirements necessary for the CLI tool.

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

1. Setup the developer device

With your developer device on hand, just 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
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 setup earlier.

$ mason login
User: techguy@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 custom 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, we should see a screen showing us the 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 dashboard

Now lets create project by clicking on 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. We will henceforth refer to this project using its identifier monitoringassistant

Creating a new project

We will choose the 5.5 inch device for this project (make sure to choose the 8 inch if you have a tablet), and click on Create. Upon creation we should be redirected to the project page listing our newly created MonitoringAssistant project.

My Projects listing

Let’s proceed with creating a group.

4. Create a group

Let’s create a group to house our device. 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.

Clicking on the Devices tab on the left pane of the dashboard takes us to the list of our devices, and we find the device in it.

Device list

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 an group before you can deploy a project’s configuration to it.

Let’s create a group named development to house our developer device. We click Add Group, give our group a name and description, and click Create.

Create group

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

Updated groups

We then select the checkbox next to our device – the only one currently listed, click the Move button and select development.

Move to group

You will now see the device in the new group.

Device in new group

We’re now ready to start building out a configuration to meet our specification.

5. Publish the app

Let’s start by ensuring we have the monitoring app ready for use in our configuration. Assuming we have a regular Android app ready to go in the form of an APK, let’s publish the first version of this app to the Mason registry to be able to refer to it from our configuration.

From the Mason CLI:

$ mason register apk MonitoringApp/MonitoringApp-release-v1.apk
------------ APK ------------
File Name: MonitoringApp/MonitoringApp-release-v1.apk
File size: 1287262
Package: com.iheartlives.monitoringapp
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 for use with our device. If you’re curious, it looks something like this:

Monitoring App Screenshot

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 made by hand for our purposes.

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:

$ 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 including OS features, included applications, etc. Read the Project Configuration page for more information.

To build our configuration, we create a YML file that:

  1. References our monitoring application and the version we published (version 1)
  2. References the boot-up animation and the version that we published (version 1)
  3. Sets the device be in “kiosk mode” and launches straight into the monitoring application

The YML looks like this:

  name: monitoringassistant               # This must match the project identifier of the project we created earlier
  version: 1
      direct_boot_package: com.iheartlives.monitoringapp
      disable_keyguard: true              # Turns off the keyguard/lock screen
      disable_status_bar: false           # Keep status bar so we can get to settings
  - name: com.iheartlives.monitoringapp   # Just use the package name
    package_name: com.iheartlives.monitoringapp
    version_code: 1
    name: iheartlives-anim
    version: 1

Let’s save this configuration to a file monitoringassistant-v1.yml.


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.

Let’s register the above configuration now, using the Mason CLI.

$ 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 device!

8. Issue a build request

In order to deploy that new 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 that can be deployed to a group of devices. Once you invoke a build, you can see the build status in the Mason Build Dashboard.

Let’s start a build for our configuration using the CLI:

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

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

9. Check the dashboard

Now we switch back to the Mason Platform dashboard to check that this build task was actually queued. Let’s click on Builds on the left tab and see what we find.

Build Queued

It looks like we have a build queued for the configuration that we requested. We should see the status updating to IN PROGRESS within a minute or two:

Build in progress

Once the build completes (typically about 5 minutes), we should see the status updating to SUCCESS:

Build successful

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

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 drop down to the CLI once more:

$ 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

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.

You should now see a popup on your device indicating that an update has been downloaded and ready to install.

FOTA popup

Our device should now be running the monitoring app in “kiosk mode” and not allow other apps to run.

And that’s it!

There 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 platform, or get in touch with solutions@bymason.com to schedule a demo!