CSSettings Class Reference
Inherits from | NSObject |
---|---|
Declared in | CSSettings.h |
Overview
This singleton is used to control the settings of the sense platform. Using this class all available settings can be set.
Each setting is stored in a CSSetting object that contains a name and value (see above). All the potential settings are listed here, as well as their potential values. Several methods for changing and obtaining the settings are available and documented below.
Setting types
Each setting also has a type, which makes it easier to group them and listen only to setting changes of a specific type. Currently, 5 different types have been defined:
kCSSettingTypeGeneral
: This a placeholder for all settings that don’t belong to any of the other types.kCSSettingTypeBiometric
: User specific settings like age, height, date of birth, and gender.kCSSettingTypeLocation
: All settings related to the location sensor, visits sensor, and the location provider, including sampling settings and accuracy.kCSSettingTypeSpatial
: All settings related to the spatial settings and spatial data provider. This includes the accelerometer sensors and motion features.kCSSettingTypeAmbience
: All settings related to the ambience sensors. Right now this is only the noise sensor (microphone data).
General settings
kCSGeneralSettingUsername
The username of the user is stored as a setting for persistency. This is handled in CSSensePlatform login, logout, and register methods so doesn’t need to be set manually. Any valid string value is accepted.kCSGeneralSettingPassword
The password of the uer is stored as a setting for persistency. This is handled in CSSensePlatform login, logout, and register methods so it doesn’t to be set manually. Note that when encryption is enabled, the settings including the password are also encrypted. The password itself is stored as an MD5 hashed String.kCSGeneralSettingSenseEnabled
This is a shorthand for disabling all sensors and uploads to commonsense. When enabled, the old settings are restored, enabling all the sensors that have been individually enabled. Values arekCSSettingYes
orkCSSettingNo
. Enabled by default.kCSGeneralSettingUploadInterval
The interval is seconds specifies the time between consecutive uploads to commonsense. Value can be specified in seconds using a string. There are also three special settings available but they are not implement right now so they should not be used. 1800 seconds (30 minutes) by default.kCSGeneralSettingPollInterval
This setting is not being used currently. Polling intervals are specified per sensor.kCSGeneralSettingAutodetect
This setting is not being used.kCSGeneralSettingUploadToCommonSense
When enabled, data will be uploaded to commonsense according to a specified interval. Values arekCSSettingYes
orkCSSettingNo
. Enabled by default.kCSGeneralSettingDontUploadBursts
This specifies whether or not data from burst sensors should be uploaded to commonsense. Data in burst sensors contains all data that is often sampled at a high frequency. It can be used effectively for specific algorithms to detect behavior of the user for instance, but uploading it might take time, battery, and data usage. For improved battery usage, we advice not to upload burst data but only use it locally. Values arekCSSettingYes
orkCSSettingNo
. Enabled by default.kCSGeneralSettingBackgroundRestarthack
This settings enables the running of sense library in the background. For this, it enables the CSLocationProvider. If one has already enabled the location sensor, or any sensor that uses the location provider there is no need for enabling this setting because the individual sensors that make use of the location provider also can enable it. For more details, see the Background services document. Enabled by default to be able to run in the background.kCSGeneralSettingLocalStorageEncryption
This setting enables or disables encryption of local data (settings file and sensordata database). Note that encryption will decrease performance slightly. Values arekCSSettingYes
orkCSSettingNo
. Disabled by default.kCSGeneralSettingLocalStorageEncryptionKey
Key used for encryption.kCSGeneralSettingUseStaging
This setting enables or disables the use of the staging server. It changes all URLs for remote communication to either the commonsense live API or the commonsense staging API. Values arekCSSettingYes
orkCSSettingNo
. Disabled by default.
Biometric settings
These are placeholders not currently being used actively. We discourage usage of them for now.
kCSBiometricSettingGender
kCSBiometricSettingBirthDate
kCSBiometricSettingWeight
kCSBiometricSettingHeight
kCSBiometricSettingBodyFat
kCSBiometricSettingMaxPulse
Activity settings
These are placeholder not currently being used actively. We discourage usage of them for now.
kCSActivitySettingDetection
kCSActivitySettingPrivacy
Location settings
kCSLocationSettingAccuracy
Accuracy with which iOS will detect location data points. Lower values will provide higher accuracy but will also use more battery. Apple generally distinguishes three levels: GPS, WiFi, Cell tower. GPS is the most accurate (< 1 meter) but uses a lot of battery power. Wifi is accurate at around ~100 meters and uses less battery. Cell tower is accurate at about ~2 km and uses the least amount of battery. Setting is specified in meters (as a String). The default value is set to 100 meters.kCSLocationSettingMinimumDistance
Minimum distance used before getting a location update. When not specified it updates whenever iOS deems it relevant to update, this is recommended. Specified in meters. Uses the standard iOS functionality. Not set by default.kCSLocationSettingCortexAutoPausing
Setting for automatically pausing location updates for three minutes after a new datapoint has come in, this might save battery life. Values arekCSSettingYes
orkCSSettingNo
. Disabled by default.
Spatial settings
kCSSpatialSettingInterval
Interval between sampling spatial (motion) data. Specified in seconds, by default set to 60 seconds.kCSSpatialSettingFrequency
Sample frequency of the motion data sampling. Specified in Herz. By default set to 50 Hz. Note that this is limited by hardware potential.kCSSpatialSettingNrSamples
Number of samples to collect for each sampling cycle. Specified in numbers of samples. By default set to 150 samples, this means 3 seconds of sampled data when using the standard of 50 Hz as sampling frequency.
Ambience settings
kCSAmbienceSettingInterval
Interval between sampling ambience (currently only noise) data. Specified in seconds, by default set to 60 seconds.kCSAmbienceSettingSampleOnlyWhenScreenLocked
Enabling or disabling sampling when the screen is on. When the screen is on and mircrophone is being sampled iOS shows a red bar at the top of the screen. This might scare users. A solution could be to only sample ambience (noise) data when the screen is turned off. When this setting is turned on, that is what will happen. Note that when the screen gets turned on at the moment the sampling has already started the sampling will be finished (and hence there is a small chance the red bar will be seen by the user). Disabled by default.
Persistency
Settings are by default persisted in a local storage file to make sure that when the app is killed settings are restored when restarted. The settings in the file are loaded whenever CSSettings.h is instantiated (if it exists). The settings file can be encrypted by setting the kCSGeneralSettingLocalStorageEncryption
to Yes. When it does not exist a new file is created with the default settings.
Default settings
- Upload interval to commonsense: 1800 seconds (
kCSGeneralSettingUploadInterval
) - Enabling upload to commonsense: Yes (
kCSGeneralSettingUploadToCommonSense
) - Enabling sensors that have been requested: Yes (
kCSGeneralSettingSenseEnabled
) - Enabling encryption on the local storage: No (
kCSGeneralSettingLocalStorageEncryption
) - Using the staging server: No (
kCSGeneralSettingUseStaging
) - Sample ambience (noise) only when screen is locked: No (
kCSAmbienceSettingSampleOnlyWhenScreenLocked
) - Sample interval for ambience (noise) sensors: 60 seconds (
kCSAmbienceSettingInterval
) - Location sampling accuracy: 100 meters (
kCSLocationSettingAccuracy
) - Automatically pausing the location sensing for 3 minutes between updates: No (
kCSLocationSettingCortexAutoPausing
) - Interval of sampling spatial (motion) sensors: 60 seconds (
kCSSpatialSettingInterval
) - Sample frequency when sampling spatial (motion) sensors: 50 Hz (
kCSSpatialSettingFrequency
) - Number of samples to sample every cycle: 150 samples (
kCSSpatialSettingNrSamples
)
Listening to changes
When a setting is changed a notification is broadcasted to all listeners. To listen to sensor enabling or disabling, a class can declare
[[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(enabledChanged:) name:[CSSettings enabledChangedNotificationNameForSensor:[MySensor name]] object:nil];
Or to listen to other specific sensor notifications
[[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(enabledChanged:) name:[CSSettings settingChangedNotificationNameForSensor:[MySensor name]] object:nil];
To listen to notifications of a specific type
[[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(enabledChanged:) name:[CSSettings settingChangedNotificationNameForType:[MyObject type]] object:nil];
Warning
Note that some of the functionality of this class should no longer be used directly by the developer but instead can be used through CSSensorRequirements.h, which provides a way of dealing with potentially conflicting settings. Especially the enabling/disabling of sensors or the setting of specific parameters for sensors should be done there. See CSSensorRequirements.h for more details.
Warning
Settings are not stored specifically for each user. Hence when another user would start using the same install of the app without removing it first, it would be using the same settings. Login/Register and Logout do clear the credential settings though.
Class methods
+ sharedSettings
Provides the singleton object for this class
+ (CSSettings *)sharedSettings
Declared In
CSSettings.h
+ enabledChangedNotificationNameForSensor:
Returns the name of enable notifications for the specified sensor. This can be used for an object to instantiate an observer.
+ (NSString *)enabledChangedNotificationNameForSensor:(NSString *)sensor
Parameters
sensor |
The of the sensor for which the enable notifications should be observed. |
---|
Return Value
The name of the enable notifications for the specified sensor.
Declared In
CSSettings.h
+ settingChangedNotificationNameForType:
Returns the name of setting changed notifications for a specified type of settings. This can be used for an object to instantiate an observer.
+ (NSString *)settingChangedNotificationNameForType:(NSString *)type
Parameters
type |
The type of sensor changes that one wants to listen to. This can be either kCSSettingTypeGeneral, kCSSettingTypeGeneral, kCSSettingTypeLocation,kCSSettingTypeSpatial,kCSSettingTypeAmbience. See the overview of this class for more info. |
---|
Return Value
The name of the enable notifications for the specified type
Declared In
CSSettings.h
+ permissionGrantedForProvider:
Returns the name of the permission granted notification for a specific provider.
+ (NSString *)permissionGrantedForProvider:(NSString *)provider
Parameters
provider |
The provider for which the permission was granted. |
---|
Return Value
The name of the permission granted notification.
Declared In
CSSettings.h
+ permissionDeniedForProvider:
Returns the name of the permission denied notification for a specific provider.
+ (NSString *)permissionDeniedForProvider:(NSString *)provider
Parameters
provider |
The provider for which the permission was granted. |
---|
Return Value
The name of the permission denied notification.
Declared In
CSSettings.h
Setting settings (pun intended)
– setSensor:enabled:
Enable/disable the specified sensor, setting is persistent.
- (BOOL)setSensor:(NSString *)sensor enabled:(BOOL)enable
Parameters
sensor |
Name of the sensor to enable or disable |
---|---|
enable |
True if it should be enabled, false if sensor should be disabled |
Return Value
New value of the sensor’s isEnabled method.
Discussion
This notifies observers.
Declared In
CSSettings.h
– setSensor:enabled:persistent:
Enable/disable the specified sensor, specifying whether or not the setting should be persistent.
- (BOOL)setSensor:(NSString *)sensor enabled:(BOOL)enable persistent:(BOOL)persistent
Parameters
sensor |
Name of the sensor |
---|---|
enable |
Wether to enable or disable the sensor |
persistent |
Whether this setting is persistent |
Return Value
New value of the sensor’s isEnabled method.
Discussion
This notifies observers.
Declared In
CSSettings.h
– setSettingType:setting:value:
Set the value of the specified setting, the setting is persistent.
- (BOOL)setSettingType:(NSString *)type setting:(NSString *)setting value:(NSString *)value
Parameters
type |
The setting type |
---|---|
setting |
The specific setting for the type |
value |
The value of to set the setting to |
Return Value
Whether or not updating the setting was successful.
Discussion
This notifies observers.
Declared In
CSSettings.h
– setSettingType:setting:value:persistent:
Set the value of the specified setting
- (BOOL)setSettingType:(NSString *)type setting:(NSString *)setting value:(NSString *)value persistent:(BOOL)persistent
Parameters
type |
The setting type. See the overview above for the available types. |
---|---|
setting |
The specific setting for the type |
value |
The value of to set the setting to |
persistent |
Whether the setting should be persistent |
Return Value
Whether or not updating the setting was successful.
Discussion
This notifies observers.
Declared In
CSSettings.h
– setLogin:withPassword:
Login with user and password
- (BOOL)setLogin:(NSString *)user withPassword:(NSString *)password
Parameters
user |
the username |
---|---|
password |
the plain password |
Declared In
CSSettings.h
– setLogin:withPasswordHash:
Login with user and a hash of the password
- (BOOL)setLogin:(NSString *)user withPasswordHash:(NSString *)passwordHash
Parameters
user |
the username |
---|---|
passwordHash |
the hash of the password |
Declared In
CSSettings.h
Getting settings
– isSensorEnabled:
Returns wether the specified sensor is enabled
- (BOOL)isSensorEnabled:(NSString *)sensor
Parameters
sensor |
Name of the sensor to check |
---|
Return Value
Whether or not the specified sensor is enabled
Declared In
CSSettings.h
– sendNotificationForSensor:
Send notifications for a specific sensor. Notifies all observers about this sensor.
- (void)sendNotificationForSensor:(NSString *)sensor
Parameters
sensor |
Name of the sensor |
---|
Declared In
CSSettings.h
– getSettingType:setting:
Get the value of the specified setting
- (NSString *)getSettingType:(NSString *)type setting:(NSString *)setting
Parameters
type |
the setting type |
---|---|
setting |
the specific setting for the type |
Return Value
the value of the setting
Declared In
CSSettings.h
Reset
– resetToDefaults
Reset the settings to defaults.
- (void)resetToDefaults
Discussion
The default settings are:
- Upload interval to commonsense: 1800 seconds (
kCSGeneralSettingUploadInterval
) - Enabling upload to commonsense: Yes (
kCSGeneralSettingUploadToCommonSense
) - Enabling sensors that have been requested: Yes (
kCSGeneralSettingSenseEnabled
) - Enabling encryption on the local storage: No (
kCSGeneralSettingLocalStorageEncryption
) - Using the staging server: No (
kCSGeneralSettingUseStaging
) - Sample ambience (noise) only when screen is locked: No (
kCSAmbienceSettingSampleOnlyWhenScreenLocked
) - Sample interval for ambience (noise) sensors: 60 seconds (
kCSAmbienceSettingInterval
) - Location sampling accuracy: 100 meters (
kCSLocationSettingAccuracy
) - Automatically pausing the location sensing for 3 minutes between updates: No (
kCSLocationSettingCortexAutoPausing
) - Interval of sampling spatial (motion) sensors: 60 seconds (
kCSSpatialSettingInterval
) - Sample frequency when sampling spatial (motion) sensors: 50 Hz (
kCSSpatialSettingFrequency
) - Number of samples to sample every cycle: 150 samples (
kCSSpatialSettingNrSamples
)
Declared In
CSSettings.h