updated devices docs

microsoft · Sep 16, 2023 · afa5ce6 · afa5ce6
1 parent b880bc5
commit afa5ce6
Show file tree

Hide file tree

Showing 11 changed files with 71 additions and 61 deletions.
diff --git a/compiler/src/board.ts b/compiler/src/board.ts
@@ -10,7 +10,7 @@ import {
 } from "@devicescript/interop"
 import { DeviceCatalog, deviceCatalogImage, unique } from "jacdac-ts"
 import { resolveBuildConfig } from "./specgen"
-import { assert } from "./jdutil"
+import { assert, ellipseFirstSentence } from "./jdutil"
 
 export function boardInfos(info: RepoInfo) {
     return Object.values(info.boards).map(b =>
@@ -174,7 +174,7 @@ select "${devName}".
         `\`\`\`ts
 import { pins, board } from "@dsboard/${devId}"
 \`\`\``,
-        `\n{@import optional ./${devId.replace(/_/g, '-')}-examples.mdp}`,
+        `\n{@import optional ./${devId.replace(/_/g, "-")}-examples.mdp}`,
         `\n## Firmware update
 
 In Visual Studio Code,
@@ -218,7 +218,7 @@ export function boardMarkdownFiles() {
     const boardsjson: any = {}
     Object.keys(boards).forEach(boardid => {
         const board = boards[boardid]
-        const { archId, productId, devName } = board
+        const { archId, productId, devName, $description, url } = board
         if (!archId || archId === "wasm" || archId == "native") return
         const spec: jdspec.DeviceSpec =
             catalog.specificationFromProductIdentifier(parseAnyInt(productId))
@@ -230,15 +230,16 @@ export function boardMarkdownFiles() {
             spec
         )
 
+        const descr = ellipseFirstSentence($description) || ""
         const boardjson: any = board
         boardsjson[boardid] = boardjson
         const aidmd = `${aid}/boards.mdp`
-        const img = deviceCatalogImage(spec, "avatar")
-        if (img) {
+        const img = deviceCatalogImage(spec, "preview")
+        if (img && url) {
             r[aidmd] =
                 (r[aidmd] || "") +
                 `
-- [![photograph of ${devName}](${img}) ${devName}](/devices/${pa})`
+<DeviceCard image="${img}" href="/devices/${pa}" title="${devName}" description="${descr}" />`
             boardjson.img = deviceCatalogImage(spec, "catalog")
         }
     })

diff --git a/compiler/src/jdutil.ts b/compiler/src/jdutil.ts
@@ -626,6 +626,7 @@ export function ellipse(text: string, maxChars: number, suffix = "...") {
 }
 
 export function ellipseFirstSentence(text: string) {
+    if (!text) return text
     const i = text.indexOf(".")
     if (i < 0) return text
     else return text.slice(0, i + 1)

diff --git a/vscode/src/server-info.json b/vscode/src/server-info.json
@@ -345,6 +345,15 @@
                 "WaveSharePicoLCD114": "@devicescript/drivers"
             },
             "snippet": "const shield = new WaveSharePicoLCD114()\n"
+        },
+        {
+            "label": "Pimoroni Pico Badger",
+            "detail": "Support for Badger 2040 W (Pico W Aboard)",
+            "startName": "PimoroniBadger2040W",
+            "imports": {
+                "PimoroniBadger2040W": "@devicescript/drivers"
+            },
+            "snippet": "const shield = new PimoroniBadger2040W()\n"
         }
     ]
 }
diff --git a/website/docs/devices/boards.json b/website/docs/devices/boards.json
@@ -731,8 +731,7 @@
         "pinFault": 13,
         "service": "power"
       }
-    ],
-    "img": "https://microsoft.github.io/jacdac-docs/images/devices/microsoft-research/jmbrainesp3248v03.catalog.jpg"
+    ]
   },
   "msr59": {
     "$description": "Prototype board",
@@ -783,8 +782,7 @@
         "pinFault": 25,
         "service": "power"
       }
-    ],
-    "img": "https://microsoft.github.io/jacdac-docs/images/devices/microsoft-research/rp2040devicescript59v01.catalog.jpg"
+    ]
   },
   "pico": {
     "$description": "RP2040 board from Raspberry Pi.",

diff --git a/website/docs/devices/esp32/boards.mdp b/website/docs/devices/esp32/boards.mdp
@@ -1,10 +1,9 @@
 
-- [![photograph of Adafruit QT Py ESP32-C3 WiFi](https://microsoft.github.io/jacdac-docs/images/devices/adafruit/qtpyesp32c3wifidevboardv10.avatar.jpg) Adafruit QT Py ESP32-C3 WiFi](/devices/esp32/adafruit-qt-py-c3)
-- [![photograph of ESP32-C3FH4-RGB](https://microsoft.github.io/jacdac-docs/images/devices/01space/esp32c3fh4rgbv10.avatar.jpg) ESP32-C3FH4-RGB](/devices/esp32/esp32-c3fh4-rgb)
-- [![photograph of Espressif ESP32-DevKitC](https://microsoft.github.io/jacdac-docs/images/devices/espressif/esp32devkitcdevicescriptv40.avatar.jpg) Espressif ESP32-DevKitC](/devices/esp32/esp32-devkit-c)
-- [![photograph of Espressif ESP32-C3-RUST-DevKit](https://microsoft.github.io/jacdac-docs/images/devices/espressif/esp32c3rustdevkitv12a.avatar.jpg) Espressif ESP32-C3-RUST-DevKit](/devices/esp32/esp32c3-rust-devkit)
-- [![photograph of Espressif ESP32-S3 DevKitM](https://microsoft.github.io/jacdac-docs/images/devices/espressif/esp32s3devkitmv10.avatar.jpg) Espressif ESP32-S3 DevKitM](/devices/esp32/esp32s3-devkit-m)
-- [![photograph of Unexpected Maker FeatherS2 ESP32-S2](https://microsoft.github.io/jacdac-docs/images/devices/unexpected-maker/feathers2esp32s2v20.avatar.jpg) Unexpected Maker FeatherS2 ESP32-S2](/devices/esp32/feather-s2)
-- [![photograph of MSR JacdacIoT 48 v0.2](https://microsoft.github.io/jacdac-docs/images/devices/microsoft-research/jmbrainesp3248v03.avatar.jpg) MSR JacdacIoT 48 v0.2](/devices/esp32/msr48)
-- [![photograph of Seeed Studio XIAO ESP32C3](https://microsoft.github.io/jacdac-docs/images/devices/seeed-studio/xiaoesp32c3v00.avatar.jpg) Seeed Studio XIAO ESP32C3](/devices/esp32/seeed-xiao-esp32c3)
-- [![photograph of Seeed Studio XIAO ESP32C3 with MSR218 base](https://microsoft.github.io/jacdac-docs/images/devices/seeed-studio/xiaoesp32c3withmsr218base218v46.avatar.jpg) Seeed Studio XIAO ESP32C3 with MSR218 base](/devices/esp32/seeed-xiao-esp32c3-msr218)
+<DeviceCard image="https://microsoft.github.io/jacdac-docs/images/devices/adafruit/qtpyesp32c3wifidevboardv10.preview.jpg" href="/devices/esp32/adafruit-qt-py-c3" title="Adafruit QT Py ESP32-C3 WiFi" description="A tiny ESP32-C3 board." />
+<DeviceCard image="https://microsoft.github.io/jacdac-docs/images/devices/01space/esp32c3fh4rgbv10.preview.jpg" href="/devices/esp32/esp32-c3fh4-rgb" title="ESP32-C3FH4-RGB" description="A tiny ESP32-C3 board with 5x5 LED array." />
+<DeviceCard image="https://microsoft.github.io/jacdac-docs/images/devices/espressif/esp32devkitcdevicescriptv40.preview.jpg" href="/devices/esp32/esp32-devkit-c" title="Espressif ESP32-DevKitC" description="There are currently issues with serial chip on these, best avoid." />
+<DeviceCard image="https://microsoft.github.io/jacdac-docs/images/devices/espressif/esp32c3rustdevkitv12a.preview.jpg" href="/devices/esp32/esp32c3-rust-devkit" title="Espressif ESP32-C3-RUST-DevKit" description="A ESP32-C3 dev-board from Espressif with IMU and Temp/Humidity sensor, originally for ESP32 Rust port." />
+<DeviceCard image="https://microsoft.github.io/jacdac-docs/images/devices/espressif/esp32s3devkitmv10.preview.jpg" href="/devices/esp32/esp32s3-devkit-m" title="Espressif ESP32-S3 DevKitM" description="ESP32-S3 DevKitM development board." />
+<DeviceCard image="https://microsoft.github.io/jacdac-docs/images/devices/unexpected-maker/feathers2esp32s2v20.preview.jpg" href="/devices/esp32/feather-s2" title="Unexpected Maker FeatherS2 ESP32-S2" description="ESP32-S2 based development board in a Feather format." />
+<DeviceCard image="https://microsoft.github.io/jacdac-docs/images/devices/seeed-studio/xiaoesp32c3v00.preview.jpg" href="/devices/esp32/seeed-xiao-esp32c3" title="Seeed Studio XIAO ESP32C3" description="A tiny ESP32-C3 board." />
+<DeviceCard image="https://microsoft.github.io/jacdac-docs/images/devices/seeed-studio/xiaoesp32c3withmsr218base218v46.preview.jpg" href="/devices/esp32/seeed-xiao-esp32c3-msr218" title="Seeed Studio XIAO ESP32C3 with MSR218 base" description="A tiny ESP32-C3 board mounted on base with Jacdac, Qwiic and Grove connectors." />
diff --git a/website/docs/devices/esp32/index.mdx b/website/docs/devices/esp32/index.mdx
@@ -1,7 +1,14 @@
+import DeviceCard from "@site/src/components/DeviceCard"
+
 # ESP32
 
 The following devices use the firmware from https://github.com/microsoft/devicescript-esp32 which builds on top of ESP-IDF.
 
+<DeviceCard image="https://microsoft.github.io/jacdac-docs/images/devices/seeed-studio/xiaoesp32c3v00.preview.jpg" href="/devices/esp32/seeed-xiao-esp32c3" title="Seeed Studio XIAO ESP32C3" description="A tiny ESP32-C3 board." />
+<DeviceCard image="https://microsoft.github.io/jacdac-docs/images/devices/adafruit/qtpyesp32c3wifidevboardv10.preview.jpg" href="/devices/esp32/adafruit-qt-py-c3" title="Adafruit QT Py ESP32-C3 WiFi" description="A tiny ESP32-C3 board." />
+
+and more...
+
 {@import ./boards.mdp}
 
 :::tip

diff --git a/website/docs/devices/rp2040/boards.mdp b/website/docs/devices/rp2040/boards.mdp
@@ -1,4 +1,3 @@
 
-- [![photograph of MSR Brain RP2040 59 v0.1](https://microsoft.github.io/jacdac-docs/images/devices/microsoft-research/rp2040devicescript59v01.avatar.jpg) MSR Brain RP2040 59 v0.1](/devices/rp2040/msr59)
-- [![photograph of Raspberry Pi Pico](https://microsoft.github.io/jacdac-docs/images/devices/raspberry-pi/picov00.avatar.jpg) Raspberry Pi Pico](/devices/rp2040/pico)
-- [![photograph of Raspberry Pi Pico W](https://microsoft.github.io/jacdac-docs/images/devices/raspberry-pi/picowv00.avatar.jpg) Raspberry Pi Pico W](/devices/rp2040/pico-w)
+<DeviceCard image="https://microsoft.github.io/jacdac-docs/images/devices/raspberry-pi/picov00.preview.jpg" href="/devices/rp2040/pico" title="Raspberry Pi Pico" description="RP2040 board from Raspberry Pi." />
+<DeviceCard image="https://microsoft.github.io/jacdac-docs/images/devices/raspberry-pi/picowv00.preview.jpg" href="/devices/rp2040/pico-w" title="Raspberry Pi Pico W" description="RP2040 board from Raspberry Pi with a WiFi chip." />
diff --git a/website/docs/devices/rp2040/index.mdx b/website/docs/devices/rp2040/index.mdx
@@ -1,3 +1,5 @@
+import DeviceCard from "@site/src/components/DeviceCard"
+
 # RP2040
 
 The following devices use the firmware from https://github.com/microsoft/devicescript-pico

diff --git a/website/docs/devices/shields/index.mdx b/website/docs/devices/shields/index.mdx
@@ -13,34 +13,30 @@ import DeviceCard from "@site/src/components/DeviceCard"
 Shields typically bundle a number of sensor and connectors to accelerate the use of general purpose boards.
 DeviceScript provides support for a few shield "out of box" but more can be contributed or loaded through a package.
 
--   <DeviceCard
-        image={xiaoUrl}
-        href="/devices/shields/xiao-expansion-board"
-        title="Xiao Expansion Board"
-        description="For Xiao ESP32-C3 and similar boards."
-    />
-
--   <DeviceCard
-        image={picoBricksUrl}
-        href="/devices/shields/pico-bricks"
-        title="Pico Bricks"
-        description="For Raspberry Pi Pico and Pico-W"
-    />
-
--   <DeviceCard
-        image={waveUrl}
-        href="/devices/shields/waveshare-pico-lcd-114"
-        title="WaveShare Pico LCD 114"
-        description="For Raspberry Pi Pico and Pico-W"
-    />
-
--   <DeviceCard
-        image={badgerUrl}
-        href="/devices/shields/pimoroni-pico-badger"
-        title="Pimoroni Pico Badger"
-        description="For Raspberry Pi Pico and Pico-W"
-    />
-
+<DeviceCard
+    image={xiaoUrl}
+    href="/devices/shields/xiao-expansion-board"
+    title="Xiao Expansion Board"
+    description="For Xiao ESP32-C3 and similar boards."
+/>
+<DeviceCard
+    image={picoBricksUrl}
+    href="/devices/shields/pico-bricks"
+    title="Pico Bricks"
+    description="For Raspberry Pi Pico and Pico-W"
+/>
+<DeviceCard
+    image={waveUrl}
+    href="/devices/shields/waveshare-pico-lcd-114"
+    title="WaveShare Pico LCD 114"
+    description="For Raspberry Pi Pico and Pico-W"
+/>
+<DeviceCard
+    image={badgerUrl}
+    href="/devices/shields/pimoroni-pico-badger"
+    title="Pimoroni Pico Badger"
+    description="For Raspberry Pi Pico and Pico-W"
+/>
 
 ## See Also
 

diff --git a/website/src/components/DeviceCard/index.tsx b/website/src/components/DeviceCard/index.tsx
@@ -12,19 +12,18 @@ export default function DeviceCard(props: {
     const { image, imageAlt, description, title, href } = props
     const bhref = useBaseUrl(href)
     return (
-        <div className="avatar">
-            <a
+        <a href={bhref} className="avatar margin-vert--md">
+            <img
                 className={`avatar__photo-link avatar__photo avatar__photo--xl ${styles.device__photo}`}
-                href={bhref}
-            >
-                <img alt={imageAlt || `photograph of ${title}`} src={image} />
-            </a>
+                alt={imageAlt || `photograph of ${title}`}
+                src={image}
+            />
             <div className="avatar__intro">
                 <div className="avatar__name">{title}</div>
-                {description && (
+                {description ? (
                     <small className="avatar__subtitle">{description}</small>
-                )}
+                ) : null}
             </div>
-        </div>
+        </a>
     )
 }
diff --git a/website/src/components/DeviceCard/styles.module.css b/website/src/components/DeviceCard/styles.module.css
@@ -1,5 +1,4 @@
 .device__photo {
-  border-radius: 0.5rem;
+  border-radius: 0;
   height: unset;
-  --ifm-avatar-photo-size: 10rem;
 }