--- title: "Background Worker" canonical_url: https://developer.repebble.com/guides/events-and-services/background-worker/ last_updated: 2025-08-03 sdk_version: 4.33.1 --- # Background Worker Source: https://developer.repebble.com/guides/events-and-services/background-worker/ 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_](#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()`](https://developer.repebble.com/docs/c/Worker.md#worker_launch_app "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`](https://developer.repebble.com/docs/c/Foundation/Wakeup.md "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, created in the `/worker_src` project directory. This project structure can also be generated using the [`pebble` tool](https://developer.repebble.com/guides/tools-and-resources/pebble-tool.md) with the `--worker` flag as shown below: ``` $ pebble new-project --worker project_name ``` 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 \static void prv\_init() {// Initialize the worker here}static void prv\_deinit() {// Deinitialize the worker here}int main(void) {prv\_init();worker\_event\_loop();prv\_deinit();} ``` ## Launching the Worker To launch the worker from the foreground app, use [`app_worker_launch()`](https://developer.repebble.com/docs/c/Foundation/AppWorker.md#app_worker_launch "app\_worker\_launch"): ``` // Launch the background workerAppWorkerResult result = app\_worker\_launch(); ``` The [`AppWorkerResult`](https://developer.repebble.com/docs/c/Foundation/AppWorker.md#AppWorkerResult "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`](https://developer.repebble.com/docs/c/Foundation/AppWorker.md#APP_WORKER_RESULT_SUCCESS "APP\_WORKER\_RESULT\_SUCCESS") | `0` | The worker launch was successful, but may not start running immediately. Use [`app_worker_is_running()`](https://developer.repebble.com/docs/c/Foundation/AppWorker.md#app_worker_is_running "app\_worker\_is\_running") to determine when the worker has started running. | | [`APP_WORKER_RESULT_NO_WORKER`](https://developer.repebble.com/docs/c/Foundation/AppWorker.md#APP_WORKER_RESULT_NO_WORKER "APP\_WORKER\_RESULT\_NO\_WORKER") | `1` | No worker found for the current app. | | [`APP_WORKER_RESULT_ALREADY_RUNNING`](https://developer.repebble.com/docs/c/Foundation/AppWorker.md#APP_WORKER_RESULT_ALREADY_RUNNING "APP\_WORKER\_RESULT\_ALREADY\_RUNNING") | `4` | The worker is already running. | | [`APP_WORKER_RESULT_ASKING_CONFIRMATION`](https://developer.repebble.com/docs/c/Foundation/AppWorker.md#APP_WORKER_RESULT_ASKING_CONFIRMATION "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()`](https://developer.repebble.com/docs/c/Foundation/AppWorker.md#app_worker_is_running "app\_worker\_is\_running") for a short period after receiving this result. | ## Communicating Between Tasks There are three methods of passing data between the foreground and background worker tasks: - Save the data using the [`Storage`](https://developer.repebble.com/docs/c/Foundation/Storage.md "Storage") API, then read it in the other task. - Send the data to a companion phone app using the [`DataLogging`](https://developer.repebble.com/docs/c/Foundation/DataLogging.md "DataLogging") API. Details on how to do this are available in [_Datalogging_](https://developer.repebble.com/guides/communication/datalogging.md). - Pass the data directly while the other task is running, using an [`AppWorkerMessage`](https://developer.repebble.com/docs/c/Foundation/AppWorker.md#AppWorkerMessage "AppWorkerMessage"). These messages can be sent bi-directionally by creating an `AppWorkerMessageHandler` in each task. The handler will fire in both the foreground and the background tasks, so you must identify the source of the message using the `type` parameter. ## Managing the Worker The current running state of the background worker can be determined using the [`app_worker_is_running()`](https://developer.repebble.com/docs/c/Foundation/AppWorker.md#app_worker_is_running "app\_worker\_is\_running") function: ``` // Check to see if the worker is currently activebool 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()`](https://developer.repebble.com/docs/c/Foundation/AppWorker.md#app_worker_kill "app\_worker\_kill"): ``` // Stop the background workerAppWorkerResult result = app\_worker\_kill(); ``` Possible `result` values when attempting to kill the worker are as follows: | Result | Value | Description | | --- | --- | --- | | [`APP_WORKER_RESULT_SUCCESS`](https://developer.repebble.com/docs/c/Foundation/AppWorker.md#APP_WORKER_RESULT_SUCCESS "APP\_WORKER\_RESULT\_SUCCESS") | `0` | The worker launch was killed successfully. | | [`APP_WORKER_RESULT_DIFFERENT_APP`](https://developer.repebble.com/docs/c/Foundation/AppWorker.md#APP_WORKER_RESULT_DIFFERENT_APP "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`](https://developer.repebble.com/docs/c/Foundation/AppWorker.md#APP_WORKER_RESULT_NOT_RUNNING "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`](https://developer.repebble.com/docs/c/Foundation/AppMessage.md "AppMessage") API or load resources. Most other APIs are available including (but not limited to) [`AccelerometerService`](https://developer.repebble.com/docs/c/Foundation/Event_Service/AccelerometerService.md "AccelerometerService"), [`CompassService`](https://developer.repebble.com/docs/c/Foundation/Event_Service/CompassService.md "CompassService"), [`DataLogging`](https://developer.repebble.com/docs/c/Foundation/DataLogging.md "DataLogging"), [`HealthService`](https://developer.repebble.com/docs/c/Foundation/Event_Service/HealthService.md "HealthService"), [`ConnectionService`](https://developer.repebble.com/docs/c/Foundation/Event_Service/ConnectionService.md "ConnectionService"), [`BatteryStateService`](https://developer.repebble.com/docs/c/Foundation/Event_Service/BatteryStateService.md "BatteryStateService"), [`TickTimerService`](https://developer.repebble.com/docs/c/Foundation/Event_Service/TickTimerService.md "TickTimerService") and [`Storage`](https://developer.repebble.com/docs/c/Foundation/Storage.md "Storage"). The compiler will throw an error if the developer attempts to use an API unsupported by the worker. For a definitive list of available APIs, check `pebble_worker.h` in the SDK bundle for the presence of the desired API.