Update and Streamline READMEs (#1146)

fixes #1145

README.md

@@ -37,7 +37,15 @@ matter.js serves various purposes and can be employed for:
 
 Explore the versatile capabilities of matter.js and adapt it to your specific use cases!
 
-## Compatibility
+## Compatibility to Matter Standard
+
+The Matter standard evolves continuously and delivers two updates per year. matter.js tries to follow the standard as closely as possible. The following list provides an overview which matter.js version is implementing which Matter standard version:
+- **Matter 1.0**: matter.js up to 0.7.x
+- **Matter 1.1**: matter.js 0.8.x - 0.9.x
+- **Matter 1.2**: skipped
+- **Matter 1.3**: matter.js 0.10.x and higher
+
+## Compatibility to Ecosystems 
 
 Devices created with matter.js/matter-node.js have been tested with:
 
@@ -70,10 +78,10 @@ Please report any outdated or newly discovered information on compatible ecosyst
 This repository contains multiple packages (and because of this it is a monorepo). The packages are contained in the `packages` directory and are all published separately to NPM.
 
 - **[matter.js](./packages/matter.js)**: the core Matter implementation in typescript which is JavaScript only and has no native dependencies. It is build and published as CommonJS and ES6 variants in one package.
-- **[matter-node.js](./packages/matter-node.js)**: a node.js implementation of a Matter DeviceNode and ControllerNode which also re-exports all matter.js exports and so can be used as only dependency. It is build and published as CommonJS and ES6 variants in one package.
-- **[matter-node-ble.js](./packages/matter-node-ble.js)**: a node.js based implementation of BLE features for matter-node.js to allow commissioning via BLE (Device and Controller). It is build and published as CommonJS and ES6 variants in one package.
-- **[matter-node-shell.js](./packages/matter-node-shell.js)**: a node.js based Matter Shell script to allow to interact with Matter devices as controllers via a CLI interface
-- **[matter-node.js-examples](./packages/matter-node.js-examples)**: Reference implementations of Matter devices and controller as CLI scripts using matter-node.js and matter-node-ble.js
+- **[matter-node.js](./packages/matter-node.js)**: Node.js specific platform implementations to enable running Matter devices or Controller with Node.js. This package is build and published as CommonJS and ES6 variants in one package and meant to be used together with the matter.js package.
+- **[matter-node-ble.js](./packages/matter-node-ble.js)**: Node.js based implementation of BLE features for matter-node.js to allow commissioning via BLE (Device and Controller). It is build and published as CommonJS and ES6 variants in one package and meant to be used together with the matter.js and the matter-node.js package.
+- **[matter-node-shell.js](./packages/matter-node-shell.js)**: a Node.js based Matter Shell script to allow to interact with Matter devices as controllers via a CLI interface running on Node.js.
+- **[matter-node.js-examples](./packages/matter-node.js-examples)**: Reference implementations of several usage ready Matter devices and controller as CLI scripts running on Node.js.
 - **[matter.js-react-native](./packages/matter.js-react-native)**: An implementation of the platform specific parts needed for matter.js using react-native.
 - **[matter.js-tools](./packages/matter.js-tools)**: Tools used internally to build, test and run the project which incorporates on-the-fly Typescript building. You most likely do not need these tools for your projects but are free to use them.
 

packages/matter-node-ble.js/README.md

@@ -4,11 +4,11 @@
 
 Matter BLE support using bleno for Peripheral/Device side and noble (not implemented yet) for Central/Controller side.
 
-> This package requires Node 16+
+> This package supports all Node.js LTS versions starting with 18.x
 
-This package implements all needed Interfaces and classes to enable BLE Support for matter.js. It implements a class BluetoothNode which can be used as singleton Ble instance.
+This package contains the specific Platform implementations for Bluetooth LE with Node.js. It is designed to be used in addition to the @project-chip/matter.js and @project-chip/matter-node.js packages to enable BLE specific functionality.
 
-## Prerquisites and Limitations
+## Prerequisites and Limitations
 
 The used packages have some limitations and prerequisites. Please check the Readme's of the packages for more details:
 * [bleno](https://github.com/abandonware/bleno#readme)
@@ -20,6 +20,26 @@ The used packages have some limitations and prerequisites. Please check the Read
   * When using Device and Controller in parallel: https://github.com/abandonware/noble#bleno-compatibility-linux-specific (NOBLE_MULTI_ROLE might be needed to set)
   * Please also see common issues and solutions: https://github.com/abandonware/noble#common-problems
 
+## How to use this package
+This package is designed to be used in addition to matter.ja and matter-node.js to enable BLE support. It is not intended to be used standalone.
+
+Add this package to your package dependencies and make sure it is exactly the same version as matter.js and matter-node.js.
+
+In your code you register the BLE instance by using:
+```javascript
+import { BleNode } from "@project-chip/matter-node-ble.js/ble";
+import { Ble } from "@project-chip/matter.js/ble";
+
+Ble.get = singleton(
+    () =>
+        new BleNode({
+          // hciId: 1, // If you need to change it from default 0 on linux systems
+        }),
+);
+```
+
+The relevant classes in matter.js will detect the registration and use the BLE instance for BLE operations if needed.
+
 ## How to choose the HCI device (Linux)
 
 You can optionally set an options object when instantiating BleNode. this object can have the following properties:

packages/matter-node-shell.js/README.md

@@ -1,9 +1,9 @@
 # matter.js Node Shell
 
-STATUS: Work In Progress (WIP)
-
 This project provides a light-weight node.js implementation of a Matter shell application like the chip-tool from the official Matter-SDK.
 
+> This package supports all Node.js LTS versions starting with 18.x
+
 ## Install
 
 If you want to install just the shell app then you can do so by running:

packages/matter-node.js-examples/README.md

@@ -2,9 +2,9 @@
 
 [![license](https://img.shields.io/badge/license-Apache2-green.svg?style=flat)](https://raw.githubusercontent.com/mfucci/node-matter/master/LICENSE)
 
-This project provides a set of reference implementations to offer several types of Matter device nodes or also a controller.
+This project provides a set of reference implementations to show several types of Matter device nodes or also a controller implementation.
 
-> This package requires Node 18+
+> This package supports all Node.js LTS versions starting with 18.x
 
 # matter-node.js Usage examples / Reference implementations
 

packages/matter-node.js/README.md

@@ -2,27 +2,27 @@
 
 [![license](https://img.shields.io/badge/license-Apache2-green.svg?style=flat)](https://raw.githubusercontent.com/mfucci/node-matter/master/LICENSE) 
 
-Matter protocol for node.js with no native dependencies (and very limited dependencies).
+Matter protocol for Node.js with no native dependencies (and very limited dependencies).
 
-> This package requires Node 18+
+> This package supports all Node.js LTS versions starting with 18.x
 
-This package is meant to be used as library as basis for Node.js based implementation of Matter Device and controller functionality
+This package contains the specific Platform implementations to allow running Matter Devices and Controllers on Node.js. It is designed to be used in addition to the @project-chip/matter.js package to enable Node.js specific functionality.
 
-A basic CLI reference implementation of a Matter Device and Controller (might be split in own package soon) is available in the [matter-node.js-examples](../matter-node.js-examples/README.md) package.
+Some usage ready examples of a Matter Device and Controller (might be split in own package soon) are available in the [matter-node.js-examples](../matter-node.js-examples/README.md) package.
 
 For questions on how to use or pair Matter devices or controllers please refer to the [base package Readme](../../README.md#pairing-and-usage-information)! Especially for Google special steps are needed and mostly Hub devices are needed.
 
 ## Exported functionality
-This library enhances Matter.js and implements the needed native functionality using Node.js 16+ as platform. The library exports the added Node.js specific implementations as named exports.
-Ideally you only need to import the main functionality as very first import of your application using
+Ideally you only need to import the main functionality as very first import of your application to register the Node.js environment functionalities.
+
+Use
 
 ```javascript
 import "@project-chip/matter-node.js";
 ```
-
 to automatically register all needed Node.js specific features for the Environment and initialize the default environment.
 
-Most other functions should be imported from the @project-chip/matter.js package (unless it's Node.js specific functionality).
+Most other functions should be imported from the @project-chip/matter.js package (unless it's Node.js specific functionality only needed in some special cases).
 
 For more details please refer to the [API Documentation](../../docs/matter-node.js).
 
@@ -38,7 +38,7 @@ For more details please refer to the [API Documentation](../../docs/matter-node.
 | `@project-chip/matter-node.js/util`        | Exports Basic Utility functionality and enhance it by adding some Node.js specific functionality                                                  |
 
 ### Unchanged Re-Exports from Matter.js (Deprecated! Only used for Legacy API)
-The re-exports are deprecated as of 0.8+ release of matter.js. Please change your code to use these imports from matter.js directly and make sure to sync the versions of both packages (matter-node.js and matter.js) in your dependencies to not point to different versions!
+The re-exports are deprecated as of 0.8+ release of matter.js. Please change your code to use these imports from matter.js directly and make sure to sync the versions of both packages (matter-node.js and matter.js) in your dependencies to always point to the same version!
 
 | Export                                       | Description                                                                      |
 |----------------------------------------------|----------------------------------------------------------------------------------|

packages/matter.js-react-native/README.md

@@ -2,7 +2,7 @@
 
 [![license](https://img.shields.io/badge/license-Apache2-green.svg?style=flat)](https://raw.githubusercontent.com/mfucci/node-matter/master/LICENSE)
 
-Matter protocol for react-native.
+This package contains the specific Platform implementations to allow running Matter Devices and Controllers on React-Native. It is designed to be used in addition to the @project-chip/matter.js package to enable React-Native specific functionality.
 
 [!Note] This package is still in development and should be considered experimental and not suited for production usage!
 
@@ -11,7 +11,6 @@ The main idea of this package is to provide a react-native implementation of the
 extensibility of the matter.js library. Currently a full commissioning process was not successfully tested. WHen you 
 try to use it feel free to report where the process stops for you with which error message.
 
-
 ## Dependencies
 
 This package uses the following react-native libraries to provide the needed functionality:
@@ -22,7 +21,6 @@ This package uses the following react-native libraries to provide the needed fun
 - @react-native-async-storage/async-storage
   Please check these projects if special preparations need to be done for your developed app.
 
-
 ## Building
 
 -   `npm run build`: Build all code and create CommonJS and ES6 variants in dist directory. This will built incrementally and only build the changed files.

packages/matter.js-tools/README.md

@@ -3,12 +3,14 @@
 This package supports build, test and execution infrastructure for other
 `@project-chip/matter.js` packages.
 
+> This package supports all Node.js LTS versions starting with 18.x
+
 ## Rational
 
 Matter.js consists of a large number of generated TypeScript files.  We support
 multiple module formats targeting disparate JavaScript runtimes including Node
 and web browsers.  We publish a moderate (and growing) number of packages to
-NPM.  We support Linux, Windows and Mac OS.
+NPM.  We support Linux, Windows and MacOS.
 
 Previously, TSC analysis and test times had become quite slow.  A proliferation
 of configuration files for TSC and test framework was adding significant

packages/matter.js/README.md

@@ -2,15 +2,18 @@
 
 Implementation of Matter protocol in typescript with no native dependencies (and very limited dependencies).
 
-This is the JavaScript only Core of the Matter protocol. It is used by other projects to implement Matter Nodes and Clients and add the relevant specific implementations for Network and other elements.
+This is the JavaScript-only Core of the Matter protocol. It is used by other projects to implement Matter Nodes and Clients and add the relevant specific implementations for Network and other elements.
+
+> This package supports all Node.js LTS versions starting with 18.x
 
 The following features are abstracted away to allow to be implemented environment specific:
 
 -   Network (UDP/MDNS)
--   Crypto (to be split out)
+-   Crypto
 -   Storage
 -   Date/Timer
 -   Logger (Default uses "console")
+-   Environment (Process and Configuration handling)
 
 ## Exported functionality
 
@@ -29,7 +32,7 @@ This library exports the Matter protocol functionality as well as some helper fu
 | `@project-chip/matter.js/device`        | Exports Matter Device relevant classes (Legacy API!)                                                                                                                                                |
 | `@project-chip/matter.js/devices`       | Exports Matter Device type classes (NEW API!)                                                                                                                                                       |
 | `@project-chip/matter.js/endpoint`      | Exports Matter Endpoint structure classes (NEW API!)                                                                                                                                                |
-| `@project-chip/matter-.js/environment`  | Exports environment functionalities, which handes central functions like MDNS and configuration                                                                                                     |
+| `@project-chip/matter-.js/environment`  | Exports environment functionalities, which handles central functions like MDNS and configuration                                                                                                    |
 | `@project-chip/matter.js/elements`      | Exports every standard Matter element defined by the [Matter Object Model](./src/model/README.md)                                                                                                   |
 | `@project-chip/matter.js/fabric`        | Exports Matter-Fabric functionality                                                                                                                                                                 |
 | `@project-chip/matter.js/interaction`   | Exports Matter Interaction protocol functionality                                                                                                                                                   |
@@ -45,6 +48,7 @@ This library exports the Matter protocol functionality as well as some helper fu
 | `@project-chip/matter.js/session`       | Exports Session and Secure-Session functionality                                                                                                                                                    |
 | `@project-chip/matter.js/spec`          | Exports Matter Specification References                                                                                                                                                             |
 | `@project-chip/matter.js/storage`       | Exports Basic Storage abstract functionality that needs to be implemented platform specific!                                                                                                        |
+| `@project-chip/matter.js/tags`          | Exports Semantic Tag Standard namespace definitions of the Matter specification                                                                                                                     |
 | `@project-chip/matter.js/time`          | Exports Basic Time/Timer abstract functionality that needs to be implemented platform specific!                                                                                                     |
 | `@project-chip/matter.js/tlv`           | Exports Matter TLV type definitions                                                                                                                                                                 |
 | `@project-chip/matter.js/util`          | Exports Basic Utility functionality                                                                                                                                                                 |