neopixel.ts

/**
 * Well known colors for a NeoPixel cube
 */
enum NeoPixelColors {
	//% block=red
	Red = 0xff0000,
	//% block=orange
	Orange = 0xffa500,
	//% block=yellow
	Yellow = 0xffff00,
	//% block=green
	Green = 0x00ff00,
	//% block=blue
	Blue = 0x0000ff,
	//% block=indigo
	Indigo = 0x4b0082,
	//% block=violet
	Violet = 0x8a2be2,
	//% block=purple
	Purple = 0xff00ff,
	//% block=white
	White = 0xffffff,
	//% block=black
	Black = 0x000000,
}

/**
 * Different modes for RGB or RGB+W NeoPixel cubes
 */
enum NeoPixelMode {
	//% block="RGB (GRB format)"
	RGB = 1,
	//% block="RGB+W"
	RGBW = 2,
	//% block="RGB (RGB format)"
	RGB_RGB = 3,
}

/**
 * Functions to operate NeoPixel cubes.
 */
//% weight=5 color=#2699BF icon="\uf110"
namespace neopixel_3d {
	/**
	 * A NeoPixel cube
	 */
	export class Strip {
		buf: Buffer;
		pin: DigitalPin;
		// TODO: encode as bytes instead of 32bit
		brightness: number;
		start: number; // start offset in LED cube
		_length: number; // number of LEDs
		_mode: NeoPixelMode;
		_cubeWidthX: number; // number of leds in a cube in x direction - if any
		_cubeWidthY: number; // number of leds in a cube in y direction - if any
		_cubeWidthZ: number; // number of leds in a cube in z direction - if any

		/**
		 * Shows all LEDs to a given color (range 0-255 for r, g, b).
		 * @param rgb RGB color of the LED
		 */
		//% blockId="neopixel_set_color" block="%cube|show color %rgb=neopixel_colors"
		//% cube.defl=cube
		//% weight=85 blockGap=8
		//% parts="neopixel"
		showColor(rgb: number) {
			rgb = rgb >> 0;
			this.setAllRGB(rgb);
			this.show();
		}

		private setPixelColor(pixeloffset: number, rgb: number): void {
			this.setPixelRGB(pixeloffset >> 0, rgb >> 0);
		}

		/**
		 * Set LED to a given color (range 0-255 for r, g, b) in a cube shaped cube
		 * You need to call ``show`` to make the changes visible.
		 * @param x horizontal position
		 * @param y horizontal position
		 * @param z vertical position
		 * @param rgb RGB color of the LED
		 */
		//% blockId="neopixel_set_cube_color" block="set cube %cube x-coordinate %x y-coordinate %y z-coordinate %z to color %rgb=neopixel_colors"
		//% cube.defl=cube
		//% weight=86
		//% parts="neopixel"
		setCubeColor(x: number, y: number, z: number, rgb: number) {
			if (
				this._cubeWidthX <= 0 ||
				this._cubeWidthY <= 0 ||
				this._cubeWidthZ <= 0
			)
				return;
			x = x >> 0;
			y = y >> 0;
			z = z >> 0;
			rgb = rgb >> 0;
			if (
				x < 0 ||
				x >= this._cubeWidthX ||
				y < 0 ||
				y >= this._cubeWidthY ||
				z < 0 ||
				z >= this._cubeWidthZ
			)
				return;
			let i =
				x + y * this._cubeWidthX + z * this._cubeWidthX * this._cubeWidthY;
			this.setPixelColor(i, rgb);
		}

		/**
		 * Send all the changes to the cube.
		 */
		//% blockId="neopixel_show" block="%cube|show" blockGap=8
		//% cube.defl=cube
		//% weight=79
		//% parts="neopixel"
		show() {
			// only supported in beta
			// ws2812b.setBufferMode(this.pin, this._mode);
			ws2812b.sendBuffer(this.buf, this.pin);
		}

		/**
		 * Turn off all LEDs.
		 * You need to call ``show`` to make the changes visible.
		 */
		//% blockId="neopixel_clear" block="%cube|clear"
		//% cube.defl=cube
		//% weight=76
		//% parts="neopixel"
		clear(): void {
			const stride = this._mode === NeoPixelMode.RGBW ? 4 : 3;
			this.buf.fill(0, this.start * stride, this._length * stride);
		}

		/**
		 * Basiclly a combination of show and clear: this will clear then show
		 */
		//% blockId="neopixel_update" block="%cube|clear all"
		//% cube.defl=cube
		//% weight=80
		//% parts="neopixel"
		update(): void {
			const stride = this._mode === NeoPixelMode.RGBW ? 4 : 3;
			this.buf.fill(0, this.start * stride, this._length * stride);
			ws2812b.sendBuffer(this.buf, this.pin);
		}

		/**
		 * Gets the number of pixels declared on the cube
		 */
		//% blockId="neopixel_length" block="%cube|total LEDs" blockGap=8
		//% cube.defl=cube
		//% weight=60
		length() {
			return this._length;
		}

		/**
		 * Gets the number of pixels on the x direction
		 */
		//% blockId="neopixel_lengthX" block="%cube|x" blockGap=8
		//% cube.defl=cube
		//% weight=63
		lengthX() {
			return this._cubeWidthX;
		}

		/**
		 * Gets the number of pixels on the y direction
		 */
		//% blockId="neopixel_lengthY" block="%cube|y" blockGap=8
		//% cube.defl=cube
		//% weight=62
		lengthY() {
			return this._cubeWidthY;
		}

		/**
		 * Gets the number of pixels on the z direction
		 */
		//% blockId="neopixel_lengthZ" block="%cube|z" blockGap=8
		//% cube.defl=cube
		//% weight=61
		lengthZ() {
			return this._cubeWidthZ;
		}

		/**
		 * Set the brightness of the cube. This flag only applies to future operation.
		 * @param brightness a measure of LED brightness in 0-255. eg: 255
		 */
		//% blockId="neopixel_set_brightness" block="%cube|set brightness %brightness" blockGap=8
		//% cube.defl=cube
		//% weight=59
		//% parts="neopixel"
		setBrightness(brightness: number): void {
			this.brightness = brightness & 0xff;
		}

		/**
		 * Apply brightness to current colors using a quadratic easing function.
		 **/
		//% blockId="neopixel_each_brightness" block="%cube|ease brightness" blockGap=8
		//% cube.defl=cube
		//% weight=58
		//% parts="neopixel"
		easeBrightness(): void {
			const stride = this._mode === NeoPixelMode.RGBW ? 4 : 3;
			const br = this.brightness;
			const buf = this.buf;
			const end = this.start + this._length;
			const mid = Math.idiv(this._length, 2);
			for (let i = this.start; i < end; ++i) {
				const k = i - this.start;
				const ledoffset = i * stride;
				const br =
					k > mid
						? Math.idiv(
								255 * (this._length - 1 - k) * (this._length - 1 - k),
								mid * mid
						  )
						: Math.idiv(255 * k * k, mid * mid);
				const r = (buf[ledoffset + 0] * br) >> 8;
				buf[ledoffset + 0] = r;
				const g = (buf[ledoffset + 1] * br) >> 8;
				buf[ledoffset + 1] = g;
				const b = (buf[ledoffset + 2] * br) >> 8;
				buf[ledoffset + 2] = b;
				if (stride == 4) {
					const w = (buf[ledoffset + 3] * br) >> 8;
					buf[ledoffset + 3] = w;
				}
			}
		}

		/**
		 * Set the pin where the neopixel is connected, defaults to P0.
		 */
		//% weight=10
		//% parts="neopixel"
		setPin(pin: DigitalPin): void {
			this.pin = pin;
			pins.digitalWritePin(this.pin, 0);
			// don't yield to avoid races on initialization
		}

		/**
		 * Estimates the electrical current (mA) consumed by the current light configuration.
		 */
		//% weight=9 blockId=neopixel_power block="%cube|power (mA)"
		//% cube.defl=cube
		//%
		power(): number {
			const stride = this._mode === NeoPixelMode.RGBW ? 4 : 3;
			const end = this.start + this._length;
			let p = 0;
			for (let i = this.start; i < end; ++i) {
				const ledoffset = i * stride;
				for (let j = 0; j < stride; ++j) {
					p += this.buf[i + j];
				}
			}
			return (
				Math.idiv(this.length() * 7, 10) /* 0.7mA per neopixel */ +
				Math.idiv(p * 480, 10000)
			); /* rought approximation */
		}

		private setBufferRGB(
			offset: number,
			red: number,
			green: number,
			blue: number
		): void {
			if (this._mode === NeoPixelMode.RGB_RGB) {
				this.buf[offset + 0] = red;
				this.buf[offset + 1] = green;
			} else {
				this.buf[offset + 0] = green;
				this.buf[offset + 1] = red;
			}
			this.buf[offset + 2] = blue;
		}

		private setAllRGB(rgb: number) {
			let red = unpackR(rgb);
			let green = unpackG(rgb);
			let blue = unpackB(rgb);

			const br = this.brightness;
			if (br < 255) {
				red = (red * br) >> 8;
				green = (green * br) >> 8;
				blue = (blue * br) >> 8;
			}
			const end = this.start + this._length;
			const stride = this._mode === NeoPixelMode.RGBW ? 4 : 3;
			for (let i = this.start; i < end; ++i) {
				this.setBufferRGB(i * stride, red, green, blue);
			}
		}
		private setAllW(white: number) {
			if (this._mode !== NeoPixelMode.RGBW) return;

			let br = this.brightness;
			if (br < 255) {
				white = (white * br) >> 8;
			}
			let buf = this.buf;
			let end = this.start + this._length;
			for (let i = this.start; i < end; ++i) {
				let ledoffset = i * 4;
				buf[ledoffset + 3] = white;
			}
		}
		private setPixelRGB(pixeloffset: number, rgb: number): void {
			if (pixeloffset < 0 || pixeloffset >= this._length) return;

			let stride = this._mode === NeoPixelMode.RGBW ? 4 : 3;
			pixeloffset = (pixeloffset + this.start) * stride;

			let red = unpackR(rgb);
			let green = unpackG(rgb);
			let blue = unpackB(rgb);

			let br = this.brightness;
			if (br < 255) {
				red = (red * br) >> 8;
				green = (green * br) >> 8;
				blue = (blue * br) >> 8;
			}
			this.setBufferRGB(pixeloffset, red, green, blue);
		}
		private setPixelW(pixeloffset: number, white: number): void {
			if (this._mode !== NeoPixelMode.RGBW) return;

			if (pixeloffset < 0 || pixeloffset >= this._length) return;

			pixeloffset = (pixeloffset + this.start) * 4;

			let br = this.brightness;
			if (br < 255) {
				white = (white * br) >> 8;
			}
			let buf = this.buf;
			buf[pixeloffset + 3] = white;
		}
	}

	/**
	 * Create a new NeoPixel driver for `numleds` LEDs.
	 * @param pin the pin where the neopixel is connected.
	 * @param numleds number of leds in the cube, eg: 24,30,60,64
	 */
	//% blockId="neopixel_create" block="NeoPixel cube at pin %pin|size x%x|by y%y|by z%z|as %mode"

	//% weight=90 blockGap=8
	//% parts="neopixel"
	//% trackArgs=0,2
	//% blockSetVariable=cube
	export function create(
		pin: DigitalPin,
		x: number,
		y: number,
		z: number,
		mode: NeoPixelMode
	): Strip {
		x = x >> 0;
		y = y >> 0;
		z = z >> 0;
		const numleds = x * y * z;
		let cube = new Strip();
		let stride = mode === NeoPixelMode.RGBW ? 4 : 3;
		cube.buf = pins.createBuffer(numleds * stride);
		cube.start = 0;
		cube._length = numleds;
		cube._mode = mode || NeoPixelMode.RGB;
		cube.setBrightness(128);
		cube.setPin(pin);
		// Validate cube dimensions
		if (x <= 0 || y <= 0 || z <= 0) {
			cube._cubeWidthX = 0;
			cube._cubeWidthY = 0;
			cube._cubeWidthZ = 0;
			return cube;
		}

		// Set valid cube dimensions
		cube._cubeWidthX = x;
		cube._cubeWidthY = y;
		cube._cubeWidthZ = z;

		return cube;
		return cube;
	}

	/**
	 * Converts red, green, blue channels into a RGB color
	 * @param red value of the red channel between 0 and 255. eg: 255
	 * @param green value of the green channel between 0 and 255. eg: 255
	 * @param blue value of the blue channel between 0 and 255. eg: 255
	 */
	//% weight=1
	//% blockId="neopixel_rgb" block="red %red|green %green|blue %blue"
	//%
	export function rgb(red: number, green: number, blue: number): number {
		return packRGB(red, green, blue);
	}

	/**
	 * Gets the RGB value of a known color
	 */
	//% weight=2 blockGap=8
	//% blockId="neopixel_colors" block="%color"
	//%
	export function colors(color: NeoPixelColors): number {
		return color;
	}

	function packRGB(a: number, b: number, c: number): number {
		return ((a & 0xff) << 16) | ((b & 0xff) << 8) | (c & 0xff);
	}
	function unpackR(rgb: number): number {
		let r = (rgb >> 16) & 0xff;
		return r;
	}
	function unpackG(rgb: number): number {
		let g = (rgb >> 8) & 0xff;
		return g;
	}
	function unpackB(rgb: number): number {
		let b = rgb & 0xff;
		return b;
	}

	/**
	 * Converts a hue saturation luminosity value into a RGB color
	 * @param h hue from 0 to 360
	 * @param s saturation from 0 to 99
	 * @param l luminosity from 0 to 99
	 */
	//% blockId=neopixelHSL block="hue %h|saturation %s|luminosity %l"
	//% weight=2
	export function hsl(h: number, s: number, l: number): number {
		h = Math.round(h);
		s = Math.round(s);
		l = Math.round(l);

		h = h % 360;
		s = Math.clamp(0, 99, s);
		l = Math.clamp(0, 99, l);
		let c = Math.idiv(((100 - Math.abs(2 * l - 100)) * s) << 8, 10000); //chroma, [0,255]
		let h1 = Math.idiv(h, 60); //[0,6]
		let h2 = Math.idiv((h - h1 * 60) * 256, 60); //[0,255]
		let temp = Math.abs((h1 % 2 << 8) + h2 - 256);
		let x = (c * (256 - temp)) >> 8; //[0,255], second largest component of this color
		let r$: number;
		let g$: number;
		let b$: number;
		if (h1 == 0) {
			r$ = c;
			g$ = x;
			b$ = 0;
		} else if (h1 == 1) {
			r$ = x;
			g$ = c;
			b$ = 0;
		} else if (h1 == 2) {
			r$ = 0;
			g$ = c;
			b$ = x;
		} else if (h1 == 3) {
			r$ = 0;
			g$ = x;
			b$ = c;
		} else if (h1 == 4) {
			r$ = x;
			g$ = 0;
			b$ = c;
		} else if (h1 == 5) {
			r$ = c;
			g$ = 0;
			b$ = x;
		}
		let m = Math.idiv(Math.idiv((l * 2) << 8, 100) - c, 2);
		let r = r$ + m;
		let g = g$ + m;
		let b = b$ + m;
		return packRGB(r, g, b);
	}

	export enum HueInterpolationDirection {
		Clockwise,
		CounterClockwise,
		Shortest,
	}
}