Feat: Update Discover-More

content/wiki/discover-more/contribution.md

@@ -1,7 +1,7 @@
 ---
 title: "Contribution"
 description: "Few hints how to contribute to our wiki!"
-lead: ""
+lead: "You want to add something to our Wiki."
 date: 2021-04-05T13:22:31.000Z
 draft: false
 images: []
@@ -12,7 +12,9 @@ weight: 10
 toc: true
 ---
 
-## Editing
+## How to Edit
+
+If you want to edit a page of our wiki, nothing could be simpler, follow the steps below:
 
 1. Open desired page
    * For example [`https://nrchkb.github.io/wiki/service/lock-mechanism/`](https://nrchkb.github.io/wiki/service/lock-mechanism/)
@@ -21,39 +23,97 @@ toc: true
 3. In GitHub editor, add or edit content after last `---`
    * For content, you can use markdown (preferred) or html
 4. Create new branch for commit and create Pull Request
-   * Our Moderators will respond shortly!
+   * We welcome all PRs and will try to work through any suggested features & fixes.
 
-## Page parameters
 
-On each raw page between `---` you can find page specific parameters.
+## Page Parameters
 
-| parameter | description |
+On each raw page between `---` you can find page specific parameters:
+
+| Parameter | Description |
 |---|---|
 | title | Page title, used in browser tab and also displayed at the top of the page |
-| description | Page description, displayed when you share page link |
+| description | Description page, only displayed when you share a page |
+| lead | Mini-summary displayed below the title |
 | date | Page creation date (ISO 8601) |
 | lastmod | Page last modification date (ISO 8601), to be edited after every change. You can use [this](https://www.timestamp-converter.com/) page to generate one. |
 | weight | Page order in menu |
-| toc | If page table of content should be displayed |
+| toc | If page table of content `On This Page` should be displayed |
 | contributors | List of contributors |
 
-## Repository directory structure
+{{< alert icon="💡" >}}Other parameters such as draft, images and menu are also present but you are not asked to complete them.{{< /alert >}}
 
-All our wiki pages are located in `content/wiki` folder [in our repository](https://github.com/NRCHKB/NRCHKB.github.io/tree/master/content/wiki).
+## Markup Language used
+
+We mainly use the [markdown](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax) language to edit our pages and for more complex cases of [HTML](https://developer.mozilla.org/en-US/docs/Web/HTML).
+
+## Image
+
+To add an image, you must **upload** it to the **same folder** as the page you are editing and **insert this code** `![Edit view](edit-view.png)` where you want to put your image.
+
+## Link
+
+If you want to add a link to another page, to a chapter (point) of a page or a link to an external site.
+
+### Within our Wiki
+
+Structure : `[Name display on the Page]({{</* ref... */>}} "Name of the link")`.
+
+| Option | Description |
+|---|---|
+| `ref "/wiki/folder"` | Link to a `index.md` Page |
+| `ref "/wiki/folder/fileName"` | Link to a `fileName.md` Page |
+| `ref "/wiki/folder/fileName#point"` | Link to a Point of the Page |
+| `ref . "#point"` | Link to a Point of the **same** Page |
+
+#### Example
 
-## Linking to other pages within our wiki
+- Link to a Page:
 
-When referencing other wiki pages, please use [Hugo mechanism](https://gohugo.io/content-management/cross-references/). This helps keep things organized and prevent broken links in the future.
+`[Host Node]({{</* ref "/wiki/nodes/host-node" */>}} "Host Node")`
 
-Example `[Bridge]({{</* ref "/wiki/nodes/host-node" */>}} "Host Node")`
-Where you specify text, reference link, and text which is displayed on link hover.
+- Link to a Point:
 
-## Screenshots
+`[Bridge Name]({{</* ref "/wiki/nodes/host-node#name" */>}} "Name")`
 
-When uploading screenshots, it is preferred to upload them to the GitHub repository in the same folder as the wiki page you are editing. The screenshot should be uploaded to the branch you are using for your pull request.
+{{< alert icon="💡" >}}For our links within our wiki we use the [Hugo mechanism](https://gohugo.io/content-management/cross-references/).{{< /alert >}}
+
+### External
+
+Structure : `[Name display on the Page](url)`.
+
+#### Example
+
+`[Google](https://google.com)`
+
+## Alert
+
+If you want to add an Alert banner, insert this code:
+
+`{{</* alert icon="👋" */>}}Your Text{{</* /alert */>}}`
+
+Display:
+
+{{< alert icon="👋" >}}Your Text{{< /alert >}}
+\
+Icon frequently used: 💡|👉|‼️
+
+## Repository directory structure
+
+All our wiki pages are located in `content/wiki` folder [in our repository](https://github.com/NRCHKB/NRCHKB.github.io/tree/master/content/wiki).
 
-An example can be found [here](https://github.com/NRCHKB/NRCHKB.github.io/tree/master/content/wiki/nodes/status-node). Markdown is then used to reference the uploaded image file:
-`![Edit view](edit-view.png)`
+```bash
+..
+├── wiki/
+│   ├── characteristic/
+│   ├── discover-more/
+│   ├── examples/
+│   ├── introduction/
+│   ├── nodes/
+│   ├── service/
+│   └── _index.md
+└── _index.md
+```
 
 ## Adding contributor
 

content/wiki/discover-more/credits.md

@@ -12,7 +12,9 @@ weight: 100
 toc: true
 ---
 
-This is a place where we would like to thank those who have come before to build the work that we have added to.
+*First of all, we would like to express our deepest thanks to the creators of this project.*
+*Next, we would like to especially thank @Shaquu for his time and work in developing and maintaining this project.*\
+*Finally, we would like to sincerely express our thanks with deep gratitude to everyone who contributed near or far to its realization, because a project cannot be the work of one person.*
 
 ## History
 

content/wiki/discover-more/experimental/index.md

@@ -1,7 +1,7 @@
 ---
 title: "Experimental"
-description: "NRCHKB experimental features"
-lead: ""
+description: "NRCHKB experimental features."
+lead: "During development, we add new features that are marked as <code>experimental</code>."
 date: 2021-10-11T23:32:09.000Z
 draft: false
 images: []
@@ -12,40 +12,65 @@ weight: 100
 toc: true
 ---
 
-During development, we add new features that are marked as `experimental`.
+These are beta versions containing possible future features.
+We use beta versions to test and improve our features without compromising the experience of our users.
 
-They can be marked that way for few reasons:
+{{< alert icon="‼️" text="Beta versions may contain bug fixes and improvements!" />}}
 
-1. Early adopting and testing, allows us to phase new features.
-2. Discovering better ways to solve problems.
-3. Easier to test new designs without releasing to public.
+## Open Node-RED in beta mode
 
-> **Important Notice,** any experimental feature is subject to change and might be not bug free.
+In order to be able to use experimental features you have to start Node-RED with `NRCHKB_EXPERIMENTAL=true` environment variable.
 
-## Getting started
+Enter this command in your terminal:
 
-In order to be able to use experimental features you have to start Node-RED with `NRCHKB_EXPERIMENTAL=true` environment variable.
+```bash
+sudo NRCHKB_EXPERIMENTAL=true node-red
+```
+
+With `DEBUG` in addition:
+
+```bash
+sudo NRCHKB_EXPERIMENTAL=true DEBUG=NRCHKB* node-red
+```
+
+{{< alert icon="💡" text="Don't forget to stop Node-RED first before launching it in experimental mode." />}}
 
-Examples
 
-### Terminal
+## Use of Debug
 
-`NRCHKB_EXPERIMENTAL=true node-red` or with `DEBUG` you can use `NRCHKB_EXPERIMENTAL=true DEBUG=NRCHKB* node-red`
+Using debug allows you to see logs and possible errors.
 
-### System Service (Raspberry Pi)
+Below is a table with all the possible logs and their description:
 
-If you run Node-RED using the provided system service after installing with their Raspberry Pi script, then you will need to modify the system service file.
+| Options | Description |
+|---|---|
+| NRCHKB* | Show all HK logs |
+| ServiceUtils | Show Service node logs |
+| BridgeUtils | Show Bridge logs |
+| AccessoryUtils | Show Accessory logs |
+| CharacteristicUtils | Show Characteristic logs |
+| MdnsUtils | Show Mdns logs |
+
+## Start automatically in beta mode
+
+If you want to start Node-RED in experimental mode when your system restarts:
+
+### Raspberry Pi
 
 The file should be located at `/lib/systemd/system/nodered.service`
 
+```bash
+sudo nano /lib/systemd/system/nodered.service
+```
+
 Find a line starting with `Environment` and add one (or both) of the following lines.
 
 ```bash
 Environment="NRCHKB_EXPERIMENTAL=true"
 Environment="DEBUG=NRCHKB*"
 ```
 
-**Watching these logs** after enabling the logging can be done using the `journalctl -f` command. Specifically on Raspberry Pi, run this command:
+**Watching these logs** after enabling the logging can be done using the `journalctl -f` command.
 
 ```bash
 sudo journalctl -u nodered.service -f
@@ -73,23 +98,25 @@ services:
 
 ### Custom Characteristics
 
-[NRCHKB/node-red-contrib-homekit-bridged#52](https://github.com/NRCHKB/node-red-contrib-homekit-bridged/issues/52)
+It's possible to add custom characteristics ([issues#52](https://github.com/NRCHKB/node-red-contrib-homekit-bridged/issues/52)).
 
-Using nrchkb node ![nrchkb node](nrchkb-node.png) you can define new Characteristics.
+To do this:
+
+1. Configure the ![nrchkb node](nrchkb-node.png)node.
 
 ![Custom Characteristics editor](custom-characteristics-nrchkb-node.png)
 
-After you add them you need to also enable them on Service node.
+{{< alert icon="💡" >}}You can use this [documentation](https://gist.github.com/simont77/3f4d4330fa55b83f8ca96388d9004e7d) to configure your custom characteristics based on existing characteristics.{{< /alert >}}
+
+2. Add your Characteristics on Service node.
 
 ![Service node Custom Characteristics](custom-characteristics-service-node.png)
 
-> **Important Notice,** currently, Home.app (default Apple app for managing smart home) is not displaying Custom Characteristics.
-> To see them in action you have to use alternative app like Eve.app
-> ![Custom Characteristics Eve.app](custom-characteristics-eve-app.jpeg)
+{{< alert icon="💡" text="Home.app does not display Custom Characteristics but you can use Eve.app" />}}
 
 #### Example Eve Characteristics
 
-##### Sumary
+![Custom Characteristics Eve.app](custom-characteristics-eve-app.jpeg)
 
 | name          | UUID                                 | format | description       | minValue | maxValue   | minStep |
 | ------------- | ------------------------------------ | ------ | ----------------- | -------- | ---------- | ------- |
@@ -99,12 +126,47 @@ After you add them you need to also enable them on Service node.
 | Kilowatt-Hour | E863F10C-079E-48FF-8F27-9C2605A29F52 | float  | Eve Kilowatt-Hour | 0        | 4294967295 | 0.01    |
 | Volt-Ampere   | E863F110-079E-48FF-8F27-9C2605A29F52 | float  | Eve Volt-Ampere   | 0        | 4000       | 0.01    |
 
-##### `~/.node-red/nrchkb/35b973f1696b4cd60b78ca5f719b83ca`
+You can add the above Characteristics directly in the folder `~/.node-red/nrchkb/35b973f1696b4cd60b78ca5f719b83ca` by pasting the content below into it:
 
 ```json
 {"key":"customCharacteristics","value":[{"name":"Volt","UUID":"E863F10A-079E-48FF-8F27-9C2605A29F52","format":"uint16","unit":"","perms":["pr","pw","ev","tw","wr"],"ev":"true","description":"Eve Volt","minValue":"0","maxValue":"400","minStep":"3","maxLen":"","maxDataLen":"","validValues":"","adminOnlyAccess":["0","1","2"]},{"name":"Ampere","UUID":"E863F126-079E-48FF-8F27-9C2605A29F52","format":"float","unit":"","perms":["pr","pw","ev","tw","wr"],"ev":"true","description":"Eve Ampere","minValue":"0","maxValue":"16","minStep":"0.01","maxLen":"","maxDataLen":"","validValues":"","adminOnlyAccess":["0","1","2"]},{"name":"Watt","UUID":"E863F10D-079E-48FF-8F27-9C2605A29F52","format":"uint16","unit":"","perms":["pr","pw","ev","tw","wr"],"ev":"true","description":"Eve Watt","minValue":"0","maxValue":"3500","minStep":"","maxLen":"","maxDataLen":"","validValues":"","adminOnlyAccess":["0","1","2"]},{"name":"Kilowatt-Hour","UUID":"E863F10C-079E-48FF-8F27-9C2605A29F52","format":"float","unit":"","perms":["pr","pw","ev","tw","wr"],"ev":"true","description":"Eve Kilowatt-Hour","minValue":"0","maxValue":"4294967295","minStep":"0.01","maxLen":"","maxDataLen":"","validValues":"","adminOnlyAccess":["0","1","2"]},{"name":"Volt-Ampere","UUID":"E863F110-079E-48FF-8F27-9C2605A29F52","format":"float","unit":"","perms":["pr","pw","ev","tw","wr"],"ev":"true","description":"Eve Volt-Ampere","minValue":"0","maxValue":"4000","minStep":"0.01","maxLen":"","maxDataLen":"","validValues":"","adminOnlyAccess":["0","1","2"]}]}
 ```
 
 ### Service 2
 
-[NRCHKB/node-red-contrib-homekit-bridged#392](https://github.com/NRCHKB/node-red-contrib-homekit-bridged/issues/392)
+Added `Get` functionality so that the node can retrieve attribute values when a refresh is requested. [issues#392](https://github.com/NRCHKB/node-red-contrib-homekit-bridged/issues/392)
+
+Together with NRCHKB 2.0.0 (TBC) `onSet` and `onChange` will be merged into unified output called events.
+
+It will output data for all event types defined below:
+
+- set
+- change
+- subscribe
+- unsubscribe
+- characteristic-warning
+
+Node output will look like:
+
+```ts
+type HAPServiceNodeEvent = {name: CharacteristicEventTypes, context?: any}
+
+type HAPServiceNodeOutput = {
+    payload: { [key: string]: any }
+    hap: {
+        oldValue?: any
+        newValue?: any
+        context?: any
+        event: HAPServiceNodeEvent
+        session?: {
+            sessionID?: SessionIdentifier,
+            username?: HAPUsername,
+            remoteAddress?: string,
+            localAddress?: string,
+            httpPort?: number,
+        }
+    }
+    name?: string
+    topic: string
+}
+```

content/wiki/discover-more/migration.md

@@ -1,7 +1,7 @@
 ---
 title: "Migration"
-description: "Migration"
-lead: ""
+description: "Discover how to migrate to new setup or to new flow."
+lead: "Discover how to migrate to new setup or to new flow."
 date: 2021-08-03T21:37:19.000Z
 draft: false
 images: []
@@ -14,22 +14,44 @@ toc: true
 
 ## Migration to new setup
 
-There are some cases when you may want to move your HomeKit devices to a new Node-RED instance while not changing your Home App pairings.
+There are some cases when you may want to move your HomeKit devices to a new Node-RED instance while not changing your Home.app pairings.
 This could be when you are migrating to a new computer, flashing a new SD card for your pi, or restoring from a backup.
-While not guaranteed, this process should allow migration without needing to remove your bridge or standalone devices from the Home app.
+While not guaranteed, this process should allow migration without needing to remove your bridge or standalone devices from the Home.app.
 
-### How to do it!
-
-Moving to a new server is fairly simple, and only takes a few of steps,
-
-1. Install Node-RED on your new server
-2. Shut down Node-RED on the old server
+<!--
 3. Changed to the `.node-red` directory on the new server and run `npm install node-red-contrib-homekit-bridged` (and any other node modules you use in your flows)
 4. Copy over `homekit-persist` from the `.node-red` directory on the old server to the `.node-red` directory on the new server
 5. Copy over `flows_<old machine's hostname>.json` from the `.node-red` directory on the old server to the `.node-red` directory on the new server
 6. Rename the `flows_<old machine's hostname>.json` to `flows.json` on the new server.
 7. Edit the `settings.js` file on the new server, and uncomment the line `flowFile: 'flows.json'
+-->
+
+1. Install Node-RED on your new server
+    ```bash
+    bash <(curl -sL https://raw.githubusercontent.com/node-red/linux-installers/master/deb/update-nodejs-and-nodered)
+    ```
+2. Install Node Modules used on your new server
+    ```bash
+    cd /home/pi/.node-red/ && npm install node-red-contrib-homekit-bridged@latest
+    ```
+3. Shut down Node-RED on the old server
+    ```bash
+    sudo node-red-stop
+    ```
+4. Copy over `homekit-persist` from the `.node-red` directory on the old server to the new server
+
+5. Copy over `flows_<old machine's hostname>.json` from the `.node-red` directory on the old server to the new server
+
+6. Rename the `flows_<old machine's hostname>.json` to `flows.json` on the new server.
+
+7. Edit the `settings.js` file on the new server, and uncomment the line `flowFile: flows.json`
+    ```bash
+    sudo nano /home/pi/.node-red/settings.js
+    ```
 8. (Re)Start Node-RED on your new server.
+    ```bash
+    sudo node-red-start
+    ```
 
 ## Migration to new flow
 
@@ -41,6 +63,9 @@ New id means that HomeKit will loose data about that Service which can cause som
 3. Backup your files that are in `.node-red` directory
 4. Shut down Node-RED
 5. Locate flows file `flows_<machine's hostname>.json` and open it
+    ```
+    sudo nano /home/pi/.node-red/flows_<machine's hostname>.json
+    ```
 6. Locate node in the flow file. Example `"id":"6bed989d.116308","type":"homekit-service","z":"6c3f03b4.f0351c"`
 7. `z` is flow id. Change it to new flow id.
 8. Save file and start Node-RED.