Import the pebble dev site into devsite/

devsite/source/_guides/events-and-services/wakeups.md

@@ -0,0 +1,206 @@
+---
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+title: Wakeups
+description: |
+  Using the Wakeup API to launch an app at some future time.
+guide_group: events-and-services
+order: 8
+related_examples:
+  - title: Tea Timer
+    url: https://github.com/pebble-examples/feature-app-wakeup
+related_docs:
+  - Wakeup
+  - AppLaunchReason
+  - launch_reason
+  - Timer
+---
+
+The ``Wakeup`` API allows developers to schedule an app launch in the future,
+even if the app itself is closed in the meantime. A wakeup event is scheduled in
+a similar manner to a ``Timer`` with a future timestamp calculated beforehand.
+
+
+## Calculating Timestamps
+
+To schedule a wakeup event, first determine the timestamp of the desired wakeup
+time as a `time_t` variable. Most uses of the ``Wakeup`` API will fall into
+three distinct scenarios discussed below.
+
+
+### A Future Time
+
+Call ``time()`` and add the offset, measured in seconds. For example, for 30
+minutes in the future:
+
+```c
+// 30 minutes from now
+time_t timestamp = time(NULL) + (30 * SECONDS_PER_MINUTE);
+```
+
+
+### A Specific Time
+
+Use ``clock_to_timestamp()`` to obtain a `time_t` timestamp by specifying a day
+of the week and hours and minutes (in 24 hour format). For example, for the next
+occuring Monday at 5 PM:
+
+```c
+// Next occuring monday at 17:00 
+time_t timestamp = clock_to_timestamp(MONDAY, 17, 0);
+```
+
+
+### Using a Timestamp Provided by a Web Service
+
+The timestamp will need to be translated using the 
+[`getTimezoneOffset()`](http://www.w3schools.com/jsref/jsref_gettimezoneoffset.asp) 
+method available in PebbleKit JS or with any timezone information given by the
+web service.
+
+
+## Scheduling a Wakeup
+
+Once a `time_t` timestamp has been calculated, the wakeup event can be
+scheduled:
+
+```c
+// Let the timestamp be 30 minutes from now
+const time_t future_timestamp = time() + (30 * SECONDS_PER_MINUTE);
+
+// Choose a 'cookie' value representing the reason for the wakeup
+const int cookie = 0;
+
+// If true, the user will be notified if they missed the wakeup 
+// (i.e. their watch was off)
+const bool notify_if_missed = true;
+
+// Schedule wakeup event
+WakeupId id = wakeup_schedule(future_timestamp, cookie, notify_if_missed);
+
+// Check the scheduling was successful
+if(id >= 0) {
+  // Persist the ID so that a future launch can query it
+  const wakeup_id_key = 43;
+  persist_write_int(wakeup_id_key, id);
+}
+```
+
+After scheduling a wakeup event it is possible to perform some interaction with
+it. For example, reading the timestamp for when the event will occur using the
+``WakeupId`` with ``wakeup_query()``, and then perform simple arithmetic to get
+the time remaining:
+
+```c
+// This will be set by wakeup_query()
+time_t wakeup_timestamp = 0;
+
+// Is the wakeup still scheduled?
+if(wakeup_query(id, &wakeup_timestamp)) {
+  // Get the time remaining
+  int seconds_remaining = wakeup_timestamp - time(NULL);
+  APP_LOG(APP_LOG_LEVEL_INFO, "%d seconds until wakeup", seconds_remaining);
+}
+```
+
+To cancel a scheduled event, use the ``WakeupId`` obtained when it was
+scheduled:
+
+```c
+// Cancel a wakeup
+wakeup_cancel(id);
+```
+
+To cancel all scheduled wakeup events:
+
+```c
+// Cancel all wakeups
+wakeup_cancel_all();
+```
+
+
+## Limitations
+
+There are three limitations that should be taken into account when using 
+the Wakeup API:
+
+* There can be no more than 8 scheduled wakeup events per app at any one time.
+
+* Wakeup events cannot be scheduled within 30 seconds of the current time.
+
+* Wakeup events are given a one minute window either side of the wakeup time. In
+  this time no app may schedule an event. The return ``StatusCode`` of
+  ``wakeup_schedule()`` should be checked to determine whether the scheduling of
+  the new event should be reattempted. A negative value indicates that the
+  wakeup could not be scheduled successfully.
+
+The possible ``StatusCode`` values are detailed below:
+
+|StatusCode|Value|Description|
+|----------|-----|-----------|
+| `E_RANGE` | `-8` | The wakeup event cannot be scheduled due to another event in that period. |
+| `E_INVALID_ARGUMENT` | `-4` | The time requested is in the past. |
+| `E_OUT_OF_RESOURCES` | `-7` | The application has already scheduled all 8 wakeup events. |
+| `E_INTERNAL` | `-3` | A system error occurred during scheduling. |
+
+
+## Handling Wakeup Events
+
+A wakeup event can occur at two different times - when the app is closed, and
+when it is already launched and in the foreground.
+
+If the app is launched due to a previously scheduled wakeup event, check the
+``AppLaunchReason`` and load the app accordingly:
+
+```c
+static void init() {
+  if(launch_reason() == APP_LAUNCH_WAKEUP) {
+    // The app was started by a wakeup event.
+    WakeupId id = 0;
+    int32_t reason = 0;
+
+    // Get details and handle the event appropriately
+    wakeup_get_launch_event(&id, &reason);
+  }
+
+  /* other init code */
+
+}
+```
+
+If the app is expecting a wakeup to occur while it is open, use a subscription
+to the wakeup service to be notified of such events:
+
+```c
+static void wakeup_handler(WakeupId id, int32_t reason) {
+  // A wakeup event has occurred while the app was already open
+}
+```
+
+```c
+// Subscribe to wakeup service
+wakeup_service_subscribe(wakeup_handler);
+```
+
+The two approaches can also be combined for a unified response to being woken
+up, not depenent on the state of the app:
+
+```c
+// Get details of the wakeup
+wakeup_get_launch_event(&id, &reason);
+
+// Manually handle using the handler
+wakeup_handler(id, reason);
+```