Initial commit

.github/workflows/publish_docs.yml

@@ -0,0 +1,33 @@
+name: Create and publish documentation
+on:
+  workflow_dispatch:
+  release:
+    types: [published]
+jobs:
+  documentation:
+    runs-on: ubuntu-latest
+    name: Create the documentation and deploy it to GitHub Pages
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Node.js
+        uses: actions/setup-node@v1
+        with:
+          node-version: "14.x"
+      - name: Set up Python
+        uses: actions/setup-python@v2
+        with:
+          python-version: "3.7"
+      - name: Install build dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install requests
+          npm install
+      - name: Build documentation
+        run: |
+          npm run docs:build
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs/.vuepress/dist
+          cname: tbridge01.theengs.io

.gitignore

@@ -0,0 +1 @@
+node_modules

docs/.vuepress/config.js

@@ -0,0 +1,46 @@
+module.exports = {
+  markdown: {
+    lineNumbers: true
+  },
+  title: 'Theengs Bridge Quick Start Guide',
+  description: 'Manufacturer agnostic BLE to MQTT bridge',
+  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/TBRIDGE1',
+    docsDir: 'docs',
+    docsBranch: 'development',
+    lastUpdated: 'Last Updated',
+    editLinks: true,
+    nav: [
+      { text: 'Shop🆕', link: 'https://shop.theengs.io/'},
+      { text: 'Home', link: 'https://www.theengs.io', target:'_self', rel:''},
+      { text: 'App', link: 'https://app.theengs.io', target:'_self', rel:''},
+      { text: 'Gateway', link: 'https://gateway.theengs.io', target:'_self', rel:''},
+      { text: 'Decoder', link: 'https://decoder.theengs.io', target:'_self', rel:''}
+    ],
+    sidebar: [
+      ['/','Quick start 🏠'],
+      ['advanced/advanced','Advanced ✈️']
+  ]
+  },
+  plugins: [
+    ['@vuepress/pwa', {
+      serviceWorker: true,
+      updatePopup: true
+    }],
+    ['@vuepress/medium-zoom', true],
+    ['@vuepress/nprogress']
+  ]
+}

docs/README.md

@@ -0,0 +1,104 @@
+## Theengs Bridge, Easy Setup Guide
+
+Discover the **Theengs Bridge**, a smart Bridge and BLE gateway in one device. This guide will help you quickly connect your Bridge to an MQTT broker.
+
+1. **Plug it in**: Plug the device to an USB-C power supply. An orange LED will turn on steadily.
+
+2. **Connect to WiFi**: On your smartphone, search for a WiFi network starting with `OMG_`.
+Alternatively you can connect an ethernet cable to the bridge and access the configuration by typing the bridge IP into a browser (the bridge IP can be found on your router or by a serial connection)
+<p align="left">
+  <img src="./img/Theengs-plug01-wifi.png">
+</p>
+
+3. **Enter the password**: Click on the network and enter the last 8 digits of the device's MAC address as the password (the MAC address is printed on the side of the device). For example, if the MAC address is `409151234678`, the password will be `51234678`.
+
+4. **Access the setup page**: A webpage may pop up automatically. If not, click on the gear icon next to the WiFi network.
+<p align="left">
+  <img src="./img/Theengs-plug01-wifi-manage-gear.png">
+</p>
+1. Then click on "Manage router".
+<p align="left">
+  <img src="./img/Theengs-plug01-wifi-manage-router.png">
+</p>
+
+::: tip
+If your smartphone disconnects from the Bridge's WiFi network and reconnects to your main WiFi, "forget" your main WiFi to maintain a stable connection with the Bridge. After configuration, reconnect to your main WiFi. If the configuration portal doesn't appear, access it at `192.168.4.1` in your web browser.
+:::
+
+5. **Configure WiFi**: Click on "Configure WiFi".
+<p align="left">
+  <img src="./img/Theengs-plug01-wifi-manage-configure.png">
+</p>
+
+6. **Enter your settings**: Fill in the following required details:
+* Your WiFi Access Point (SSID - optional if ethernet connected)
+* Your WiFi password (Password - optional if ethernet connected)
+* Your MQTT server
+* Your MQTT port
+
+Optionally, adjust the following settings if needed:
+* MQTT user
+* MQTT password
+* Secure connection and certificates (if required)
+* Gateway name
+* Base topic
+* Password (this password will be used for configuration portal and Over The Air updates)
+<p align="left">
+  <img src="./img/Theengs-plug01-wifi-manage-parameter.png">
+</p>
+
+::: tip
+When using the bridge with ethernet, entering WiFi Access Point and Password will enable to have a fallback connection network if ethernet is disconnect.
+:::
+
+7. **Save**: Click on Save.
+
+When connected, the bridge first LED should turn green and second LED will blink blue during scanning.
+
+For further integration with a Home Automation Controller, refer to the [OpenMQTTGateway documentation](https://docs.openmqttgateway.com/use/ble.html).
+
+::: tip
+To reset the parameters, access the bridge portal through its IP address (login: admin, default password: OTAPASSWORD). The WiFi configuration portal will then be available (step 2).
+:::
+
+For assistance or support, email: [[email protected]](mailto:[email protected]).
+
+## Safety Instructions
+When using the Theengs Bridge, please follow these safety guidelines to ensure proper operation and to prevent potential hazards:
+
+a. Read and follow all instructions provided in this manual before using the Theengs Bridge.
+
+b. The Theengs Bridge is designed for indoor use only. Do not use it outdoors or expose it to moisture, excessive heat, or direct sunlight.
+
+c. Ensure that the power supply used, is in good working condition and complies with local electrical codes.
+
+e. Keep the Theengs Bridge away from water, flammable materials, and sources of ignition.
+
+f. Disconnect the Theengs Bridge from its power supply before cleaning or performing any maintenance. Use a dry cloth to clean the Theengs Bridge, and avoid using harsh chemicals or abrasive materials.
+
+g. Do not attempt to disassemble, repair, or modify the Theengs Bridge. Doing so may cause damage, void the warranty, and potentially create safety hazards.
+
+h. In the event of a malfunction or suspected problem with the Theengs Bridge, disconnect it immediately and contact customer support for assistance.
+
+i. Keep the Theengs Bridge and its packaging materials out of reach of children and pets to avoid the risk of choking or injury.
+
+## Specifications
+| Feature         | Specification                                |
+|-----------------|----------------------------------------------|
+| Power Supply    | USB-C 5.0V                                   |
+| Microcontroller | ESP32                                        |
+| Memory          | 8MB                                          |
+| WiFi Band       | 2.4 GHz                                      |
+| Protocol        | MQTT                                         |
+| Ethernet        | RJ45                                         |
+| Antenna         | 2.4GHz 6dBi 50ohm Wireless Antenna           |
+| LED             | 4 RGBs                                       |
+| Board type      | Development board with Grove connector       |
+| Dimensions      | 4.05in * 1.37in * 2.4in (160 × 120 × 30 mm without antenna) |
+|Usage| Indoor use only|
+
+
+## Warranty
+The Theengs Bridge hardware warranty is one year from the date of purchase. See details [here](https://shop.theengs.io/pages/limited-product-warranty)
+
+The Bridge is delivered with firmware developed under [GPLv3 license](https://github.com/1technophile/OpenMQTTGateway/blob/development/LICENSE.txt), by using it, you accept the terms and conditions of this license.

docs/advanced/advanced.md

@@ -0,0 +1,82 @@
+# User Guide
+
+## LED Indicator Guide
+
+### Steady Orange
+The bridge is generating an Access Point for network onboarding.
+
+### Orange (5 seconds on, 5 seconds off)
+The bridge is disconnected from the MQTT broker.
+
+### Orange (2 seconds on, 2 seconds off)
+The bridge is disconnected from the WiFi network.
+
+### Steady Green
+The bridge is connected to both the network and the MQTT broker.
+
+### Steady Blue
+An update or operation is currently in progress.
+
+### Flashing Blue
+Scanning or communication is in progress.
+
+## Modules and Parameters
+
+### Home Assistant Discovery Convention
+The bridge publishes its configuration and detected BLE sensors to the broker following the [Home Assistant discovery convention](https://www.home-assistant.io/integrations/mqtt/#mqtt-discovery). You can find the devices in the Configuration->Devices menu with [Home Assistant](https://docs.openmqttgateway.com/integrate/home_assistant.html).
+
+<p align="left">
+  <img src="./../img/Theengs-Plug-Settings-HomeAssistant.png">
+</p>
+
+<p align="left">
+  <img src="./../img/Theengs-Plug-Settings-HomeAssistant-2.png">
+</p>
+
+::: tip
+Other controllers can also use the Home Assistant convention for automatic discovery.
+:::
+
+### Bluetooth Gateway
+The bridge detects [Bluetooth devices](https://docs.openmqttgateway.com/prerequisites/devices.html#for-ble-devices) and publishes their data to the MQTT broker.
+```
+home/112233445566/BTtoMQTT/AABBCCDDEEFF
+{"id":"AA:BB:CC:DD:EE:FF","rssi":-88,"brand":"ClearGrass/Qingping","model":"Alarm Clock","model_id":"CGC1/CGD1","tempc":20.3,"tempf":68.54,"hum":55.3,"batt":41}
+```
+For example with auto-discovery
+<p align="left">
+  <img src="./../img/Theengs-Plug-Settings-HomeAssistant-3.png">
+</p>
+
+### Default parameters
+* Adaptive scanning activated (from v1.5.0)
+* Connect to BLE devices deactivated
+* BLE adaptive scan activated
+
+The BLE parameters can be changed with the commands detailed into [BLE gateway usage](https://docs.openmqttgateway.com/use/ble.html).
+
+## Updating Theengs Bridge
+Theengs bridge can benefit from Over The Air updates following these different methods:
+* From Home Assistant directly, Settings->Devices & Services->Devices, click on the bridge, click on the firmware version, click Update
+* From the WifiManager portal, by uploading a binary directly to the bridge
+  * Download the last version binary named "Theengs-Bridge-firmware" from the Github [release page of OpenMQTTGateway](https://github.com/1technophile/OpenMQTTGateway/releases)
+  * Reset the bridge with a long button press
+  * Connect to the Wifi access point with your smartphone
+  * Click Update
+  * Add the binary downloaded previously
+  * Click Update and wait a few minutes until you get "Update successfull"
+  * Reconfigure the bridge into the Wifi portal
+* From an MQTT command to trigger the download of the firmware from a webserver
+  * Connect to your MQTT broker with a client like MQTT Explorer
+  * Publish the update command like below (OTAPASSWORD being your Over The Air password if you changed it during the configuration):
+
+```
+{
+  "version": "latest"
+}
+```
+To this topic (112233445566 being your gateway_name):
+```
+home/112233445566/commands/MQTTtoSYS/firmware_update
+```
+  * The bridge will restart with the new version