3.4.0: Added support for the ancient Launchpad MK1 (#9)

* 3.4.0: Added support for the ancient Launchpad MK1

* 3.4.1: Fixed typo in inline documentation

* 3.4.2: Clarification on terms flashing and pulsing for MK1

* 3.4.3: Replaced resource documents in README with links to archived documents

* 3.4.4: Improved compatibility for Launchpad MK1

README.md

@@ -11,16 +11,28 @@ After re-writing a broken launchpad library I decided to release the library to
 
 Some sample programs can be found in the [examples folder](./examples).
 
+
+
 ## Launchpad models currently supported
 
+- Launchpad MK1 ([limited support][limited-support-mk1])
 - Launchpad MK2
 - Launchpad MK3 (only tested with Mini)
 
+
 ### Why are only these launchpads supported?
 
 These launchpads are supported because I own them myself and have been able to test them.
 If a launchpad is not listed here it means that I do not own one and have not been able to test that one with the program.
 
+
+
+## Installation
+
+Install from NPM using `npm i launchpad.js` and make sure you have drivers installed for your device.
+
+
+
 ## Examples
 
 More examples can be found in the [examples folder](./examples), this is just a simple button listener.
@@ -57,6 +69,8 @@ lp.once('ready', (deviceName) => {
 });
 ```
 
+
+
 ## Low-level API
 
 A number of methods are available to control the button colors on
@@ -81,6 +95,8 @@ The follow methods control a button's color:
 - `lp.pulse(button, color)`: a button will pulse between black and the given
   palette color.
 
+
+
 ## Surface API
 
 There is also a buffer-oriented API you can use, which works much like
@@ -93,16 +109,69 @@ A helper class `Drawing` exists to help with performing common drawing operation
 See the [`examples/surface.js`](./examples/surface.js) example for more information
 on how to use this API.
 
+
+
+## Limited support for the legacy Launchpad MK1
+
+[limited-support-mk1]: #limited-support-for-the-legacy-launchpad-mk1 "Jump to section"
+
+Launchpad MK1 offers less functionality over newer models and therefore has some limitations.
+  As a result of the implementation for the MK1 being retro-fitted into this package, that has
+  been designed to work with more advanced models, the API for MK1 isn't fully compatible with
+  that of newer models. The differences are specified in this section.
+
+
+### Colors
+
+Buttons on Launchpad MK1 only have two LEDs, red and green, that can output four intensities each:
+- `0` off.
+- `1` low brightness.
+- `2` medium brightness.
+- `3` full brightness.
+
+This means the MK1 can only display a few different colors and that `RgColor` and `RgbColor` values (in range
+  `0..1`) consumed by methods like `lp.setButtonColor()`, `lp.flash()` and `lp.pulse()` are converted to either
+  one of the four color intensities. See type `RgColor` for more information on this conversion.
+
+Because there is no blue LED, methods that consume an `RgbColor` value also accept `RgColor` values.
+
+
+### Color palette
+
+The Launchpad MK1 doesn't have a color palette. Methods that consume a `PaletteColor` may instead accept a
+  `Velocity` value (specific to MK1). See method `lp.velocity()` and type `Velocity` for more information.
+
+Methods that exclusively consume `PaletteColor`s on newer models (being `lp.flash()` and `lp.pulse()`) instead
+  accept an `RgColor`, `RgbColor` or `Velocity` value on Launchpad MK1.
+
+Method `lp.setButtons()` uses different styles (`Mk1ButtonStyle` and `Mk1Style`) due to color palettes not being
+  available, see type `Mk1Style` for more information.
+
+
+### Flashing buttons
+
+Buttons on Launchpad MK1 can only **pulse** between off and a specified color, it does not support **flash**ing
+  between two specified colors. This results in method `lp.flash()` only accepting one color argument and
+  thus providing the exact same signature and functionality as `lp.pulse()`.
+
+
+
 ## TODO
 
 - Add support for the same launchpads as launchpad.py
 
-### Links
 
-- [Launchpad developer manual](https://resource.novationmusic.com/support/product-downloads?product=Launchpad)
+## Related resources
+
+- [Launchpad (MK1) programmers reference](https://web.archive.org/web/20240521041224/https://fael-downloads-prod.focusrite.com/customer/prod/downloads/launchpad-programmers-reference.pdf "View on archive.org") (archived)
+- [Launchpad MK2 programmers reference](http://web.archive.org/web/20231011173853/https://fael-downloads-prod.focusrite.com/customer/prod/s3fs-public/downloads/Launchpad%20MK2%20Programmers%20Reference%20Manual%20v1.03.pdf "View on archive.org") (archived)
+- [Launchpad Mini MK3 programmers reference](https://web.archive.org/web/20240127061723/https://fael-downloads-prod.focusrite.com/customer/prod/s3fs-public/downloads/Launchpad%20Mini%20-%20Programmers%20Reference%20Manual.pdf "View on archive.org") (archived)
+
+More recent versions of programmers references may be available on [Novation Music's website](https://novationmusic.com/ "Visit website").
+
 
-### Notice
+## Notice
 
-This project contains modified code from https://github.com/Lokua/launchpad which was released under the MIT license
+This project contains modified code from https://github.com/Lokua/launchpad which was released under the MIT license.
 
 [rewards-interaction]: https://github.com/duncte123/rewards-interaction

package.json

@@ -1,6 +1,6 @@
 {
   "name": "launchpad.js",
-  "version": "3.3.0",
+  "version": "3.4.4",
   "description": "A javascript api to control your Novation launchpads",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

src/colorHelpers.ts

@@ -1,5 +1,5 @@
 import convert from 'color-convert';
-import { RgbColor } from './launchpads/base/ILaunchpad.js';
+import { RgbColor, RgColor } from './launchpads/base/ILaunchpad.js';
 
 export const defaultColors: Record<string, RgbColor> = {
   off: [0, 0, 0],
@@ -9,6 +9,26 @@ export const defaultColors: Record<string, RgbColor> = {
   orange: [1, 0.26984127, 0],
 };
 
+/**
+ * Specifies pre-defined colors for the legacy Launchpad (MK1).
+ *
+ * @since 3.4.0
+ */
+export const legacyColors: Record<LegacyColor, RgColor> = {
+  off: [0, 0],
+  redLow: [0.1, 0],
+  redMedium: [0.1, 0],
+  red: [1, 0],
+  amberLow: [0.1, 0.1],
+  amberMedium: [0.5, 0.5],
+  amber: [1, 1],
+  yellowMedium: [0.1, 0.5],
+  yellow: [0.5, 1],
+  greenLow: [0, 0.1],
+  greenMedium: [0, 0.5],
+  green: [0, 1],
+};
+
 /**
  * How many Palette colors there are
  */
@@ -41,3 +61,10 @@ export function colorFromHex(hex: string): RgbColor {
     // scale the colors to fit between, 0-63
     .map((v: number) => v / 255) as RgbColor;
 }
+
+/**
+ * Specifies names of pre-defined colors for the legacy Launchpad (MK1).
+ *
+ * @since 3.4.0
+ */
+export type LegacyColor = 'off' | 'redLow' | 'redMedium' | 'red' | 'amberLow' | 'amberMedium' | 'amber' | 'yellowMedium' | 'yellow' | 'greenLow' | 'greenMedium' | 'green';

src/index.ts

@@ -1,5 +1,6 @@
 import SegfaultHandler from 'segfault-handler';
 
+export * from './launchpads/MK1/LaunchpadMK1.js';
 export * from './launchpads/MK2/LaunchpadMK2.js';
 export * from './launchpads/MK3/LaunchpadMK3.js';
 export * from './launchpads/base/ILaunchpad.js';