improves docs

README.md

@@ -12,6 +12,7 @@ Bluetooth Low Energy (BLE) library written with pure Node.js (no bindings) - bak
 
 # Documentation
 - [Documentation testing](https://github.com/chrvadala/node-ble/blob/main/docs/documentation-testing.md)
+- [Quick start guide](#quick-start-guide)
 - [APIs](https://github.com/chrvadala/node-ble/blob/main/docs/api.md)
   - [createBluetooth](https://github.com/chrvadala/node-ble/blob/main/docs/api.md#createBluetooth)
   - [Bluetooth](https://github.com/chrvadala/node-ble/blob/main/docs/api.md#Bluetooth)
@@ -26,7 +27,7 @@ This library works on many architectures supported by Linux. However Windows and
 
 It leverages the `bluez` driver, a component supported by the following platforms and distributions <https://www.bluez.org/about>.
 
-*node-ble* has been tested on the following architectures:
+*node-ble* has been tested on the following operating systems:
 - Raspbian
 - Ubuntu
 - Debian
@@ -36,30 +37,30 @@ It leverages the `bluez` driver, a component supported by the following platform
 npm install node-ble
 ```
 
-# Examples
+# Quick start guide
 
 ## Provide permissions
 In order to allow a connection with the DBus daemon, you have to set up right permissions.
 
-Create the file `/etc/dbus-1/system.d/node-ble.conf` with the following content (customize with userid)
+Execute the following command, in order to create the file `/etc/dbus-1/system.d/node-ble.conf`, configured with the current *user id* (Note: You may need to manually change the *user id*).
 
-```xml
-<!DOCTYPE busconfig PUBLIC "-//freedesktop//DTD D-BUS Bus Configuration 1.0//EN"
+```sh
+echo '<!DOCTYPE busconfig PUBLIC "-//freedesktop//DTD D-BUS Bus Configuration 1.0//EN"
   "http://www.freedesktop.org/standards/dbus/1.0/busconfig.dtd">
 <busconfig>
-  <policy user="%userid%">
+  <policy user="__USERID__">
    <allow own="org.bluez"/>
     <allow send_destination="org.bluez"/>
     <allow send_interface="org.bluez.GattCharacteristic1"/>
     <allow send_interface="org.bluez.GattDescriptor1"/>
     <allow send_interface="org.freedesktop.DBus.ObjectManager"/>
     <allow send_interface="org.freedesktop.DBus.Properties"/>
   </policy>
-</busconfig>
+</busconfig>' | sed "s/__USERID__/$(id -un)/" | sudo tee /etc/dbus-1/system.d/node-ble.conf > /dev/null
 ```
 
 ## STEP 1: Get Adapter
-To start a Bluetooth Low Energy (BLE) connection you need a Bluetooth adapter.
+To start a Bluetooth Low Energy (BLE) connection you need a Bluetooth adapter instance.
 
 ```javascript
 const {createBluetooth} = require('node-ble')
@@ -75,7 +76,7 @@ if (! await adapter.isDiscovering())
 ```
 
 ## STEP 3: Get a device, Connect and Get GATT Server
-Use an adapter to get a remote Bluetooth device, then connect to it and bind to the GATT (Generic Attribute Profile) server.
+Use the adapter instance in order to get a remote Bluetooth device, then connect and interact with the GATT (Generic Attribute Profile) server.
 
 ```javascript
 const device = await adapter.waitDevice('00:00:00:00:00:00')
@@ -124,7 +125,7 @@ destroy()
 - **1.9** - Upgrades deps; Adds `writeValueWithoutResponse()` and `writeValueWithResponse` methods [#47](https://github.com/chrvadala/node-ble/pull/47); Improves typescript definition [#48](https://github.com/chrvadala/node-ble/pull/48) 
 - **1.10** - Upgrades deps and gh-actions; Fixes memory leak [#37](https://github.com/chrvadala/node-ble/pull/37); Makes MAC Address case insensitive
 - **1.11** - Upgrades deps; Fixes doc [#69](https://github.com/chrvadala/node-ble/pull/69); Adds `getManufacturerData` and `getAdvertisingData`  functions on `Device` [#67](https://github.com/chrvadala/node-ble/pull/67); Adds `getServiceData` functions on `Device`; Improves pre-requisite doc section [#68](https://github.com/chrvadala/node-ble/pull/68)
-- **1.12** - Upgrades deps and actions; Fix memory leak [#75](https://github.com/chrvadala/node-ble/pull/75)
+- **1.12** - Upgrades deps and actions; Fixes memory leak [#75](https://github.com/chrvadala/node-ble/pull/75); Improved docs with copy-and-paste configuration scripts.
 
 # Contributors
 - [chrvadala](https://github.com/chrvadala) (author)

docs/documentation-testing.md

@@ -1,26 +1,25 @@
 # Running tests
 
-This library provides two test suites:
-- Unit tests: They are available in the `/test` folder and they test every single component.
+This library provides two test suite types:
+- Unit tests: They are available in the `/test` folder and they test every single component (class/function).
 - End to end tests: They are available in the `/test-e2e` folder and they test the interaction with a real bluetooth device that you spawn on your own.
 
 
 ## Pre-requisite
 
-In order to run the available test suites you have to set up right DBus permissions.
+In order to run the available test suites you have to set up right D-Bus permissions.
+Execute the following script on a bash terminal
 
-Create the file `/etc/dbus-1/system.d/node-ble-test.conf` with the following content (customize with userid)
-
-```xml
-<!DOCTYPE busconfig PUBLIC "-//freedesktop//DTD D-BUS Bus Configuration 1.0//EN"
+```sh
+echo '<!DOCTYPE busconfig PUBLIC "-//freedesktop//DTD D-BUS Bus Configuration 1.0//EN"
   "http://www.freedesktop.org/standards/dbus/1.0/busconfig.dtd">
 <busconfig>
-  <policy user="%userid%">
+  <policy user="__USERID__">
     <allow own="org.test"/>
     <allow send_destination="org.test"/>
     <allow send_interface="org.test.iface"/>
   </policy>
-</busconfig>
+</busconfig>' | sed "s/__USERID__/$(id -un)/" | sudo tee /etc/dbus-1/system.d/node-ble-test.conf > /dev/null
 ```
 
 ## Run unit tests
@@ -30,10 +29,10 @@ npm test
 
 ## Run end to end (e2e) tests
 
-The end to end test will try to connect to a real bluetooth device and read some characteristics. To do that, you need two different devices.
-Prior to that, you need to create a test device via [installation guide](https://github.com/chrvadala/node-ble/blob/main/ble-test-device).
+The end to end test will try to connect to a real bluetooth device and read some characteristics. To do that, you need two different devices a central and a peripheral.
+The test suite will act as a central, but you to need to create a fake peripheral (test device). You can follow [fake device setup guide](https://github.com/chrvadala/node-ble/blob/main/ble-test-device).
 
-After you have prepared the device, you have to read via USB its mac address, then lunch the test suite.
+After you have prepared the device, you have to read via USB its mac address, then launch the test suite.
 
 ```shell script
 TEST_DEVICE=00:00:00:00:00:00 npm run test:e2e