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 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.
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 emailing firstname.lastname@example.org. See the introduction page for more info what a Developer Kit is.
- 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.
- 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. 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 setup earlier.
$ mason login User: email@example.com 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 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:
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.
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. We will henceforth refer to this project using its identifier
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
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.
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
At this point, the dashboard updates itself to show the new group.
We then select the checkbox next to our device – the only one currently listed, click the
Move button and select
You will now see the device in the 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:
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:
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:
- References our monitoring application and the version we published (version
- References the boot-up animation and the version that we published (version
- Sets the device be in “kiosk mode” and launches straight into the monitoring application
The YML looks like this:
os: name: monitoringassistant # This must match the project identifier of the project we created earlier version: 1 configurations: mason-management: 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 apps: - name: com.iheartlives.monitoringapp # Just use the package name package_name: com.iheartlives.monitoringapp version_code: 1 media: bootanimation: name: iheartlives-anim version: 1
Let’s save this configuration to a file
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.
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:
Once the build completes (typically about 5 minutes), we should see the status updating to
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
--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.
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 firstname.lastname@example.org to schedule a demo!