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.
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:
- 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.
- Limit the Settings menu so the user can only access wifi, cellular, bluetooth and get basic information about the device.
- Disable the Status bar so the user cannot accidentally turn wifi or cellular off.
- Disable the camera for privacy
- 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.
- 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.
- 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.
- 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.
- 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 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. Options: -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. Commands: 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 User: firstname.lastname@example.org Password: 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:
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 lets create project by clicking on
New Project and call it
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
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
Create Group > give our group a name and description > select
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
On the Devices page, you will now see the device in the new 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:
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:
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:
apps: - name: com.iheartlives.monitor package_name: com.iheartlives.monitor version_code: 1 os: name: monitoringassistant #Project Name version: 1 #Project Version -- Increase every time you change a configuration configurations: mason-management: 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 settings: 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 media: bootanimation: 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.
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
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
$ 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:
- Is the battery over 20% charged? The default configs require the battery level be at least 20%.
- 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.
- Is the date/time correct? Check the Date & Time settings to make sure they are both correct.
- 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 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:
- 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 > paste the
device ID > and select
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!