Difference between revisions of "IOS Sensors"

From Beiwe Wiki
Jump to: navigation, search
(Created page with "IOS sensors June 30, 2016 Changes from what was previously documented and posted: 1. Gyro: accuracy removed 2. Magnetometer: accuracy removed 3. DeviceMotion: accuracy remo...")
 
m
 
(3 intermediate revisions by 2 users not shown)
Line 1: Line 1:
IOS sensors  
+
iOS sensors  
June 30, 2016
 
  
Changes from what was previously documented and posted:
+
August 8, 2016
1. Gyro:  accuracy removed
+
 
2. Magnetometer: accuracy removed
+
'''GPS'''
3. DeviceMotion: accuracy removed
 
4. SurveyAnswers:  Skipped questions have “NO_ANSWER_SELECTED” instead of blank
 
  
GPS
 
 
[ "timestamp", "latitude", "longitude", "altitude", "accuracy"];
 
[ "timestamp", "latitude", "longitude", "altitude", "accuracy"];
  
 
These fields should be the same as Android.
 
These fields should be the same as Android.
  
Accelerometer
+
'''Accelerometer'''
 +
 
 
["timestamp", "accuracy", "x", "y", "z"]
 
["timestamp", "accuracy", "x", "y", "z"]
  
 
These fields should be the same as Android except for accuracy which iOS does not return.  Instead, after discussion with Eli, in the accuracy field is the deviceType/OS version (in case accuracy can be inferred from those).
 
These fields should be the same as Android except for accuracy which iOS does not return.  Instead, after discussion with Eli, in the accuracy field is the deviceType/OS version (in case accuracy can be inferred from those).
  
PowerState
+
'''PowerState'''
["timestamp", "event"]
+
 
 +
["timestamp", "event","level"]
  
 
event:
 
event:
 +
 
Charging:  The phone is currently charging
 
Charging:  The phone is currently charging
 +
 
Full:  The phone is plugged in, battery is full
 
Full:  The phone is plugged in, battery is full
 +
 
Unplugged:  The phone is not charging
 
Unplugged:  The phone is not charging
 +
 
PowerUnknown:  Not sure if/when this value will appear, but it's in the case the iOS reports an unknown charging state.
 
PowerUnknown:  Not sure if/when this value will appear, but it's in the case the iOS reports an unknown charging state.
  
Proximity
+
Event Locked:  Phone was locked
["timestamp", "event"]
+
 
 +
Event Unlocked:  Phone was unlocked
 +
 
 +
level: 
 +
 
 +
Battery level in percent
 +
 
 +
'''Proximity'''
 +
 
 +
["timestamp", "event"]
  
 
event:
 
event:
 +
 
NearUser:  The device is "near" the user, specifically intended to indicate the phone thinks it is near the users ear.
 
NearUser:  The device is "near" the user, specifically intended to indicate the phone thinks it is near the users ear.
 +
 
NotNearUser:  The device does not believe it is near the users ear.
 
NotNearUser:  The device does not believe it is near the users ear.
  
Gyro
+
'''Gyro'''
 +
 
 
["timestamp", "x", "y", "z"]
 
["timestamp", "x", "y", "z"]
  
Line 40: Line 54:
 
"The axis rotation rate in radians per second. The sign follows the right hand rule: If the right hand is wrapped around the axis such that the tip of the thumb points toward positive, a positive rotation is one toward the tips of the other four fingers."
 
"The axis rotation rate in radians per second. The sign follows the right hand rule: If the right hand is wrapped around the axis such that the tip of the thumb points toward positive, a positive rotation is one toward the tips of the other four fingers."
  
Magnetometer
+
'''Magnetometer'''
 +
 
 
["timestamp", "x", "y", "z"]
 
["timestamp", "x", "y", "z"]
  
 
x,y,z:  Raw, uncalibrated magnetic field in each direction measured in microteslas.
 
x,y,z:  Raw, uncalibrated magnetic field in each direction measured in microteslas.
  
DeviceMotion
+
'''DeviceMotion'''
 +
 
 
["timestamp", "roll", "pitch", "yaw",
 
["timestamp", "roll", "pitch", "yaw",
                  "rotation_rate_x", "rotation_rate_y", "rotation_rate_z",
+
 
                  "gravity_x", "gravity_y", "gravity_z",
+
"rotation_rate_x", "rotation_rate_y", "rotation_rate_z",
                  "user_accel_x", "user_accel_y", "user_accel_z",
+
 
                  "magnetic_field_calibration_accuracy", "magnetic_field_x", "magnetic_field_y", "magnetic_field_z"
+
"gravity_x", "gravity_y", "gravity_z",
                  ]
+
 
 +
"user_accel_x", "user_accel_y", "user_accel_z",
 +
 
 +
"magnetic_field_calibration_accuracy", "magnetic_field_x", "magnetic_field_y", "magnetic_field_z"                 ]
  
 
These are similar to acceleration, magnetometer, and gyro with the exception that these are all calculated & calibrated values.  The sensor influence each other and are used to try and get calibrated values.  i.e. What part of the acceleration is due to gravity, and what part is due to the user exerting force on the phone.   
 
These are similar to acceleration, magnetometer, and gyro with the exception that these are all calculated & calibrated values.  The sensor influence each other and are used to try and get calibrated values.  i.e. What part of the acceleration is due to gravity, and what part is due to the user exerting force on the phone.   
Line 59: Line 78:
  
 
rotation_rate_x,y,z: Same as gyro
 
rotation_rate_x,y,z: Same as gyro
 +
 
gravity_x,y,z:  device acceleration attributed to gravity
 
gravity_x,y,z:  device acceleration attributed to gravity
 +
 
user_accel_x,y,z:  device acceleration attributed to the user
 
user_accel_x,y,z:  device acceleration attributed to the user
 +
 
magnetic_field_calibration_accuracy: uncalibrated, low, medium, high, unknown
 
magnetic_field_calibration_accuracy: uncalibrated, low, medium, high, unknown
 +
 
magnetic_field_x,y,z:  The magnetic field calibrated to remove the influence of the magnetic fields of the device itself, and in some cases other interfering magnetic fields.
 
magnetic_field_x,y,z:  The magnetic field calibrated to remove the influence of the magnetic fields of the device itself, and in some cases other interfering magnetic fields.
  
Reachability
+
'''Reachability'''
 +
 
 
["timestamp", "event"]
 
["timestamp", "event"]
  
Line 70: Line 94:
  
 
events:
 
events:
 +
 
wifi:  Connected via wifi
 
wifi:  Connected via wifi
 +
 
cellular:  Connected via cellular data
 
cellular:  Connected via cellular data
 +
 
unreachable:  Internet not reachable
 
unreachable:  Internet not reachable
  
Survey Answers
+
'''Survey Answers'''
 +
 
 
Headers:   
 
Headers:   
 +
 
["question id", "question type", "question text", "question answer options","answer"]
 
["question id", "question type", "question text", "question answer options","answer"]
 +
 
(survey_id is added automatically by the server)
 
(survey_id is added automatically by the server)
  
Line 83: Line 113:
 
NO_ANSWER_SELECTED is used when no answer was provided for a question (ie. question was skipped)
 
NO_ANSWER_SELECTED is used when no answer was provided for a question (ie. question was skipped)
  
Survey Timings
+
'''Survey Timings'''
 +
 
 
Headers:
 
Headers:
 +
 
["timestamp","question id", "question type", "question text", "question answer options","answer", "event"]
 
["timestamp","question id", "question type", "question text", "question answer options","answer", "event"]
 +
 
(survey_id is added automatically by the server)
 
(survey_id is added automatically by the server)
  
Line 91: Line 124:
  
 
Events not associated with a particular question, but with a survey as a whole:
 
Events not associated with a particular question, but with a survey as a whole:
notified
+
 
 +
''notified''
 +
 
 
This event is added everytime a new survey becomes available for the user to answer (i.e. the user is notified a new survey is available)
 
This event is added everytime a new survey becomes available for the user to answer (i.e. the user is notified a new survey is available)
  
submitted
+
''submitted''
This event is added when the user finishes a survey and selects "submit" to submit the survey to the server.
+
 
expired
+
This event is added when the user finishes a survey and selects "submit" to submit the survey to the server.  
 +
 
 +
''expired''
 +
 
 
This event is added if a survey expires before the user has selected "submit".  
 
This event is added if a survey expires before the user has selected "submit".  
  
 
Events always associated with a parituclar question/answer:
 
Events always associated with a parituclar question/answer:
present
+
 
 +
''present''
 +
 
 
This event is added when the question is presented onscreen for the user to answer.  The answer field contains the value of the answer before the user answers it.  (So this could be either blank/the default answer, or if the user has already answered this question but has gone back to edit his answer it would be his previous answer)
 
This event is added when the question is presented onscreen for the user to answer.  The answer field contains the value of the answer before the user answers it.  (So this could be either blank/the default answer, or if the user has already answered this question but has gone back to edit his answer it would be his previous answer)
  
unpresent
+
''unpresent''
 +
 
 
This event is added when the question is being removed from the screen (the user has moved on to the next question, or left the survey).  The answer will be the answer the user entered (if any), and will be recorded in survey answers if the survey where to be submitted/expire at this point.
 
This event is added when the question is being removed from the screen (the user has moved on to the next question, or left the survey).  The answer will be the answer the user entered (if any), and will be recorded in survey answers if the survey where to be submitted/expire at this point.
  
changed
+
''changed''
 +
 
 
This event is added every time a question answer changes in real-time as the user is answering the question (so this will come between present and unpresent).  For instance for a freeform text answer, if the user enters "Doggie" you will see a bunch of changed events.  With answers like "D", "Do", "Dog", "Dogg", etc.  So you will be able to see the exact editing process and timings for the user.  The only slight exception to this is for the "slider' events in which case the values are "debounced" and only recorded when the user lets the slider rest a single position for 0.25 seconds.  This is to prevent a deluge of data as the user is sliding the slider.
 
This event is added every time a question answer changes in real-time as the user is answering the question (so this will come between present and unpresent).  For instance for a freeform text answer, if the user enters "Doggie" you will see a bunch of changed events.  With answers like "D", "Do", "Dog", "Dogg", etc.  So you will be able to see the exact editing process and timings for the user.  The only slight exception to this is for the "slider' events in which case the values are "debounced" and only recorded when the user lets the slider rest a single position for 0.25 seconds.  This is to prevent a deluge of data as the user is sliding the slider.
 
 
 
Modified for version 1.0.1+:
 
PowerState
 
* Added level
 
* Added new events Locked & Unlocked
 
["timestamp", "event","level"]
 
level:  Battery level in percent
 
Event Locked:  Phone was locked
 
Event Unlocked:  Phone was unlocked
 
Posted on Aug 8, 2016
 

Latest revision as of 10:42, 22 March 2018

iOS sensors

August 8, 2016

GPS

[ "timestamp", "latitude", "longitude", "altitude", "accuracy"];

These fields should be the same as Android.

Accelerometer

["timestamp", "accuracy", "x", "y", "z"]

These fields should be the same as Android except for accuracy which iOS does not return. Instead, after discussion with Eli, in the accuracy field is the deviceType/OS version (in case accuracy can be inferred from those).

PowerState

["timestamp", "event","level"]

event:

Charging: The phone is currently charging

Full: The phone is plugged in, battery is full

Unplugged: The phone is not charging

PowerUnknown: Not sure if/when this value will appear, but it's in the case the iOS reports an unknown charging state.

Event Locked: Phone was locked

Event Unlocked: Phone was unlocked

level:

Battery level in percent

Proximity

["timestamp", "event"]

event:

NearUser: The device is "near" the user, specifically intended to indicate the phone thinks it is near the users ear.

NotNearUser: The device does not believe it is near the users ear.

Gyro

["timestamp", "x", "y", "z"]

x,y,z: The motion in each direction "The axis rotation rate in radians per second. The sign follows the right hand rule: If the right hand is wrapped around the axis such that the tip of the thumb points toward positive, a positive rotation is one toward the tips of the other four fingers."

Magnetometer

["timestamp", "x", "y", "z"]

x,y,z: Raw, uncalibrated magnetic field in each direction measured in microteslas.

DeviceMotion

["timestamp", "roll", "pitch", "yaw",

"rotation_rate_x", "rotation_rate_y", "rotation_rate_z",

"gravity_x", "gravity_y", "gravity_z",

"user_accel_x", "user_accel_y", "user_accel_z",

"magnetic_field_calibration_accuracy", "magnetic_field_x", "magnetic_field_y", "magnetic_field_z" ]

These are similar to acceleration, magnetometer, and gyro with the exception that these are all calculated & calibrated values. The sensor influence each other and are used to try and get calibrated values. i.e. What part of the acceleration is due to gravity, and what part is due to the user exerting force on the phone.

roll,pitch,yaw: The roll pitch and yaw euler angles around an arbitrary X axis, with Z being vertical NOTE: There are other frames of reference, but they rely on the compass being calibrated frequently, but that process requires manual user interaction (and possibly frequently).

rotation_rate_x,y,z: Same as gyro

gravity_x,y,z: device acceleration attributed to gravity

user_accel_x,y,z: device acceleration attributed to the user

magnetic_field_calibration_accuracy: uncalibrated, low, medium, high, unknown

magnetic_field_x,y,z: The magnetic field calibrated to remove the influence of the magnetic fields of the device itself, and in some cases other interfering magnetic fields.

Reachability

["timestamp", "event"]

Whether and how the phone is connected to the internet

events:

wifi: Connected via wifi

cellular: Connected via cellular data

unreachable: Internet not reachable

Survey Answers

Headers:

["question id", "question type", "question text", "question answer options","answer"]

(survey_id is added automatically by the server)

This file should be exactly the same as Android, with the addition of "not_presented" as a possible value for the "answer" field. If the answer field contains "not_presented" it means that particular question was never presented to the user. (In other words, they didn't get that far in the survey).

NO_ANSWER_SELECTED is used when no answer was provided for a question (ie. question was skipped)

Survey Timings

Headers:

["timestamp","question id", "question type", "question text", "question answer options","answer", "event"]

(survey_id is added automatically by the server)

The only addition to this data file for iOS is the "event" field. Everytime a new event is recorded (with the time), the current status of the question is recorded. For some events which aren't associated with a particular question, the question fields will be blank and only the survey_id, timestamp and event are recorded.

Events not associated with a particular question, but with a survey as a whole:

notified

This event is added everytime a new survey becomes available for the user to answer (i.e. the user is notified a new survey is available)

submitted

This event is added when the user finishes a survey and selects "submit" to submit the survey to the server.

expired

This event is added if a survey expires before the user has selected "submit".

Events always associated with a parituclar question/answer:

present

This event is added when the question is presented onscreen for the user to answer. The answer field contains the value of the answer before the user answers it. (So this could be either blank/the default answer, or if the user has already answered this question but has gone back to edit his answer it would be his previous answer)

unpresent

This event is added when the question is being removed from the screen (the user has moved on to the next question, or left the survey). The answer will be the answer the user entered (if any), and will be recorded in survey answers if the survey where to be submitted/expire at this point.

changed

This event is added every time a question answer changes in real-time as the user is answering the question (so this will come between present and unpresent). For instance for a freeform text answer, if the user enters "Doggie" you will see a bunch of changed events. With answers like "D", "Do", "Dog", "Dogg", etc. So you will be able to see the exact editing process and timings for the user. The only slight exception to this is for the "slider' events in which case the values are "debounced" and only recorded when the user lets the slider rest a single position for 0.25 seconds. This is to prevent a deluge of data as the user is sliding the slider.