🫧clean 🧼🫧

.github/workflows/CI.yml

@@ -1,34 +1,14 @@
 name: CI
-on: [ push, pull_request]
+on: [ push, pull_request ]
 
 jobs:
   Build:
-    runs-on: ubuntu-latest
-    steps:
-    - uses: actions/checkout@v4
-    - uses: actions/[email protected]
-    - run: npm install
-    - run: npm run build --if-present
-  Lnt:
-    runs-on: ubuntu-latest
-    steps:
-    - uses: actions/checkout@v4
-    - uses: actions/setup-node@v4
-    - run: npm install
-    - run: npm run lint --if-present -- --quiet
-  Test:
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v4
     - uses: actions/setup-node@v4
     - run: npm install
     - run: npm run build --if-present
+    - run: npm run lint --if-present -- --quiet
     - run: npm run test --if-present -- --quiet
-  Cover:
-    runs-on: ubuntu-latest
-    steps:
-    - uses: actions/checkout@v4
-    - uses: actions/setup-node@v4
-    - run: npm install
-    - run: npm run build --if-present
-    - run: npm run coverage --if-present -- --quiet
+    - run: npm run coverage --if-present -- --quiet

README.md

@@ -1,5 +1,5 @@
 # MCP2221
-Full featured library MCP2221 (A) via USB HID for the Web and Node
+Full featured MCP2221 library with WebHID and node support over StreamAPI 🥳
 
 [![npm Version](http://img.shields.io/npm/v/@johntalton/mcp2221.svg)](https://www.npmjs.com/package/@johntalton/mcp2221)
 ![GitHub package.json version](https://img.shields.io/github/package-json/v/johntalton/mcp2221)
@@ -14,16 +14,18 @@ Standard [Adafruit](https://www.adafruit.com/product/4471) link.
 - [Stream API](#stream-api)
   - [WebHID](#web-hid)
   - [Node-HID](#node-hid)
-- [I²C](#ic) (raw)
+- [I²C](#direct-api) (raw)
 - [`I2CBus`](#i2cbus-abstraction-recommended)
 
+![i2c scan](./example/mcp2221-scan.png)
 
 # Features
+
 Support full range of command and functionality, including:
 
 - Password Protected
     - Access Password setting
-    - new password Flash writes
+    - New password Flash writes
     - Alter Security settings
     - no guard against humans
 
@@ -53,12 +55,13 @@ Support full range of command and functionality, including:
 
 
 # Example
-The following example give the outline of the usage pattern for creating the binding layer between the underlying HID implementations and the chip library itself.
+
+The following example gives the outline of the usage pattern for creating the binding layer between the underlying HID implementations and this chip library.
 
 ```javascript
-import { MCP2221A } from '@johntalton/mcp2221'
+import { MCP2221 } from '@johntalton/mcp2221'
 
-const hidDevice = {} /* likely navigator.hid.getDevices() ... etc */
+const hidDevice = { /* likely navigator.hid.getDevices() ... etc */ }
 const source = new HIDStreamSource(hidDevice)
 const chip = MCP2221.from(source)
 
@@ -67,24 +70,21 @@ const { adc } = await chip.common.status()
 const { ch0, ch1, ch2 } = adc
 ```
 
-
 # Stream API
 
-Individual HID implementations are abstrated over the [Stream API](https://developer.mozilla.org/en-US/docs/Web/API/Streams_API) that supports BYOB (bring you own buffer) and Byte specific stream.
-
-As such, a `HIDStreamSource` is used to normalize the WebHID (`EventTarget`) API into a stream (as well as other concrete implementations).
+Individual HID implementations are abstracted over the [Stream API](https://developer.mozilla.org/en-US/docs/Web/API/Streams_API) that supports BYOB (bring you own buffer) and Byte specific stream.
 
-A simplified stream reader is used which ignore (assumes zero) the report Id, which is correct in this case.
+As such, the interface `HIDStreamSource` is used to normalize the sources  into a stream.
 
 Two examples of Stream Sources are given bellow: WebHID and Node-HID.
 
 ## Web HID
 
-the WebHID api provides a simplified HID implementation within the browser.
+The [WebHID](https://developer.mozilla.org/en-US/docs/Web/API/WebHID_API) interface provides a robust browser based HID implementation ([browser support](https://developer.mozilla.org/en-US/docs/Web/API/WebHID_API#browser_compatibility))
 
-The example code above can replace the abstract `HIDStreamSource` with the concrete [`WebHIDStreamSource`]()
+The example code above can be updated to use the the concrete `WebHIDStreamSource`.
 
-The HID API has several way of acquiring a `HIDDevice`, most common is to make a request for existing connected devices via [`navigator.hid.getDevices()`](https://developer.mozilla.org/en-US/docs/Web/API/HID/getDevices).
+The API has several way of acquiring a `HIDDevice`, most common is to make a request for existing connected devices via [`navigator.hid.getDevices()`](https://developer.mozilla.org/en-US/docs/Web/API/HID/getDevices).
 
 
 NOTE: an un-packaged version of WebHIDStraemSource can be found [here](https://github.com/johntalton/webapp-device-playground/blob/main/public/util/hid-stream.js). (future package publication may be forthcoming)
@@ -116,21 +116,55 @@ await chip.sram.set({ gp: { interrupt: { clear: true } } })
 
 # I²C
 
+## `I2CBus` abstraction (recommended)
+
+Basic usage of such API can be useful in some instances. However, due to complexities and error checking logic, it is recommended to use the [`I2CBus`](https://github.com/johntalton/i2c-bus-mcp2221) abstraction layer
+
+
+## Direct API
+
 The MCP2221 exposes several low-level I²C constructs.
+These can be used to build custom bus interactions
+
+Note: the chip's I²C state machine can hang / crash is care is not taken to check status and appropriately cancel transaction.  `I2CBus` usage is encouraged, and may also be a good reference.
+
+The following example is simplification from the the above `I2CBus` implementation [code](https://github.com/johntalton/i2c-bus-mcp2221/blob/main/src/utils/read.ts).
 
 ```javascript
-// chip from above examples
+const chip // chip from base examples
+
+// request a read of length 3 bytes from address 0x70 (7-bit address)
+const REQUESTED_I2C_BYTE_LENGTH = 3
 
-const { status } = await chip.i2c.readData()
-if(status !== 'success') { throw new Error('not ok') }
-const { validData, buffer } = await chip.i2c.readGetData({
-    address: 0x79,
-    length: 1
+// start the request
+const { status } = await chip.i2c.readData({
+    address: 0x70,
+    length: REQUESTED_I2C_BYTE_LENGTH
 })
+if(status !== 'success') { throw new Error('☠️') }
+// check i2c state and other transfer values for readiness
 
+//
+// it is almost sertian that a call to `status` is needed, the commands "success" status value is not sufficiant for checking the state of the bus
+// const { status, i2cStateName, ... } = await device.common.status({ opaque })
+// if (__i2cStatusIsNotOk__) { throw new Error('😢') }
 
-```
+// if that all went well then attempt to get the buffer
+// here we allow the chip to allocate the buffer
+// BYOB can be used here also for performance / efficiency
+const { validData, buffer, readBackBytes } = await chip.i2c.readGetData()
+if(!validData) { throw new Error('🧨') }
+if(readBackBytes === REQUESTED_I2C_BYTE_LENGTH) { throw new Error('👎') }
 
-## `I2CBus` abstraction (recommended)
 
-Basic usage of such API can be useful in some instances. However, due to the complexities and error checking, it is recommended to sue the [`I2CBus`](https://github.com/johntalton/i2c-bus-mcp2221) abstraction layer
+// process the data
+// check if the returned buffer is a view and coheres it into a Uint8Array
+const u8 = ArrayBuffer.isView(buffer) ?
+    new Uint8Array(buffer, buffer.byteOffset, buffer.byteLength) :
+    new Uint8Array(buffer)
+
+// deconstruct TypedArray
+const [ one, two, three ] = u8
+
+
+```