# Part rest

How an app puts away the parts of a Kode Dot it does not use while the board stays awake: the seven parts, their order, what wakes the processor and the refusals.

## What it is

An app rarely uses every part of the Kode Dot. A part rest lets it name the parts it does not use, and **AO_LowPower** puts them away one at a time while the board stays **AWAKE** for everything else. The parts stay away until the app ends the rest, until the board goes to a state of its own (asleep or off), until a request for AWAKE, or until a restart.

There are seven parts. Each one belongs to the owner that runs it, and AO_LowPower asks that owner alone, with the same kind of round it uses for the board's own rest (`sdk/kaos/lowpower`). The owners that are not named go on as they were, and `LOWPOWER_STATE_SIG` says nothing: for the rest of the system the board is awake.

The rest has three doors, all served by the same code:

- `kode_rest()` and `kode_rest_end()` in `kode.h`, which block until the answer and are for `app_main()` and tasks of your own (`sdk/kode`).
- `kode_sys_rest()` and `kode_sys_rest_end()` in `kode_sys.h`, which post the request and return. The answer arrives as an event, so an Active Object can use them.
- The console verbs `rest` and `rest_end` (`internals/command-set`).

The rest exists only with `CONFIG_KODE_LOWPOWER`. The option is off in the SDK and on in KodeOS. Without it, `kode_rest()` returns false, `kode_sys_rest()` returns `KODE_DENIED`, and both log `low power not built`.

## How it is connected

```mermaid
flowchart LR
  subgraph down["Putting away"]
    direction LR
    s["sound<br/>AO_Audio"] --> c["card<br/>AO_Storage"] --> t["touch<br/>AO_Touch"] --> sc["screen<br/>AO_Display"] --> p["panel<br/>AO_Display"] --> r["radio<br/>AO_Radio"] --> cpu["CPU<br/>AO_IoExp"]
  end
  subgraph up["Bringing back"]
    direction LR
    cpu2["CPU"] --> r2["radio"] --> g2["screen and panel"] --> t2["touch"]
  end
```

*The order of a rest*

A request names a mask of parts. AO_LowPower first judges the whole request, and a request that cannot be done is refused whole, with nothing moved. Then it walks the parts in the order above, one owner at a time. Each owner has `KODE_LOWPOWER_PART_STEP_MS` (3000 ms) to put its part away and answer. An owner that answers busy is asked again `KODE_LOWPOWER_REQUEST_RETRY_MS` (1000 ms) later, as long as that ask falls inside `KODE_LOWPOWER_REQUEST_RETRY_WINDOW_MS` (10000 ms) of the request. Busy past the window, or silent for its step, it stops the request there. The parts put away before it stay at rest, and the answer names the part that did not.

An owner that answers after its step ran out still counts, and so does each of several. While the app's rest wants that part, it is held, and the end of the rest brings it back. When the app has ended its rest since, or asked for a rest without that part, the owner is told at once to bring it back. A part whose owner has no room for that wake stays held, so the next end of the rest brings it back.

A board round takes the app's rest for its own (`sdk/kaos/lowpower`). From then no app holds the radio, so a scan is not refused in an app's name. While the C5 sleeps between wakes for the board, a scan is refused as busy, to ask again.

`rest_end` brings the parts back in the other order: the CPU first, then the radio, the glass and the touch. The sound and the card are never held, so there is nothing to bring back for them.

An owner with no room in its queue for the AWAKE that brings its part back counts as busy. Its part stays at rest, and it is asked again every second inside the request's window, as a busy answer is. Past the window the end is refused with `<part>: out of events`, such as `radio: out of events`, and the part stays held until an end of the rest reaches its owner.

### The owner's side

The owners of the parts take part in the board's rounds already (`sdk/kaos/lowpower`). A part rest uses the same signal with one more field:

- The screen goes to sleep through `DISPLAY_SLEEP_REQ_SIG` (`who` = `DISPLAY_SLEEP_WHO_REST`), as `kode_display_sleep(true)` asks for it.
- The panel's supply goes through `DISPLAY_SUPPLY_REQ_SIG`. AO_Display drives the reset line low, then asks AO_IoExp for P7 low (`sdk/kaos/display`).
- Every other part is asked with `LOWPOWER_ROUND_SIG` posted to its owner alone, with `parts` set to that part's bit. A round with `parts` at 0 is the board's. The owner puts that part away and answers with `lowpower_ready()` as for any round.
- The owner brings its part back on a `LOWPOWER_STATE_SIG` with state AWAKE posted to it.

## Specifications

### The parts

| Part | Facade constant | `kode_sys.h` constant | Bit | Owner (joins as) | What it does | Held |
| --- | --- | --- | --- | --- | --- | --- |
| Screen | `KODE_REST_SCREEN` | `KODE_SYS_REST_SCREEN` | `0x01` | AO_Display (`display`) | The panel in sleep-in and its link down, as `kode_display_sleep(true)` | Yes |
| Panel | `KODE_REST_PANEL` | `KODE_SYS_REST_PANEL` | `0x02` | AO_Display (`display`) | The panel's supply off: the reset line low, then the supply. Takes the screen and the touch with it, because the touch controller shares the reset line | Yes |
| Touch | `KODE_REST_TOUCH` | `KODE_SYS_REST_TOUCH` | `0x04` | AO_Touch (`touch`) | The touch controller in auto-sleep, with no interrupt. It reports nothing | Yes |
| Sound | `KODE_REST_SOUND` | `KODE_SYS_REST_SOUND` | `0x08` | AO_Audio (`audio`) | The speaker's amplifier off and the codec closed | Once |
| Card | `KODE_REST_CARD` | `KODE_SYS_REST_CARD` | `0x10` | AO_Storage (`storage`) | The microSD card unmounted and its supply off | Once |
| Radio | `KODE_REST_RADIO` | `KODE_SYS_REST_RADIO` | `0x20` | AO_Radio (`radio`) | The C5 asleep between wakes, its sessions kept: Wi-Fi stays associated and Bluetooth keeps its connections. Needs the sound in the same request | Yes |
| CPU | `KODE_REST_CPU` | `KODE_SYS_REST_CPU` | `0x40` | AO_IoExp (`ioexp`) | The P4 light-sleeps whenever every task is idle. Needs the screen at rest and no USB cable | Until a wake |

The mask of every part is `0x7F` (`KODE_LP_PART_ALL`). **Held** says what happens after the part is put away:

- **Yes**: the part stays away until the rest ends.
- **Once**: the part is put away, and its next use brings it back. The next sound opens the codec and the amplifier again, and the next file on the card mounts it again. Such a part is never among the parts the answer reports at rest. Ask again to put it away again.
- **Until a wake**: the CPU part ends at the first wake, and the other parts stay away.

**The radio needs the sound.** The amplifier's enable is a line of the C5 (`PA_CTRL`, IO4), and a sound put away earlier may have come back. So a request that names the radio must name the sound too, and its owner is asked again. With the radio at rest, AO_Radio goes on as with the board awake: Wi-Fi joins its network again by itself and a C5 link that fell is built again. Only the C5 sleeps between wakes.

**The card stays in while it rests.** AO_Storage reports it with `rested` set on `STORAGE_CARD_SIG`, never as a card taken out, and the next file on it mounts it again (`sdk/kaos/storage`). In KodeOS, AO_AppMgr's idle copies of the apps begin nothing on a resting card. An install that would evict an app wakes the card to check or make that app's copy first, and the card then stays awake (`sdk/kaos/appmgr`).

**The CPU needs the screen at rest.** The panel's link holds the lock that keeps the P4 out of light sleep. The rule applies to an app that linked the display. An app that never calls a door of the display has nothing on the glass to rest.

### The CPU part

With the CPU part, AO_LowPower stops the QP tick and lets go of the lock, as in the board's ASLEEP. No Active Object counts time until a wake: work in flight in an owner that was not named stands still, and a `QTimeEvt` of the app does not expire. AO_LowPower keeps its own minute on a one-shot timer meanwhile. The minute reads the charger, counts `off_after` and serves the owners' times. AO_LowPower also looks for a cable every 2 s, as in the board's ASLEEP.

These always end the CPU part:

- Any button.
- A console line, on any port.
- An MQTT message, from the Kode channel or from an MQTT client of the app.
- A request to AO_LowPower, a part rest included.
- A USB cable, found by the look for a cable within 3 s (`sdk/kaos/lowpower`). AO_Log then shows the USB-C port to the computer again when the computer sends it no frames (`sdk/kaos/log`).
- The cell at its cut, when AO_Power is about to open the battery path.
- An entry of AO_Scheduler, or an owner's time that has come.

The app adds its own sources in the wake argument (`kode_rest_wake_t` or `kode_sys_rest_wake_t`):

| Field | What wakes the P4 | Rules |
| --- | --- | --- |
| `touch` | A touch | Refused while the touch or the panel is at rest |
| `pin`, `pin_level` | A level on a position of the expansion header J3, 1 to 14 (`KODE_PIN_FIRST` to `KODE_PIN_LAST`, `KODE_SYS_EXP_POS_MIN` to `_MAX`). 0 for none | The position must be free, or an input with no interrupt attached. During the rest it is an input pulled toward the other level. Afterwards it is what it was: free, or an input with the pull it had |
| `after_ms` | A time, in ms from the answer. 0 for none | At most two one-shots are out at once (`KODE_LOWPOWER_PART_TIMERS`). A time longer than a minute is counted in steps of `KODE_LOWPOWER_PART_HOP_MS` (60000 ms) |

A wake ends only the CPU part. The log says `rest: the P4 is awake again (<cause>); parts 0x<mask> stay at rest`, and `LOWPOWER_PART_SIG` reports it with `what` = `KODE_LP_PART_WOKE` and the cause. Ask for the CPU part again to let the P4 sleep again. A request that names other parts but not the CPU also wakes the P4, and the P4 sleeps again only when a request names the CPU part.

**`off_after` counts from the moment the P4 rests.** A P4 left at rest for the user's `off_after` time takes the board OFF, as a board asleep does (`sdk/kaos/lowpower`).

| Cause (`kode_lp_wake_t`) | What woke the P4 |
| --- | --- |
| `KODE_LP_WAKE_BUTTON` | A button |
| `KODE_LP_WAKE_TOUCH` | A touch the app chose |
| `KODE_LP_WAKE_PIN` | The pin the app chose |
| `KODE_LP_WAKE_TIMER` | The time the app chose |
| `KODE_LP_WAKE_CONSOLE` | A console line |
| `KODE_LP_WAKE_MQTT` | An MQTT message |
| `KODE_LP_WAKE_CABLE` | A USB cable |
| `KODE_LP_WAKE_REQUEST` | A request to AO_LowPower |
| `KODE_LP_WAKE_OWNER` | An entry of the scheduler, or an owner's time |
| `KODE_LP_WAKE_BATTERY` | The cell at its cut: AO_Power is about to open the battery path |

### The board keeps the last word

- **A round of the board asks the rest's owners last.** A round for ASLEEP that another owner refuses leaves the rest as it was. A round that goes through first reports `KODE_LP_PART_TAKEN` and then asks those owners.
- **An order for OFF takes the rest at once**, and so does a round that begins while a rest is being arranged.
- **A request for AWAKE takes the rest whenever it comes.** `LOWPOWER_PART_SIG` says `KODE_LP_PART_TAKEN`, then `LOWPOWER_STATE_SIG` says AWAKE over AWAKE and every part comes back. AO_Radio makes this request when its sleep sentinel stands down with the bus up, because the C5 stays awake through its rest (`sdk/kaos/lowpower`).
- **Holding the Back button to go home ends the rest**, because going home restarts the board.
- While a round of the board runs, a request is refused with `board: not awake`.

### The glass and the rest

`kode_display_sleep(false)`, or `kode_sys_screen_sleep(false)` from an Active Object, wakes a glass the rest put to sleep, with its supply. From then the screen and the panel are no longer held, and the next answer's mask says so. The CPU part is refused until the screen is at rest again.

`kode_rest_end()` leaves the display as `kode_display_sleep(false)` leaves it.

### The calls

| Call | What it does |
| --- | --- |
| `bool kode_rest(uint32_t parts, const kode_rest_wake_t *wake)` | Puts the parts away and waits, at most `KODE_REST_BOUND_MS` (37000 ms), one step over the longest answer. True when every named part is at rest. False with `kode_error()` naming the part that is not. Called again, it adds parts and takes the new wake sources. `wake` is NULL for no source beyond the buttons |
| `bool kode_rest_end(void)` | Brings back what the rest put away. True when all of it is back. False with `kode_error()` saying why, such as `the rest did not end: radio: out of events` |
| `kode_status_t kode_sys_rest(uint32_t parts, const kode_sys_rest_wake_t *wake)` | The command form, for an Active Object. `KODE_OK` means exactly one `LOWPOWER_PART_SIG` with `what` = `KODE_LP_PART_ANSWER` follows. `KODE_DENIED` while another request is being arranged (`rest: underway`) or in a build without `CONFIG_KODE_LOWPOWER` |
| `kode_status_t kode_sys_rest_end(void)` | The command form of the end. With nothing at rest the answer is `KODE_OK` at once. An owner with no room for its wake past the window makes the answer `KODE_DENIED` with `<part>: out of events`, and that part stays at rest |

**One asker at a time.** The answer carries no number, so two tasks of the app that ask at once can each take the other's answer. A request made while another is being arranged, the console's included, is refused at once and the one in hand goes on to its own answer.

### The answer: `LOWPOWER_PART_SIG`

AO_LowPower publishes `LOWPOWER_PART_SIG` with a `LowPowerPartEvt`:

| Field | What it holds |
| --- | --- |
| `what` | `KODE_LP_PART_ANSWER` (the answer to a request), `KODE_LP_PART_WOKE` (a wake ended the CPU part) or `KODE_LP_PART_TAKEN` (the board, or a request for AWAKE, took the rest over) |
| `rc` | For an answer, the request's `kode_status_t` |
| `parts` | The mask of the parts at rest after the event. The sound and the card never appear in it |
| `cause` | For a wake, the `kode_lp_wake_t` |
| `src` | For an answer, the source of the request |
| `why` | For a refusal, a copy of the text, `part: why` |

The request itself is `LOWPOWER_PART_REQ_SIG` (`LowPowerPartReqEvt`: `parts`, `end`, `wake_touch`, `wake_level`, `wake_pin`, `src`, `wake_after_ms`), posted to AO_LowPower. Build it with `lowpower_part_req_evt()` from `kaos.h`. A wake source the app chose posts `LOWPOWER_PART_WAKE_SIG` (`LowPowerPartWakeEvt`: the cause, `KODE_LP_WAKE_PIN` or `KODE_LP_WAKE_TIMER`). `lowpower_part_last()` reads the last answer, and `lowpower_part_why()` the last refusal.

### Refusals

| Text | Meaning |
| --- | --- |
| `request: no parts` | The mask is empty |
| `request: no such part` | A bit outside `0x7F` |
| `radio: needs sound at rest` | The radio was named without the sound |
| `cable: external power` | The CPU part was named with a USB cable in |
| `cpu: needs the screen at rest` | The CPU part was named while the screen is up |
| `touch: at rest cannot wake` | A touch was chosen as a wake source with the touch or the panel at rest |
| `pin: no such position` | The pin is not a position of J3 |
| `pin: in use` | The position is an output, a PWM, an analog input, a loan to a driver, or an input somebody listens to |
| `pin: no wake line` | The position's wake line would not arm |
| `timer: busy` | The wake time found no free one-shot |
| `cpu: out of events` | No event was left to ask the CPU's owner. `<part>: out of events` is the same for another part. At the end of a rest it says the part's owner had no room for its wake through the whole window, and the part stays at rest |
| `cpu: power management did not start` | `khal_power_init()` failed |
| `rest: underway` | Another request is being arranged |
| `board: not awake` | A round of the board runs |
| `board: takes the rest` | The board took the rest over while the request was arranged |
| `<part>: <why>` | The part's owner answered busy, for example `display: glass not asleep` |
| `<part>: no answer` | The part's owner did not answer in 3000 ms |

### The console

| Verb | Answer |
| --- | --- |
| `rest parts=<1..127> [touch=on\|off] [pin=<1..14> level=on\|off] [after_ms=<1..86400000>]` | `>\|rest parts=<mask at rest>` then `>ok`, or `>err code=4 msg="<part>: <why>"`. A queue with no room answers `>err code=4 msg=busy` |
| `rest_end` | The same answer |
| `lowpower_info` | Its third record, `>\|lowpower_rest parts=<mask> last_busy="<text>"\|-`, holds the parts at rest and the last refusal of a rest |

The answer goes to the port that asked. A wake and a rest that the board took are news, and the verb does not answer them.

## Gotchas

> **WARNING**
>
> **The CPU part stops the system's clock.** A timer of your Active Object, a download in AO_Net, a write in AO_Storage: anything that counts time waits for the wake. Finish file and network work before you ask for the CPU part, and wait for the wake with `kode_event_wait()` or a button, not by asking the board for things.

> **WARNING**
>
> **`cable: external power` on the bench.** The CPU part is refused while a USB cable is in, as the board's sleep is. The other six parts rest on a cable. Test the CPU part on the battery, and read `lowpower_info` once the cable is back.

> **NOTE**
>
> **The sound and the card come back by themselves.** They are put away once and their next use brings them back. A request that names them again puts them away again.

> **NOTE**
>
> **What a part rest saves is not a measured figure.**

## Example code

No runnable example is available for this page. `sdk/kode` lists the calls, and the console's `rest` drives the same code from the bench.

## In the SDK

- [`components/kaos/lowpower`](https://github.com/kodediy/kode-sdk/tree/main/components/kaos/lowpower): `lowpower_part.c` holds the rules and the order, `lowpower_ao.c` the walk over the owners, `lowpower_verbs.c` the verbs.
- [`kode.h`](https://github.com/kodediy/kode-sdk/blob/main/components/kode/include/kode.h): `kode_rest()`, `kode_rest_end()` and their types.
- [`kode_sys.h`](https://github.com/kodediy/kode-sdk/blob/main/components/kode_sys/include/kode_sys.h): `kode_sys_rest()`, `kode_sys_rest_end()` and the `KODE_SYS_REST_*` bits.
