added schedule blinky sample

packages/runtime/src/schedule.ts

@@ -1,4 +1,4 @@
-import { AsyncVoid } from "@devicescript/core"
+import { AsyncVoid, millis } from "@devicescript/core"
 
 /**
  * Schedules a handler to be called at a later time. Executes timeout before interval if combined.
@@ -9,7 +9,20 @@ import { AsyncVoid } from "@devicescript/core"
  * @returns clear timer function
  */
 export function schedule(
-    handler: () => AsyncVoid,
+    handler: (props: {
+        /**
+         * Number of times the handler has been called.
+         */
+        counter: number
+        /**
+         * Time in milliseconds since the first execution of the handler.
+         */
+        elapsed: number
+        /**
+         * Time in milliseconds since the last execution of the handler.
+         */
+        delta: number
+    }) => AsyncVoid,
     options?: {
         /**
          * Time in milliseconds to wait before the first execution of the handler.
@@ -31,22 +44,36 @@ export function schedule(
 
     if (!handler) return unsub
 
+    let start = millis()
+    let last = millis()
+    let counter = 0
+
+    const run = async () => {
+        const now = millis()
+        const props = {
+            counter: counter++,
+            elapsed: now - start,
+            delta: now - last,
+        }
+        last = now
+        await handler(props)
+    }
+
     let { interval, timeout } = options || {}
     if (interval === undefined && timeout === undefined) {
         timeout = 20
         interval = 60000
     }
     if (timeout >= 0 && interval >= 0) {
         timerId = setTimeout(async () => {
-            await handler()
+            await run()
             // check if cancelled or schedule
-            if (timerId !== undefined)
-                intervalId = setInterval(handler, interval)
+            if (timerId !== undefined) intervalId = setInterval(run, interval)
         }, 20)
     } else if (timeout) {
-        timerId = setTimeout(handler, timeout)
+        timerId = setTimeout(run, timeout)
     } else if (interval) {
-        intervalId = setInterval(handler, interval)
+        intervalId = setInterval(run, interval)
     }
     return unsub
 }

packages/sampleprj/src/mainscheduleblinky.ts

@@ -0,0 +1,16 @@
+import { schedule, setStatusLight } from "@devicescript/runtime"
+
+// counter increments on every invocation
+schedule(
+    async ({ counter }) => {
+        console.data({ counter })
+        // toggle between red and off
+        await setStatusLight(counter % 2 === 0 ? 0xff0000 : 0x000000)
+    },
+    {
+        // first delay
+        timeout: 100,
+        // repeated delay
+        interval: 1000,
+    }
+)

vscode/src/debugger.ts

@@ -223,24 +223,11 @@ export class DeviceScriptConfigurationProvider
                 "extension.devicescript.terminal.show"
             )
         if (settings.get("showSimulatorsOnStart")) {
-            if (this.simsShownOnce) {
-                vscode.window
-                    .showInformationMessage(
-                        "DeviceScript: Start simulators?",
-                        "Start"
-                    )
-                    .then(res => {
-                        if (res === "Start")
-                            vscode.commands.executeCommand(
-                                "extension.devicescript.openSimulators"
-                            )
-                    })
-            } else {
-                this.simsShownOnce = true
-                vscode.commands.executeCommand(
-                    "extension.devicescript.openSimulators"
-                )
-            }
+            vscode.commands.executeCommand(
+                "extension.devicescript.openSimulators",
+                { askUser: this.simsShownOnce }
+            )
+            this.simsShownOnce = true
         }
     }
 

vscode/src/simulatorWebView.ts

@@ -115,7 +115,16 @@ export class SimulatorsWebView extends JDEventSource {
         }
     }
 
-    private async handleOpen() {
+    private async handleOpen(options?: { askUser?: boolean }) {
+        const { askUser } = options || {}
+        if (!this.simulatorsWebviewPanel && askUser) {
+            const res = await vscode.window.showInformationMessage(
+                "DeviceScript: Start simulators?",
+                "Start"
+            )
+            if (res !== "Start") return
+        }
+
         if (this.simulatorsWebviewPanel) {
             this.simulatorsWebviewPanel.reveal(undefined, true)
             // make sure the tools are running

website/docs/api/runtime/_category_.json

@@ -0,0 +1,5 @@
+{
+    "label": "Runtime",
+    "position": 12,
+    "collapsible": true
+}

website/docs/api/runtime/index.md

@@ -0,0 +1,27 @@
+# Runtime
+
+The `@devicescript/runtime` [builtin](/developer/packages) module provides additional runtime helpers.
+
+### `schedule` {#schedule}
+
+The schedule function combines `setTimeout` and `setInterval` to provide a single function that can be used to schedule a function to run once or repeatedly.
+The function also tracks the number of invocation, total elapsed time and time since last invocation.
+
+```ts
+import { schedule, setStatusLight } from "@devicescript/runtime"
+
+// counter increments on every invocation
+schedule(
+    async ({ counter, elapsed, delta }) => {
+        console.data({ counter })
+        // toggle between red and off
+        await setStatusLight(counter % 2 === 0 ? 0xff0000 : 0x000000)
+    },
+    {
+        // first delay
+        timeout: 100,
+        // repeated delay
+        interval: 1000,
+    }
+)
+```

website/docs/samples/schedule-blinky.mdx

@@ -0,0 +1,27 @@
+---
+sidebar_position: 2.1
+title: Schedule Blinky
+---
+
+# Schedule Blinky
+
+This sample blinks the onboard LED using the [schedule](/api/runtime#schedule)
+
+```ts
+import { schedule, setStatusLight } from "@devicescript/runtime"
+
+// counter increments on every invocation
+schedule(
+    async ({ counter, elapsed, delta }) => {
+        console.data({ counter })
+        // toggle between red and off
+        await setStatusLight(counter % 2 === 0 ? 0xff0000 : 0x000000)
+    },
+    {
+        // first delay
+        timeout: 100,
+        // repeated delay
+        interval: 1000,
+    }
+)
+```