BACKGROUND WORKER
This page contains some instructions that are different if you're using CloudPebble or if you're using the SDK locally on your computer.
Select whether you're using CloudPebble or the SDK below to show the relevant instructions!
CLOUDPEBBLE
SDK
In addition to the main foreground task that every Pebble app implements, a second background worker task can also be created. This worker is capable of running even when the foreground task is closed, and is useful for tasks that must continue for long periods of time. For example, apps that log sensor data.
There are several important points to note about the capabilities of this worker when compared to those of the foreground task:
The worker is constrained to 10.5 kB of memory.
Some APIs are not available to the worker. See the Available APIs section below for more information.
There can only be one background worker active at a time. In the event that a second one attempts to launch from another watchapp, the user will be asked to choose whether the new worker can replace the existing one.
The user can determine which app's worker is running by checking the 'Background App' section of the Settings menu. Workers can also be launched from there.
The worker can launch the foreground app using worker_launch_app(). This means that the foreground app should be prepared to be launched at any time that the worker is running.
Note: This API should not be used to build background timers; use the Wakeup API instead.
Adding a Worker
The background worker's behavior is determined by code written in a separate C file to the foreground app. Add a new source file and set the 'Target' field to 'Background Worker'.
The worker C file itself has a basic structure similar to a regular Pebble app, but with a couple of minor changes, as shown below:
#include <pebble_worker.h>
static void init() {
// Initialize the worker here
}
static void deinit() {
// Deinitialize the worker here
}
int main(void) {
init();
worker_event_loop();
deinit();
}
Launching the Worker
To launch the worker from the foreground app, use app_worker_launch():
// Launch the background worker
AppWorkerResult result = app_worker_launch();
The AppWorkerResult returned will indicate any errors encountered as a result of attempting to launch the worker. Possible result values include:
Result Value Description
APP_WORKER_RESULT_SUCCESS 0 The worker launch was successful, but may not start running immediately. Use app_worker_is_running() to determine when the worker has started running.
APP_WORKER_RESULT_NO_WORKER 1 No worker found for the current app.
APP_WORKER_RESULT_ALREADY_RUNNING 4 The worker is already running.
APP_WORKER_RESULT_ASKING_CONFIRMATION 5 The user will be asked for confirmation. To determine whether the worker was given permission to launch, use app_worker_is_running() for a short period after receiving this result.
Communicating with the Worker
There are three methods of obtaining the data from the worker:
Save the data using the Storage API and read it in the foreground app.
Receive the data directly while the foreground app is open using an AppWorkerMessage.
Worker
const int some_value = 1;
const int another_value = 2;
// Construct a data packet
AppWorkerMessage message = {
.data0 = some_value,
.data1 = another_value
};
// Send the data to the foreground app
const int message_type = 0;
app_worker_send_message(message_type, &message);
Foreground App
// Subscribe to get AppWorkerMessages
app_worker_message_subscribe(worker_message_handler);
static void worker_message_handler(uint16_t type,
AppWorkerMessage *message) {
// Get the data
int some_value = message->data0,
int another_value = message->data1
}
Send the data to a companion phone app using the DataLogging API. Details on how to do this are available in Datalogging.
Managing the Worker
The current running state of the background worker can be determined using the app_worker_is_running() function:
// Check to see if the worker is currently active
bool running = app_worker_is_running();
The user can tell whether the worker is running by checking the system 'Background App' settings. Any installed workers with be listed there.
The worker can be stopped using app_worker_kill():
// Stop the background worker
AppWorkerResult result = app_worker_kill();
Possible result values when attempting to kill the worker are as follows:
Result Value Description
APP_WORKER_RESULT_SUCCESS 0 The worker launch was killed successfully.
APP_WORKER_RESULT_DIFFERENT_APP 2 A worker from a different app is running, and cannot be killed by this app.
APP_WORKER_RESULT_NOT_RUNNING 3 The worker is not currently running.
Available APIs
Background workers do not have access to the UI APIs. They also cannot use the AppMessage API or load resources. Most other APIs are available including (but not limited to) AccelerometerService, CompassService, DataLogging and Storage.
CloudPebble users will be notified by the editor and compiler if they attempt to use an unavailable API.
