Server to drivers, Display documentation

scripts/genhwsupport.mjs

@@ -10,7 +10,7 @@ function fail(msg) {
 const drivers = `runtime/jacdac-c/drivers/`
 const driversURL = `https://github.com/microsoft/jacdac-c/blob/main/drivers`
 const servicesURL = `/api/clients`
-const serversURL = `/api/servers`
+const serversURL = `/api/drivers`
 
 const srvNames = {
     "accelerometers": "accelerometer",
@@ -80,16 +80,16 @@ function collectAnalog() {
         let m = /interface (\w+)Config extends AnalogConfig/.exec(line)
         if (m) {
             const serv = m[1]
-            analog += `* [${serv}](${serversURL}/${serv.toLowerCase()})\n`
+            analog += `-   [${serv}](${serversURL}/${serv.toLowerCase()})\n`
         }
 
         m = /interface (\w+)Config extends BaseServiceConfig/.exec(line)
         if (m) {
             const serv = m[1]
             if (serv.startsWith("Hid")) {
-                hid += `* [HID ${serv.slice(3)}](/api/servers/${serv.toLowerCase()})\n`
+                hid += `-   [HID ${serv.slice(3)}](/api/drivers/${serv.toLowerCase()})\n`
             } else if (serv != "Analog") {
-                servers += `* [${serv}](${serversURL}/${serv.toLowerCase()})\n`
+                servers += `-   [${serv}](${serversURL}/${serv.toLowerCase()})\n`
             }
         }
     }

website/docs/api/servers/_category_.json → website/docs/api/drivers/_category_.json

@@ -1,5 +1,5 @@
 {
-    "label": "Servers",
+    "label": "Drivers",
     "position": 12,
     "collapsible": true
 }

website/docs/api/servers/aht20.mdx → website/docs/api/drivers/aht20.mdx

@@ -9,9 +9,10 @@ Driver for AHT20 temperature/humidity sensor at I2C address `0x38`.
 ## Usage
 
 ```ts
-// highlight-next-line
 import { startAHT20 } from "@devicescript/drivers"
-
-// highlight-next-line
 const { temperature, humidity } = await startAHT20()
 ```
+
+## Configuration
+
+-   Configure I2C throught the [board configuration](/developer/board-configuration)

website/docs/api/servers/bme680.mdx → website/docs/api/drivers/bme680.mdx

@@ -1,6 +1,7 @@
 # BME680
 
-Driver for BME680 temperature/humidity/air pressure/aqi.
+Driver for BME680 temperature/humidity/air pressure/aqi
+at I2C address `0x76` (default) or `0x77`.
 
 -   Services: [temperature](/api/clients/temperature/), [humidity](/api/clients/humidity/), [air pressure](/api/clients/airpressure/), [air quality index](/api/clients/airqualityindex/)
 -   [Datasheet](https://www.bosch-sensortec.com/media/boschsensortec/downloads/datasheets/bst-bme680-ds001.pdf)
@@ -12,3 +13,8 @@ Driver for BME680 temperature/humidity/air pressure/aqi.
 import { startBME680 } from "@devicescript/drivers"
 const { temperature, humidity, pressure, airQualityIndex } = await startBME680()
 ```
+
+## Configuration
+
+-   Configure I2C throught the [board configuration](/developer/board-configuration)
+-   Check that you are using the correct I2C address

website/docs/api/drivers/ssd1306.mdx

@@ -0,0 +1,38 @@
+---
+title: SSD1306
+---
+
+# SSD1306
+
+Driver for SSD1306 OLED screen at I2C address `0x3c` (or `0x3d`).
+
+This screen can be driven directly or through a character screen service.
+
+-   [Datasheet](https://www.digikey.com/htmldatasheets/production/2047793/0/0/1/ssd1306.html)
+
+![Photo of a SSD1306 screen](./ssd1306.png)
+
+## Hardware configuration
+
+-   Configure the I2C connection through the [board configuration](/developer/board-configuration)
+-   Check that you are using the proper I2C address
+
+## Display
+
+The driver implements the [Display](/developer/graphics/display) interface and can be used as various services.
+Using the driver through services provides a better simulation experience.
+
+## Driver
+
+You can also use the SS1306 driver directly. However, it will not be usable from a simulator.
+
+-   [Source](https://github.com/microsoft/devicescript/blob/main/packages/drivers/src/ssd1306.ts)
+
+```ts
+import { SSD1306Driver } from "@devicescript/drivers"
+
+const ssd = new SSD1306Driver({ width: 64, height: 48 })
+await ssd.init()
+ssd.image.print("Hello world!", 3, 10)
+await ssd.show()
+```

website/docs/developer/drivers/index.mdx

@@ -15,7 +15,7 @@ The [drivers builtin package](/developer/packages) exposes drivers for a number
 DeviceScript provides helper functions to mount a variety of servers out of the box
 in the `@devicescript/servers` module.
 
-For example, the [startButton](/api/servers/button) function allows your script
+For example, the [startButton](/api/drivers/button) function allows your script
 to mount a [button server](https://microsoft.github.io/jacdac-docs/services/button)
 over a pin and returns the [client](/api/clients/button) for it.
 

website/docs/developer/graphics/_category_.json

@@ -0,0 +1,4 @@
+{
+    "label": "Graphics",
+    "position": 10
+}

website/docs/api/servers/ssd1306.mdx → website/docs/developer/graphics/display.mdx

@@ -1,15 +1,15 @@
-# SS1306
+---
+sidebar_position: 2
+title: Display
+---
 
-Driver for SS1306 OLED screen at I2C address `0x3c` (or `0x3d`).
+# Display
 
-This screen can be driven directly or through a character screen service.
+The [Display](https://github.com/microsoft/devicescript/blob/main/packages/graphics/src/display.ts)
+interface provides an abstraction over a small screen. The `Display` interface is implemented
+for various hardware peripherical and can be used with various services.
 
--   [Datasheet](https://www.digikey.com/htmldatasheets/production/2047793/0/0/1/ssd1306.html)
-
-## Hardware configuration
-
--   Configure the I2C connection through the [board configuration](/developer/board-configuration)
--   Check that you are using the proper I2C address
+-   [SSD1306](/api/drivers/ssd1306)
 
 ## Indexed screen
 
@@ -75,18 +75,3 @@ await dots.writeImage(img`# # . # #
 . # # # .
 # . # . .`)
 ```
-
-## Driver
-
-You can also use the SS1306 driver directly. However, it will not be usable from a simulator.
-
--   [Source](https://github.com/microsoft/devicescript/blob/main/packages/drivers/src/ssd1306.ts)
-
-```ts
-import { SSD1306Driver } from "@devicescript/drivers"
-
-const ssd = new SSD1306Driver({ width: 64, height: 48 })
-await ssd.init()
-ssd.image.print("Hello world!", 3, 10)
-await ssd.show()
-```

website/docs/developer/graphics.mdx → website/docs/developer/graphics/image.mdx

@@ -1,30 +1,19 @@
 ---
-sidebar_position: 10
-title: Graphics
+sidebar_position: 1
+title: Image
 ---
 
-# Graphics
-
-The `@devicescript/graphics` package provides an `Image` type support which can be used to author efficient driver for small screens
-such as the [SSD1306 LCD screen](/api/servers/ssd1306)
-
-```ts
-import { Image } from "@devicescript/graphics"
-
-const img = Image.alloc(128, 64, 1)
-```
-
-## Image
+# Image
 
 The `Image` represents a space-optimized pateletted image, with either 1 or 4 bit per pixels.
 
-### `img`
+## `img`
 
 `img` is a [template literal](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals) that allows to declare images from ASCII art.
 The compiler will automatically generate an image in flash.
 This image is initially readonly; if you modify it, the runtime will internally allocate a buffer in RAM for it.
 
-The image format is the grid of pixels with either `.` or the palette color index (`#` treated as 1). 
+The image format is the grid of pixels with either `.` or the palette color index (`#` treated as 1).
 
 ```ts
 import { img } from "@devicescript/graphics"
@@ -45,7 +34,7 @@ You can use the [MakeCode Arcade](https://arcade.makecode.com) sprite editor to
 
 :::
 
-### Rendering context
+## Rendering context
 
 You can create a rendering context for an image; that provides a HTML canvas-like API (smaller subset).
 

website/docs/developer/graphics/index.mdx

@@ -0,0 +1,38 @@
+---
+sidebar_position: 10
+title: Graphics
+---
+
+# Graphics
+
+The `@devicescript/graphics` package provides an `Image` type and a `Display` type that supports
+paletted graphics.
+
+![Progress bar image](../jsx.png)
+
+The [image](/developer/graphics/image) can be used to author efficient driver for small screens
+such as the [SSD1306 OLED screen](/api/drivers/ssd1306)
+
+```ts
+import { Image } from "@devicescript/graphics"
+
+const img = Image.alloc(128, 64, 1)
+```
+
+-   [Image](/developer/graphics/image)
+
+A [display](/developer/graphics/display) driver for a screen, such as the [SSD1306](/api/drivers/ssd1306),
+exposes an image that represents the screen buffer. The driver typically
+can be used as an indexed screen service which provides simulation support.
+
+```ts
+import { SSD1306Driver, startIndexedScreen } from "@devicescript/drivers"
+
+const screen = await startIndexedScreen(
+    new SSD1306Driver({ width: 128, height: 64, devAddr: 0x3c })
+)
+screen.image.print(`Hello world!`, 3, 10)
+await screen.show()
+```
+
+-   [Display](/developer/graphics/display)

website/docs/developer/jsx.mdx

@@ -16,10 +16,12 @@ DeviceScript supports TSX compilation as documented in the TypeScript documentat
 ## Sample
 
 The [sampleui](https://github.com/microsoft/devicescript/tree/main/packages/sampleui) package is a sample UI framework based on a set of TSX functional components.
-It is designed to be used with small LCD screens such as the [SSD1306](/api/servers/ssd1306).
+It is designed to be used with small OLED screens using the [graphics](/developer/graphics) package.
 
 This snippet show a potential use of the JSX syntax to render a progress bar on a screen.
 
+![A progress bar screenshot](./jsx.png)
+
 ```tsx skip
 pot.reading.subscribe(async (pos: number) => {
     await renderOnImage(

website/docs/devices/analog.mdp

@@ -1,6 +1,6 @@
-* [LightLevel](/api/servers/lightlevel)
-* [ReflectedLight](/api/servers/reflectedlight)
-* [WaterLevel](/api/servers/waterlevel)
-* [SoundLevel](/api/servers/soundlevel)
-* [SoilMoisture](/api/servers/soilmoisture)
-* [Potentiometer](/api/servers/potentiometer)
+-   [LightLevel](/api/drivers/lightlevel)
+-   [ReflectedLight](/api/drivers/reflectedlight)
+-   [WaterLevel](/api/drivers/waterlevel)
+-   [SoundLevel](/api/drivers/soundlevel)
+-   [SoilMoisture](/api/drivers/soilmoisture)
+-   [Potentiometer](/api/drivers/potentiometer)

website/docs/devices/hid.mdp

@@ -1,3 +1,3 @@
-* [HID Mouse](/api/servers/hidmouse)
-* [HID Keyboard](/api/servers/hidkeyboard)
-* [HID Joystick](/api/servers/hidjoystick)
+-   [HID Mouse](/api/drivers/hidmouse)
+-   [HID Keyboard](/api/drivers/hidkeyboard)
+-   [HID Joystick](/api/drivers/hidjoystick)

website/docs/devices/index.mdx

@@ -6,7 +6,7 @@ sidebar_position: 0
 
 This page links to various developer boards that have a DeviceScript runtime firmware.
 
-For sensors and other peripherals, see [servers](/api/servers).
+For sensors and other peripherals, see [drivers](/api/drivers).
 
 ## Implementation status
 

website/docs/devices/servers.mdp

@@ -1,11 +1,13 @@
-* [RotaryEncoder](/api/servers/rotaryencoder)
-* [Button](/api/servers/button)
-* [Switch](/api/servers/switch)
-* [Flex](/api/servers/flex)
-* [Relay](/api/servers/relay)
-* [LightBulb](/api/servers/lightbulb)
-* [Buzzer](/api/servers/buzzer)
-* [Servo](/api/servers/servo)
-* [Motion](/api/servers/motion)
-* [Power](/api/servers/power)
-* [Accelerometer](/api/servers/accelerometer)
+-   [RotaryEncoder](/api/drivers/rotaryencoder)
+-   [Button](/api/drivers/button)
+-   [Switch](/api/drivers/switch)
+-   [Flex](/api/drivers/flex)
+-   [Relay](/api/drivers/relay)
+-   [LightBulb](/api/drivers/lightbulb)
+-   [Buzzer](/api/drivers/buzzer)
+-   [Motor](/api/drivers/motor)
+-   [Servo](/api/drivers/servo)
+-   [Motion](/api/drivers/motion)
+-   [Power](/api/drivers/power)
+-   [Accelerometer](/api/drivers/accelerometer)
+-   [Gamepad](/api/drivers/gamepad)

website/docs/samples/copy-paste-button.mdx

@@ -15,7 +15,7 @@ keywords:
 In this example, we use a single button to create a `copy-paste` micro-keyboard
 on [Raspberry Pi Pico](/devices/rp2040).
 
--   The button is connected to the Pico's GP14 pin. When the button is pressed, the Pico will send a `ctrl+c` or `ctrl+v` keystroke to the computer using a [HID keyboard](/api/servers/hidkeyboard) server.
+-   The button is connected to the Pico's GP14 pin. When the button is pressed, the Pico will send a `ctrl+c` or `ctrl+v` keystroke to the computer using a [HID keyboard](/api/drivers/hidkeyboard) server.
     The `ctrl+c` keystroke will copy the selected text, and the `ctrl+v` keystroke will paste the copied text.
 -   The status of the clipboard is indicated by a status LED connected to the Pico's GP1 pin. When the LED is on, the clipboard is full, and when the LED is off, the clipboard is empty.