Add initial Toit SDK info

SW-786

Author: addshore

.vitepress/config.mts

@@ -278,6 +278,7 @@ export default withMermaid(defineConfig({
             },
             {
               text: 'Structure',
+              collapsed: true,
               link: '/devices/api/structure',
               items: [
                 {
@@ -300,11 +301,13 @@ export default withMermaid(defineConfig({
             },
             {
               text: 'Messages',
+              collapsed: true,
               link: '/devices/api/messages',
               items: protocolMenuItems,
             },
             {
               text: 'Tools',
+              collapsed: true,
               items: [
                 {
                   text: 'Generate',
@@ -320,6 +323,26 @@ export default withMermaid(defineConfig({
                 },
               ]
             },
+            {
+              text: 'SDKs',
+              collapsed: true,
+              items: [
+                {
+                  text: 'Toit',
+                  link: '/devices/api/sdks/toit/',
+                  items: [
+                    { text: 'Getting Started', link: '/devices/api/sdks/toit/getting-started' },
+                    {
+                      text: 'Examples',
+                      link: '/devices/api/sdks/toit/examples',
+                      items: [
+                        { text: 'EInk Hello World', link: '/devices/api/sdks/toit/examples/eink' },
+                      ]
+                    },
+                  ],
+                },
+              ]
+            },
           ]
         },
       ],

devices/api/index.md

@@ -22,15 +22,24 @@ The protocol builds on top of existing Lightbug Protocols, and is designed to be
  - Easy to use and understand
  - Usable in a variety of settings, without complex dependencies
 
-## Example
+## API Access
 
-An example prefixed and minimal message might look as follows:
+API access depends on the device and may not be supported on all models.
+
+Typically, it can be accessed via UART, I2C, or a UDP network connection.
+
+For access details, please [contact our support team](https://lightbug.io/contact/).
+
+Or you can get started with Toit quickly using the Lightbug provided SDK.
+
+## Example Message
+
+An example [prefixed](structure#prefix) and minimal message might look as follows:
 
 | Format | Message |
 | ------ | --- |
 | Bytes  | 76 66 3 11 0 1 0 0 0 0 0 75 190 |
 | Hex | `4c 42 03 0b 00 01 00 00 00 00 00 4b be` |
-| Hex (0x notation)    | `0x4c 0x42 0x03 0x0b 0x00 0x01 0x00 0x00 0x00 0x00 0x00 0x4b 0xbe` |
 
 <ProtocolBytes
     byteString="76 66 3 11 0 1 0 0 0 0 0 75 190"

devices/api/sdks/toit/examples/eink.md

@@ -0,0 +1,86 @@
+# Eink Hello World
+
+The latest version of the eink example can be [found on GitHub](https://github.com/lightbug-io/toit-lightbug/blob/main/examples/eink.toit).
+
+
+## Output
+
+When the program is running, you should see some output through the `monitor` command that looks something like this:
+
+```
+[lb-comms] INFO: Comms starting
+[lb-comms] INFO: Comms started
+💬 Sending text page to device
+💬 Text page sent
+Waiting on message latch
+✅ Text page ACKed
+Latch response: Message type: 5 length: 40 response-to: 3405447839
+```
+
+## Device
+
+The device EInk screen will update, displaying the text that was included in the message.
+
+## Code
+
+First, the required dependencies are [imported](https://docs.toit.io/language/imports).
+
+This primarily includes things from the `lightbug` package, but also the [log library](https://libs.toit.io/log/library-summary) that is part of the toit SDK.
+
+```toit
+import lightbug.devices as devices
+import lightbug.services as services
+import lightbug.messages as messages
+import log
+```
+
+A `main` function is defined, which is the entry point of the toit program.
+
+Here we start setting up the application, such as the log level to use, the device to use, and the communication service.
+
+```toit
+main:
+  // Setup the Toit logger with the INFO log level
+  log.set-default (log.default.with-level log.INFO-LEVEL)
+
+  // This example is setup to work with the RH2 device
+  device := devices.RtkHandheld2
+
+  // Setup the comms service, which allows communication with the Lightbug device
+  comms := services.Comms --device=device
+```
+
+We then send a single message to the device, which is a [text page](./../../../messages/10009-text-page.md).
+
+The `send` function is used to send the message, and it can take a number of optional parameters that allow hooking into the message lifecycle.
+
+```toit
+  // Send a basic text page to the device to display
+  // https://docs.lightbug.io/devices/api/tools/parse?bytes=03%2C57%2C00%2C19%2C27%2C02%2C00%2C05%2C01%2C01%2C01%2C04%2C7f%2C0e%2C60%2C9b%2C05%2C00%2C03%2C04%2C06%2C65%2C66%2C02%2Cd1%2C07%2C0b%2C48%2C65%2C6c%2C6c%2C6f%2C20%2C77%2C6f%2C72%2C6c%2C64%2C01%2C02%2C1f%2C57%2C65%2C6c%2C63%2C6f%2C6d%2C65%2C20%2C74%2C6f%2C20%2C79%2C6f%2C75%2C72%2C20%2C4c%2C69%2C67%2C68%2C74%2C62%2C75%2C67%2C20%2C64%2C65%2C76%2C69%2C63%2C65%2C0c%2C72%2C75%2C6e%2C6e%2C69%2C6e%2C67%2C20%2C54%2C6f%2C69%2C74%2Cb8%2C71
+  latch := comms.send (messages.TextPage.to-msg
+    --page-id=2001
+    --page-title="Hello world"
+    --line2="Welcome to your Lightbug device"
+    --line3="running Toit"
+    --redraw-type=2 // FullRedraw
+  )
+    --now=true
+    --withLatch=true
+    --preSend=(:: print "💬 Sending text page to device")
+    --postSend=(:: print "💬 Text page sent")
+    --onAck=(:: print "✅ Text page ACKed")
+    --onNack=(:: print "❌ Text page NACKed")
+    --onError=(:: print "❌ Text page error")
+```
+
+The code then waits for the message to be responded to, printing the response to the console.
+
+See [Latch](https://docs.toit.io/language/tasks/#latch) from the Toit [monitor library](https://libs.toit.io/monitor/library-summary).
+
+```toit
+  print "Waiting on message latch"
+  response := latch.get
+  // The value of the latch will be false on timeout or unknown error, or the msg object for the response
+  // Such as https://docs.lightbug.io/devices/api/tools/parse?bytes=03%2C28%2C00%2C05%2C00%2C04%2C00%2C03%2C04%2C01%2C02%2C04%2C7f%2C0e%2C60%2C9b%2C01%2C00%2C04%2Cd9%2C16%2C00%2C00%2C08%2Cb3%2Cd5%2C9b%2C00%2C00%2C00%2C00%2C00%2C01%2C00%2C01%2C02%2C19%2C27%2Ca9%2C0c
+  print "Latch response: $response"
+```

devices/api/sdks/toit/examples/index.md

@@ -0,0 +1,5 @@
+# Examples
+
+The lightbug pkg comes with a variety of examples that can be used to get started with the Lightbug device API.
+
+These are found in the `examples` directory of the pkg, which itself is a standalone Toit package.

devices/api/sdks/toit/getting-started.md

@@ -0,0 +1,87 @@
+
+# Getting started
+
+### 1. Get an ESP32 enabled device
+
+ESP32s are being introduced on some Lightbug devices.
+
+You'll need one of these devices to run Toit on a Lightbug device.
+
+### 2. Install Jaguar
+
+[Jaguar](https://github.com/toitlang/jaguar) is a small Toit application that runs on your ESP32 which comes with a command line tool that allows you to update and restart your ESP32 code written in Toit over WiFi, which is ideal for fast development.
+
+Install Jaguar, [following step 2](https://docs.toit.io/getstarted/device/#2-install-jaguar) in the Toit getting started guide.
+
+::: info
+We currently require `v1.50.3`+ of Jaguar, which bundles at least `v2.0.0-alpha.179` of Toit.
+:::
+
+Once installed, you should be able to run the version command:
+
+```sh
+jag version
+Version:         v1.50.3
+SDK version:     v2.0.0-alpha.179
+Build date:      2025-04-31T10:10:10Z
+```
+
+### 3. Flash the ESP
+
+Now it is time to connect your ESP enabled Lightbug device with a USB cable to your computer, and flash the ESP32 with the Jaguar firmware.
+
+::: info
+All ESP enabled Lightbug devices currently have ESP32C6 chips, so `--chip esp32c6` is required for flashing.
+:::
+
+Running `jag flash --chip esp32c6` will ask you for the serial port to use, and the WiFi credentials, but be aware that the tooling requires [permission to access your serial port](https://github.com/toitlang/jaguar#permission-to-access-serial-port).
+
+It's possible to configure default WiFi credentials, see the [Toit guide](https://docs.toit.io/getstarted/device/#3-flash-your-device) for more info.
+
+After flashing, your device boots up and starts the Toit virtual machine. The Jaguar service on the device starts a small HTTP server that listens for incoming requests. You can follow along by monitoring the serial output of the device:
+
+```sh
+jag monitor
+```
+
+### 4. Start a project
+
+Create a new directory for your project, and run the following command to create a new Toit project:
+
+```sh
+mkdir my-lightbug-project
+cd my-lightbug-project
+jag pkg init
+jag pkg install github.com/lightbug-io/toit-lightbug
+```
+
+You can copy the example [eink based Hello World application](https://github.com/lightbug-io/toit-lightbug/blob/main/examples/eink.toit) for the RTK Handheld 2 device into your project with the following command:
+
+```sh
+cp ./.packages/github.com/lightbug-io/toit-lightbug/0.7.0/examples/eink.toit ./main.toit
+```
+
+### 5. Run the code
+
+Use the `jag run` command to run the code on your device.
+
+```sh
+jag run ./main.toit
+```
+
+If your device can not be found automatically, you can specify the device IP address in the command line with the `--device` flag.
+
+Once the code is running, you should see some output through the `monitor` command you ran earlier.
+
+```
+[jaguar] INFO: program cf533602-d549-c9bd-34a3-3ae1093bda51 started
+[lb-comms] INFO: Comms starting
+[lb-comms] INFO: Comms started
+💬 Sending text page to device
+💬 Text page sent
+Waiting on message latch
+✅ Text page ACKed
+Latch response: Message type: 5 length: 40 response-to: 3405447839
+```
+
+And you should see the device screen update

devices/api/sdks/toit/index.md

@@ -0,0 +1,9 @@
+# Toit
+
+[Toit](https://toitlang.org/) is a modern high-level open source object oriented language designed for microcontrollers and the Internet of Things.
+
+[Jaguar](https://github.com/toitlang/jaguar) is a small Toit application that runs on your ESP32 which comes with a command line tool that allows you to update and restart your ESP32 code written in Toit over WiFi, which is ideal for fast development.
+
+Lightbug provides a [Toit package](https://pkg.toit.io/package/github.com%2Flightbug-io%2Ftoit-lightbug) that includes a set of bindings to Lightbug devices and the [Lightbug device API](./../../).
+
+Together, these tools allow you to quickly develop and deploy applications on Lightbug devices using Toit.