support for LED driver + simulation

cli/src/snippets.ts

@@ -55,7 +55,7 @@ export async function snippets(options: SnippetsOptions) {
             await writeFile(fullname, snip)
             imports += `import "./${mod}"\n`
             numsnip++
-            if (numsnip % 150 == 0) {
+            if (numsnip % 100 == 0) {
                 allImports.push(imports)
                 imports = ""
             }

compiler/src/specgen.ts

@@ -460,8 +460,7 @@ This service is ${status} and may change in the future.
 `
             : undefined,
         patchLinks(info.notes["short"]),
-        `-  client for [${info.name} service](https://microsoft.github.io/jacdac-docs/services/${info.shortId}/)`,
-        baseclass ? `-  inherits ${baseclass}` : undefined,
+        `\n{@import optional ../clients-custom/${info.shortId}-short.mdp}\n`,
         info.notes["long"]
             ? `## About
 

packages/core/src/index.ts

@@ -8,7 +8,6 @@ import "./array"
 import "./string"
 import "./events"
 import "./jacdac"
-import "./led"
 import "./lightbulb"
 import "./rotaryencoder"
 import "./button"

packages/drivers/src/index.ts

@@ -14,5 +14,6 @@ export * from "./dotmatrix"
 export * from "./st7735"
 export * from "./uc8151"
 export * from "./trafficlight"
+export * from "./ledserver"
 
 configureHardware({ scanI2C: false })

packages/drivers/src/ledserver.ts

@@ -0,0 +1,144 @@
+import * as ds from "@devicescript/core"
+import {
+    PixelBuffer,
+    fillFade,
+    pixelBuffer,
+    correctGamma,
+} from "@devicescript/runtime"
+import { Server, ServerOptions, startServer } from "@devicescript/server"
+
+export interface LedServerOptions {
+    /**
+     * Number of LEDs
+     */
+    length: number
+    /**
+     * Brightness applied to pixels before being rendered.
+     * This allocate twice the memory if less than 1 as an additional buffer is needed to compute the color.
+     * @default 1
+     */
+    intensity?: number
+    /**
+     * Number of columns of a LED matrix
+     */
+    columns?: number
+    ledsPerPixel?: number
+    /**
+     * For monochrome LEDs, the LED wavelength
+     */
+    waveLength?: number
+    /**
+     * The luminous power of the LEDs, is it very bright?
+     */
+    luminousIntensity?: number
+    /**
+     * The shape and topology of the LEDs
+     */
+    variant?: ds.LedVariant
+    /**
+     * Specify the amount of gamma correction
+     */
+    gamma?: number
+}
+
+class LedServer extends Server implements ds.LedServerSpec {
+    private _intensity: number
+    private _columns: number
+    private _ledPerPixels: number
+    private _waveLength: number
+    private _luminousIntensity: number
+    private _variant: ds.LedVariant
+    private _gamma: number
+
+    readonly buffer: PixelBuffer
+
+    constructor(options: LedServerOptions & ServerOptions) {
+        super(ds.Led.spec, options)
+        this.buffer = pixelBuffer(options.length)
+        this._intensity = options.intensity ?? 1
+        this._columns = options.columns
+        this._ledPerPixels = options.ledsPerPixel
+        this._waveLength = options.waveLength
+        this._luminousIntensity = options.luminousIntensity
+        this._variant = options.variant
+        this._gamma = options.gamma
+    }
+
+    pixels(): ds.Buffer {
+        if (this.buffer.length < 64) return this.buffer.buffer
+        else return Buffer.alloc(0)
+    }
+    set_pixels(value: ds.Buffer): void {
+        this.buffer.buffer.blitAt(0, value, 0, value.length)
+    }
+    intensity(): number {
+        return this._intensity
+    }
+    set_intensity(value: number): void {
+        this._intensity = Math.clamp(0, value, 1)
+    }
+    actualBrightness(): number {
+        return this._intensity
+    }
+    numPixels(): number {
+        return this.buffer.length
+    }
+    numColumns(): number {
+        return this._columns
+    }
+    ledsPerPixel(): number {
+        return this._ledPerPixels
+    }
+    waveLength(): number {
+        return this._waveLength || 0
+    }
+    luminousIntensity(): number {
+        return this._luminousIntensity
+    }
+    variant(): ds.LedVariant {
+        return this._variant
+    }
+
+    /**
+     * Display buffer on hardware
+     */
+    async show(): Promise<void> {
+        let b = this.buffer
+        // full brightness so we can use the buffer as is
+        if (this._intensity < 1 || this._gamma) {
+            const r = b.allocClone()
+            if (this._intensity < 1) fillFade(r, this._intensity)
+            if (this._gamma) correctGamma(r, this._gamma)
+            b = r
+        }
+        // TODO: render b to hardware
+    }
+}
+
+/**
+ * Starts a programmable LED server.
+ * Simulation is supported for up to 64 LEDs; otherwise only the simulator
+ * will reflect the state of LEDs.
+ * @param options
+ * @returns
+ */
+export async function startLed(
+    options: LedServerOptions & ServerOptions
+): Promise<ds.Led> {
+    const { length } = options
+    const server = new LedServer(options)
+    const client = new ds.Led(startServer(server))
+
+    ;(client as any)._buffer = server.buffer
+    client.show = async function () {
+        await server.show()
+        if (length <= 64) await client.pixels.write(server.buffer.buffer)
+        else if (ds.isSimulator()) {
+            // the simulator handles brightness separately
+            const topic = `jd/${server.serviceIndex}/leds`
+            await ds._twinMessage(topic, server.buffer.buffer)
+        }
+    }
+
+    return client
+}

packages/graphics/src/image.ts

@@ -33,14 +33,14 @@ export declare class Image {
     buffer: Buffer
 
     /**
-     * Get a pixel color
+     * Return a copy of the current image
      */
-    get(x: number, y: number): number
+    clone(): Image
 
     /**
-     * Return a copy of the current image
+     * Get a pixel color
      */
-    clone(): Image
+    get(x: number, y: number): number
 
     /**
      * Set pixel color

packages/graphics/src/palette.ts

@@ -1,55 +1,82 @@
 export class Palette {
     readonly buffer: Buffer
-    readonly numColors: number
+    /**
+     * Number of colors in the palette
+     */
+    readonly length: number
 
+    /**
+     * Allocates a 4bpp palette similar to MakeCode Arcade
+     * @returns
+     */
     static arcade() {
         return new Palette(hex`
             000000 ffffff ff2121 ff93c4 ff8135 fff609 249ca3 78dc52 
             003fad 87f2ff 8e2ec4 a4839f 5c406c e5cdc4 91463d 000000
         `)
     }
 
+    /**
+     * Allocates a 1bpp monochrome palette
+     * @returns
+     */
     static monochrome() {
         return new Palette(hex`000000 ffffff`)
     }
 
     constructor(init: Buffer) {
         this.buffer = init.slice(0)
         this.buffer.set(init)
-        this.numColors = (this.buffer.length / 3) >> 0
+        this.length = (this.buffer.length / 3) >> 0
     }
 
-    color(idx: number) {
-        if (idx < 0 || idx >= this.numColors) return 0
+    /**
+     * Returns the 24bit RGB color at the given index
+     * @param index
+     * @returns
+     */
+    getAt(index: number) {
+        if (index < 0 || index >= this.length) return 0
         return (
-            (this.buffer[3 * idx + 0] << 16) |
-            (this.buffer[3 * idx + 1] << 8) |
-            (this.buffer[3 * idx + 2] << 0)
+            (this.buffer[3 * index] << 16) |
+            (this.buffer[3 * index + 1] << 8) |
+            (this.buffer[3 * index + 2] << 0)
         )
     }
 
-    setColor(idx: number, color: number) {
-        this.buffer[3 * idx + 0] = color >> 16
-        this.buffer[3 * idx + 1] = color >> 8
-        this.buffer[3 * idx + 2] = color >> 0
+    /**
+     * Sets a 24bit RGB color at the given index
+     * @param index
+     * @param color 24bit RGB color
+     */
+    setAt(index: number, color: number) {
+        this.buffer[3 * index] = color >> 16
+        this.buffer[3 * index + 1] = color >> 8
+        this.buffer[3 * index + 2] = color >> 0
     }
 
-    // r,g,b,padding
+    /**
+     * Packs palette for Jacdac packet
+     * @returns
+     */
     packed(): Buffer {
-        const res: Buffer = Buffer.alloc(this.numColors << 2)
-        for (let i = 0; i < this.numColors; ++i) {
+        const res: Buffer = Buffer.alloc(this.length << 2)
+        for (let i = 0; i < this.length; ++i) {
             res[i * 4] = this.buffer[i * 3]
             res[i * 4 + 1] = this.buffer[i * 3 + 1]
             res[i * 4 + 2] = this.buffer[i * 3 + 2]
         }
         return res
     }
 
-    // r,g,b,padding
+    /**
+     * Unpacks palette from Jacdac packet
+     * @param buffer
+     */
     unpack(buffer: Buffer) {
-        if (buffer.length >> 2 !== this.numColors)
+        if (buffer.length >> 2 !== this.length)
             throw new RangeError("incorrect number of colors")
-        for (let i = 0; i < this.numColors; ++i) {
+        for (let i = 0; i < this.length; ++i) {
             this.buffer[i * 3] = buffer[i * 4]
             this.buffer[i * 3 + 1] = buffer[i * 4 + 1]
             this.buffer[i * 3 + 2] = buffer[i * 4 + 2]