[SITE] Renew the web board presentation and the ESP32 web upload + [SYS] Security checks (#2277)
* Refactor GitHub Actions workflows for build, documentation, and linting - Consolidated build logic into reusable workflows (`task-build.yml` and `task-docs.yml`) to reduce duplication across multiple workflows. - Introduced `environments.json` to centralize the list of PlatformIO build environments, improving maintainability and clarity. - Updated `build.yml` and `build_and_docs_to_dev.yml` to utilize the new reusable workflows and environment definitions. - Enhanced `release.yml` to streamline the release process and integrate documentation generation. - Created reusable linting workflow (`task-lint.yml`) to standardize code formatting checks across the repository. - Simplified manual documentation workflow by leveraging the new reusable documentation workflow. - Improved artifact management and retention policies across workflows. - Updated dependencies and versions in workflows to ensure compatibility and performance. CI/CD pipeline agnostic of Workflow Engine and integrated on github actions - Implemented ci.sh for orchestrating the complete build pipeline. - Created ci_00_config.sh for centralized configuration of build scripts. - Created ci_build_firmware.sh for building firmware for specified PlatformIO environments. - Created ci_prepare_artifacts.sh for preparing firmware artifacts for upload or deployment. - Created ci_set_version.sh for updating version tags in firmware configuration files. - Created ci_build.sh to orchestrate the complete build pipeline. - Created ci_qa.sh for code linting and formatting checks using clang-format. - Created ci_site.sh for building and deploying VuePress documentation with version management. - Implemented checks for required tools and dependencies in the new scripts. - Improved internal scripts for better error handling and logging. UPDATE the web installer manifest generation and update documentation structure - Enhanced ci_list-env.sh to list environments from a JSON file. - Replaced common_wu.py and gen_wu.py scripts with new npm scripts for site generation and previewing on docsgen/gen_wu.js - Replaced generate_board_docs.py with docsgen/generated_board_docs.js - Added new npm scripts for integration of site generation on build phase. - Created preview_site.js to serve locally generated site over HTTPS with improved error handling. - Added new CI environments for CI builds in environments.json. - Deleted lint.yml as part of workflow cleanup. - Enhanced task-build.yml to include linting as a job and added support for specifying PlatformIO version. - Improved task-docs.yml to handle versioning more effectively and added clean option. Enhance documentation - ADD CLEAR Mark of development version of site - Updated README.md to include detailed workflow dependencies and relationships using mermaid diagrams. - Improved development.md with a quick checklist for contributors and clarified the code style guide. - Enhanced quick_start.md with tips for contributors and streamlined the workflow explanation. LINT FIX - Refined User_config.h for better formatting consistency. - Adjusted blufi.cpp and gatewayBT.cpp for improved code readability and consistency in formatting. - Updated gatewaySERIAL.cpp and mqttDiscovery.cpp to enhance logging error messages. - Improved sensorDS1820.cpp for better logging of device information. Add security scan workflows for vulnerability detection Add SBOM generation and upload to release workflow; update security scan summary handling Add shellcheck suppor + FIX shellcheck warning Enhance documentation for CI/CD scripts and workflows, adding details for security scanning and SBOM generation processes Fix formatting and alignment in BLE connection handling Reviewed the full web board presentation and the ESP32 web upload. The project uses a modern pattern where data is divided from the presentation layer. - Removed the `generate_board_docs` script. - Updated the `gen_wu` script in order to generate `boards-info.json`: the fail that containe all information about the configuration - Created and isolate the file `boards-info.js` to streamline the parsing of PlatformIO dependencies, modules, environments and improve the handling of library information. - Introduced vuepress component `BoardEnvironmentTable.vue` that render `boards-info.json` as UI card component - Introduced vuepress component `FlashEnvironmentSelector.vue` that render a selectred environment from `boards-info.json` and provide esp-web-upload feature on it - Introduced a new board page `board-selector.md` for improved firmware selection. - Updated `web-install.md` to enhance the firmware upload process, including a new board environment table. - Enhanced custom descriptions in `environments.ini` to include HTML links for better user guidance and board image link Add CC1101 initialization improvements and logging enhancements Add installation step for PlatformIO dependencies in documentation workflow Remove ci_set_version.sh script and associated versioning functionality * Fix comment provisined Fix PlatformIO version input reference in documentation workflow Remove outdated Squeezelite-ESP32 installer documentation
This commit is contained in:
Alessandro Staniscia authored and GitHub committed
1 parent
5f0966c2c1
commit
98481c5145
73 files changed
+5985
-2447
No files matched your search
@@ -0,0 +1,440 @@
|
||||
<template>
|
||||
<div class="board-environment-list">
|
||||
<div v-if="loading" class="custom-block tip">
|
||||
<p class="custom-block-title">
|
||||
<span class="loading-spinner" aria-label="Loading"></span>
|
||||
Loading supported environments...
|
||||
</p>
|
||||
</div>
|
||||
|
||||
<div v-if="error" class="custom-block danger">
|
||||
<p class="custom-block-title">Error</p>
|
||||
<p>{{ error }}</p>
|
||||
</div>
|
||||
|
||||
<div v-if="!loading && !error" class="boards-grid">
|
||||
<article
|
||||
v-for="board in boards"
|
||||
:key="board.environment"
|
||||
class="board-card"
|
||||
@click="openSelector(board.environment)">
|
||||
|
||||
<div class="board-card__image">
|
||||
<img
|
||||
:src="getBoardImageUrl(board)"
|
||||
:alt="board.environment"
|
||||
loading="lazy">
|
||||
</div>
|
||||
|
||||
<div class="board-card__content">
|
||||
<div class="board-card__header">
|
||||
<h3 class="board-card__title">
|
||||
<code>{{ board.environment }}</code>
|
||||
</h3>
|
||||
<span v-if="board.microcontroller" class="board-card__chip">
|
||||
{{ board.microcontroller }}
|
||||
</span>
|
||||
</div>
|
||||
|
||||
<p v-if="board.description" class="board-card__description" v-html="board.description">
|
||||
</p>
|
||||
|
||||
|
||||
<!-- Modules Section with expand/collapse -->
|
||||
<div v-if="Array.isArray(board.modules) && board.modules.length" class="board-card__libraries">
|
||||
<div class="modules-label-row">
|
||||
<span class="libraries-label">Modules:</span>
|
||||
<span
|
||||
v-if="board.modules.length > 2"
|
||||
class="expand-icon-btn"
|
||||
@click.stop="toggleModules(board.environment)"
|
||||
:title="expandedModules[board.environment] ? 'Hide' : 'Show all'">
|
||||
<svg :class="{rotated: expandedModules[board.environment]}" width="19" height="19" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polyline points="9 6 15 12 9 18"/></svg>
|
||||
</span>
|
||||
</div>
|
||||
<transition name="expand-fade">
|
||||
<div class="libraries-badges"
|
||||
:style="expandedModules[board.environment] ? '' : 'max-height: 2.2em; overflow: hidden;'">
|
||||
<span
|
||||
v-for="(mod, index) in board.modules"
|
||||
:key="index"
|
||||
class="lib-badge">
|
||||
{{ mod }}
|
||||
</span>
|
||||
</div>
|
||||
</transition>
|
||||
|
||||
</div>
|
||||
|
||||
<!-- Libraries Section with expand/collapse -->
|
||||
<div v-if="Array.isArray(board.libraries) && board.libraries.length" class="board-card__libraries">
|
||||
<div class="modules-label-row">
|
||||
<span class="libraries-label">Libraries:</span>
|
||||
<span
|
||||
v-if="board.libraries.length > 2"
|
||||
class="expand-icon-btn"
|
||||
@click.stop="toggleLibraries(board.environment)"
|
||||
:title="expandedLibraries[board.environment] ? 'Hide' : 'Show all'">
|
||||
<svg :class="{rotated: expandedLibraries[board.environment]}" width="19" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polyline points="9 6 15 12 9 18"/></svg>
|
||||
</span>
|
||||
|
||||
</div>
|
||||
<transition name="expand-fade">
|
||||
<div class="libraries-badges"
|
||||
:style="expandedLibraries[board.environment] ? '' : 'max-height: 2.2em; overflow: hidden;'">
|
||||
<span
|
||||
v-for="(lib, index) in board.libraries"
|
||||
:key="index"
|
||||
class="lib-badge">
|
||||
{{ lib }}
|
||||
</span>
|
||||
</div>
|
||||
</transition>
|
||||
|
||||
</div>
|
||||
|
||||
<div class="board-card__action">
|
||||
<span class="action-text">More info →</span>
|
||||
</div>
|
||||
</div>
|
||||
</article>
|
||||
</div>
|
||||
</div>
|
||||
</template>
|
||||
|
||||
<script>
|
||||
export default {
|
||||
name: 'BoardEnvironmentTable',
|
||||
props: {
|
||||
boardsUrl: {
|
||||
type: String,
|
||||
default: '/boards-info.json'
|
||||
},
|
||||
selectorPath: {
|
||||
type: String,
|
||||
default: '/upload/board-selector.html'
|
||||
}
|
||||
},
|
||||
data() {
|
||||
return {
|
||||
boards: [],
|
||||
loading: false,
|
||||
error: null,
|
||||
expandedModules: {},
|
||||
expandedLibraries: {}
|
||||
};
|
||||
},
|
||||
computed: {
|
||||
resolvedBoardsUrl() {
|
||||
return this.buildUrl(this.boardsUrl);
|
||||
},
|
||||
resolvedSelectorUrl() {
|
||||
return this.buildUrl(this.selectorPath);
|
||||
}
|
||||
},
|
||||
methods: {
|
||||
buildUrl(path) {
|
||||
const base = this.$site?.base || '/';
|
||||
const cleanBase = base.endsWith('/') ? base.slice(0, -1) : base;
|
||||
const cleanPath = path.startsWith('/') ? path : `/${path}`;
|
||||
return `${cleanBase}${cleanPath}`;
|
||||
},
|
||||
async loadBoards() {
|
||||
this.loading = true;
|
||||
this.error = null;
|
||||
try {
|
||||
const response = await fetch(this.resolvedBoardsUrl);
|
||||
if (!response.ok) {
|
||||
throw new Error(`HTTP ${response.status}: ${response.statusText}`);
|
||||
}
|
||||
const data = await response.json();
|
||||
if (!Array.isArray(data)) {
|
||||
throw new Error('boards-info.json must be an array');
|
||||
}
|
||||
this.boards = data
|
||||
.filter(board => board && typeof board.environment === 'string')
|
||||
.sort((a, b) => a.environment.localeCompare(b.environment));
|
||||
} catch (err) {
|
||||
console.error('Failed to load boards-info:', err);
|
||||
this.error = err.message || 'Unable to load board information';
|
||||
} finally {
|
||||
this.loading = false;
|
||||
}
|
||||
},
|
||||
toggleModules(env) {
|
||||
this.$set(this.expandedModules, env, !this.expandedModules[env]);
|
||||
},
|
||||
toggleLibraries(env) {
|
||||
this.$set(this.expandedLibraries, env, !this.expandedLibraries[env]);
|
||||
},
|
||||
openSelector(environment) {
|
||||
if (!environment) return;
|
||||
const url = `${this.resolvedSelectorUrl}?env=${encodeURIComponent(environment)}`;
|
||||
window.location.href = url;
|
||||
},
|
||||
getBoardImageUrl(board) {
|
||||
const customImg = board.customImg || board.CustomImg;
|
||||
if (customImg) {
|
||||
// If it's an absolute URL, use it as-is
|
||||
if (customImg.startsWith('http')) {
|
||||
return customImg;
|
||||
}
|
||||
// Otherwise, build the URL with site base
|
||||
return this.buildUrl(customImg);
|
||||
}
|
||||
return this.buildUrl('/img/microcontroller.gif');
|
||||
}
|
||||
},
|
||||
mounted() {
|
||||
this.loadBoards();
|
||||
}
|
||||
};
|
||||
</script>
|
||||
|
||||
<style scoped>
|
||||
.board-environment-list {
|
||||
margin: 2rem 0;
|
||||
}
|
||||
|
||||
/* Grid Layout */
|
||||
.boards-grid {
|
||||
display: grid;
|
||||
grid-template-columns: repeat(auto-fill, minmax(320px, 1fr));
|
||||
gap: 1.5rem;
|
||||
margin-top: 1.5rem;
|
||||
}
|
||||
|
||||
/* Card Design */
|
||||
.board-card {
|
||||
background: #ffffff;
|
||||
border: 1px solid var(--border-color, #eaecef);
|
||||
border-radius: 8px;
|
||||
overflow: hidden;
|
||||
cursor: pointer;
|
||||
transition: all 0.3s ease;
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
box-shadow: 0 2px 4px rgba(0, 0, 0, 0.05);
|
||||
}
|
||||
|
||||
.board-card:hover {
|
||||
transform: translateY(-4px);
|
||||
box-shadow: 0 8px 16px rgba(0, 0, 0, 0.1);
|
||||
border-color: var(--accent-color, #3eaf7c);
|
||||
}
|
||||
|
||||
/* Image Section */
|
||||
.board-card__image {
|
||||
background: var(--code-bg-color, #f6f8fa);
|
||||
padding: 1.5rem;
|
||||
display: flex;
|
||||
align-items: center;
|
||||
justify-content: center;
|
||||
min-height: 120px;
|
||||
border-bottom: 1px solid var(--border-color, #eaecef);
|
||||
}
|
||||
|
||||
.board-card__image img {
|
||||
max-width: 100px;
|
||||
max-height: 100px;
|
||||
object-fit: contain;
|
||||
}
|
||||
|
||||
/* Content Section */
|
||||
.board-card__content {
|
||||
padding: 1.25rem;
|
||||
flex: 1;
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
gap: 0.75rem;
|
||||
}
|
||||
|
||||
/* Header */
|
||||
.board-card__header {
|
||||
display: flex;
|
||||
justify-content: space-between;
|
||||
align-items: flex-start;
|
||||
gap: 0.75rem;
|
||||
margin-bottom: 0.25rem;
|
||||
}
|
||||
|
||||
.board-card__title {
|
||||
margin: 0;
|
||||
font-size: 1rem;
|
||||
font-weight: 600;
|
||||
line-height: 1.4;
|
||||
flex: 1;
|
||||
}
|
||||
|
||||
.board-card__title code {
|
||||
background: transparent;
|
||||
color: var(--accent-color, #3eaf7c);
|
||||
font-size: 0.9em;
|
||||
padding: 0;
|
||||
font-weight: 600;
|
||||
}
|
||||
|
||||
.board-card__chip {
|
||||
background: var(--code-bg-color, #f6f8fa);
|
||||
color: var(--text-color-secondary, #666);
|
||||
padding: 0.3rem 0.8rem;
|
||||
border-radius: 4px;
|
||||
font-size: 0.75rem;
|
||||
font-weight: 600;
|
||||
white-space: nowrap;
|
||||
flex-shrink: 0;
|
||||
border: 1px solid var(--border-color, #eaecef);
|
||||
}
|
||||
|
||||
/* Description */
|
||||
.board-card__description {
|
||||
margin: 0;
|
||||
font-size: 0.9rem;
|
||||
line-height: 1.5;
|
||||
color: var(--text-color-secondary, #666);
|
||||
|
||||
}
|
||||
|
||||
/* Libraries Section */
|
||||
.board-card__libraries {
|
||||
margin-top: 0.5rem;
|
||||
padding-top: 0.25rem;
|
||||
border-top: 1px solid var(--border-color, #eaecef);
|
||||
}
|
||||
|
||||
.modules-label-row {
|
||||
display: flex;
|
||||
align-items: center;
|
||||
gap: 0.2em;
|
||||
margin-bottom: 0.5rem;
|
||||
}
|
||||
.libraries-label {
|
||||
font-size: 0.8rem;
|
||||
font-weight: 600;
|
||||
color: var(--text-color-secondary, #666);
|
||||
display: inline-block;
|
||||
}
|
||||
|
||||
.libraries-badges {
|
||||
display: flex;
|
||||
flex-wrap: wrap;
|
||||
gap: 0.4rem;
|
||||
}
|
||||
|
||||
.lib-badge {
|
||||
display: inline-block;
|
||||
background: var(--code-bg-color, #f6f8fa);
|
||||
color: var(--text-color, #2c3e50);
|
||||
padding: 0.2rem 0.6rem;
|
||||
border-radius: 4px;
|
||||
font-size: 0.75rem;
|
||||
font-weight: 500;
|
||||
border: 1px solid var(--border-color, #eaecef);
|
||||
}
|
||||
|
||||
/* Action Footer */
|
||||
.board-card__action {
|
||||
padding-top: 0.75rem;
|
||||
margin-top: 0.5rem;
|
||||
border-top: 1px solid var(--border-color, #eaecef);
|
||||
}
|
||||
|
||||
.action-text {
|
||||
color: var(--accent-color, #3eaf7c);
|
||||
font-size: 0.85rem;
|
||||
font-weight: 600;
|
||||
display: flex;
|
||||
align-items: center;
|
||||
gap: 0.25rem;
|
||||
}
|
||||
|
||||
.board-card:hover .action-text {
|
||||
text-decoration: underline;
|
||||
}
|
||||
|
||||
/* Loading Spinner */
|
||||
.loading-spinner {
|
||||
display: inline-block;
|
||||
width: 16px;
|
||||
height: 16px;
|
||||
min-width: 16px;
|
||||
border: 2px solid #cfd8dc;
|
||||
border-top-color: var(--accent-color, #3eaf7c);
|
||||
border-radius: 50%;
|
||||
animation: spin 0.8s linear infinite;
|
||||
vertical-align: middle;
|
||||
margin-right: 0.5rem;
|
||||
}
|
||||
|
||||
@keyframes spin {
|
||||
to {
|
||||
transform: rotate(360deg);
|
||||
}
|
||||
}
|
||||
|
||||
/* Responsive */
|
||||
@media (max-width: 768px) {
|
||||
.boards-grid {
|
||||
grid-template-columns: 1fr;
|
||||
gap: 1rem;
|
||||
}
|
||||
|
||||
.board-card__image {
|
||||
min-height: 100px;
|
||||
padding: 1rem;
|
||||
}
|
||||
|
||||
.board-card__image img {
|
||||
max-width: 80px;
|
||||
max-height: 80px;
|
||||
}
|
||||
}
|
||||
|
||||
@media (max-width: 480px) {
|
||||
.board-card__header {
|
||||
flex-direction: column;
|
||||
align-items: flex-start;
|
||||
}
|
||||
|
||||
.board-card__chip {
|
||||
align-self: flex-start;
|
||||
}
|
||||
}
|
||||
/* Espansione animata per badge */
|
||||
.expand-fade-enter-active, .expand-fade-leave-active {
|
||||
transition: max-height 0.3s cubic-bezier(0.4, 0, 0.2, 1), opacity 0.3s;
|
||||
}
|
||||
.expand-fade-enter, .expand-fade-leave-to {
|
||||
opacity: 0;
|
||||
max-height: 0;
|
||||
}
|
||||
.expand-fade-enter-to, .expand-fade-leave {
|
||||
opacity: 1;
|
||||
max-height: 500px;
|
||||
}
|
||||
|
||||
.expand-icon-btn {
|
||||
display: inline-flex;
|
||||
align-items: center;
|
||||
justify-content: center;
|
||||
background: none;
|
||||
border: none;
|
||||
color: var(--accent-color, #3eaf7c);
|
||||
cursor: pointer;
|
||||
margin-top: 0.3em;
|
||||
margin-left: 0.2em;
|
||||
padding: 0.1em 0.2em;
|
||||
border-radius: 50%;
|
||||
transition: background 0.2s;
|
||||
}
|
||||
.expand-icon-btn:hover {
|
||||
background: rgba(62, 175, 124, 0.08);
|
||||
}
|
||||
.expand-icon-btn svg {
|
||||
transition: transform 0.25s cubic-bezier(0.4,0,0.2,1);
|
||||
vertical-align: middle;
|
||||
}
|
||||
.expand-icon-btn svg.rotated {
|
||||
transform: rotate(90deg);
|
||||
}
|
||||
</style>
|
||||
@@ -0,0 +1,686 @@
|
||||
<template>
|
||||
<div class="flash-selector">
|
||||
<!-- Loading State -->
|
||||
<div v-if="loading" class="custom-block tip">
|
||||
<p class="custom-block-title">
|
||||
<span class="loading-spinner"></span>
|
||||
Loading environments...
|
||||
</p>
|
||||
</div>
|
||||
|
||||
<!-- Error State -->
|
||||
<div v-if="error" class="custom-block danger">
|
||||
<p class="custom-block-title">Error</p>
|
||||
<p>{{ error }}</p>
|
||||
</div>
|
||||
|
||||
<!-- Board Details (when selected) -->
|
||||
<transition name="fade">
|
||||
<div v-if="currentEnvironment && !loading" class="board-details">
|
||||
|
||||
<!-- Hero Section - Clean and Focused -->
|
||||
<div class="board-hero">
|
||||
<div class="board-hero__content">
|
||||
<!-- Inline Board Switcher -->
|
||||
<h2>
|
||||
<div class="board-switcher">
|
||||
<label for="envSelect" class="switcher-label">Environment:</label>
|
||||
<div class="switcher-select-wrapper">
|
||||
<select
|
||||
id="envSelect"
|
||||
v-model="selectedEnvironment"
|
||||
class="switcher-select">
|
||||
<option
|
||||
v-for="env in environments"
|
||||
:key="env.environment"
|
||||
:value="env.environment">
|
||||
{{ env.environment }}
|
||||
</option>
|
||||
</select>
|
||||
<span class="switcher-icon">⚙️</span>
|
||||
</div>
|
||||
</div>
|
||||
</h2>
|
||||
|
||||
<div v-if="currentEnvironment.microcontroller" class="board-hero__meta">
|
||||
<span class="meta-label">MCU:</span>
|
||||
<span class="meta-value">{{ currentEnvironment.microcontroller }}</span>
|
||||
</div>
|
||||
|
||||
<p v-if="currentEnvironment.description" class="board-hero__description">
|
||||
<span class="meta-label">Description:</span> <span v-html="currentEnvironment.description"></span>
|
||||
</p>
|
||||
|
||||
<!-- Primary Action -->
|
||||
<div class="hero-action">
|
||||
<esp-web-install-button
|
||||
v-if="manifestUrl"
|
||||
:manifest="manifestUrl"
|
||||
aria-label="Flash firmware to device">
|
||||
</esp-web-install-button>
|
||||
<button v-else class="connect-button connect-button--disabled" disabled>
|
||||
CONNECT
|
||||
</button>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<!-- Image Optional -->
|
||||
<div v-if="boardImageUrl && !imageError" class="board-hero__image">
|
||||
<img
|
||||
:src="boardImageUrl"
|
||||
:alt="currentEnvironment.environment"
|
||||
loading="lazy"
|
||||
@error="handleImageError">
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<!-- Technical Details - Collapsible -->
|
||||
<details class="tech-details" open>
|
||||
<summary class="tech-details__summary">
|
||||
<span class="tech-details__icon">📋</span>
|
||||
<span class="tech-details__title">Technical Information</span>
|
||||
<span class="tech-details__toggle">▼</span>
|
||||
</summary>
|
||||
|
||||
<div class="tech-details__content">
|
||||
<div class="tech-grid">
|
||||
|
||||
<!-- Libraries -->
|
||||
<div v-if="currentEnvironment.libraries && currentEnvironment.libraries.length" class="tech-section">
|
||||
<h4 class="tech-section__title">Libraries</h4>
|
||||
<div class="tech-section__content">
|
||||
<div class="chip-group">
|
||||
<span v-for="(lib, index) in currentEnvironment.libraries" :key="index" class="chip">
|
||||
{{ lib }}
|
||||
</span>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<!-- Gateway Modules -->
|
||||
<div v-if="currentEnvironment.modules && currentEnvironment.modules.length" class="tech-section">
|
||||
<h4 class="tech-section__title">Gateway Modules</h4>
|
||||
<div class="tech-section__content">
|
||||
<div class="chip-group">
|
||||
<span v-for="(mod, index) in currentEnvironment.modules" :key="index" class="chip">
|
||||
{{ mod }}
|
||||
</span>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<!-- Hardware -->
|
||||
<div v-if="currentEnvironment.hardware" class="tech-section">
|
||||
<h4 class="tech-section__title">Hardware</h4>
|
||||
<div class="tech-section__content" >
|
||||
<span class="chip" v-html="currentEnvironment.hardware"></span>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
<!-- Partitions -->
|
||||
<div v-if="currentEnvironment.partitions" class="tech-section">
|
||||
<h4 class="tech-section__title">Partitions</h4>
|
||||
<div class="tech-section__content">
|
||||
<code class="code-inline">{{ currentEnvironment.partitions }}</code>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<!-- Build Options -->
|
||||
<div v-if="currentEnvironment.options" class="tech-section tech-section--full">
|
||||
<h4 class="tech-section__title">Build Options</h4>
|
||||
<div class="tech-section__content">
|
||||
<pre class="code-block">{{ formatOptions(currentEnvironment.options) }}</pre>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</details>
|
||||
</div>
|
||||
|
||||
</transition>
|
||||
<!-- Borad Detail not selected message -->
|
||||
<transition name="fade">
|
||||
<div v-if="!currentEnvironment && !loading && !error" class="custom-block info">
|
||||
<p class="custom-block-title">Need to select one environment...</p>
|
||||
</div>
|
||||
</transition>
|
||||
</div>
|
||||
</template>
|
||||
|
||||
<script>
|
||||
export default {
|
||||
name: 'FlashEnvironmentSelector',
|
||||
props: {
|
||||
boardsUrl: {
|
||||
type: String,
|
||||
default: '/boards-info.json'
|
||||
},
|
||||
firmwareBaseUrl: {
|
||||
type: String,
|
||||
default: '/firmware_build/'
|
||||
}
|
||||
},
|
||||
data() {
|
||||
return {
|
||||
environments: [],
|
||||
selectedEnvironment: '',
|
||||
loading: true,
|
||||
error: null,
|
||||
imageError: false
|
||||
};
|
||||
},
|
||||
computed: {
|
||||
currentEnvironment() {
|
||||
return this.environments.find(env => env.environment === this.selectedEnvironment);
|
||||
},
|
||||
resolvedBoardsUrl() {
|
||||
return this.buildUrl(this.boardsUrl);
|
||||
},
|
||||
resolvedFirmwareBaseUrl() {
|
||||
return this.buildUrl(this.firmwareBaseUrl);
|
||||
},
|
||||
manifestUrl() {
|
||||
if (!this.selectedEnvironment) return null;
|
||||
return `${this.resolvedFirmwareBaseUrl}${this.selectedEnvironment}.manifest.json`;
|
||||
},
|
||||
boardImageUrl() {
|
||||
if (!this.currentEnvironment) return null;
|
||||
const customImg = this.currentEnvironment.customImg || this.currentEnvironment.CustomImg;
|
||||
if (customImg && !this.imageError) {
|
||||
// If it's an absolute URL, use it as-is
|
||||
if (customImg.startsWith('http')) {
|
||||
return customImg;
|
||||
}
|
||||
// Otherwise, build the URL with site base
|
||||
return this.buildUrl(customImg);
|
||||
}
|
||||
return this.buildUrl('/img/microcontroller.gif');
|
||||
}
|
||||
},
|
||||
watch: {
|
||||
selectedEnvironment(newValue) {
|
||||
this.imageError = false;
|
||||
this.error = null;
|
||||
}
|
||||
},
|
||||
mounted() {
|
||||
const script = document.createElement('script');
|
||||
script.type="module";
|
||||
script.src="https://unpkg.com/esp-web-tools@10/dist/web/install-button.js?module";
|
||||
document.head.appendChild(script);
|
||||
this.loadEnvironments();
|
||||
},
|
||||
methods: {
|
||||
buildUrl(path) {
|
||||
// Concatenate this.$site.base with the provided path
|
||||
const base = this.$site?.base || '/';
|
||||
// Remove trailing slash from base and leading slash from path to avoid double slashes
|
||||
const cleanBase = base.endsWith('/') ? base.slice(0, -1) : base;
|
||||
const cleanPath = path.startsWith('/') ? path : `/${path}`;
|
||||
return `${cleanBase}${cleanPath}`;
|
||||
},
|
||||
getQueryParam(param) {
|
||||
// Extract query parameter from URL
|
||||
const params = new URLSearchParams(window.location.search);
|
||||
return params.get(param);
|
||||
},
|
||||
async loadEnvironments() {
|
||||
this.loading = true;
|
||||
this.error = null;
|
||||
|
||||
try {
|
||||
const response = await fetch(this.resolvedBoardsUrl);
|
||||
|
||||
if (!response.ok) {
|
||||
throw new Error(`HTTP ${response.status}: ${response.statusText}`);
|
||||
}
|
||||
|
||||
const data = await response.json();
|
||||
|
||||
if (!Array.isArray(data)) {
|
||||
throw new Error('Invalid data format: expected an array');
|
||||
}
|
||||
|
||||
const validEnvironments = data.filter(env =>
|
||||
env &&
|
||||
typeof env === 'object' &&
|
||||
env.environment &&
|
||||
typeof env.environment === 'string'
|
||||
);
|
||||
|
||||
if (validEnvironments.length === 0) {
|
||||
throw new Error('No valid environments found in data');
|
||||
}
|
||||
|
||||
this.environments = validEnvironments;
|
||||
|
||||
// Check for env parameter in query string and auto-select
|
||||
const envParam = this.getQueryParam('env');
|
||||
if (envParam) {
|
||||
const matchingEnv = validEnvironments.find(env => env.environment === envParam);
|
||||
if (matchingEnv) {
|
||||
this.selectedEnvironment = envParam;
|
||||
} else {
|
||||
console.warn(`Environment '${envParam}' not found in available environments`);
|
||||
}
|
||||
}
|
||||
} catch (error) {
|
||||
console.error('Failed to load environments:', error);
|
||||
this.error = error.message || 'Failed to load environments';
|
||||
} finally {
|
||||
this.loading = false;
|
||||
}
|
||||
},
|
||||
|
||||
formatOptions(optionsText) {
|
||||
if (!optionsText) return '';
|
||||
let optionsTextMap=[];
|
||||
if (typeof optionsText === 'string'){
|
||||
optionsTextMap = optionsText.split('\n')
|
||||
}else if (Array.isArray(optionsText)){
|
||||
optionsTextMap = optionsText;
|
||||
}
|
||||
|
||||
return optionsTextMap.map(line => line.trim())
|
||||
.filter(line => line.length > 0)
|
||||
.join('\n');
|
||||
},
|
||||
|
||||
handleImageError(event) {
|
||||
this.imageError = true;
|
||||
}
|
||||
}
|
||||
};
|
||||
</script>
|
||||
|
||||
<style scoped>
|
||||
/* Main Container */
|
||||
.flash-selector {
|
||||
max-width: 1200px;
|
||||
margin: 2rem auto;
|
||||
padding: 0 1rem;
|
||||
}
|
||||
|
||||
/* Board Details */
|
||||
cursor: pointer;
|
||||
/* Board Details Container */
|
||||
.board-details {
|
||||
margin-top: 2rem;
|
||||
}
|
||||
|
||||
/* Hero Section - Material Design 3 */
|
||||
.board-hero {
|
||||
display: grid;
|
||||
grid-template-columns: 1fr auto;
|
||||
gap: 24px;
|
||||
background: #ffffff;
|
||||
border-radius: 12px;
|
||||
padding: 32px;
|
||||
margin-bottom: 16px;
|
||||
box-shadow: 0 1px 2px 0 rgba(0, 0, 0, 0.05);
|
||||
border: 1px solid rgba(0, 0, 0, 0.08);
|
||||
}
|
||||
|
||||
.board-hero__content {
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
gap: 16px;
|
||||
}
|
||||
|
||||
.board-hero__title {
|
||||
margin: 0 0 8px 0;
|
||||
font-size: 1.75rem;
|
||||
font-weight: 400;
|
||||
color: var(--accent-color, #3eaf7c);
|
||||
font-family: 'Monaco', 'Courier New', monospace;
|
||||
line-height: 1.2;
|
||||
letter-spacing: -0.01em;
|
||||
}
|
||||
|
||||
/* Board Switcher - Material Chip Style */
|
||||
.board-switcher {
|
||||
display: flex;
|
||||
align-items: center;
|
||||
gap: 8px;
|
||||
margin: 0;
|
||||
}
|
||||
|
||||
.switcher-label {
|
||||
font-size: 0.75rem;
|
||||
text-transform: uppercase;
|
||||
font-weight: 500;
|
||||
letter-spacing: 0.1em;
|
||||
color: rgba(0, 0, 0, 0.6);
|
||||
}
|
||||
|
||||
.switcher-select-wrapper {
|
||||
position: relative;
|
||||
display: inline-flex;
|
||||
align-items: center;
|
||||
}
|
||||
|
||||
.switcher-select {
|
||||
appearance: none;
|
||||
background: rgba(0, 0, 0, 0.08);
|
||||
color: rgba(0, 0, 0, 0.87);
|
||||
border: none;
|
||||
padding: 6px 32px 6px 12px;
|
||||
border-radius: 16px;
|
||||
font-size: 0.875rem;
|
||||
font-weight: 500;
|
||||
font-family: 'Monaco', 'Courier New', monospace;
|
||||
cursor: pointer;
|
||||
transition: background 0.2s cubic-bezier(0.4, 0, 0.2, 1);
|
||||
height: 32px;
|
||||
min-width: 180px;
|
||||
}
|
||||
|
||||
.switcher-select:hover {
|
||||
background: rgba(0, 0, 0, 0.12);
|
||||
}
|
||||
|
||||
.switcher-select:focus {
|
||||
outline: 2px solid var(--accent-color, #3eaf7c);
|
||||
outline-offset: 2px;
|
||||
}
|
||||
|
||||
.switcher-icon {
|
||||
position: absolute;
|
||||
right: 8px;
|
||||
pointer-events: none;
|
||||
font-size: 1rem;
|
||||
opacity: 0.6;
|
||||
}
|
||||
|
||||
.board-hero__meta {
|
||||
display: flex;
|
||||
align-items: baseline;
|
||||
gap: 8px;
|
||||
margin: 0;
|
||||
}
|
||||
|
||||
.meta-label {
|
||||
font-size: 0.75rem;
|
||||
text-transform: uppercase;
|
||||
font-weight: 500;
|
||||
letter-spacing: 0.1em;
|
||||
color: rgba(0, 0, 0, 0.6);
|
||||
}
|
||||
|
||||
.meta-value {
|
||||
font-size: 0.875rem;
|
||||
font-weight: 500;
|
||||
color: rgba(0, 0, 0, 0.87);
|
||||
font-family: 'Monaco', 'Courier New', monospace;
|
||||
}
|
||||
|
||||
.board-hero__description {
|
||||
margin: 0;
|
||||
font-size: 1rem;
|
||||
line-height: 1.5;
|
||||
color: rgba(0, 0, 0, 0.87);
|
||||
max-width: 600px;
|
||||
}
|
||||
|
||||
.board-hero__image {
|
||||
display: flex;
|
||||
align-items: flex-start;
|
||||
justify-content: center;
|
||||
min-width: 180px;
|
||||
max-width: 200px;
|
||||
}
|
||||
|
||||
.board-hero__image img {
|
||||
max-width: 100%;
|
||||
max-height: 180px;
|
||||
object-fit: contain;
|
||||
}
|
||||
|
||||
/* Primary Action - Material Filled Button */
|
||||
.hero-action {
|
||||
margin-top: 8px;
|
||||
}
|
||||
|
||||
.connect-button {
|
||||
background: #1976d2;
|
||||
color: #ffffff;
|
||||
border: none;
|
||||
padding: 10px 24px;
|
||||
border-radius: 20px;
|
||||
font-size: 0.875rem;
|
||||
font-weight: 500;
|
||||
cursor: pointer;
|
||||
transition: box-shadow 0.28s cubic-bezier(0.4, 0, 0.2, 1);
|
||||
box-shadow: 0 1px 2px 0 rgba(0, 0, 0, 0.3), 0 1px 3px 1px rgba(0, 0, 0, 0.15);
|
||||
text-transform: uppercase;
|
||||
letter-spacing: 0.125em;
|
||||
height: 40px;
|
||||
min-width: 120px;
|
||||
}
|
||||
|
||||
.connect-button:hover:not(:disabled) {
|
||||
box-shadow: 0 1px 2px 0 rgba(0, 0, 0, 0.3), 0 2px 6px 2px rgba(0, 0, 0, 0.15);
|
||||
}
|
||||
|
||||
.connect-button:active:not(:disabled) {
|
||||
box-shadow: 0 1px 2px 0 rgba(0, 0, 0, 0.3), 0 1px 3px 1px rgba(0, 0, 0, 0.15);
|
||||
}
|
||||
|
||||
.connect-button--disabled {
|
||||
background: rgba(0, 0, 0, 0.12);
|
||||
color: rgba(0, 0, 0, 0.38);
|
||||
cursor: not-allowed;
|
||||
box-shadow: none;
|
||||
}
|
||||
|
||||
/* Technical Details - Material Surface */
|
||||
.tech-details {
|
||||
background: #ffffff;
|
||||
border-radius: 12px;
|
||||
overflow: hidden;
|
||||
box-shadow: 0 1px 2px 0 rgba(0, 0, 0, 0.05);
|
||||
border: 1px solid rgba(0, 0, 0, 0.08);
|
||||
}
|
||||
|
||||
.tech-details__summary {
|
||||
display: flex;
|
||||
align-items: center;
|
||||
gap: 12px;
|
||||
padding: 16px 24px;
|
||||
cursor: pointer;
|
||||
user-select: none;
|
||||
background: rgba(0, 0, 0, 0.02);
|
||||
transition: background 0.2s cubic-bezier(0.4, 0, 0.2, 1);
|
||||
list-style: none;
|
||||
}
|
||||
|
||||
.tech-details__summary::-webkit-details-marker {
|
||||
display: none;
|
||||
}
|
||||
|
||||
.tech-details__summary:hover {
|
||||
background: rgba(0, 0, 0, 0.04);
|
||||
}
|
||||
|
||||
.tech-details__icon {
|
||||
font-size: 1.25rem;
|
||||
opacity: 0.6;
|
||||
}
|
||||
|
||||
.tech-details__title {
|
||||
font-size: 1rem;
|
||||
font-weight: 500;
|
||||
color: rgba(0, 0, 0, 0.87);
|
||||
flex: 1;
|
||||
letter-spacing: 0.01em;
|
||||
}
|
||||
|
||||
.tech-details__toggle {
|
||||
font-size: 0.875rem;
|
||||
transition: transform 0.2s cubic-bezier(0.4, 0, 0.2, 1);
|
||||
opacity: 0.6;
|
||||
}
|
||||
|
||||
.tech-details[open] .tech-details__toggle {
|
||||
transform: rotate(180deg);
|
||||
}
|
||||
|
||||
.tech-details__content {
|
||||
padding: 24px;
|
||||
}
|
||||
|
||||
/* Tech Grid */
|
||||
.tech-grid {
|
||||
display: grid;
|
||||
grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
|
||||
gap: 24px;
|
||||
}
|
||||
|
||||
.tech-section {
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
gap: 12px;
|
||||
}
|
||||
|
||||
.tech-section--full {
|
||||
grid-column: 1 / -1;
|
||||
}
|
||||
|
||||
.tech-section__title {
|
||||
margin: 0;
|
||||
font-size: 0.75rem;
|
||||
text-transform: uppercase;
|
||||
font-weight: 500;
|
||||
letter-spacing: 0.1em;
|
||||
color: rgba(0, 0, 0, 0.6);
|
||||
}
|
||||
|
||||
.tech-section__content {
|
||||
font-size: 0.875rem;
|
||||
line-height: 1.5;
|
||||
color: rgba(0, 0, 0, 0.87);
|
||||
}
|
||||
|
||||
/* Chips - Material Design */
|
||||
.chip-group {
|
||||
display: flex;
|
||||
flex-wrap: wrap;
|
||||
gap: 8px;
|
||||
}
|
||||
|
||||
.chip {
|
||||
background: rgba(0, 0, 0, 0.08);
|
||||
color: rgba(0, 0, 0, 0.87);
|
||||
padding: 6px 12px;
|
||||
border-radius: 8px;
|
||||
font-size: 0.875rem;
|
||||
font-weight: 400;
|
||||
border: none;
|
||||
height: 32px;
|
||||
display: inline-flex;
|
||||
align-items: center;
|
||||
}
|
||||
|
||||
/* Code Styles - Material Surface */
|
||||
.code-inline {
|
||||
background: rgba(0, 0, 0, 0.05);
|
||||
padding: 2px 6px;
|
||||
border-radius: 4px;
|
||||
font-size: 0.875rem;
|
||||
font-family: 'Monaco', 'Courier New', monospace;
|
||||
color: rgba(0, 0, 0, 0.87);
|
||||
}
|
||||
|
||||
.code-block {
|
||||
background: rgba(0, 0, 0, 0.03);
|
||||
padding: 16px;
|
||||
border-radius: 8px;
|
||||
font-size: 0.8125rem;
|
||||
line-height: 1.5;
|
||||
overflow-x: auto;
|
||||
margin: 0;
|
||||
border: 1px solid rgba(0, 0, 0, 0.08);
|
||||
white-space: pre-wrap;
|
||||
word-break: break-word;
|
||||
font-family: 'Monaco', 'Courier New', monospace;
|
||||
color: rgba(0, 0, 0, 0.87);
|
||||
}
|
||||
|
||||
/* Loading Spinner */
|
||||
.loading-spinner {
|
||||
display: inline-block;
|
||||
width: 18px;
|
||||
height: 18px;
|
||||
border: 2px solid rgba(62, 175, 124, 0.3);
|
||||
border-top-color: var(--accent-color, #3eaf7c);
|
||||
border-radius: 50%;
|
||||
animation: spin 0.8s linear infinite;
|
||||
vertical-align: middle;
|
||||
margin-right: 0.5rem;
|
||||
}
|
||||
|
||||
@keyframes spin {
|
||||
to { transform: rotate(360deg); }
|
||||
}
|
||||
|
||||
/* Fade Transition */
|
||||
.fade-enter-active, .fade-leave-active {
|
||||
transition: opacity 0.3s ease;
|
||||
}
|
||||
|
||||
.fade-enter-from, .fade-leave-to {
|
||||
opacity: 0;
|
||||
}
|
||||
|
||||
/* Accessibility */
|
||||
.visually-hidden {
|
||||
position: absolute;
|
||||
width: 1px;
|
||||
height: 1px;
|
||||
margin: -1px;
|
||||
padding: 0;
|
||||
overflow: hidden;
|
||||
clip: rect(0, 0, 0, 0);
|
||||
border: 0;
|
||||
}
|
||||
|
||||
/* Responsive Design */
|
||||
@media (max-width: 968px) {
|
||||
.board-hero {
|
||||
grid-template-columns: 1fr;
|
||||
}
|
||||
|
||||
.board-hero__image {
|
||||
order: -1;
|
||||
max-width: 150px;
|
||||
margin: 0 auto;
|
||||
}
|
||||
|
||||
.tech-grid {
|
||||
grid-template-columns: 1fr;
|
||||
}
|
||||
}
|
||||
|
||||
@media (max-width: 640px) {
|
||||
.selector-card {
|
||||
padding: 1.5rem;
|
||||
}
|
||||
|
||||
.board-hero {
|
||||
padding: 1.5rem;
|
||||
}
|
||||
|
||||
.board-hero__title {
|
||||
font-size: 1.5rem;
|
||||
}
|
||||
|
||||
.connect-button {
|
||||
width: 100%;
|
||||
padding: 0.9rem 2rem;
|
||||
}
|
||||
}
|
||||
</style>
|
||||
+32
-14
@@ -1,20 +1,35 @@
|
||||
let meta = require('./defaults.json');
|
||||
try {
|
||||
meta_overload = require('./meta.json');
|
||||
meta = { ...meta, ...meta_overload };
|
||||
} catch (e) {
|
||||
console.warn('meta.json not found or not valid. Using default configuration.');
|
||||
}
|
||||
|
||||
|
||||
|
||||
const fs = require('fs');
|
||||
const path = require('path');
|
||||
const commonConfigPath = path.resolve(__dirname, 'public/commonConfig.js');
|
||||
if (!fs.existsSync(commonConfigPath)) {
|
||||
throw new Error(`commonConfig.js not found in ${commonConfigPath}.\nPlease download from https://www.theengs.io/commonConfig.js or create this file before you build the documentation.`);
|
||||
}
|
||||
const commonConfig = require('./public/commonConfig');
|
||||
|
||||
module.exports = {
|
||||
...commonConfig,
|
||||
title: 'Theengs OpenMQTTGateway version_tag',
|
||||
base: '/',
|
||||
title: `${meta.title} - ${meta.version}`,
|
||||
base: meta.url_prefix,
|
||||
dest: meta.dest, // default is generated/site
|
||||
description: 'One gateway, many technologies: MQTT gateway for ESP8266 or ESP32 with bidirectional 433mhz/315mhz/868mhz, Infrared communications, BLE, LoRa, beacons detection, mi flora / mi jia / LYWSD02/ Mi Scale compatibility, SMS & LORA.',
|
||||
head: [
|
||||
...commonConfig.head,
|
||||
['script', {type: 'module', src: 'https://unpkg.com/esp-web-tools@9.4.3/dist/web/install-button.js?module'}]
|
||||
],
|
||||
head: [...commonConfig.head],
|
||||
themeConfig: {
|
||||
repo: '1technophile/OpenMQTTGateway',
|
||||
docsDir: 'docs',
|
||||
...commonConfig.themeConfig,
|
||||
repo: meta.theme_config_repo,
|
||||
docsDir: 'docs',
|
||||
mode: meta.mode,
|
||||
sidebar: [
|
||||
['/','0 - What is it for 🏠'],
|
||||
['/', '0 - What is it for 🏠'],
|
||||
{
|
||||
title: '1 - Prerequisites🧭', // required
|
||||
//collapsable: true, // optional, defaults to true
|
||||
@@ -42,9 +57,10 @@ module.exports = {
|
||||
},
|
||||
{
|
||||
title: '3 - Upload ➡️', // required
|
||||
path: '/upload/',
|
||||
sidebarDepth: 1, // optional, defaults to 1
|
||||
children: [
|
||||
'upload/web-install',
|
||||
['upload/web-install', "(Option 1) Upload from the web"],
|
||||
'upload/binaries',
|
||||
'upload/builds',
|
||||
'upload/gitpod',
|
||||
@@ -86,23 +102,25 @@ module.exports = {
|
||||
},
|
||||
{
|
||||
title: '6 - Participate 💻', // required
|
||||
path: '/participate/',
|
||||
sidebarDepth: 1, // optional, defaults to 1
|
||||
children: [
|
||||
'participate/quick_start',
|
||||
'participate/support',
|
||||
'participate/development',
|
||||
'participate/adding-protocols',
|
||||
'participate/community',
|
||||
['https://github.com/1technophile/OpenMQTTGateway/blob/development/LICENSE.txt','License']
|
||||
[meta.url_license_file, 'License']
|
||||
]
|
||||
}
|
||||
]
|
||||
]
|
||||
},
|
||||
plugins: {
|
||||
'sitemap': {
|
||||
hostname: 'https://docs.openmqttgateway.com',
|
||||
hostname: meta.hostname,
|
||||
urls: [
|
||||
'https://decoder.theengs.io/devices/devices.html',
|
||||
'https://community.openmqttgateway.com/',
|
||||
meta.url_community_forum,
|
||||
'https://shop.theengs.io/',
|
||||
'https://shop.theengs.io/products/theengs-plug-smart-plug-ble-gateway-and-energy-consumption',
|
||||
'https://shop.theengs.io/products/theengs-bridge-esp32-ble-mqtt-gateway-with-ethernet-and-external-antenna',
|
||||
|
||||
@@ -0,0 +1,12 @@
|
||||
{
|
||||
"title": "Theengs OpenMQTTGateway",
|
||||
"version": "edge",
|
||||
"url_prefix": "/",
|
||||
"dest": "generated/site",
|
||||
"mode": "prod",
|
||||
"url_license_file": "https://github.com/1technophile/OpenMQTTGateway/blob/development/LICENSE.txt",
|
||||
"url_community_forum": "https://community.openmqttgateway.com",
|
||||
"hostname": "https://docs.openmqttgateway.com",
|
||||
"repo": "1technophile/OpenMQTTGateway",
|
||||
"theme_config_repo": "1technophile/OpenMQTTGateway"
|
||||
}
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 324 KiB |
@@ -1,3 +1,13 @@
|
||||
<ClientOnly>
|
||||
<span v-if="$site.themeConfig.mode === 'dev'">
|
||||
|
||||
::: warning Development Version
|
||||
This is the edge version of the documentation. It is under active development and may contain bugs, incomplete features, or breaking changes. Use it at your own risk.
|
||||
:::
|
||||
|
||||
</span>
|
||||
</ClientOnly>
|
||||
|
||||
OpenMQTTGateway aims to unify various technologies and protocols into a single firmware. This reduces the need for multiple physical bridges and streamlines diverse technologies under the widely-used [MQTT](http://mqtt.org/) protocol.
|
||||
|
||||
<div style="text-align: center;">
|
||||
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 20 KiB |
@@ -0,0 +1,46 @@
|
||||
# Participate in OpenMQTTGateway
|
||||
|
||||
OpenMQTTGateway is community-driven: every feature, bug fix, and doc improvement comes from contributors like you. Whether you want to add support for a new sensor, fix a bug, improve documentation, or just help others—there's a place for you here.
|
||||
|
||||
## Choose your path
|
||||
|
||||
### 🚀 New to the project? Start here
|
||||
[**Quick Start Guide**](./quick_start.md) walks you through setting up your development environment, building firmware, and previewing the docs. It covers PlatformIO, VS Code, terminal workflows, and troubleshooting. Perfect if you're new to ESP32/ESP8266 development or just want to get your hands dirty quickly.
|
||||
|
||||
**What you'll learn:** Installing tools · Building firmware · Flashing boards · Running tests · Working with the docs
|
||||
|
||||
---
|
||||
|
||||
### 💻 Ready to contribute code?
|
||||
[**Development Contributions**](./development.md) covers the contribution workflow: naming conventions, code quality checks, testing on multiple boards, and opening pull requests. This is your checklist before submitting code.
|
||||
|
||||
**What you'll find:** PR workflow · Naming rules (ZgatewayXXX, ZsensorYYY) · QA automation · DCO · CI/CD integration
|
||||
|
||||
---
|
||||
|
||||
### 🔌 Adding a new protocol or device?
|
||||
[**Adding Protocols**](./adding-protocols.md) explains how to integrate RF, IR, or BLE devices. Most protocol work happens upstream (RCSwitch, Pilight, IRRemoteESP8266, Theengs Decoder), and this guide shows you how to wire it into OMG.
|
||||
|
||||
**What you'll learn:** Upstream contribution · Protocol integration · Testing decoders · Payload validation
|
||||
|
||||
---
|
||||
|
||||
### 💬 Join the community
|
||||
[**Community Participation**](./community.md) is where you ask questions, share your projects, and help others. The forum is the first stop for feature requests, debugging help, and general IoT/home automation discussion.
|
||||
|
||||
**What you can do:** Ask questions · Share builds · Propose features · Help newcomers
|
||||
|
||||
---
|
||||
|
||||
### ❤️ Support the project
|
||||
[**Supporting the Project**](./support.md) lists all the ways you can help beyond code: answering forum questions, improving docs, purchasing Theengs products, sponsoring developers, or creating content about your OMG setup.
|
||||
|
||||
**How you can help:** Forum support · Documentation · Sponsorship · Content creation
|
||||
|
||||
---
|
||||
|
||||
::: tip Not sure where to start?
|
||||
- **First time here?** → [Quick Start](./quick_start.md)
|
||||
- **Have a fix or feature ready?** → [Development contributions](./development.md)
|
||||
- **Need help or want to discuss?** → [Community](./community.md)
|
||||
:::
|
||||
@@ -1,12 +1,22 @@
|
||||
# Adding protocols
|
||||
|
||||
Adding your device protocol to OpenMQTTGateway enables it to increase interoperability and to create new use cases with your device. Below you will find some guidance to do that.
|
||||
Adding your device protocol to OpenMQTTGateway increases interoperability and creates new use cases. Use the steps below to pick the right path and upstream your changes.
|
||||
|
||||
::: tip Before you open a PR
|
||||
Read the [Development contributions guide](./development.md) for naming rules, QA, and PR steps. It keeps your protocol addition reviewable.
|
||||
:::
|
||||
|
||||
## RF or IR
|
||||
For adding RF and IR protocols to OpenMQTTGateway the best way is to do a pull request to [RCSwitch](https://github.com/1technophile/rc-switch), [Pilight](https://github.com/pilight/pilight) for RF, and [IRRemoteESP8266](https://github.com/crankyoldgit/IRremoteESP8266) for IR.
|
||||
1. Implement or extend the protocol in the upstream libs first: [RCSwitch](https://github.com/1technophile/rc-switch) or [Pilight](https://github.com/pilight/pilight) for RF, and [IRRemoteESP8266](https://github.com/crankyoldgit/IRremoteESP8266) for IR.
|
||||
2. Once merged (or while your PR is pending), wire it in OMG as a new decoder/mapping.
|
||||
3. Add a short test sniff/build locally with the relevant environment (for example `esp32dev-all-test`).
|
||||
|
||||
## BLE
|
||||
For BLE message decoding OpenMQTTGateway uses the [Theengs Decoder](https://decoder.theengs.io/) library. New device decoder pull requests can be submitted directly to the [GitHub repository](https://github.com/theengs/decoder).
|
||||
1. For BLE message decoding, OpenMQTTGateway uses [Theengs Decoder](https://decoder.theengs.io/). Submit new device decoders directly to the [GitHub repository](https://github.com/theengs/decoder).
|
||||
2. After the decoder exists, ensure the device is reported correctly through OMG (advertising devices are supported without connection).
|
||||
3. Build locally for a BLE-enabled environment and validate the payload.
|
||||
|
||||
Currently we support the reading of advertizing BLE devices, advertizing means that the BLE device broadcasts regularly its sensor data without the need of a BLE connection.
|
||||
Notes:
|
||||
- We support reading **advertising** BLE devices (they broadcast regularly without a connection).
|
||||
- Keep payloads compact and follow existing JSON fields for consistency.
|
||||
|
||||
@@ -1,4 +1,9 @@
|
||||
# Community participation
|
||||
The first entry step for participating to OMG is sharing and discussing with the [community](https://community.openmqttgateway.com), by sharing your experiences and answering to other questions you are giving back what the others gave to you.
|
||||
The first entry step for participating to OMG is sharing and discussing with the [community](https://community.openmqttgateway.com). By sharing your experiences and answering questions you give back what others gave to you.
|
||||
|
||||
You can use the forum to ask questions, post answers, suggest features and discuss about home automation or Internet of things in a more general way.
|
||||
Use the forum to:
|
||||
- Ask questions about hardware, builds, MQTT, BLE/RF/IR, or docs.
|
||||
- Share projects, logs, and payload samples that help others.
|
||||
- Suggest features or confirm if something already exists.
|
||||
|
||||
When you have a change to contribute, follow the [Development contributions guide](./development.md) for the PR flow.
|
||||
@@ -1,30 +1,37 @@
|
||||
# Development contributions
|
||||
|
||||
We like pull requests from everyone. By participating in this project, you
|
||||
agree to follow the code of conduct below
|
||||
We like pull requests from everyone and ask you to follow the code of conduct below.
|
||||
|
||||
[code of conduct](https://github.com/1technophile/OpenMQTTGateway/blob/master/CODE_OF_CONDUCT.md)
|
||||
* [Code of conduct](https://github.com/1technophile/OpenMQTTGateway/blob/master/CODE_OF_CONDUCT.md)
|
||||
|
||||
[code style guide](https://google.github.io/styleguide/cppguide.html#Formatting)
|
||||
* [Code style guide](https://google.github.io/styleguide/cppguide.html#Formatting)
|
||||
|
||||
So as to format automatically 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".
|
||||
If you need a step-by-step install and build guide, read the [Quick Start to Develop OpenMQTTGateway](./quick_start.md). It explains the tools, PlatformIO, and docs workflow. Use this page as a fast checklist once you know the flow.
|
||||
|
||||
Fork the [development branch](https://github.com/1technophile/OpenMQTTGateway/tree/development), then clone the repo
|
||||
**Quick checklist**
|
||||
1. Fork the [development branch](https://github.com/1technophile/OpenMQTTGateway/tree/development) and clone the repo.
|
||||
2. Make your changes and follow the naming rules:
|
||||
* New gateway: `ZgatewayXXX` where `XXX` is the protocol name.
|
||||
* New sensor: `ZsensorYYY` where `YYY` is the sensor type.
|
||||
* New actuator: `ZactuatorZZZ` where `ZZZ` is the actuator type.
|
||||
3. Review your code and compile for ESP32 and ESP8266.
|
||||
4. Test on your hardware.
|
||||
5. Open a pull request, verify the GitHub Actions CI build, and request a review.
|
||||
|
||||
Make your modification,
|
||||
* If you want to add a new gateway, name it `ZgatewayXXX`, `XXX` replaced by your gateway communication type, can be more than three letters
|
||||
* If you want to add a new sensor, name it `ZsensorYYY`, `YYY` replaced by your sensor type, can be more than three letters
|
||||
* If you want to add a new actuator, name it `ZactuatorZZZ`, `ZZZ` replaced by your actuator type, can be more than three letters
|
||||
## Automated Testing and CI
|
||||
|
||||
Review your code, compile it for ESP32 and ESP8266
|
||||
Your pull request will be automatically tested by GitHub Actions. If you want to run the same checks locally before pushing, you can use the `ci.sh` script in the scripts folder.
|
||||
|
||||
Test it locally on your hardware config
|
||||
**Need help with the ci.sh commands?** See [section 5 in Quick Start](./quick_start.md#5-firmware-development-from-the-terminal-with-cish) for detailed examples of running QA checks and builds from the terminal.
|
||||
|
||||
Emit a pull request
|
||||
For more details on how CI works and available scripts, see the [CI documentation](https://github.com/1technophile/OpenMQTTGateway/blob/development/scripts) in the scripts folder.
|
||||
|
||||
Verify the GitHub Actions CI compilation results
|
||||
For a comprehensive overview of all GitHub Actions workflows used in this project, check the [Workflows README](https://github.com/1technophile/OpenMQTTGateway/tree/development/.github/workflows).
|
||||
|
||||
## Code Quality
|
||||
|
||||
To format your code automatically, add the "clang-Format" extension to VSCode, then right click in the file and choose "Format document".
|
||||
|
||||
Request for review
|
||||
|
||||
We may suggest some changes, improvements or alternatives.
|
||||
|
||||
|
||||
@@ -0,0 +1,840 @@
|
||||
---
|
||||
title: Quick Start to Develop OpenMQTTGateway
|
||||
permalink: /participate/quick_start.html
|
||||
sidebarDepth: 2
|
||||
lang: en-US
|
||||
---
|
||||
|
||||
# Quick Start to Develop OpenMQTTGateway
|
||||
|
||||
This document helps a new contributor. Maybe this is your first time with:
|
||||
|
||||
- Git
|
||||
- PlatformIO
|
||||
- ESP32 or ESP8266
|
||||
|
||||
It is normal to feel a bit lost at the beginning. This guide walks with you, step by step.
|
||||
|
||||
::: tip Already experienced?
|
||||
If you only need the contribution rules and PR flow, jump to [Development contributions](./development.md). For community help or non-code support, see [Community participation](./community.md) and [Supporting the project](./support.md).
|
||||
:::
|
||||
|
||||
|
||||
|
||||
In this document you will learn how to:
|
||||
|
||||
- Prepare the development environment on Windows or Linux.
|
||||
- Build and flash the firmware (ESP32 / ESP8266 and other boards).
|
||||
- Build and preview the documentation website in the docs folder.
|
||||
|
||||
At the end of each step you see a **Check**. Use it to confirm that the previous step is correct before you go to the next one. If a check fails, do not worry: read the step again, fix it, and try one more time.
|
||||
|
||||
|
||||
|
||||
## 1. Understand this project
|
||||
|
||||
OpenMQTTGateway is a firmware project. It runs on ESP32, ESP8266 and other boards. It connects many protocols (Bluetooth, RF, IR, LoRa, sensors) to MQTT.
|
||||
|
||||
The repository also contains the documentation website. The docs use VuePress and live in the docs folder.
|
||||
|
||||
Very simple view of the repository:
|
||||
|
||||
- main: C++ source code for the firmware.
|
||||
- lib: reusable libraries.
|
||||
- scripts: helper scripts for build, test, CI.
|
||||
- docs: documentation website.
|
||||
|
||||
You will mainly work on:
|
||||
|
||||
- Firmware code: files under main and sometimes lib.
|
||||
- Docs site: files under docs and docs/.vuepress.
|
||||
|
||||
**Check:** open the repository in a file explorer and confirm you see at least main, lib, scripts and docs folders. If not, read section 3 again.
|
||||
|
||||
|
||||
|
||||
## 2. Prepare your computer
|
||||
|
||||
You can use Windows or Linux. The steps are very similar. The examples use a terminal. On Windows you can use **Git Bash** or **WSL**; on Linux you can use your normal shell.
|
||||
|
||||
Not everybody needs to install the same tools. It depends on what you want to do:
|
||||
|
||||
- **Only firmware (with VS Code or terminal):** you mainly need Git, PlatformIO, VS Code (if you like GUI) and a bash shell.
|
||||
- **Only documentation website:** you mainly need Git, Node.js and npm.
|
||||
- **Both firmware and docs:** you need everything.
|
||||
|
||||
The next subsections explain this.
|
||||
|
||||
### 2.1 Common tools (for everyone)
|
||||
|
||||
Install these tools first. They are useful for **all** types of work:
|
||||
|
||||
- Git
|
||||
- Visual Studio Code (recommended, but you can also use another editor)
|
||||
- A bash shell
|
||||
- On Windows: Git Bash or WSL (Ubuntu is a good choice).
|
||||
|
||||
On Windows you can download:
|
||||
|
||||
- Git from the official site: <https://git-scm.com/downloads>
|
||||
- Visual Studio Code from <https://code.visualstudio.com/>
|
||||
- Git Bash comes with "Git for Windows".
|
||||
|
||||
On Linux you can install these with your package manager (for example apt on Ubuntu). For more help you can read the Git book: <https://git-scm.com/book/en/v2/Getting-Started-Installing-Git>.
|
||||
|
||||
**Check (common tools):** open a terminal (Git Bash, WSL, or Linux shell) and run:
|
||||
|
||||
```bash
|
||||
git --version
|
||||
```
|
||||
|
||||
If this command fails, install Git again and then close and reopen the terminal.
|
||||
|
||||
### 2.2 Tools for firmware development
|
||||
|
||||
For firmware builds you need **PlatformIO**. PlatformIO itself will install the right compiler and frameworks for your boards.
|
||||
|
||||
You have two main options:
|
||||
|
||||
1. Use **PlatformIO inside VS Code** (recommended for most users).
|
||||
2. Use **PlatformIO CLI in the terminal** (good for advanced or CI usage).
|
||||
|
||||
#### 2.2.1 PlatformIO inside VS Code (recommended)
|
||||
|
||||
If you only plan to build firmware from VS Code, you usually do **not** need to install Python or PlatformIO CLI manually. The PlatformIO extension will download what it needs.
|
||||
|
||||
- Just install VS Code and the PlatformIO extension (see section 2.3).
|
||||
- When you first open the project, PlatformIO will set up its own tools.
|
||||
|
||||
**Check:** after installing the extension and opening the project, the VS Code status bar shows something like "PlatformIO: Ready".
|
||||
|
||||
#### 2.2.2 PlatformIO command line (CLI) with Python (for terminal builds)
|
||||
|
||||
If you want to use the bash scripts (ci.sh, ci_build_firmware.sh, etc.) or build from a plain terminal, you need Python and PlatformIO CLI.
|
||||
|
||||
Install these extra tools:
|
||||
|
||||
- Python 3.10 or newer
|
||||
- PlatformIO CLI (pip package)
|
||||
|
||||
PlatformIO is the main build system for this project. We will use it from VS Code and from the terminal. If you want to read more, the official docs are here: <https://docs.platformio.org/>.
|
||||
|
||||
On Windows you can download Python from: <https://www.python.org/downloads/>
|
||||
|
||||
On Linux you can install Python with your package manager.
|
||||
|
||||
Then install PlatformIO CLI globally with Python:
|
||||
|
||||
```bash
|
||||
python3 -m pip install -U platformio
|
||||
```
|
||||
|
||||
**Check (firmware tools):**
|
||||
|
||||
```bash
|
||||
python3 --version
|
||||
platformio --version
|
||||
```
|
||||
|
||||
If you see version numbers, the install is good. If the platformio command is not found, check that Python added the scripts folder (for example ~/.local/bin on Linux) to your PATH, then open a new terminal and try again.
|
||||
|
||||
### 2.3 Tools for documentation website (Node.js and npm)
|
||||
::: warning Note
|
||||
This section is **only needed** if you want to **build or preview the site on your own computer**.
|
||||
:::
|
||||
|
||||
If you want to build or edit the **documentation website**, you also need Node.js and npm. You do **not** need these tools just to build firmware.
|
||||
|
||||
Install:
|
||||
|
||||
- Node.js 18 or newer
|
||||
- npm (usually comes with Node.js)
|
||||
|
||||
On Windows you can get Node.js from: <https://nodejs.org/en/download>
|
||||
|
||||
On Linux you can install Node.js with your package manager or by following the docs: <https://nodejs.org/en/download/package-manager>.
|
||||
|
||||
**Check (docs tools):**
|
||||
|
||||
```bash
|
||||
node --version
|
||||
npm --version
|
||||
```
|
||||
|
||||
If one of these commands fails, reinstall Node.js, close the terminal, and try again.
|
||||
|
||||
### 2.4 PlatformIO extension in Visual Studio Code
|
||||
Now add PlatformIO inside VS Code. You can also see pictures of these steps in many ESP32 + PlatformIO tutorials, for example on the PlatformIO site: <https://platformio.org/install/ide?install=vscode>.
|
||||
|
||||
Steps (based on common PlatformIO + VS Code ESP32 guides, adapted for this project):
|
||||
|
||||
1. Open Visual Studio Code.
|
||||
2. Click the Extensions icon on the left.
|
||||
3. In the search box, type "PlatformIO IDE".
|
||||
4. Click **Install** on the "PlatformIO IDE" extension.
|
||||
|
||||
When the install finishes, a new icon appears on the left sidebar. It looks like an ant or an alien head. This opens the PlatformIO view.
|
||||
|
||||
**Check:**
|
||||
|
||||
- In VS Code, you see the PlatformIO icon on the left.
|
||||
- If you click it, PlatformIO opens without errors.
|
||||
|
||||
If you do not see the icon, restart VS Code and wait a few seconds.
|
||||
|
||||
**Friendly tip:** the first install can take several minutes because PlatformIO downloads tools for many boards. It happens only once. You can get a coffee while it works.
|
||||
|
||||
|
||||
|
||||
## 3. Get the source code
|
||||
|
||||
Now download this repository to your computer from GitHub.
|
||||
|
||||
1. Open a terminal (Git Bash, WSL or Linux shell).
|
||||
2. Choose a parent folder where you want to keep your projects.
|
||||
3. Run:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/1technophile/OpenMQTTGateway.git
|
||||
cd OpenMQTTGateway
|
||||
```
|
||||
|
||||
**Check:**
|
||||
|
||||
- Run:
|
||||
|
||||
```bash
|
||||
git status
|
||||
```
|
||||
|
||||
- The output should say "On branch" and "nothing to commit".
|
||||
- In your file explorer or with:
|
||||
|
||||
```bash
|
||||
ls
|
||||
```
|
||||
|
||||
you should see main, lib, scripts, docs and other files.
|
||||
|
||||
If the clone fails, check your internet connection or a possible proxy. Then try again. If you are new to Git, the GitHub "Hello World" guide can also help: <https://docs.github.com/en/get-started/start-your-journey/hello-world>.
|
||||
|
||||
|
||||
|
||||
## 4. Firmware development with Visual Studio Code and PlatformIO
|
||||
|
||||
This section explains how to build and flash the firmware using Visual Studio Code with the PlatformIO extension.
|
||||
|
||||
If you know the classic Arduino IDE, you can think of PlatformIO as a more powerful alternative. It manages many boards, libraries, and environments for you. The official introduction is here: <https://docs.platformio.org/en/latest/what-is-platformio.html>.
|
||||
|
||||
You do **not** create a new PlatformIO project. This repository is already a PlatformIO project. You just open it.
|
||||
|
||||
### 4.1 Open the project in VS Code
|
||||
|
||||
1. Start Visual Studio Code.
|
||||
2. Click **File → Open Folder…**.
|
||||
3. Select the OpenMQTTGateway folder you cloned in section 3.
|
||||
4. Click **Open**.
|
||||
|
||||
VS Code will load the folder. PlatformIO will detect the platformio.ini file and start to prepare its toolchain (compiler, libraries, board support). You do not need to install these by hand.
|
||||
|
||||
**Check:**
|
||||
|
||||
- In the bottom status bar you see messages like "PlatformIO: Installing" and then "PlatformIO: Ready".
|
||||
- You can also open a terminal inside VS Code (View → Terminal) and run:
|
||||
|
||||
```bash
|
||||
pio --version
|
||||
```
|
||||
|
||||
You should see the PlatformIO version.
|
||||
|
||||
If PlatformIO stays stuck on "Installing" for a long time, close VS Code, reopen it and wait again. Check that your internet connection is working.
|
||||
|
||||
### 4.2 Look at the PlatformIO project structure
|
||||
|
||||
PlatformIO projects usually have folders like (you will see similar names in many tutorials):
|
||||
|
||||
- src: main source code.
|
||||
- lib: libraries.
|
||||
- include: headers.
|
||||
- platformio.ini: configuration for boards and environments.
|
||||
|
||||
In OpenMQTTGateway the structure is a bit different, because it is a large project:
|
||||
|
||||
- main: main C++ files for the firmware.
|
||||
- lib: libraries used by the firmware.
|
||||
- platformio.ini and environments.ini: list many PlatformIO environments.
|
||||
- test: tests for PlatformIO unit test framework.
|
||||
|
||||
**Check:** open platformio.ini in VS Code and scroll. You should see several [env:...] sections. This means PlatformIO understands the project.
|
||||
|
||||
If you want to know more about this file, see the PlatformIO docs about configuration: <https://docs.platformio.org/en/latest/projectconf/index.html>.
|
||||
|
||||
### 4.3 Choose a PlatformIO environment
|
||||
|
||||
An "environment" in PlatformIO is a build target. It defines the board, framework and options. You can think of it as a named profile for a specific device.
|
||||
|
||||
To select the environment for your board:
|
||||
|
||||
1. Press Ctrl+Shift+P (on macOS use Cmd+Shift+P).
|
||||
2. Type "PlatformIO: Switch Project Environment" and press Enter.
|
||||
3. A list of environments appears (for example esp32dev-all-test, theengs-bridge and many others).
|
||||
4. Choose an environment that matches your board. For a generic ESP32 DevKit you can start with **esp32dev-all-test**.
|
||||
|
||||
**Check:**
|
||||
|
||||
- Look at the bottom blue bar. You should see the selected environment name.
|
||||
|
||||
If you chose the wrong environment, repeat the steps and pick another one.
|
||||
|
||||
### 4.4 Build the firmware in VS Code
|
||||
|
||||
Now compile the firmware.
|
||||
|
||||
1. In VS Code, open the PlatformIO view (left sidebar icon).
|
||||
2. In the PlatformIO toolbar (bottom of the window), click the **check** (✓) icon. This runs the "Build" task.
|
||||
|
||||
PlatformIO now compiles the code for the selected environment. This can take several minutes the first time.
|
||||
|
||||
**Check:**
|
||||
|
||||
- In the Terminal panel, the build ends with the word "SUCCESS".
|
||||
- On disk, a file like:
|
||||
|
||||
```
|
||||
.pio/build/<your-env-name>/firmware.bin
|
||||
```
|
||||
|
||||
exists.
|
||||
|
||||
If the build fails, read the error at the end of the log. Take your time; errors are part of the normal developer life.
|
||||
|
||||
Common problems:
|
||||
|
||||
- Missing tools: check that platformio works from the terminal (section 2.2).
|
||||
- Wrong environment: try with esp32dev-all-test first.
|
||||
|
||||
Fix the problem, then run the build again.
|
||||
|
||||
### 4.5 Upload the firmware to the board
|
||||
|
||||
After a successful build you can flash the firmware (upload the program to the board).
|
||||
|
||||
1. Connect your ESP board to the computer with a good USB cable.
|
||||
2. In the PlatformIO toolbar click the **right arrow** (→) icon. This runs the "Upload" task.
|
||||
|
||||
PlatformIO selects a serial port automatically in many cases.
|
||||
|
||||
**Check:**
|
||||
|
||||
- The upload log ends with success, and no "Failed to connect" error.
|
||||
- The board reboots after upload.
|
||||
|
||||
If the upload fails:
|
||||
|
||||
- Check the USB cable (some cables are power-only and do not carry data).
|
||||
- On some boards you must press and hold the BOOT button during upload.
|
||||
- Make sure no other program is using the same serial port (for example another serial monitor).
|
||||
- You can set the serial port manually in platformio.ini with the upload_port option.
|
||||
|
||||
### 4.6 Open the Serial Monitor
|
||||
|
||||
The Serial Monitor lets you see log messages from the firmware.
|
||||
|
||||
1. In the PlatformIO toolbar click the **plug** icon. This opens the Serial Monitor.
|
||||
2. Set the baud rate to 115200 if it is not already set.
|
||||
|
||||
**Check:**
|
||||
|
||||
- After reset, you see text from the board, for example boot messages and MQTT logs.
|
||||
|
||||
If the text is unreadable, check that the baud rate matches the value in platformio.ini (monitor_speed). In this project the default is usually 115200.
|
||||
|
||||
If you want to learn more about Serial Monitor problems, the PlatformIO docs have a short page: <https://docs.platformio.org/en/latest/core/userguide/device/cmd_monitor.html>.
|
||||
|
||||
### 4.7 Run PlatformIO tests (optional)
|
||||
|
||||
You can run unit tests for the project.
|
||||
|
||||
1. Open a terminal inside VS Code (View → Terminal).
|
||||
2. In the project root, run:
|
||||
|
||||
```bash
|
||||
pio test -e test
|
||||
```
|
||||
|
||||
**Check:**
|
||||
|
||||
- The output ends with "SUCCESS". If tests fail, read which test failed and open the file under test to understand why.
|
||||
|
||||
|
||||
## 5. Firmware development from the terminal with ci.sh
|
||||
|
||||
You can also work only from the terminal. This is useful if you prefer command line, use remote development, or want to reproduce the same steps as the CI (Continuous Integration, the automatic build that runs on GitHub).
|
||||
|
||||
All helper scripts live in the scripts folder. The main entry point is:
|
||||
|
||||
- scripts/ci.sh
|
||||
|
||||
This script calls other scripts:
|
||||
|
||||
- scripts/ci_build.sh
|
||||
- scripts/ci_build_firmware.sh
|
||||
- scripts/ci_prepare_artifacts.sh
|
||||
- scripts/ci_site.sh
|
||||
- scripts/ci_qa.sh
|
||||
- scripts/ci_list-env.sh
|
||||
|
||||
The scripts are written for bash. On Windows always use **Git Bash** or **WSL** for them, not plain PowerShell or cmd.
|
||||
|
||||
If you are new to bash, a gentle introduction is here: <https://ubuntu.com/tutorials/command-line-for-beginners>.
|
||||
|
||||
### 5.1 Check that you are in the right place
|
||||
|
||||
1. Open a bash terminal.
|
||||
2. Go to your clone:
|
||||
|
||||
```bash
|
||||
cd path/to/OpenMQTTGateway
|
||||
```
|
||||
|
||||
**Check:** run:
|
||||
|
||||
```bash
|
||||
ls scripts main docs
|
||||
```
|
||||
|
||||
You should see these folders listed. If not, you are in the wrong directory.
|
||||
|
||||
### 5.2 List available firmware environments
|
||||
|
||||
You can ask the helper scripts which PlatformIO environments exist.
|
||||
|
||||
```bash
|
||||
./scripts/ci.sh list-env
|
||||
```
|
||||
|
||||
**Check:**
|
||||
|
||||
- The command prints many names in columns (for example esp32dev-all-test, theengs-bridge, rfbridge-direct, and so on).
|
||||
|
||||
If the command fails with "command not found" or similar, confirm that bash is used and that the file has execute permission (on Linux you may need chmod +x scripts/ci.sh).
|
||||
|
||||
### 5.3 Quick build of one firmware (simple mode)
|
||||
|
||||
Use ci.sh with the build command to build one firmware from the terminal.
|
||||
|
||||
Example for a development build on esp32dev-all-test:
|
||||
|
||||
```bash
|
||||
./scripts/ci.sh build esp32dev-all-test --mode dev --verbose
|
||||
```
|
||||
|
||||
What this does:
|
||||
|
||||
- Checks that Python, PlatformIO and git are installed.
|
||||
- Calls ci_build_firmware.sh to run platformio run -e esp32dev-all-test.
|
||||
- Optionally prepares artifacts if you add deployment options.
|
||||
|
||||
Useful flags:
|
||||
|
||||
- --mode dev or --mode prod: choose development or production mode. For local work, **dev** is usually enough.
|
||||
- --clean: remove old build files before building.
|
||||
- --verbose: show more logs from PlatformIO.
|
||||
|
||||
**Check:**
|
||||
|
||||
- The command ends with a "Build Summary" block and "Status: SUCCESS".
|
||||
- The folder .pio/build/esp32dev-all-test contains firmware.bin.
|
||||
|
||||
If the build fails, read the error line near the bottom. Fix missing tools (see section 2) or wrong environment name, then run the command again.
|
||||
|
||||
### 5.4 Use ci_build_firmware.sh directly (advanced control)
|
||||
|
||||
Sometimes you want to work closer to PlatformIO.
|
||||
|
||||
You can call scripts/ci_build.sh directly when you want more control or when you debug a CI issue:
|
||||
|
||||
```bash
|
||||
./scripts/ci_build.sh esp32dev-all-test --dev-ota --clean --verbose
|
||||
```
|
||||
|
||||
This script:
|
||||
|
||||
- Validates the environment name.
|
||||
- Sets environment variables for the build (for example OMG_VERSION, OTA flags).
|
||||
- Runs platformio run for the chosen environment.
|
||||
- Verifies that firmware.bin and other files exist.
|
||||
|
||||
**Check:**
|
||||
|
||||
- At the end you see a "Build Summary" for that environment.
|
||||
- The directory .pio/build/esp32dev-all-test contains .bin and .elf files.
|
||||
|
||||
If there are no artifacts, check that PlatformIO is installed and that the environment name matches one from ci_list-env.sh.
|
||||
|
||||
### 5.5 Prepare artifacts for sharing or flashing tools
|
||||
|
||||
After a successful build, you can create a clean set of files ready for release or for use with external flashing tools (for example esptool.py or web uploaders).
|
||||
|
||||
Use scripts/ci_prepare_artifacts.sh through ci_build.sh, or call it directly.
|
||||
|
||||
Example (after a build) with ci_build.sh wrapper:
|
||||
|
||||
```bash
|
||||
./scripts/ci_build.sh esp32dev-all-test --mode prod --deploy-ready
|
||||
```
|
||||
|
||||
Example direct call to ci_prepare_artifacts.sh:
|
||||
|
||||
```bash
|
||||
./scripts/ci_prepare_artifacts.sh esp32dev-all-test --clean
|
||||
```
|
||||
|
||||
This script:
|
||||
|
||||
- Copies firmware.bin, partitions.bin, bootloader.bin and other files from .pio/build/<env> into the output folder.
|
||||
- Renames them with the environment name, for example esp32dev-all-test-firmware.bin.
|
||||
- Creates archives for the libraries used by that environment.
|
||||
|
||||
**Check:**
|
||||
|
||||
- The folder generated/toDeploy (or your custom output) exists.
|
||||
- It contains files like <env>-firmware.bin and one or more *-libraries.tgz archives.
|
||||
|
||||
If the script says the build directory is missing, run a firmware build first (section 5.3 or 5.4).
|
||||
|
||||
### 5.6 Run QA checks from the terminal
|
||||
|
||||
Before you send a pull request, it is good to check the code style.
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
./scripts/ci.sh qa --check
|
||||
```
|
||||
|
||||
This uses scripts/ci_qa.sh to run clang-format checks on files under main by default.
|
||||
|
||||
**Check:**
|
||||
|
||||
- The summary says "Status: SUCCESS".
|
||||
|
||||
If there are formatting problems, you can auto-fix them:
|
||||
|
||||
```bash
|
||||
./scripts/ci.sh qa --fix
|
||||
```
|
||||
|
||||
After this, review the changes with git diff, then commit them.
|
||||
|
||||
### 5.7 Run the full pipeline (QA + firmware build + docs)
|
||||
|
||||
For a full local run, similar to CI, use:
|
||||
|
||||
```bash
|
||||
./scripts/ci.sh all esp32dev-all-test --mode prod
|
||||
```
|
||||
|
||||
This will:
|
||||
|
||||
- Run QA checks.
|
||||
- Build the firmware.
|
||||
- Build the documentation site in production mode (unless you add --no-site).
|
||||
|
||||
**Check:**
|
||||
|
||||
- At the end you see a "Complete Pipeline Summary" with "Status: SUCCESS".
|
||||
|
||||
If QA fails, fix style issues first. If the build fails, fix code or environment problems, then run again.
|
||||
|
||||
::: tip Next Steps
|
||||
Once your code builds successfully, check the [Development contributions guide](./development.md) for:
|
||||
- Code naming rules (ZgatewayXXX, ZsensorYYY, etc.)
|
||||
- Code style and quality requirements
|
||||
- How to open a pull request
|
||||
- Contributing workflow
|
||||
:::
|
||||
|
||||
|
||||
|
||||
## 6. Work on the documentation website (from the terminal)
|
||||
|
||||
The documentation website uses VuePress and Node.js. The site source is in the docs folder.
|
||||
|
||||
::: warning Note
|
||||
This section is **only needed** if you want to **build or preview the site on your own computer**.
|
||||
If you make a **very small change** in a markdown (.md) file (for example fix a typo or add one sentence), you can:
|
||||
|
||||
- Edit the file in VS Code.
|
||||
- Push your change and open a pull request.
|
||||
|
||||
In that case it is **not mandatory** to install Node.js, npm, or to run `./scripts/ci.sh site`. The CI on GitHub will build the site for you and show problems if there are any.
|
||||
|
||||
If you want to see your doc changes locally before you push (recommended for bigger edits), then follow the steps below.
|
||||
:::
|
||||
|
||||
### 6.1 Install Node dependencies
|
||||
|
||||
From the project root:
|
||||
|
||||
```bash
|
||||
cd OpenMQTTGateway # only if you are not already inside
|
||||
npm install
|
||||
```
|
||||
|
||||
This command reads package.json and installs all Node modules needed for the docs.
|
||||
|
||||
**Check:**
|
||||
|
||||
- The command finishes without error.
|
||||
- A node_modules folder exists in the project root.
|
||||
|
||||
If install is slow, your internet may be the reason. If it fails, try again later or clear the npm cache with:
|
||||
|
||||
```bash
|
||||
npm cache clean --force
|
||||
```
|
||||
|
||||
### 6.2 Build the docs site with ci.sh
|
||||
|
||||
If you want to check that everything still builds well after bigger doc changes, you can build the site locally.
|
||||
|
||||
The recommended way is:
|
||||
|
||||
```bash
|
||||
./scripts/ci.sh site --mode prod --url-prefix / --version 1.8.0
|
||||
```
|
||||
|
||||
Important options:
|
||||
|
||||
- `--mode dev` or `--mode prod`: development or production build (default: dev).
|
||||
- `--url-prefix PATH`: base URL path for links, e.g. `/` for root or `/dev/` for dev (default: /dev/).
|
||||
- `--version TAG`: version string written into docs/.vuepress/meta.json (default: edge).
|
||||
- `--preview`: if added, starts a local HTTPS preview server after build.
|
||||
- `--clean`: remove generated/site folder before build.
|
||||
- `--insecure-curl`: allow curl to skip TLS verification if needed.
|
||||
|
||||
The script (scripts/ci_site.sh) will:
|
||||
|
||||
- Check that node, npm and openssl are available.
|
||||
- Download a shared configuration file for the site.
|
||||
- Create docs/.vuepress/meta.json with site info.
|
||||
- Run npm run docs:build to build the site.
|
||||
|
||||
**Check:**
|
||||
|
||||
- The summary at the end says "Site Build Summary" and "Status: SUCCESS".
|
||||
- The folder docs/.vuepress/dist exists and contains HTML files.
|
||||
|
||||
If openssl or node is missing, go back to section 2 and install them.
|
||||
|
||||
### 6.3 Preview the docs site locally
|
||||
|
||||
To preview the site in your browser:
|
||||
|
||||
```bash
|
||||
./scripts/ci.sh site --mode dev --url-prefix /dev/ --version edge --preview
|
||||
```
|
||||
|
||||
The script will start a local HTTPS server.
|
||||
|
||||
**Check:**
|
||||
|
||||
- The log prints a line similar to: "Preview server running at https://localhost:8443/dev/".
|
||||
- Open that URL in your browser. You should see the OpenMQTTGateway documentation.
|
||||
|
||||
To stop the preview, go back to the terminal and press Ctrl+C.
|
||||
|
||||
### 6.4 Work on docs with plain npm commands
|
||||
|
||||
If you prefer not to use the ci.sh wrapper, you can work directly with npm and VuePress.
|
||||
|
||||
From the project root:
|
||||
|
||||
```bash
|
||||
npm run docs:dev
|
||||
```
|
||||
|
||||
This runs VuePress in development mode with hot reload. When you change a .md file under docs, the browser reloads.
|
||||
|
||||
For a production build:
|
||||
|
||||
```bash
|
||||
npm run docs:build
|
||||
```
|
||||
|
||||
**Check:**
|
||||
|
||||
- For docs:dev, the terminal prints a local URL like http://localhost:8080. Open it in the browser and see the docs.
|
||||
- For docs:build, the folder docs/.vuepress/dist is created.
|
||||
|
||||
If docs:build fails with an OpenSSL error on new Node versions, set:
|
||||
|
||||
```bash
|
||||
export NODE_OPTIONS="--openssl-legacy-provider"
|
||||
```
|
||||
|
||||
then run the command again. The ci_site.sh script already does this for you.
|
||||
|
||||
### 6.5 Where to edit docs
|
||||
|
||||
- All documentation pages are markdown (.md) files under docs.
|
||||
- This file itself is in docs/participate/quick_start.md.
|
||||
|
||||
To add or edit docs:
|
||||
|
||||
1. Open the docs folder in VS Code.
|
||||
2. Change or create markdown files.
|
||||
3. Run npm run docs:dev to check how the page looks.
|
||||
|
||||
**Check:** after a change and a page refresh, your new text appears on the site.
|
||||
|
||||
|
||||
|
||||
## 7. Typical workflows for contributors
|
||||
|
||||
This section gives some example "day to day" flows.
|
||||
|
||||
### 7.1 Quick firmware change with VS Code
|
||||
|
||||
1. Open the project folder in VS Code.
|
||||
2. Choose the right environment (section 4.3).
|
||||
3. Edit code in main or lib.
|
||||
4. Build (section 4.4).
|
||||
5. Upload (section 4.5).
|
||||
6. Watch logs in Serial Monitor (section 4.6).
|
||||
|
||||
**Check:** your change has the expected effect on the real device.
|
||||
|
||||
### 7.2 Firmware change using terminal only
|
||||
|
||||
1. Open a bash terminal.
|
||||
2. Go to the project root.
|
||||
3. Build firmware with:
|
||||
|
||||
```bash
|
||||
./scripts/ci.sh build <env> --mode dev --verbose
|
||||
```
|
||||
|
||||
4. Flash firmware using PlatformIO CLI or another flash tool with the generated firmware file.
|
||||
|
||||
**Check:** the device boots with your new firmware and behaves as expected.
|
||||
|
||||
### 7.3 Change documentation and preview
|
||||
|
||||
1. Edit markdown files under docs.
|
||||
2. In a terminal, run npm run docs:dev or ./scripts/ci.sh site --mode dev --preview.
|
||||
3. Open the local URL in your browser.
|
||||
|
||||
**Check:** your text appears on the page and looks correct.
|
||||
|
||||
|
||||
|
||||
## 8. Troubleshooting
|
||||
|
||||
This list gives quick help for common problems.
|
||||
|
||||
- **Problem:** platformio command not found.
|
||||
- **Fix:** install it with python3 -m pip install -U platformio and open a new terminal.
|
||||
|
||||
- **Problem:** Build fails for all environments.
|
||||
- **Fix:** run ./scripts/ci.sh list-env to confirm you use a valid env. Check that you did not change platformio.ini or environments.ini in a wrong way.
|
||||
|
||||
- **Problem:** Build fails with missing libraries.
|
||||
- **Fix:** run a clean build (add --clean). If you work only with VS Code, press the trash icon or use the clean target from PlatformIO.
|
||||
|
||||
- **Problem:** Upload fails ("Failed to connect to ESP32").
|
||||
- **Fix:** choose the right serial port, check the cable, try holding BOOT during upload.
|
||||
|
||||
- **Problem:** Serial output is garbled.
|
||||
- **Fix:** set Serial Monitor baud to 115200 and confirm monitor_speed in platformio.ini is the same.
|
||||
|
||||
- **Problem:** npm install is very slow or fails.
|
||||
- **Fix:** check your internet connection. If needed run npm cache clean --force and try again.
|
||||
|
||||
- **Problem:** Site build fails with an OpenSSL error.
|
||||
- **Fix:** export NODE_OPTIONS="--openssl-legacy-provider" before running npm run docs:build, or use ./scripts/ci.sh site which already sets this.
|
||||
|
||||
If you still have problems after these steps, you can open an issue on the project GitHub page. Include:
|
||||
|
||||
- Your operating system (Windows or Linux, version).
|
||||
- What you tried to do.
|
||||
- The exact command you ran.
|
||||
- The error message from the end of the log.
|
||||
|
||||
This information helps maintainers reproduce and fix the problem.
|
||||
|
||||
|
||||
|
||||
## 9. Glossary (simple words)
|
||||
|
||||
This glossary explains some words used in this guide.
|
||||
|
||||
- **Firmware**: the program that runs inside your ESP32 or ESP8266 board.
|
||||
- **Repository (repo)**: the project folder stored on GitHub and on your computer.
|
||||
- **Commit**: a saved set of changes in Git, with a message.
|
||||
- **Branch**: a line of development in Git, like a separate copy where you work.
|
||||
- **Pull Request (PR)**: a request to merge your branch into the main project on GitHub.
|
||||
- **Environment (env)**: a PlatformIO configuration for a specific board and options.
|
||||
- **CI (Continuous Integration)**: automatic scripts that build and test the project on every change.
|
||||
- **Serial Monitor**: a window that shows text messages sent by your board over USB.
|
||||
- **MQTT**: a lightweight network protocol used to send messages between devices.
|
||||
- **VuePress**: a static site generator used to build this documentation.
|
||||
|
||||
If any word in this guide is not clear, you can search it on the web or ask in the project community. Many people had the same question before you.
|
||||
|
||||
|
||||
|
||||
## 10. External links and further reading
|
||||
|
||||
Here is a list of useful links related to tools used in this project:
|
||||
|
||||
- **OpenMQTTGateway project**: <https://github.com/1technophile/OpenMQTTGateway>
|
||||
- **PlatformIO main site**: <https://platformio.org/>
|
||||
- **PlatformIO installation for VS Code**: <https://platformio.org/install/ide?install=vscode>
|
||||
- **PlatformIO documentation**: <https://docs.platformio.org/>
|
||||
- **Visual Studio Code documentation**: <https://code.visualstudio.com/docs>
|
||||
- **Git official site**: <https://git-scm.com/>
|
||||
- **Pro Git book (free)**: <https://git-scm.com/book/en/v2>
|
||||
- **GitHub getting started**: <https://docs.github.com/en/get-started>
|
||||
- **Node.js documentation**: <https://nodejs.org/en/docs>
|
||||
- **npm documentation**: <https://docs.npmjs.com/>
|
||||
- **VuePress documentation** (v1, similar to what this project uses): <https://v1.vuepress.vuejs.org/>
|
||||
- **MQTT introduction (HiveMQ)**: <https://www.hivemq.com/mqtt-essentials/>
|
||||
|
||||
You do **not** need to read all of them now. Keep this list as a bookmark and come back when you are curious or stuck.
|
||||
|
||||
|
||||
## 11. Final words and friendly advice
|
||||
|
||||
Contributing to an open source project is a journey. The first steps (install tools, learn Git, learn PlatformIO) can feel slow. This is normal.
|
||||
|
||||
Some final tips:
|
||||
|
||||
- Change one thing at a time and test often.
|
||||
- Keep your changes small; they are easier to review.
|
||||
- Write clear commit messages.
|
||||
- When something breaks, read the last 10–20 lines of the log first.
|
||||
- Do not be afraid to ask questions; everyone started as a beginner.
|
||||
|
||||
You are now ready to work on both firmware and documentation for OpenMQTTGateway. Take your time, follow the checks after each step, and you will build confidence with the toolchain and the project. Step by step, you will become faster and more comfortable.
|
||||
|
||||
|
||||
If you are new and want to "play" a bit before you change real logic, here are some safe exercises:
|
||||
|
||||
1. **Practice the build chain only.**
|
||||
- Clone the repo, open it in VS Code, select `esp32dev-all-test`, build, and upload to your board.
|
||||
- Check that you can see logs in the Serial Monitor.
|
||||
2. **Make a tiny log change.**
|
||||
- Find a `LOG` or `Serial` message in a gateway or sensor file under `main`.
|
||||
- Change the text slightly (for example add a word), rebuild, upload, and verify you see the new message.
|
||||
3. **Edit a small doc page.**
|
||||
- Fix a typo or add one sentence of clarification in a markdown file under `docs`.
|
||||
- Run `./scripts/ci.sh site --mode prod --preview` and confirm your change appears in the browser.
|
||||
4. **Run QA locally.**
|
||||
- Run `./scripts/ci.sh qa --check`. If there are issues, run `./scripts/ci.sh qa --fix` and see how files are changed.
|
||||
5. **Open a small PR.**
|
||||
- For example, only the doc change or a very small code improvement. This lets you learn the review process without much stress.
|
||||
|
||||
These small steps build confidence. After that you can move to bigger things: adding new sensors, improving MQTT payloads, or extending the web documentation.
|
||||
@@ -1,15 +1,22 @@
|
||||
# Supporting the project
|
||||
|
||||
If you like the project and/or used it please consider supporting it! It can be done in different ways:
|
||||
* Purchase the [Theengs mobile application](https://app.theengs.io)
|
||||
* Purchase the [Theengs plug](https://shop.theengs.io)
|
||||
* Helping other users in the [community](https://community.openmqttgateway.com)
|
||||
* [Contribute](development) to the [code](https://github.com/1technophile/OpenMQTTGateway) or the [documentation](https://docs.openmqttgateway.com)
|
||||
* 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 [developers](https://github.com/1technophile/OpenMQTTGateway/graphs/contributors)
|
||||
* Make a video or a blog article about what you have done with [OpenMQTTGateway](https://docs.openmqttgateway.com) and share it.
|
||||
If you like the project, you can help in different ways. Choose what fits you best.
|
||||
|
||||
Support open-source development through sponsorship and gain exclusive access to our private forum. Your questions, issues, and feature requests will receive priority attention, plus you'll gain insider access to our roadmap.
|
||||
## Give time and knowledge
|
||||
- Help other users in the [community](https://community.openmqttgateway.com).
|
||||
- Share logs, payload samples, or how-to posts that unblock others.
|
||||
|
||||
## Contribute code or docs
|
||||
- Follow the [Development contributions guide](./development.md) to open a PR.
|
||||
- Improve docs or examples if you spot unclear steps.
|
||||
|
||||
## Financial support
|
||||
- Purchase the [Theengs mobile application](https://app.theengs.io) or the [Theengs plug](https://shop.theengs.io).
|
||||
- Buy devices or parts via the [compatible web site](https://compatible.openmqttgateway.com) (affiliate links help the project).
|
||||
- Sponsor the project [developers](https://github.com/1technophile/OpenMQTTGateway/graphs/contributors).
|
||||
- Make a video or blog article about what you built with [OpenMQTTGateway](https://docs.openmqttgateway.com) and share it.
|
||||
|
||||
Support open-source development through sponsorship and gain exclusive access to our private forum. Your questions, issues, and feature requests receive priority attention, plus you'll see the roadmap early.
|
||||
|
||||
<div style="text-align: center;">
|
||||
<iframe src="https://github.com/sponsors/theengs/button" title="Sponsor Theengs" height="32" width="228" style="border: 0; border-radius: 6px;"></iframe>
|
||||
|
||||
@@ -1,3 +1,7 @@
|
||||
---
|
||||
pageClass: table-generated-page
|
||||
---
|
||||
|
||||
# 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 ESP8266 to an ESP32.
|
||||
@@ -43,4 +47,10 @@ The plug is available in North America only, other regions are planned.
|
||||
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 table below present those (auto-generated)
|
||||
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. Use the table below to explore the latest environments.
|
||||
|
||||
<BoardEnvironmentTable
|
||||
boardsUrl="/boards-info.json"
|
||||
selectorPath="/upload/board-selector.html"
|
||||
/>
|
||||
|
||||
@@ -1,4 +0,0 @@
|
||||
# Ignore everything in this directory
|
||||
*
|
||||
# Except this file
|
||||
!.gitignore
|
||||
+18
-2
@@ -51,8 +51,22 @@ With SRX882S receiver connect the CS pin to 3.3V
|
||||
|ESP8266|D2/**D3**/D1/D8|**RX**/D2|D5|**3V3**|D7|D6|D8|GND
|
||||
|ESP32|**D27**|D12|D18|**3V3**|D23|D19|D5|GND
|
||||
|
||||
To use the CC1101 module, `ZradioCC1101` must be uncomment in the `User_config.h` or added to the `build_flags`.
|
||||
More information about the [CC1101 wiring](https://github.com/LSatan/SmartRC-CC1101-Driver-Lib#wiring). ( Please note that with OMG we are recommending CC1101 GDO2 to be connected to ESP32 D27 and GDO0 to be connected to D12, this is different than the LSatan diagram. This is due to the ESP32 using D2 as part of the boot process. )
|
||||
To use the CC1101 module, `ZradioCC1101` must be uncomment in the `User_config.h` or added to the `build_flags`.
|
||||
|
||||
More information about the [CC1101 wiring](https://github.com/LSatan/SmartRC-CC1101-Driver-Lib#wiring).
|
||||
|
||||
|
||||
:::tip Please note that with OMG we are recommending CC1101 GDO2 to be connected to ESP32 D27 and GDO0 to be connected to D12, this is different than the LSatan diagram. This is due to the ESP32 using D2 as part of the boot process.
|
||||
|
||||
If you want to use custom SPI pins for the CC1101 module, you can define the following variables in your `User_config.h` or as `build_flags` in `platformio.ini`:
|
||||
- `RF_CC1101_SCK`: SPI clock pin (SCK)
|
||||
- `RF_CC1101_SCK`: SPI clock pin (SCK)
|
||||
- `RF_CC1101_MISO`: SPI MISO pin (Master In Slave Out)
|
||||
- `RF_CC1101_MOSI`: SPI MOSI pin (Master Out Slave In)
|
||||
- `RF_CC1101_CS`: SPI chip select pin (CSN)
|
||||
|
||||
When **all** these variables are defined, OpenMQTTGateway will use your custom pinout for the CC1101 connection. This is useful if your board does not use the default pins or if you want to avoid conflicts with other devices.
|
||||
:::
|
||||
|
||||
## ESP32 Hardware setup
|
||||
|
||||
@@ -73,3 +87,5 @@ The RF processing can be achieved after the modification by either RF, RF2 or Pi
|
||||
|
||||
## WIFI RF GATEWAY Hardware setup
|
||||
This board doesn't require any hardware modifications.
|
||||
|
||||
|
||||
@@ -0,0 +1,79 @@
|
||||
# Upload
|
||||
|
||||
OpenMQTTGateway provides several installation approaches suited for different use cases. The quickest path uses pre-built binaries that work with standard configurations. For custom parameters or specific gateway module combinations, you can build firmware using your development environment. Alternatively, you can flash devices directly from your web browser without installing any software.
|
||||
|
||||
<p align="center">
|
||||
<img src="../img/upload.png" alt="Firmware upload process">
|
||||
</p>
|
||||
|
||||
## Choosing Your Upload Method
|
||||
|
||||
### Web-Based Installation
|
||||
|
||||
The [web installation](web-install.md) method represents the easiest way to get started with OpenMQTTGateway. You can flash your device directly from your browser without downloading files or installing development tools. This method works on Windows, macOS, and Linux with Chrome, Edge, or Opera browsers.
|
||||
|
||||
The web installer displays available environments for different boards and gateway configurations. Select your board type, connect via USB, and click the connect button. The installer handles everything automatically, including erasing old firmware and writing the new one. The web installer uses [ESP Web Tools](https://esphome.github.io/esp-web-tools/) technology to communicate directly with your ESP device.
|
||||
|
||||
### Ready-to-Go Binary Installation
|
||||
|
||||
[Downloading and installing pre-built binaries](binaries.md) offers control over the flashing process using desktop tools. Download the binary files for your board from the [GitHub releases page](https://github.com/1technophile/OpenMQTTGateway/releases).
|
||||
|
||||
For ESP32 devices, you need the firmware binary, bootloader, and boot application partition files written to specific memory addresses. Windows users can use the ESP32 Flash Download Tool from Espressif. On Linux and macOS, the esptool.py command-line utility provides a straightforward upload method.
|
||||
|
||||
This method works well for standard configurations without modifying source code. After flashing, you can still configure WiFi, MQTT broker settings, and basic parameters through the configuration portal.
|
||||
|
||||
### Custom Build and Upload
|
||||
|
||||
[Building from source](builds.md) becomes necessary when you need specific pin assignments, custom MQTT topics, or particular gateway module combinations not available in pre-built binaries.
|
||||
|
||||
[PlatformIO](https://platformio.org/) provides the recommended build environment. After downloading the [source code from GitHub](https://github.com/1technophile/OpenMQTTGateway), you will find a `platformio.ini` file defining build environments for various hardware combinations.
|
||||
|
||||
The configuration system uses a layering approach where default values from [`User_config.h`](https://github.com/1technophile/OpenMQTTGateway/blob/development/main/User_config.h) and [`config_XX.h`](https://github.com/1technophile/OpenMQTTGateway/tree/development/main) files can be overridden by build flags in `platformio.ini` or `environments.ini`. You can embed WiFi credentials and MQTT settings at build time for automatic connection on first boot.
|
||||
|
||||
### Browser-Based Building with Gitpod
|
||||
|
||||
For those who want to build custom firmware without setting up a local development environment, [Gitpod](gitpod.md) offers a cloud-based solution. By clicking on the [Gitpod link](https://gitpod.io#https://github.com/1technophile/OpenMQTTGateway/tree/development), you get a complete development environment running in your browser with PlatformIO already installed and configured.
|
||||
|
||||
After the automatic initial build completes, modify the environment configuration by editing `environments.ini` and run build commands in the browser terminal. Download the generated firmware files and flash them using the binary installation method.
|
||||
|
||||
## Configuring Network and MQTT Settings
|
||||
|
||||
After flashing firmware, configure network connectivity and MQTT broker settings using either runtime or build-time approaches.
|
||||
|
||||
### Runtime Configuration Portal
|
||||
|
||||
When you power on a freshly flashed device, it creates a WiFi access point named OpenMQTTGateway or starting with OMG_. You can find detailed information about the [configuration portal here](portal.md).
|
||||
|
||||
Connecting to this access point opens a portal where you configure your WiFi network, MQTT broker details, and optional security settings including TLS encryption and certificates. For devices with Ethernet, access the portal through the LAN IP address and configure WiFi as fallback connectivity.
|
||||
|
||||
The portal accepts broker IP addresses or hostnames with mDNS support like homeassistant.local. Set a gateway password to protect future configuration changes, OTA updates, and web interface access.
|
||||
|
||||
### Build-Time Configuration
|
||||
|
||||
Alternatively, embed network and MQTT settings directly in firmware during the build process. Set parameters in `User_config.h` or add them as build flags in your PlatformIO environment definition. Store sensitive information in a separate `_env.ini` file excluded from version control.
|
||||
|
||||
## Advanced Configuration Options
|
||||
|
||||
Beyond basic connectivity, OpenMQTTGateway supports several [advanced features](advanced-configuration.md) that enhance security and integration capabilities.
|
||||
|
||||
### Secure MQTT Connections
|
||||
|
||||
For deployments over the internet or public networks, enable TLS encryption to secure communication between the gateway and MQTT broker. Configure your broker with a valid certificate and obtain the Certificate Authority certificate. The gateway can verify server identity against this certificate or connect with encryption without validation.
|
||||
|
||||
Provide the CA certificate at build time in `default_server_cert.h` or paste it into the configuration portal. The gateway supports both self-signed certificates and those from public certificate authorities.
|
||||
|
||||
### Home Assistant Auto-Discovery
|
||||
|
||||
When you use [Home Assistant](https://www.home-assistant.io/) as your home automation platform, OpenMQTTGateway automatically creates device entries and sensors through Home Assistant's MQTT discovery protocol, enabled by default in all standard builds.
|
||||
|
||||
Enable discovery in your Home Assistant MQTT integration settings and create a dedicated MQTT user. The gateway registers itself as a device and creates sensor entities automatically, appearing in Configuration → Devices section.
|
||||
|
||||
### Topic Customization
|
||||
|
||||
The gateway publishes messages to MQTT topics following the format `home/OpenMQTTGateway/GATEWAYtoMQTT`. Enable the `valueAsATopic` feature to append received values to the topic path, making topic-based filtering easier and avoiding warnings in certain controllers.
|
||||
|
||||
## Next Steps
|
||||
|
||||
After successfully uploading firmware and configuring your gateway, you can proceed to configure specific gateway modules for [RF](../setitup/rf.md), [IR](../setitup/ir.md), [Bluetooth](../setitup/ble.md), [LoRa](../setitup/lora.md), or other protocols you want to use. Each module has configuration options adjustable through MQTT commands or the web interface without rebuilding firmware.
|
||||
|
||||
The [troubleshooting section](troubleshoot.md) covers common issues, but if you encounter problems not addressed here, the [OpenMQTTGateway community forum](https://community.openmqttgateway.com) provides an active place to ask questions and share solutions with other users.
|
||||
@@ -0,0 +1,10 @@
|
||||
---
|
||||
pageClass: table-generated-page
|
||||
---
|
||||
|
||||
|
||||
<FlashEnvironmentSelector
|
||||
boardsUrl="/boards-info.json"
|
||||
firmwareBaseUrl="firmware_build/" />
|
||||
|
||||
|
||||
@@ -2,7 +2,14 @@
|
||||
pageClass: table-generated-page
|
||||
---
|
||||
|
||||
# (Option 1) Upload from the web
|
||||
## Select your firmware
|
||||
To upload firmware to your ESP device directly from this page, first connect your ESP device to a USB port on your computer. Then, choose the appropriate firmware from the available options. Next, click the **Connect** button and select the USB port where your ESP is plugged in. Wait for the upload process to finish. After the upload completes, you can set up your [WiFi and MQTT credentials](portal.md).
|
||||
|
||||
<BoardEnvironmentTable
|
||||
boardsUrl="/boards-info.json"
|
||||
selectorPath="/upload/board-selector.html"
|
||||
/>
|
||||
|
||||
|
||||
::: 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/).
|
||||
@@ -15,16 +22,8 @@ The correct driver to then select in the popup of this web install is
|
||||
`/dev/cu.wchusbserialXXXXXXXXXXX`
|
||||
:::
|
||||
|
||||
You can upload the firmware to your ESP device directly from here.
|
||||
1. Plug in your ESP to a USB port.
|
||||
2. Select the firmware in the box below.
|
||||
3. Click the install button and choose the port that the ESP is connected to.
|
||||
4. Wait until the process is complete.
|
||||
5. Once completed you can configure your [WiFi and MQTT credentials](portal.md)
|
||||
|
||||
<web-uploader/>
|
||||
|
||||
Upload powered by [ESP Web Tools](https://esphome.github.io/esp-web-tools/)
|
||||
|
||||
## Using OpenMQTTGateway ?
|
||||
Support open-source development through sponsorship and gain exclusive access to our private forum. Your questions, issues, and feature requests will receive priority attention, plus you'll gain insider access to our roadmap.
|
||||
@@ -33,5 +32,4 @@ Support open-source development through sponsorship and gain exclusive access to
|
||||
<iframe src="https://github.com/sponsors/theengs/button" title="Sponsor Theengs" height="32" width="228" style="border: 0; border-radius: 6px;"></iframe>
|
||||
</div>
|
||||
|
||||
## Environments characteristics
|
||||
The auto-generated table below describes the libraries and the modules of each board configuration.
|
||||
|
||||
Reference in new issue
Block a user