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.
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.
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.
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.
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.
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.
It's now time to visit the Mason Platform website to get started with creating a project. We login using your Mason 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 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
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.
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.
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.
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.
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.
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.
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.
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 https://platform.bymason.com/controller/projects/monitoringassistant
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
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:
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.
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:
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
There are over 500+ different configurations available. Check out our Configuration Glossary for your device type to start exploring.
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.
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!