Data logging

Sessions of fixed-size items persisted to flash and spooled to the phone. More...

Modules
	Data logging endpoint
	Pebble Protocol endpoint exchanging session data with the phone.
	Session list
	In-memory list of data logging sessions, sorted by session ID.
	Data logging internals
	Session structures, limits and wire format shared by the data logging service.
	Session storage
	Session data stored in a PFS file per session.

Enumerations
enum	DlsSystemTag {   DlsSystemTagAnalyticsDeviceHeartbeat = 78 , DlsSystemTagAnalyticsAppHeartbeat = 79 , DlsSystemTagAnalyticsEvent = 80 , DlsSystemTagActivityMinuteData = 81 ,   DlsSystemTagActivityAccelSamples = 82 , DlsSystemTagActivitySession = 84 , DlsSystemTagProtobufLogSession = 85 , DlsSystemTagAnalyticsNativeHeartbeat = 87 }
	Tags used by system services, all registered with UUID_SYSTEM. More...

Functions
void	dls_init (void)
	Initialize the data logging service.
bool	dls_initialized (void)
	Check whether dls_init() has run.
void	dls_clear (void)
	Delete all sessions, both in memory and in flash.
void	dls_pause (void)
	Stop the periodic flush of sessions to the phone.
void	dls_resume (void)
	Restart the periodic flush of sessions to the phone.
void	dls_inactivate_sessions (PebbleTask task)
	Inactivate all non-system sessions created by a task.
DataLoggingSession *	dls_create_current_process (uint32_t tag, DataLoggingItemType item_type, uint16_t item_size, void *buffer, bool resume)
	Create a buffered session owned by the current process.
DataLoggingSession *	dls_create (uint32_t tag, DataLoggingItemType item_type, uint16_t item_size, bool buffered, bool resume, const Uuid *uuid)
	Create a session.
DataLoggingResult	dls_log (DataLoggingSession *s, const void *data, uint32_t num_items)
	Append items to a session.
void	dls_finish (DataLoggingSession *s)
	Finish a session.
bool	dls_is_session_valid (DataLoggingSession *logging_session)
	Check whether a pointer refers to an existing session.
void	dls_send_all_sessions (void)
	Send all stored data to the phone now instead of at the next periodic flush.
bool	dls_get_send_enable (void)
	Check whether sending to the phone is enabled.
void	dls_set_send_enable_pp (bool setting)
	Enable or disable sending, as requested by the phone.
void	dls_set_send_enable_run_level (bool setting)
	Enable or disable sending, as requested by the run level.

Detailed Description

Sessions of fixed-size items persisted to flash and spooled to the phone.

A session is identified by a tag and the UUID of its owner (UUID_SYSTEM for system services). Logged items are stored in a PFS file per session and sent to the phone over the data logging endpoint every few minutes, or right away when the session is finished.

Buffered sessions copy items into a RAM circular buffer that KernelBG writes to flash, so logging does not block. Unbuffered sessions write to flash directly and may only be used from KernelBG.

DataLoggingSession *s = dls_create(DlsSystemTagActivitySession, DATA_LOGGING_BYTE_ARRAY,
                                   sizeof(struct record), true, false, &(Uuid)UUID_SYSTEM);
if (s) {
  if (dls_log(s, &record, 1) != DATA_LOGGING_SUCCESS) {
    // dropped
  }
  dls_finish(s);
}

Defining DLS_DEBUG_SEND_IMMEDIATELY sends stored data to the phone after every dls_log(). A long press on any launcher menu item also flushes all sessions.

Enumeration Type Documentation

DlsSystemTag

enum DlsSystemTag

Tags used by system services, all registered with UUID_SYSTEM.

Enumerator
DlsSystemTagAnalyticsDeviceHeartbeat	Device analytics heartbeat.
DlsSystemTagAnalyticsAppHeartbeat	App analytics heartbeat.
DlsSystemTagAnalyticsEvent	Analytics event.
DlsSystemTagActivityMinuteData	Activity minute data.
DlsSystemTagActivityAccelSamples	Raw accelerometer samples.
DlsSystemTagActivitySession	Activity sessions.
DlsSystemTagProtobufLogSession	Protobuf log sessions, see Protobuf log.
DlsSystemTagAnalyticsNativeHeartbeat	Native analytics heartbeat.

Function Documentation

dls_clear()

void dls_clear

(

void

)

Delete all sessions, both in memory and in flash.

dls_create()

DataLoggingSession * dls_create	(	uint32_t	tag,
		DataLoggingItemType	item_type,
		uint16_t	item_size,
		bool	buffered,
		bool	resume,
		const Uuid *	uuid
	)

Create a session.

Integer items must be 1, 2 or 4 bytes wide.

Parameters

tag	Session tag.
item_type	Type of the logged items.
item_size	Size of one item in bytes.
buffered	Use a RAM buffer allocated on the kernel heap. Buffered sessions may be created from the worker or kernel tasks, unbuffered ones only from KernelBG.
resume	Reuse an active session with the same tag and UUID instead of finishing it.
uuid	Owner UUID.

Returns

Session, or NULL on invalid parameters or too many sessions.

dls_create_current_process()

DataLoggingSession * dls_create_current_process	(	uint32_t	tag,
		DataLoggingItemType	item_type,
		uint16_t	item_size,
		void *	buffer,
		bool	resume
	)

Create a buffered session owned by the current process.

Parameters

tag	Session tag.
item_type	Type of the logged items.
item_size	Size of one item in bytes, at most DLS_SESSION_MAX_BUFFERED_ITEM_SIZE.
buffer	Buffer of at least DLS_SESSION_MIN_BUFFER_SIZE bytes, freed by the service when the session is closed. May be NULL only from the worker or kernel tasks, in which case the buffer is allocated on the kernel heap.
resume	Reuse an active session with the same tag and UUID instead of finishing it.

Returns

Session, or NULL on invalid parameters or too many sessions.

dls_finish()

void dls_finish

(

DataLoggingSession *

s

)

Finish a session.

Waits up to one second for buffered data to reach flash, inactivates the session and triggers a send of all sessions. The session is deleted once all its data has been sent.

Parameters

s

Session.

dls_get_send_enable()

bool dls_get_send_enable

(

void

)

Check whether sending to the phone is enabled.

Returns

true if enabled by both the phone and the run level.

dls_inactivate_sessions()

void dls_inactivate_sessions

(

PebbleTask

task

)

Inactivate all non-system sessions created by a task.

Used when the task exits. Data still in a session's RAM buffer may be lost; data already in flash is still sent to the phone.

Parameters

task	Task whose sessions are inactivated.

dls_init()

void dls_init

(

void

)

Initialize the data logging service.

Called at boot. Rebuilds the sessions stored in flash and starts the periodic flush.

dls_initialized()

bool dls_initialized

(

void

)

Check whether dls_init() has run.

Returns

true if data logging is initialized.

dls_is_session_valid()

bool dls_is_session_valid

(

DataLoggingSession *

logging_session

)

Check whether a pointer refers to an existing session.

Safe to call with arbitrary pointers: only compares against the known sessions.

Parameters

logging_session

Pointer to check.

Returns

true if logging_session is a known session.

dls_log()

DataLoggingResult dls_log	(	DataLoggingSession *	s,
		const void *	data,
		uint32_t	num_items
	)

Append items to a session.

Buffered sessions copy the data and return; unbuffered ones write it to flash before returning. Must not be called with the Bluetooth lock held.

Parameters

s	Session.
data	Items to log.
num_items	Number of items in data.

Return values

DATA_LOGGING_SUCCESS	Data logged.
DATA_LOGGING_INVALID_PARAMS	num_items is 0, or the data does not fit in the buffer.
DATA_LOGGING_CLOSED	The session is not active.
DATA_LOGGING_BUSY	Not enough room in the session buffer.
DATA_LOGGING_INTERNAL_ERR	Writing to flash failed.

dls_pause()

void dls_pause

(

void

)

Stop the periodic flush of sessions to the phone.

dls_resume()

void dls_resume

(

void

)

Restart the periodic flush of sessions to the phone.

dls_send_all_sessions()

void dls_send_all_sessions

(

void

)

Send all stored data to the phone now instead of at the next periodic flush.

Does nothing when sending is disabled.

dls_set_send_enable_pp()

void dls_set_send_enable_pp

(

bool

setting

)

Enable or disable sending, as requested by the phone.

Parameters

setting

true to enable.

dls_set_send_enable_run_level()

void dls_set_send_enable_run_level

(

bool

setting

)

Enable or disable sending, as requested by the run level.

Parameters

setting

true to enable.