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 are kCSSettingYes or kCSSettingNo. 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 are kCSSettingYes or kCSSettingNo. 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 are kCSSettingYes or kCSSettingNo. 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 are kCSSettingYes or kCSSettingNo. 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 are kCSSettingYes or kCSSettingNo. 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 are kCSSettingYes or kCSSettingNo. 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