Add vuepress documentation

.gitignore

@@ -128,3 +128,6 @@ dmypy.json
 
 # Pyre type checker
 .pyre/
+
+# VuePress
+node_modules/

.npmignore

@@ -0,0 +1,12 @@
+pids
+logs
+node_modules
+npm-debug.log
+coverage/
+run
+dist
+.DS_Store
+.nyc_output
+.basement
+config.local.js
+basement_dist

CODE_OF_CONDUCT.md

@@ -0,0 +1,46 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at untechnophile@gmail.com. The project team will review and investigate all complaints, and will respond in a way that it deems appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available at [http://contributor-covenant.org/version/1/4][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/4/

README.md

@@ -1 +1,12 @@
-# gateway
+![Iot](docs/img/logo-Theengs.png)
+
+**Theengs Gateway** is a multi platforms, multi devices BLE to MQTT gateway that leverage the [Theengs Decoder library](https://github.com/theengs/decoder).
+It retrieves data from a wide range of BLE sensors, translate these informations into a readable JSON format and push those to an MQTT broker.
+
+Enabling integration to IOT platforms or home automation controllers like [NodeRED](https://nodered.org/), [AWS IOT](https://aws.amazon.com/fr/iot/), [Home Assistant](https://www.home-assistant.io/), [OpenHAB](https://www.openhab.org/), [FHEM](https://fhem.de/[), [IOBroker](https://www.iobroker.net/) or [DomoticZ](https://domoticz.com/).
+
+The gateway uses the bluetooth component of your Raspberry Pi, Windows, Apple desktop, laptop or server by leveraging python and multi platform libraries.
+
+**Theengs Gateway** can be used as a standalone solution or as a complementary solution to [OpenMQTTGateway](https://docs.openmqttgateway.com/) as it uses the same MQTT topic structure and the same payload messages. Your OpenMQTTGateway Home Automation BLE sensors integration will work also with Theengs gateway.
+
+The gateway will retrieve data from BLE sensors from Govee, Xiaomi, Inkbird, QingPing, ThermoBeacon, ClearGrass, Blue Maestro and many more.

docs/.vuepress/config.js

@@ -0,0 +1,57 @@
+module.exports = {
+    markdown: {
+      lineNumbers: true
+    },
+    title: 'Theengs gateway',
+    description: 'Multi platform MQTT gateway leveraging Theengs Decoder',
+    base:"/gateway/",
+    head: [
+      ['link', { rel: "apple-touch-icon", sizes: "180x180", href: ".apple-touch-icon.png"}],
+      ['link', { rel: "icon", type: "image/png", sizes: "32x32", href: "/favicon-32x32.png"}],
+      ['link', { rel: "icon", type: "image/png", sizes: "16x16", href: "/favicon-16x16.png"}],
+      ['link', { rel: 'manifest', href: '/manifest.json' }],
+      ['meta', { name: 'theme-color', content: '#3eaf7c' }],
+      ['meta', { name: 'apple-mobile-web-app-capable', content: 'yes' }],
+      ['meta', { name: 'apple-mobile-web-app-status-bar-style', content: 'black' }],
+      ['link', { rel: 'mask-icon', href: '/icons/safari-pinned-tab.svg', color: '#3eaf7c' }],
+      ['meta', { name: 'msapplication-TileImage', content: '/favicon-144x144.png' }],
+      ['meta', { name: 'msapplication-TileColor', content: '#000000' }]
+    ],
+    themeConfig: {
+      smoothScroll: true,
+      repo: 'theengs/gateway',
+      docsDir: 'docs',
+      docsBranch: 'development',
+      lastUpdated: 'Last Updated',
+      editLinks: true,
+      sidebar: [
+        ['/','0 - What is it for 🏠'],
+        {
+          title: '1 - Prerequisites🧭',
+          children: [
+            'prerequisites/devices',
+            'prerequisites/hardware',
+            'prerequisites/broker',
+            'prerequisites/controller']
+        },
+        ['/install/install','2 - Install ✔️'],
+        ['/use/use','3 - Use ✈️'],
+        {
+          title: '4 - Participate 💻',
+          children: [
+            'participate/adding-decoders',
+            'participate/support',
+            'participate/development'
+          ]
+        }
+    ]
+    },
+    plugins: [
+      ['@vuepress/pwa', {
+        serviceWorker: true,
+        updatePopup: true
+      }],
+      ['@vuepress/medium-zoom', true],
+      ['@vuepress/nprogress']
+    ]
+  }

docs/README.md

@@ -0,0 +1,12 @@
+![Iot](./img/logo-Theengs.png)
+
+**Theengs Gateway** is a multi platforms, multi devices BLE to MQTT gateway that leverage the [Theengs Decoder library](https://github.com/theengs/decoder).
+It retrieves data from a wide range of BLE sensors, translate these informations into a readable JSON format and push those to an MQTT broker.
+
+Enabling integration to IOT platforms or home automation controllers like [NodeRED](https://nodered.org/), [AWS IOT](https://aws.amazon.com/fr/iot/), [Home Assistant](https://www.home-assistant.io/), [OpenHAB](https://www.openhab.org/), [FHEM](https://fhem.de/[), [IOBroker](https://www.iobroker.net/) or [DomoticZ](https://domoticz.com/).
+
+The gateway uses the bluetooth component of your Raspberry Pi, Windows, Apple desktop, laptop or server by leveraging python and multi platform libraries.
+
+**Theengs Gateway** can be used as a standalone solution or as a complementary solution to [OpenMQTTGateway](https://docs.openmqttgateway.com/) as it uses the same MQTT topic structure and the same payload messages. Your OpenMQTTGateway Home Automation BLE sensors integration will work also with Theengs gateway.
+
+The gateway will retrieve data from BLE sensors from Govee, Xiaomi, Inkbird, QingPing, ThermoBeacon, ClearGrass, Blue Maestro and many more.

docs/install/install.md

@@ -0,0 +1,16 @@
+# Install
+
+## Install prerequisites
+* Install [Python](https://www.python.org/downloads/)
+* Install [pip](https://pip.pypa.io/en/stable/installation/)
+
+## Install Theengs Gateway
+Doing so is simple as 1 command:
+```shell
+pip3 install TheengsGateway
+```
+
+You can access advanced configuration by typing:
+```shell
+python -m TheengsGateway -h
+```

docs/participate/adding-decoders.md

@@ -0,0 +1,5 @@
+# Adding decoders
+
+Adding your device protocol to Theengs enable to increase interoperability and to create new use cases with your device. You will find below some guidance to do that. 
+
+You can do a pull request directly to the [Decoder Repository](https://github.com/theengs/decoder) by leveraging the Theengs Decoder [example](https://theengs.github.io/decoder/participate/adding-decoders.html).

docs/participate/development.md

@@ -0,0 +1,66 @@
+# Development contributions
+
+We like pull requests from everyone. By participating in this project, you
+agree to follow the code of conduct below
+
+[code of conduct](https://github.com/theengs/gateway/blob/master/CODE_OF_CONDUCT.md)
+
+[code style guide](https://google.github.io/styleguide/cppguide.html#Formatting)
+So as to format automaticaly your document you have to add the "clang-Format" extension to VSCode, once done, you can format the code by doing a right click into the code file window and clicking "Format document".
+
+Fork the [development branch](https://github.com/theengs/gateway/tree/development), then clone the repo
+
+Make your modification,
+
+Review your code, build it
+
+Test it locally on your hardware config
+
+Emit a pull request
+
+Verify the GitHub Actions CI compilation results
+
+Request for review
+
+We may suggest some changes, improvements or alternatives.
+
+Some things that will increase the chance that your pull request is accepted:
+* Comment your code,
+* Ask eventually for design guidelines,
+* Write a [good commit message][commit].
+
+[commit]: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
+
+## Developer Certificate Of Origin
+
+```
+    By making a contribution to this project, I certify that:
+
+    (a) The contribution was created in whole or in part by me and I
+        have the right to submit it under the open source license
+        indicated in the file; or
+
+    (b) The contribution is based upon previous work that, to the best
+        of my knowledge, is covered under an appropriate open source
+        license and I have the right under that license to submit that
+        work with modifications, whether created in whole or in part
+        by me, under the same open source license (unless I am
+        permitted to submit under a different license), as indicated
+        in the file; or
+
+    (c) The contribution was provided directly to me by some other
+        person who certified (a), (b) or (c) and I have not modified
+        it.
+
+    (d) I understand and agree that this project and the contribution
+        are public and that a record of the contribution (including all
+        personal information I submit with it, including my sign-off) is
+        maintained indefinitely and may be redistributed consistent with
+        this project or the open source license(s) involved.
+```
+
+This Developer Certificate Of Origin (DCO) was adopted on February 26, 2022.
+
+The text of this license is available under the [Creative Commons Attribution-ShareAlike 3.0 Unported License](http://creativecommons.org/licenses/by-sa/3.0/).  It is based on the Linux [Developer Certificate Of Origin](http://elinux.org/Developer_Certificate_Of_Origin).
+
+To accept the DCO it is required to put a x between [ ] on `[ ] I accept the DCO` in the PR template when submitting it. The [ ] is an opt-in box, so you have to manually accept it.

docs/participate/support.md

@@ -0,0 +1,8 @@
+# Supporting the project
+
+If you like the project and/or used it please consider supporting it! It can be done in different ways:
+* Helping others in the [community](https://github.com/theengs/gateway/discussions)
+* [Contribute](development) to the [code](https://github.com/theengs/gateway) or the documentation,
+* Buy devices, boards or parts from the [compatible web site](https://compatible.openmqttgateway.com), the devices and parts linked use affiliated links,
+* Donate or sponsor the project [developpers](https://github.com/theengs/gateway/graphs/contributors)
+* Make a video or a blog article about what you have done with [TheengsGateway](https://github.com/theengs/gateway) and share it.

docs/prerequisites/broker.md

@@ -0,0 +1,20 @@
+# Broker
+The broker will act as an intermediary between TheengsGateway and your [controller](/prerequisites/controller), it can be seen as a centralized hub at the heart of your automation system. It carry on messages following a publish / subscribe mechanism.
+
+All the events or commands could pass by the broker.
+
+There is many choice of brokers, here is some of the most populars:
+* [Mosquitto](https://mosquitto.org/) (Open source)
+* [Moquette](https://moquette-io.github.io/moquette/) (Open source)
+* [HiveMQ](https://www.hivemq.com/hivemq/features/)
+* Embedded MQTT brokers (Home Assistant and OpenHAB)
+
+This [wikipedia list](https://en.wikipedia.org/wiki/Comparison_of_MQTT_implementations) gives you more details about the different choices you have.
+This [github list](https://github.com/mqtt/mqtt.github.io/wiki/libraries) seems to be the most exhaustive ones.
+Here is also some [idea of criterias](https://www.hivemq.com/blog/top-10-mqtt-broker-criteria/) from HiveMQ.
+
+Once your broker installed it can be interesting to see the traffic passing to it and to publish data, so as to do that there is several tools available:
+* [MQTT Explorer](http://mqtt-explorer.com/)
+* [HIVE MQ Web client](https://github.com/hivemq/hivemq-mqtt-web-client)
+* [MQTT FX](https://mqttfx.jensd.de/)
+

docs/prerequisites/controller.md

@@ -0,0 +1,16 @@
+# Controller
+MQTT enables you to connect easily a controller so as to monitor, control and automate scenarios.
+
+The following controllers (and many other software) are compatible with MQTT:
+
+![controllers](../img/TheengsGateway_controllers.png)
+
+TheengsGateway is independant from these projets, you have the liberty of choice among all the compatibles software.
+
+* [OpenHAB2](https://www.openhab.org)
+* [Home Assistant](https://www.home-assistant.io)
+* [Domoticz](https://www.domoticz.com)
+* [Jeedom](https://www.jeedom.com)
+* [Node Red](https://nodered.org)
+* [FHEM](https://fhem.de)
+* [IO Broker](https://www.iobroker.net/)

docs/prerequisites/devices.md

@@ -0,0 +1,44 @@
+# Devices supported
+
+Here is the list of supported devices by the gateway:
+
+|Devices|Model|Measurements|
+|-|:-:|:-:|
+| BlueMaestro|TempoDisc|temperature/humidity/duepoint/voltage|
+| ClearGrass |CGG1|temperature/humidity/battery|
+| ClearGrass alarm clock|CGD1|temperature/humidity|
+| ClearGrass with atmospheric pressure |CGP1W|temperature/humidity/air pressure|
+| Clock |LYWDS02|temperature/humidity|
+| Eddystone TLM|protocol|temperature/count/volt/time|
+| GOVEE |H5075|temperature/humidity/battery|
+| GOVEE |H5072|temperature/humidity/battery|
+| GOVEE |H5102|temperature/humidity/battery|
+| HONEYWELL |JQJCY01YM|formaldehyde/temperature/humidity/battery|
+| Ibeacon|protocol|UUID/MFID/Major/Minor/Power|
+| INKBIRD|IBS-TH1|temperature/humidity/battery|
+| INKBIRD|IBS-TH2|temperature/battery|
+| INKBIRD|IBT-2X|temperature1/temperature2|
+| INKBIRD|IBT-4XS|temperature1/temperature2/temperature3/temperature4|
+| INKBIRD|IBT-6XS|temperature1/temperature2/temperature3/temperature4 /temperature5/temperature6|
+| iNode Energy Meter||power/energy/battery|
+| Mokosmart|M1|x_axis/y_axis/z_axis/battery|
+| Mokosmart|H4|temperature/humidity/volt|
+| Qingping |CGDK2|temperature/humidity|
+| Qingping |CGH1|open|
+| Qingping |CGPR1|presence/luminance|
+| RuuviTag Raw V1|RuuviTag|temperature/humidity/pressure/acceleration/volt|
+| RuuviTag Raw V2|RuuviTag|temperature/humidity/pressure/acceleration/volt/TX power/movement/counter/sequence number|
+| Thermobeacon|WS02|temperature/humidity/volt|
+| Thermobeacon|WS08|temperature/humidity/volt|
+| TPMS|TPMS|temperature/pressure/battery/alarm/count|
+| Vegtrug ||temperature/moisture/luminance/fertility|
+| XIAOMI Mi Flora |HHCCJCY01HHCC|temperature/moisture/luminance/fertility/battery(1)|
+| XIAOMI Mi Jia |LYWSDCGO|temperature/humidity/battery|
+| XIAOMI Mi Jia 2 custom firmware (2)|LYWSD03MMC ATC|temperature/humidity/battery/volt|
+| XIAOMI Mi Jia 2 custom firmware (3)|LYWSD03MMC PVVX|temperature/humidity/battery/volt|
+| XIAOMI Mi Lamp |MUE4094RT|presence|
+| XIAOMI Mi Scale v1|XMTZC04HM|weight|
+| XIAOMI Mi Scale v2|XMTZC05HM|weight|
+| XIAOMI Mi Temp/Humidity v1|MHO-C401|temperature/humidity/battery/volt|
+| XIAOMI Mi Temp/Humidity v2|XMWSDJ04MMC|temperature/humidity/battery/volt|
+| XIAOMI Mi band||steps|

docs/prerequisites/hardware.md

@@ -0,0 +1,10 @@
+# Hardware
+
+One strength of TheengsGateway is its multi hardware support, you can [install](../install/install) it on various hardware as long as they have a BLE module:
+* Windows PC
+* Apple Mac (not tested yet)
+* Raspberry Pi Zero
+* Raspberry Pi 4
+* NUC (not tested yet)
+
+If you want to use Theengs into a cheaper and more portable board you can use [OpenMQTTGateway](https://docs.openmqttgateway.com/) with an ESP32.