Overview
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
- Setting up your dev kit
- Setting up projects in the Mason platform
- Setting up device groups in the Mason platform
- Registering a Mason OS configuration in the Mason Platform
- Deploying a custom Android OS to a group of devices
- Advanced device management techniques on the Mason Platform
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:
- A Mason Platform Account: Visit our Sign Up page to create an account.
- 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.
- CLI Version 1.5+ Installed: Visit our setup instructions to learn how to install it.
- 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/bootanimation.zip
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
https://platform.bymason.com/controller/projects/monitoringassistant
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.
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/bootanimation.zip 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.
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:
- 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!
Conclusion
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
- Contact us at support@bymason.com
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.
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).