Getting Started

A step by step guide that shows you how to use the Recorder and access raw sensor data

The Moonsense Cloud and its cross-platform toolset function as an intelligent conduit for sensor data. We are making it easy for developers, data scientists, and product managers to bring environmental awareness to their applications and services.

This tutorial will give you the tools you need to acquire data from real-world activities and analyze it to extract useful insights that can be used to create new app features and services for various use cases in multiple verticals (e.g mobility, fraud & risk, fitness. etc.)

Installing The Recorder App

Let's start by installing the Recorder on your mobile device. We will use this app to collect sensor data. Think about it like a voice recorder but with the capability to capture data from all the sensors on the device and more.

The Recorder App is available both on Android (Google Play Store) and iOS (App Store).

To create an account tap on the "Create account" button on the home screen and input your email address. You will receive an invitation code on email that you can use to activate the Recorder.

Register A New Account

If you get an error that an account already exists with that email address skip to the next section to see instructions on how to access the Moonsense Console and generate an invite to connect a Recorder.

After entering the invite code it's important that you tap on the "Start Tutorial" button to preload some useful example recordings in your default project. We will use them later in this tutorial.

Before we move on let's record the first session with the phone just idle on the desk:

This simple action acquired a rich dataset that accurately describes the motion of the devices, its location in the world, and some properties of the environment. It's magical that there are so many devices in the world that can do all of that so easily.

When you tapped on the red "Record" button you got asked to select a predefined Recording Profile. The initial version of the Recorder ships with three predefined profiles for Mobility, Fraud & Risk, and Fitness. A Profile definition determines what set of sensors are captured and at what sampling rate.

Predefined Recording Profiles:

Accessing The Moonsense Console

Now we need to switch to using a desktop or a laptop computer to start to look into the data that was collected from the sensors on the device using standard data science tools, like a Jupyter Notebook.

To access the Moonsense Console go to:

You will see a standard login screen. Start by inputting your email address and follow the instructions to set a password. When done you should see a screen that looks like this:

Moonsense Console Dashboard

Let's go through this screen a bit.

At the very top, you see the list of regions currently active in the Moonsense Cloud. We are deployed in Google Cloud in multiple regions around the world to ensure we provide our customers with the best possible performance and satisfy strict data security and residency requirements.

Below that, you see a list of sessions. These have been automatically preloaded in this project when you tapped on "Start tutorial" in the Recorder app.

Connecting a Recorder App

If you discovered Moonsense by first registering for Console access you will now need to connect a Recorder App that will run on your mobile device. To do that you need to send yourself an invite from the Record page in the console:

Follow the instructions in the email and after entering the invite code tap on the "Start Tutorial" button to trigger a task that will preload some interesting data in the default project. For more details see the top section on this page "Installing The Recorder App".

Session Details

As the frontend of the Moonsense Cloud, the Console is designed to give you instant visibility into streaming data in the form of real-time summary statistics, the ability to organize data into multiple projects, and control access in a granular fashion.

Let's go through how a 40 minutes driving session is represented:

Example Driving Session

This page is designed to strike a good balance between maintaining user privacy and giving you insights into the data that was collected from the device in a quantitative and qualitative manner.

The top of the page gives you a series of high-level attributes that describe the session:

Session Attributes

The map on the right will only show a randomized bounding circle with a minimum radius of 1km in order to protect the user's privacy.

The Sensors section show per-minute counters that describe the number of data points ingested. If you click on any of them you will see an expanded version:

Accelerometer Per-minute Ingest Stats

If you click on the top-right icon on this page you can also get a qualitative view into the ingested data in the form of multiple cumulative distribution functions:

Accelerometer Cumulative Distribution Functions

These are updated in near real-time (15 seconds delay) as the data flows in.

Downloading Session Data

The easiest way to get access to raw sensor data is through the Console using the Download button on the Session page:

That will immediately trigger a download of a compressed file that contains one JSON document per line with readings from all the relevant sensors on the devices for a time interval of 5 seconds.

The easiest way to convert that plaintext is using the gzcat command.

Each line has a document with the following structure:

{
"bundle": {
"location_data": [
{
"determined_at": "1622216464998",
"horizontal_accuracy": 10,
"altitude": 1.6886863708496094,
"latitude": 37.49661021869397,
"longitude": -122.13112793874194,
"speed_accurracy": 0.15
}
],
"accelerometer_data": [
{
"determined_at": "1622216465130",
"x": -0.28875427246093754,
"y": 9.275576782226564,
"z": 3.152969360351563
},
{
"determined_at": "1622216465169",
"x": -0.35320434570312503,
"y": 9.368289184570314,
"z": 3.139511108398438
}
],
"magnetometer_data": [
{
"determined_at": "1622216465139",
"x": -55.90031433105469,
"y": 18.210159301757812,
"z": -498.796630859375
},
{
"determined_at": "1622216465179",
"x": -55.91831970214844,
"y": 18.392822265625,
"z": -498.8045654296875
}
],
"gyroscope_data": [
{
"determined_at": "1622216465131",
"x": 0.0034461303148418665,
"y": -0.009550361894071102,
"z": -0.0041057956404984
}
],
"client_time": {
"wall_time_millis": "1622216470131",
"timer_millis": "927903185",
"timer_realtime_millis": "927903186"
},
"battery": {
"capacity": 36,
"state": "CHARGING"
},
"activity_data": [
{
"determined_at": "1622216465126",
"type": "STILL",
"confidence": 100
},
{
"determined_at": "1622216469095",
"type": "IN_VEHICLE",
"confidence": 100
}
],
"orientation_data": [
{
"determined_at": "1622216465148",
"azimuth": -2.6306343,
"pitch": 1.2454388,
"roll": 0.10053941
}
]
},
"app_id": "gMbUBZdC6Ywb9bgTfik7Be",
"credential_id": "ZcYmyKKyNk39RvomDHGMUh",
"session_id": "vRaiwPndN7QaW9JmRazbgH",
"user_id": "[email protected]",
"server_time_millis": "1622216470424411"
}

See Python SDK documentation for more details on each individual property:

The Python SDK can be used to access data in a programmatic fashion. It's possible to write a script that will monitor for new sessions and act on them automatically:

The following Jupyter Notebook examples shows how to extract and plot accelerometer data:

It can be found on Github:

If you want to dive into a more realistic example, check the following article on how to build a squats counter in just a couple of hours:

For any issues don't hesitate to contact us at [email protected]. Thank you!