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:

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
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:

Specifications

The parts

PartFacade constantkode_sys.h constantBitOwner (joins as)What it doesHeld
ScreenKODE_REST_SCREENKODE_SYS_REST_SCREEN0x01AO_Display (display)The panel in sleep-in and its link down, as kode_display_sleep(true)Yes
PanelKODE_REST_PANELKODE_SYS_REST_PANEL0x02AO_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 lineYes
TouchKODE_REST_TOUCHKODE_SYS_REST_TOUCH0x04AO_Touch (touch)The touch controller in auto-sleep, with no interrupt. It reports nothingYes
SoundKODE_REST_SOUNDKODE_SYS_REST_SOUND0x08AO_Audio (audio)The speaker's amplifier off and the codec closedOnce
CardKODE_REST_CARDKODE_SYS_REST_CARD0x10AO_Storage (storage)The microSD card unmounted and its supply offOnce
RadioKODE_REST_RADIOKODE_SYS_REST_RADIO0x20AO_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 requestYes
CPUKODE_REST_CPUKODE_SYS_REST_CPU0x40AO_IoExp (ioexp)The P4 light-sleeps whenever every task is idle. Needs the screen at rest and no USB cableUntil a wake

The mask of every part is 0x7F (KODE_LP_PART_ALL). Held says what happens after the part is put 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:

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

FieldWhat wakes the P4Rules
touchA touchRefused while the touch or the panel is at rest
pin, pin_levelA 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 noneThe 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_msA time, in ms from the answer. 0 for noneAt 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_BUTTONA button
KODE_LP_WAKE_TOUCHA touch the app chose
KODE_LP_WAKE_PINThe pin the app chose
KODE_LP_WAKE_TIMERThe time the app chose
KODE_LP_WAKE_CONSOLEA console line
KODE_LP_WAKE_MQTTAn MQTT message
KODE_LP_WAKE_CABLEA USB cable
KODE_LP_WAKE_REQUESTA request to AO_LowPower
KODE_LP_WAKE_OWNERAn entry of the scheduler, or an owner's time
KODE_LP_WAKE_BATTERYThe cell at its cut: AO_Power is about to open the battery path

The board keeps the last word

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

CallWhat 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:

FieldWhat it holds
whatKODE_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)
rcFor an answer, the request's kode_status_t
partsThe mask of the parts at rest after the event. The sound and the card never appear in it
causeFor a wake, the kode_lp_wake_t
srcFor an answer, the source of the request
whyFor 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

TextMeaning
request: no partsThe mask is empty
request: no such partA bit outside 0x7F
radio: needs sound at restThe radio was named without the sound
cable: external powerThe CPU part was named with a USB cable in
cpu: needs the screen at restThe CPU part was named while the screen is up
touch: at rest cannot wakeA touch was chosen as a wake source with the touch or the panel at rest
pin: no such positionThe pin is not a position of J3
pin: in useThe position is an output, a PWM, an analog input, a loan to a driver, or an input somebody listens to
pin: no wake lineThe position's wake line would not arm
timer: busyThe wake time found no free one-shot
cpu: out of eventsNo 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 startkhal_power_init() failed
rest: underwayAnother request is being arranged
board: not awakeA round of the board runs
board: takes the restThe 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 answerThe part's owner did not answer in 3000 ms

The console

VerbAnswer
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_endThe same answer
lowpower_infoIts 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