SDK
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()andkode_rest_end()inkode.h, which block until the answer and are forapp_main()and tasks of your own (sdk/kode).kode_sys_rest()andkode_sys_rest_end()inkode_sys.h, which post the request and return. The answer arrives as an event, so an Active Object can use them.- The console verbs
restandrest_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
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
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), askode_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_SIGposted to its owner alone, withpartsset to that part's bit. A round withpartsat 0 is the board's. The owner puts that part away and answers withlowpower_ready()as for any round. - The owner brings its part back on a
LOWPOWER_STATE_SIGwith 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_TAKENand 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_SIGsaysKODE_LP_PART_TAKEN, thenLOWPOWER_STATE_SIGsays 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
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:lowpower_part.cholds the rules and the order,lowpower_ao.cthe walk over the owners,lowpower_verbs.cthe verbs.kode.h:kode_rest(),kode_rest_end()and their types.kode_sys.h:kode_sys_rest(),kode_sys_rest_end()and theKODE_SYS_REST_*bits.