chriz/OpenMQTT-Gateway
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 5 Wiki Activity

[DOCS] - Generate board documentation automaticaly from platformio.ini (#1405)

Browse Source 
* [DOCS] - Generate board documentation automaticaly from platformio.ini

To reduce maintenance effort

* [CI] Differentiate boards from platformio.ini

So that only one line can be commented to use customs environments
This commit is contained in:
Florian authored and GitHub committed 2023-01-20 09:04:18 -06:00
1 parent b4003d4ea1
commit 5297dff7bb
9 files changed
+1600 -1520
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

.github/workflows/build.yml
+1 -1
View File
@@ -9,7 +9,7 @@ jobs:
matrix:
environments:
- "rfbridge"
- "sonoff-rfbridge-direct"
- "rfbridge-direct"
- "esp32dev-all-test"
- "esp32dev-rf"
- "esp32dev-pilight-cc1101"
.github/workflows/manual_docs.yml
+2 -1
View File
@@ -18,7 +18,7 @@ jobs:
- name: Install build dependencies
run: |
python -m pip install --upgrade pip
pip install requests
pip install requests pandas markdown pytablereader tabulate
npm install
- name: get lastest release tag
id: last_release
@@ -30,6 +30,7 @@ jobs:
run: sed -i "s/version_tag/${{steps.last_release.outputs.tag_name}}/g" docs/.vuepress/config.js
- name: Build documentation
run: |
python ./scripts/generate_board_docs.py
python ./scripts/gen_wu.py ${GITHUB_REPOSITORY}
npm run docs:build
- name: Deploy to GitHub Pages
.github/workflows/release.yml
+2 -1
View File
@@ -56,12 +56,13 @@ jobs:
- name: Install build dependencies
run: |
python -m pip install --upgrade pip
pip install requests
pip install requests pandas markdown pytablereader tabulate
npm install
- name: Set version tag from git
run: sed -i "s/version_tag/${GITHUB_REF#refs/tags/}/g" docs/.vuepress/config.js
- name: Build documentation
run: |
python ./scripts/generate_board_docs.py
python ./scripts/gen_wu.py ${GITHUB_REPOSITORY}
npm run docs:build
- name: Deploy to GitHub Pages
boards.ini
+1495
View File
File diff suppressed because it is too large. Load diff
docs/prerequisites/board.md
+3 -48
View File
@@ -1,4 +1,5 @@
# Board
# Boards
OpenMQTTGateway is not closed to one board or type of board, by using the power of the Arduino framework and libraries that are cross compatibles it let you many choice of hardware, from an Arduino UNO to an ESP32.
You can take a look to the [OpenMQTTGateway compatible website](https://compatible.openmqttgateway.com) to have a view of the [supported boards](https://compatible.openmqttgateway.com/index.php/boards/).
@@ -14,53 +15,7 @@ If you want to use the BLE decoding capabilities of OpenMQTTGateway with a Raspb
If you want to use the BLE decoding capabilities of OpenMQTTGateway with a tablet or smartphone you can use [Theengs App](https://app.theengs.io/).
:::
Here is some information to find the boards suitable for your need, you have the choice between off the shelves boards and DIY setup.
## Off the shelves boards
The boards below doesn't need hardware modification (or a lite one).
|Off the shelves wifi boards|Pictures|RF|IR|BLE|LORA|Relay|Display|Low Power|
|-|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|
|AVATTO / BAKEEY|![](../img/OpenMQTTGateway_boards_avatto_s06.png)|-|[X](https://1technophile.blogspot.com/2020/07/avatto-s06-ir-gateway-compatible-with.html)|-|-|-|-|-|
|Sonoff RF Bridge (*) |![](../img/OpenMQTTGateway_boards_sonoff_rfbridge.png)|X|[mod](https://1technophile.blogspot.com/2018/02/adding-infrared-emitter-to-sonoff-rf.html)|-|-|-|-|-|
|All bare ESP32|-|-|-|X|-|X|-|X|
|OLIMEX ESP32 Ethernet|-|-|-|X|-|X|-|X|
|OLIMEX ESP32 Ethernet POE|-|-|-|X|-|X|-|X|
|OLIMEX ESP32 Ethernet POE ISO|-|-|-|X|-|X|-|X|
|ESP32-WT32-ETH01 Ethernet|-|-|-|X|-|X|-|X|
|Heltec WiFi LoRa 32 (V2.1)|-|rtl_433|-|X|X|-|X|-|
|[M5Stack Basic](M5)|![](../img/OpenMQTTgateway_M5_Stack_Board_Display_Text.png)|-|-|X|-|X|X|X|
|[M5Tough](M5)|-|-|-|X|-|X|X|X|
|M5Stick|-|-|send|X|-|X|-|X|
|[M5Stick C](M5)|![](../img/OpenMQTTgateway_M5_StickC_Board_Display_Text.png)|-|send|X|-|X|X|X|
|[M5Atom](M5)||-|send|X|-|X|X|X|
|TTGO LORA32|![](../img/OpenMQTTGateway_TTGO32_LORA_Send.jpg)|-|-|-|X|-|-|-|
|Sonoff RFR3|![](../img/OpenMQTTGateway_boards_sonoff_rfr3.png)|[receiving](https://1technophile.blogspot.com/2019/08/new-sonoff-rfr3-as-433tomqtt-gateway.html)|-|-|-|X|-|-|
|Sonoff Basic|-|-|-|-|-|X|-|-|
|RF WIFI GATEWAY|![](../img/OpenMQTTGateway_board_wifi_rf_gateway.png)|[receiving](https://1technophile.blogspot.com/2019/09/hack-of-rf-wifi-gateway-usb-stick.html)|-|-|-|-|-|-|
'(*)' *So as to extend the number of RF protocols supported by the Sonoff RF Bridge you can apply a [hardware hack](https://1technophile.blogspot.com/2019/04/sonoff-rf-bridge-pilight-or-how-to.html), this way you will be able to use RFm Pilight or RF2 gateway.*
## DIY boards
The boards below need hardware [parts](parts.md) and electronic/hardware competencies. You have more possibilities of gateways combination, compared to off the shelves ones.
|DIY boards|RF|IR|BLE|LORA|GSM|Button|Relay|
|-|:-:|:-:|:-:|:-:|:-:|:-:|:-:|
|Arduino UNO|X|X(limited compared to ESP)|-|-|-|X|X|
|Arduino MEGA|X|X(limited compared to ESP)|-|-|-|X|X|
|ESP32|X|X|X|X|not tested|X|X|
|ESP8266|X|X|-|not tested|X|X|X|
::: tip
Pilight is only supported on ESP, Arduino UNO handle only 32bits values in our context.
HM10 is no longer supported by OpenMQTTGateway
:::
![boards](../img/OpenMQTTGateway_boards.png)
Arduino + ethernet shields enables faster responsiveness of the gateway and a reliable connection.
The ESP platform is more flexible in term of installation (no need of an ethernet cable) but is less reliable in term of communication. Thanks to its higher memory and processing power it has more modules or possibilities compared to Arduino Uno & Mega.
Choosing your board depends heavily on the technologies you want to use with it.
To have a good overview of the compatibilities per board you can refer to the compatible modules attributes of each [board](https://compatible.openmqttgateway.com/index.php/boards/).
The choice between these boards will depend on your knowledge and your requirements in terms of reliability, situation, modules wanted and devices you already have.
The choice between these boards will depend on your knowledge and your requirements in terms of reliability, situation, modules wanted and devices you already have. The table below present those (auto-generated)
docs/prerequisites/boards/.gitignore
+4
View File
@@ -0,0 +1,4 @@
# Ignore everything in this directory
*
# Except this file
!.gitignore
docs/upload/web-install.md
+3 -62
View File
@@ -1,5 +1,7 @@
# (Option 1) Upload from the web
[![Hits](https://hits.seeyoufarm.com/api/count/incr/badge.svg?url=https%3A%2F%2Fdocs.openmqttgateway.com%2Fupload%2Fweb-install.html&count_bg=%2379C83D&title_bg=%23555555&icon=&icon_color=%23E7E7E7&title=hits&edge_flat=false)](https://hits.seeyoufarm.com)
::: tip Running on a tablet or phone
If you want to use the BLE decoding capabilities of OpenMQTTGateway with a tablet or smartphone you can use [Theengs App](https://app.theengs.io/).
:::
@@ -13,65 +15,4 @@ You can upload the firmware to your ESP device directly from here.
<web-uploader/>
The table below describes the libraries and the modules of each board configuration.
|Firmware|Boards compatible|Description|RF|IR|BLE|LORA|
|:-:|:-:|:-:|:-:|:-:|:-:|:-:|
|**ESP32**|
|esp32-lolin32lite-ble|ESP32 Lolin lite|Suitable for low power with BLE gateway, [tutorial](https://1technophile.blogspot.com/2021/04/low-power-esp32-ble-gateway.html)|-|-|X|-|
|esp32-m5atom-lite|M5Atom Lite|Compact enclosure ESP32 with BLE gateway|-|(Emit)|X|-|
|esp32-m5atom-matrix|M5Atom Matrix|Compact enclosure ESP32 with BLE gateway|-|(Emit)|X|-|
|esp32-m5stack-ble|M5Stack Core|Expandable module with BLE gateway, display, and little IR emitter|-|-|X|-|
|esp32-m5stick-ble|M5Stick Grey|Expandable module with BLE gateway and little IR emitter|-|(Emit)|X|-|
|esp32-m5stick-c-ble|M5Stick C Orange|Expandable module with BLE gateway, display, and little IR emitter|-|(Emit)|X|-|
|esp32-m5stick-cp-ble|M5Stick C Plus Orange|Expandable module with BLE gateway, display, and little IR emitter|-|(Emit)|X|-|
|esp32-m5tough-ble|M5Tough rugged|Expandable module with BLE gateway and display, suitable for outdoor|-|-|X|-|
|esp32-olimex-gtw-ble-eth|Olimex Ethernet Gateway (non POE)|BLE gateway with external antenna as an option|-|-|X|-|
|esp32-olimex-gtw-ble-poe|Olimex Ethernet Gateway (POE)|BLE gateway with external antenna as an option|-|-|X|-|
|esp32-olimex-gtw-ble-poe-iso|Olimex Ethernet Gateway (POE + ISO)|BLE gateway with external antenna as an option|-|-|X|-|
|esp32-olimex-gtw-ble-wifi|Olimex Ethernet Gateway (non POE) using wifi| BLE gateway|-|-|X|-|
|esp32dev-ble-cont|ESP32 dev board|BLE gateway with continuous scanning, suitable in particular for door and window BLE sensors (and all the others)|-|-|X|-|
|esp32dev-ble|ESP32 dev board|BLE gateway with one scan every 55s per default|-|-|X|-|
|esp32dev-ble-openhab|ESP32 dev board|BLE gateway with one scan every 55s per default and OpenHAB discovery|-|-|X|-|
|esp32dev-ble-mqtt-undecoded|ESP32 dev board|BLE gateway with the decoding offloaded to [Theengs Gateway](https://gateway.theengs.io/)|-|-|X|-|
|esp32s3-dev-c1-ble|ESP32 dev board|BLE gateway with one scan every 55s per default|-|-|X|-|
|esp32c3-dev-m1-ble|ESP32 dev board|BLE gateway with one scan every 55s per default|-|-|X|-|
|esp32dev-gf-sun-inverter|ESP32 dev board|RS232 reading of GridFree Sun Inverter|-|-|-|-|
|esp32dev-ir|ESP32 dev board|Infrared (Emitting and receiving) using [IRremoteESP8266](https://github.com/crankyoldgit/IRremoteESP8266)|-|X|-|-|
|esp32dev-multi_receiver|ESP32 dev board|Multi RF library with the possibility to switch between [ESPilight](https://github.com/puuu/ESPiLight), [RTL_433_ESP](https://github.com/NorthernMan54/rtl_433_ESP), [NewRemoteSwitch](https://github.com/1technophile/NewRemoteSwitch) and [RCSwitch](https://github.com/1technophile/rc-switch), need CC1101|X|-|-|-|
|esp32dev-pilight-CC1101|ESP32 dev board|Gateway using [ESPilight](https://github.com/puuu/ESPiLight) library only, need CC1101|X|-|-|-|
|esp32dev-pilight|ESP32 dev board|Gateway using [ESPilight](https://github.com/puuu/ESPiLight) without the need of CC1101|X|-|-|-|
|esp32dev-pilight-somfy-CC1101|ESP32 dev board|Gateway using [Somfy Remote](https://github.com/Legion2/Somfy_Remote_Lib) and [ESPilight](https://github.com/puuu/ESPiLight) library, need CC1101|X|-|-|-|
|esp32dev-rf|ESP32 dev board|RF gateway using [RCSwitch](https://github.com/1technophile/rc-switch) library|X|-|-|-|
|esp32dev-rtl_433|ESP32 dev board|Gateway using [RTL_433_ESP](https://github.com/NorthernMan54/rtl_433_ESP) library, need CC1101|X|-|-|-|
|esp32dev-somfy-CC1101|ESP32 dev board|Gateway using [Somfy Remote](https://github.com/Legion2/Somfy_Remote_Lib) library, need CC1101|X|-|-|-|
|esp32dev-weatherstation|ESP32 dev board|Gateway to retrieve weather station data Ventus W174/W132 (tested), Auriol H13726, Hama EWS 1500, Meteoscan W155/W160 using [WeatherStationDataRx](https://github.com/Zwer2k/WeatherStationDataRx)|X|-|-|-|
|esp32feather-ble|ESP32 Feather Adafruit|BLE for the Adafruit Feather board|-|-|X|-|
|shelly-plus1|Shelly Plus 1 relay board (for TESTS ONLY, NOT FOR PRODUCTION USE)|BLE, Relay control, Switch|-|-|X|-|
|heltec-wifi-lora32-868|ESP32 HELTEC LORA V2|LORA communication 868Mhz using [arduino-LoRA](https://github.com/sandeepmistry/arduino-LoRa) |-|-|-|X|
|heltec-wifi-lora32-915|ESP32 HELTEC LORA V2|LORA communication 915Mhz using [arduino-LoRA](https://github.com/sandeepmistry/arduino-LoRa)|-|-|-|X|
|heltec-rtl_433|ESP32 HELTEC LORA32 v2|Gateway using [RTL_433_ESP](https://github.com/NorthernMan54/rtl_433_ESP) and [RadioLib](https://github.com/jgromes/RadioLib)|X|-|-|-|
|lilygo-rtl_433|ESP32 LILYGO LoRa32 V2.1|Gateway using [RTL_433_ESP](https://github.com/NorthernMan54/rtl_433_ESP) and [RadioLib](https://github.com/jgromes/RadioLib)|X|-|-|-|
|tinypico-ble|ESP32 TinyPICO|BLE Gateway|-|-|X|-|
|ttgo-lora32-v1-868|ESP32 TTGO LORA V1|LORA communication 868Mhz using [arduino-LoRA](https://github.com/sandeepmistry/arduino-LoRa)|-|-|-|X|
|ttgo-lora32-v1-915|ESP32 TTGO LORA V1|LORA communication 915Mhz using [arduino-LoRA](https://github.com/sandeepmistry/arduino-LoRa)|-|-|-|X|
|ttgo-tbeam|ESP32 TTGO T BEAM|BLE gateway with battery holder|-|-|X|-|
|esp32dev-ble-datatest|ESP32 dev board|Default BLE gateway with additional servicedata, manufacturerdata and service uuid for analysing decoding issues|-|-|X|-|
|**ESP8266**|
|nodemcuv2-2g|ESP8266 board|SMS gateway, need A6/A7 GSM module|-|-|-|-|
|nodemcuv2-ir|ESP8266 board|Infrared gateway using [IRremoteESP8266](https://github.com/crankyoldgit/IRremoteESP8266)|-|X|-|-|
|nodemcuv2-rf-cc1101|ESP8266 board|RF gateway using [RCSwitch](https://github.com/1technophile/rc-switch) library, need CC1101|X|-|-|-|
|nodemcuv2-rf|ESP8266 board|RF gateway using [RCSwitch](https://github.com/1technophile/rc-switch) library|X|-|-|-|
|nodemcuv2-rf2-cc1101|ESP8266 board|KAKU RF gateway using [NewRemoteSwitch](https://github.com/1technophile/NewRemoteSwitch) library, need CC1101|X|-|-|
|nodemcuv2-rf2|ESP8266 board|KAKU RF gateway using [NewRemoteSwitch](https://github.com/1technophile/NewRemoteSwitch) library|X|-|-|-|
|nodemcuv2-pilight|ESP8266 board|Gateway using [ESPilight](https://github.com/puuu/ESPiLight) without the need of CC1101|X|-|-|-|
|nodemcuv2-RS232|ESP8266 board|RS232 gateway|-|-|-|-|
|nodemcuv2-somfy-cc1101|ESP8266 board|Somfy RF gateway using [Somfy Remote](https://github.com/Legion2/Somfy_Remote_Lib) library, need CC1101|X|-|-|-|
|nodemcuv2-weatherstation|ESP8266 board|RF gateway using [WeatherStationDataRx](https://github.com/Zwer2k/WeatherStationDataRx) library|X|-|-|-|
|rf-wifi-gateway|ESP8266 board|RF gateway for USB stick using [RCSwitch](https://github.com/1technophile/rc-switch) library|X|-|-|-|
|rfbridge|ESP8255 board|RF gateway for the Sonoff RF Bridge relying on the internal decoder|X|-|-|-|
|sonoff-rfbridge-direct|ESP8255 board|RF gateway for the Sonoff RF Bridge requiring direct hack, relying on [ESPilight](https://github.com/puuu/ESPiLight) library, [tutorial](https://1technophile.blogspot.com/2019/04/sonoff-rf-bridge-pilight-or-how-to.html)|X|-|-|-|
|sonoff-basic|ESP8255 board|Wifi relay|-|-|-|-|
|sonoff-basic-rfr3|ESP8255 board|Wifi relay and RF receiver using [RCSwitch](https://github.com/1technophile/rc-switch) library, [tutorial](https://1technophile.blogspot.com/2019/08/new-sonoff-rfr3-as-433tomqtt-gateway.html)|Rec|-|-|-|
[![Hits](https://hits.seeyoufarm.com/api/count/incr/badge.svg?url=https%3A%2F%2Fdocs.openmqttgateway.com%2Fupload%2Fweb-install.html&count_bg=%2379C83D&title_bg=%23555555&icon=&icon_color=%23E7E7E7&title=hits&edge_flat=false)](https://hits.seeyoufarm.com)
The auto-generated table below describes the libraries and the modules of each board configuration.
platformio.ini
+2 -1407
View File
File diff suppressed because it is too large. Load diff
scripts/generate_board_docs.py
+88
View File
@@ -0,0 +1,88 @@
import pytablereader as ptr
import pandas as pd
import os
import re
import configparser
conf = configparser.ConfigParser()
# Init the table with the columns
table_init = pd.DataFrame(columns=['Environment', 'uC', 'Hardware', 'Description', 'Modules', 'Platform',
'Partitions', 'Libraries', 'Options'])
table = table_init
# Parse platformio.ini to retrieve boards information
conf.read('boards.ini')
for each_section in conf.sections():
if ("env:" in each_section and "-test" not in each_section):
env = each_section.replace("env:", "")
uc = ""
board = ""
hardware = ""
description = ""
modules = ""
platform = ""
partitions = ""
libraries = ""
options = ""
for (k, v) in conf.items(each_section):
v = v.replace('{', '').replace('}', '').replace('$', '').replace(
"env:", '').replace('\'', '').replace("-D", "")
if (k == "board"):
uc = v
if (k == "platform"):
platform = v
if (k == "board_build.partitions"):
partitions = v
if (k == "lib_deps"):
libraries = v
libraries = libraries.replace(
"\ncom-esp.lib_deps\n", "").replace(
"\ncom-arduino.lib_deps\n", "").replace("libraries.", "")
if (k == "build_flags"):
options = v
for o in options.split('\n'):
if ("gateway" in o or "sensor" in o or "actuator" in o):
if (modules != ""):
modules = modules + "\n"
modules = modules + o[1:o.rfind("=\"")]
options = options.replace(
"com-esp.build_flags\n", "")
if (k == "custom_description"):
description = v
if (k == "custom_hardware"):
hardware = v
table.loc[len(table.index)] = [env, uc, hardware, description, modules, platform,
partitions, libraries, options]
# Sort rows per Environment name
table.sort_values(by=['Environment'], inplace=True,
key=lambda col: col.str.lower())
# Produce individual file
for ind in table.index:
table_extract = table.iloc[ind]
print(table_extract)
file = open("docs/prerequisites/boards/" +
table.iloc[ind]["Environment"] + ".md", 'w')
table_extract = table_extract.rename_axis("Board index")
table_md = table_extract.to_markdown()
n = file.write(table_md)
file.close()
# Produce list file
# Add link to the file from the environment and replace /n with ,
for ind in table.index:
table['Environment'][ind] = "[" + table['Environment'][ind] + \
"](../prerequisites/boards/" + table['Environment'][ind] + ")"
table = table.replace("\n", ", ", regex=True)
table = table.drop(["Partitions", "Hardware", "Platform", "Options","Modules"], axis=1)
table = table.reset_index(drop=True)
print(table)
# Convert to Markdown and save per Model_Id
table_md = table.to_markdown()
file = open("docs/prerequisites/board.md", 'a')
n = file.write("# Supported\n" + table_md)
file = open("docs/upload/web-install.md", 'a')
n = file.write(table_md)
file.close()