diff --git a/.github/workflows/docs-checks.yml b/.github/workflows/docs-checks.yml new file mode 100644 index 0000000000..3dd4d4c4fd --- /dev/null +++ b/.github/workflows/docs-checks.yml @@ -0,0 +1,50 @@ +name: docs-checks +# Runs on every pull request into dev or main. Each step reports problems as +# annotations on the PR's changed lines; later steps still run if an earlier +# one fails, so one run shows everything. Scripts live in tools/docs-checks/. +on: + pull_request: + branches: + - dev + - main + workflow_dispatch: +permissions: + contents: read +jobs: + checks: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v7 + with: + fetch-depth: 0 + - uses: actions/setup-python@v7 + with: + python-version: 3.x + - run: pip install -r requirements.txt + - run: sudo apt-get update && sudo apt-get install -y libimage-exiftool-perl + - name: List changed files + id: changed + run: | + base="${{ github.event.pull_request.base.sha }}" + if [ -n "$base" ]; then + git diff --name-only --diff-filter=AM "$base"...HEAD > changed.txt + else + : > changed.txt + fi + echo "Changed files:"; cat changed.txt + - name: Markdown (front matter, headings, alt text, includes) + run: python tools/docs-checks/check_markdown.py docs + - name: No secrets in text + if: always() + run: python tools/docs-checks/check_secrets.py docs + - name: Images (GPS location data, file size) + if: always() + run: CHANGED_FILES="$(cat changed.txt)" python tools/docs-checks/check_images.py docs/assets + - name: Build the site + if: always() + env: + DISABLE_MKDOCS_2_WARNING: "true" + run: mkdocs build -d site + - name: Links, anchors, and image alt text in the built site + if: always() + run: python tools/docs-checks/check_links.py site docs diff --git a/AGENTS.md b/AGENTS.md index 5dbeef18b1..71ec1488b3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -39,6 +39,10 @@ Read the full style guide, but these are the ones worth checking twice: - **Apollo addons** (hardware modules) and **Home Assistant apps** (formerly add-ons) are different things and not interchangeable. - **ESPHome** is the only correct casing. +- Firmware install links go to the product's page on the Apollo + installer (`https://install.apolloautomation.com/#/air-1`), not the + old `apolloautomation.github.io/AIR-1/` installers. See + [Flashing firmware](STYLE_GUIDE.md#flashing-firmware). - **No em dashes** anywhere in user-facing copy. - Second person, imperative voice for action copy. Wrap numbered steps with framing copy (what the reader unlocks, what success looks like). @@ -58,6 +62,14 @@ Read the full style guide, but these are the ones worth checking twice: buttons, edit the snippet file, never the include line on a page. See [Community CTA on starter-kit pages](STYLE_GUIDE.md#11-community-cta-on-starter-kit-pages). +## Automated PR checks + +Every pull request runs `tools/docs-checks/` (see its README): front +matter, heading levels, alt text, snippet includes, secrets, GPS data in +photos, and links and anchors on the built site. Run them locally before +opening a PR. They can't read text inside images, so check screenshots +and recordings for passwords, API keys, and personal details by eye. + ## Keep the style guide current If you notice a recurring pattern that should be standardized but isn't diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0f6c819eaf..4d5adcd1ce 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -43,6 +43,7 @@ mkdocs serve 4. Verify the build is clean (no broken links or missing-plugin errors) via `mkdocs build`. 5. Fill out the PR template and link any related issues. 6. Use PR title format: `: ` (types: `docs`, `fix`, `feat`, `chore`) +7. Automated checks run on every PR: front matter, heading levels, image alt text, snippet includes, secrets in text, GPS location data in photos, and broken links or anchors on the built site. Problems appear as comments on the changed lines. See [tools/docs-checks/README.md](tools/docs-checks/README.md) for what each check looks for, how to fix it, and how to run them locally. ## Key files and folders diff --git a/STYLE_GUIDE.md b/STYLE_GUIDE.md index c33229b607..1bd2a15f00 100644 --- a/STYLE_GUIDE.md +++ b/STYLE_GUIDE.md @@ -158,6 +158,20 @@ When introducing the broader project, prefer **ESPHome ecosystem** over context (for example, when the audience may not recognize the term). Avoid **burn** and **load**. +Link firmware installs to the product's own page on the Apollo +installer, `https://install.apolloautomation.com/#/` (for +example `#/air-1` or `#/r-pro-1`), not the older +`apolloautomation.github.io//` installers. Name buttons the way +the installer shows them: the variant (**USB Power**, **Battery Power**, +**WiFi**, **Ethernet**, **Smart (Wi-Fi)**, **Basic (No Wi-Fi)**) and +then **Connect & Install**, and the firmware option in the next dialog +exactly as listed (for example **Install ApolloAutomation.AIR-1**). The +B models use their parent's page with **Battery Power** (TEMP-1B on +`#/temp-1`, PLT-1B on `#/plt-1`). Keep the older installer link only +where the Apollo installer has no equivalent: the TEMP Pro-1, and TEMP-1 +Revision 1 firmware. The LED-1 uses the official WLED installer at +`https://install.wled.me/`. + --- ## 6. Voice and structure @@ -415,8 +429,16 @@ shrinks PNGs, so compress video before committing it. - **Phone recordings** (portrait) take `class="phone-media"`, which caps them at phone width and centers them. The class lives in `docs/stylesheets/extra.css`; never size media inline. -- **Trim personal details** (names, email addresses, home names, - notifications) out of every recording before it's published. +- **Trim personal details and secrets** (names, email addresses, home + names, notifications, Wi-Fi passwords, API keys) out of every recording + and screenshot before it's published. Compile and install logs print + the device's full configuration, so end a recording before the log + scrolls through it, and check YAML editor shots for an `api: + encryption: key:` value. +- **Strip location data from photos.** Phones save the GPS location in + every photo. Remove it before committing: + `exiftool -gps:all= -overwrite_original docs/assets/`. The PR + checks fail on any photo that still has it. - **Compress** with H.264, no audio track, and fast start, scaled to 540px wide for clips and 720px for a full phone walkthrough. Aim for under 1 MB per clip and a few MB for a walkthrough: diff --git a/docs/assets/installer-air-1.png b/docs/assets/installer-air-1.png new file mode 100644 index 0000000000..7e695692e1 Binary files /dev/null and b/docs/assets/installer-air-1.png differ diff --git a/docs/assets/installer-btn-1.png b/docs/assets/installer-btn-1.png new file mode 100644 index 0000000000..23d87e3bb9 Binary files /dev/null and b/docs/assets/installer-btn-1.png differ diff --git a/docs/assets/installer-h-1.png b/docs/assets/installer-h-1.png new file mode 100644 index 0000000000..45bd3c8a34 Binary files /dev/null and b/docs/assets/installer-h-1.png differ diff --git a/docs/assets/installer-h-2-smart.png b/docs/assets/installer-h-2-smart.png new file mode 100644 index 0000000000..6a897b03d8 Binary files /dev/null and b/docs/assets/installer-h-2-smart.png differ diff --git a/docs/assets/installer-msr-1.png b/docs/assets/installer-msr-1.png new file mode 100644 index 0000000000..5ce1a6e411 Binary files /dev/null and b/docs/assets/installer-msr-1.png differ diff --git a/docs/assets/installer-msr-2.png b/docs/assets/installer-msr-2.png new file mode 100644 index 0000000000..269497002b Binary files /dev/null and b/docs/assets/installer-msr-2.png differ diff --git a/docs/assets/installer-mtr-1.png b/docs/assets/installer-mtr-1.png new file mode 100644 index 0000000000..6f812ff0df Binary files /dev/null and b/docs/assets/installer-mtr-1.png differ diff --git a/docs/assets/installer-plt-1-battery-power.png b/docs/assets/installer-plt-1-battery-power.png new file mode 100644 index 0000000000..f4539c5e4b Binary files /dev/null and b/docs/assets/installer-plt-1-battery-power.png differ diff --git a/docs/assets/installer-plt-1-usb-power.png b/docs/assets/installer-plt-1-usb-power.png new file mode 100644 index 0000000000..0b23d214f8 Binary files /dev/null and b/docs/assets/installer-plt-1-usb-power.png differ diff --git a/docs/assets/installer-pump-1.png b/docs/assets/installer-pump-1.png new file mode 100644 index 0000000000..2b6ee3e744 Binary files /dev/null and b/docs/assets/installer-pump-1.png differ diff --git a/docs/assets/installer-r-pro-1-wifi.png b/docs/assets/installer-r-pro-1-wifi.png new file mode 100644 index 0000000000..fc8b9667a4 Binary files /dev/null and b/docs/assets/installer-r-pro-1-wifi.png differ diff --git a/docs/assets/installer-temp-1-battery-power.png b/docs/assets/installer-temp-1-battery-power.png new file mode 100644 index 0000000000..b5352a498c Binary files /dev/null and b/docs/assets/installer-temp-1-battery-power.png differ diff --git a/docs/assets/installer-temp-1-usb-power.png b/docs/assets/installer-temp-1-usb-power.png new file mode 100644 index 0000000000..b3e850e5fe Binary files /dev/null and b/docs/assets/installer-temp-1-usb-power.png differ diff --git a/docs/assets/plt-boot-mode-pic-4.jpg b/docs/assets/plt-boot-mode-pic-4.jpg index 374adafee5..8c4fc7ec58 100755 Binary files a/docs/assets/plt-boot-mode-pic-4.jpg and b/docs/assets/plt-boot-mode-pic-4.jpg differ diff --git a/docs/assets/r-pro-1-toggle-on-ld2450-bluetooth.png b/docs/assets/r-pro-1-toggle-on-ld2450-bluetooth.png new file mode 100644 index 0000000000..cc2c2e9ca7 Binary files /dev/null and b/docs/assets/r-pro-1-toggle-on-ld2450-bluetooth.png differ diff --git a/docs/assets/radar-gates-colored.png b/docs/assets/radar-gates-colored.png index f93ceb69f4..74c7f040da 100644 Binary files a/docs/assets/radar-gates-colored.png and b/docs/assets/radar-gates-colored.png differ diff --git a/docs/assets/wled-installer-plain.png b/docs/assets/wled-installer-plain.png new file mode 100644 index 0000000000..b7dbc0b69d Binary files /dev/null and b/docs/assets/wled-installer-plain.png differ diff --git a/docs/homey/products/air1/additonal-info/air-quality-sensor-comparison.md b/docs/homey/products/air1/additonal-info/air-quality-sensor-comparison.md index 723981735c..4c00d0ea76 100755 --- a/docs/homey/products/air1/additonal-info/air-quality-sensor-comparison.md +++ b/docs/homey/products/air1/additonal-info/air-quality-sensor-comparison.md @@ -1,4 +1,5 @@ --- +title: Air quality sensor comparison description: "A technical comparison of air quality sensors used with the AIR-1, including performance, accuracy, and specifications." --- --8<-- "products/air1/additional-info/air-quality-sensor-comparison.md:5:" \ No newline at end of file diff --git a/docs/homey/products/air1/troubleshooting/air1-code.md b/docs/homey/products/air1/troubleshooting/air1-code.md index 6bd23309b8..e077871d8f 100755 --- a/docs/homey/products/air1/troubleshooting/air1-code.md +++ b/docs/homey/products/air1/troubleshooting/air1-code.md @@ -15,11 +15,11 @@ If your Apollo AIR-1 becomes unresponsive and you've exhausted the other trouble ![AIR-1 case with a tool pointing at the boot button left of the USB-C port](/assets/air-1-boot-button.jpg) -2\. Go to the Apollo AIR-1 Installer page. +2\. Go to the Apollo AIR-1 installer page. -3\. Click the big **Connect** button. +3\. Click **Connect & Install**. -![Apollo AIR-1 Installer web page with the Connect button highlighted](/assets/air-1-reflash-pic-1.png) +![AIR-1 page of the Apollo installer with the Connect & Install button outlined in red](/assets/installer-air-1.png) 4\. Select the open COM port, then click **Connect**. diff --git a/docs/homey/products/general/calibrating-and-updating/zone-configuration/zones-ha.md b/docs/homey/products/general/calibrating-and-updating/zone-configuration/zones-ha.md index dfec82d7bc..0b9665ef5a 100644 --- a/docs/homey/products/general/calibrating-and-updating/zone-configuration/zones-ha.md +++ b/docs/homey/products/general/calibrating-and-updating/zone-configuration/zones-ha.md @@ -1,4 +1,5 @@ --- +title: MTR-1 Home Assistant zone configuration description: "Tutorial for MTR-1 Home Assistant Zone Configuration." --- --8<-- "products/mtr1/setup/zones-ha.md:5:" diff --git a/docs/homey/products/general/calibrating-and-updating/zone-configuration/zones-hlk.md b/docs/homey/products/general/calibrating-and-updating/zone-configuration/zones-hlk.md index b9bb9a130b..2234b6c7c1 100644 --- a/docs/homey/products/general/calibrating-and-updating/zone-configuration/zones-hlk.md +++ b/docs/homey/products/general/calibrating-and-updating/zone-configuration/zones-hlk.md @@ -1,4 +1,5 @@ --- +title: HLK Radar Tool app description: "Tutorial for MTR-1 HLKRadarTool app Zone Configuration." --- --8<-- "homey/products/mtr1/setup/zones-hlk.md:5:" diff --git a/docs/homey/products/general/contact-us/Facebook.md b/docs/homey/products/general/contact-us/Facebook.md index 093d7ee258..b5b29f1b94 100755 --- a/docs/homey/products/general/contact-us/Facebook.md +++ b/docs/homey/products/general/contact-us/Facebook.md @@ -1,4 +1,5 @@ --- +title: Facebook description: "Join the Apollo Automation community group on Facebook." --- --8<-- "products/general/contact-us/Facebook.md:5:" \ No newline at end of file diff --git a/docs/homey/products/general/contact-us/GitHub.md b/docs/homey/products/general/contact-us/GitHub.md index 527ecb6526..44b49c29c6 100755 --- a/docs/homey/products/general/contact-us/GitHub.md +++ b/docs/homey/products/general/contact-us/GitHub.md @@ -1,4 +1,5 @@ --- +title: GitHub description: "Apollo Automation on GitHub, where the firmware and hardware files live." --- --8<-- "products/general/contact-us/GitHub.md:5:" \ No newline at end of file diff --git a/docs/homey/products/general/contact-us/Instagram.md b/docs/homey/products/general/contact-us/Instagram.md index 66fd25ff69..cbd6fe21ce 100755 --- a/docs/homey/products/general/contact-us/Instagram.md +++ b/docs/homey/products/general/contact-us/Instagram.md @@ -1,4 +1,5 @@ --- +title: Instagram description: "Follow Apollo Automation on Instagram." --- --8<-- "products/general/contact-us/Instagram.md:5:" \ No newline at end of file diff --git a/docs/homey/products/general/contact-us/Reddit.md b/docs/homey/products/general/contact-us/Reddit.md index 4c3948a0d6..0107a25bd4 100755 --- a/docs/homey/products/general/contact-us/Reddit.md +++ b/docs/homey/products/general/contact-us/Reddit.md @@ -1,4 +1,5 @@ --- +title: Reddit description: "The Apollo Automation subreddit." --- --8<-- "products/general/contact-us/Reddit.md:5:" \ No newline at end of file diff --git a/docs/homey/products/general/contact-us/YouTube.md b/docs/homey/products/general/contact-us/YouTube.md index ce5f1d7297..501ef3bcca 100755 --- a/docs/homey/products/general/contact-us/YouTube.md +++ b/docs/homey/products/general/contact-us/YouTube.md @@ -1,4 +1,5 @@ --- +title: YouTube description: "The Apollo Automation YouTube channel, with setup guides, reviews, and live streams." --- --8<-- "products/general/contact-us/YouTube.md:5:" \ No newline at end of file diff --git a/docs/homey/products/general/contact-us/apollo-automation-shop.md b/docs/homey/products/general/contact-us/apollo-automation-shop.md index 71a25363d5..98b62e6eb8 100755 --- a/docs/homey/products/general/contact-us/apollo-automation-shop.md +++ b/docs/homey/products/general/contact-us/apollo-automation-shop.md @@ -1,4 +1,5 @@ --- +title: Apollo Automation shop description: "The Apollo Automation shop, where you can buy sensors, probes, and accessories." --- --8<-- "products/general/contact-us/apollo-automation-shop.md:6:" \ No newline at end of file diff --git a/docs/homey/products/general/contact-us/our-team.md b/docs/homey/products/general/contact-us/our-team.md index 75f6eda4a6..c357bb6b70 100755 --- a/docs/homey/products/general/contact-us/our-team.md +++ b/docs/homey/products/general/contact-us/our-team.md @@ -1,4 +1,5 @@ --- +title: Our team description: "Meet the people behind Apollo Automation." --- --8<-- "products/general/contact-us/our-team.md:5:" \ No newline at end of file diff --git a/docs/homey/products/general/setup/getting-started-msr1.md b/docs/homey/products/general/setup/getting-started-msr1.md index 52a15b418e..dd38f88117 100755 --- a/docs/homey/products/general/setup/getting-started-msr1.md +++ b/docs/homey/products/general/setup/getting-started-msr1.md @@ -1,4 +1,5 @@ --- +title: Getting started description: "Generic getting started article." --- --8<-- "homey/products/general/setup/getting-started.md:6:" \ No newline at end of file diff --git a/docs/homey/products/general/setup/getting-started-temp1.md b/docs/homey/products/general/setup/getting-started-temp1.md index 52a15b418e..dd38f88117 100755 --- a/docs/homey/products/general/setup/getting-started-temp1.md +++ b/docs/homey/products/general/setup/getting-started-temp1.md @@ -1,4 +1,5 @@ --- +title: Getting started description: "Generic getting started article." --- --8<-- "homey/products/general/setup/getting-started.md:6:" \ No newline at end of file diff --git a/docs/homey/products/general/temp-hum-calibration.md b/docs/homey/products/general/temp-hum-calibration.md index c4c757e7d8..469be7b71e 100755 --- a/docs/homey/products/general/temp-hum-calibration.md +++ b/docs/homey/products/general/temp-hum-calibration.md @@ -1,4 +1,5 @@ --- +title: Temp and humidity calibration and offset examples description: "Temp and Humidity Calibration and Offset Examples." --- --8<-- "products/general/temp-hum-calibration.md:5:" \ No newline at end of file diff --git a/docs/homey/products/led1/examples/led-1-controlling-govee-lights.md b/docs/homey/products/led1/examples/led-1-controlling-govee-lights.md index 9b9d60d88d..37df0ceb3e 100644 --- a/docs/homey/products/led1/examples/led-1-controlling-govee-lights.md +++ b/docs/homey/products/led1/examples/led-1-controlling-govee-lights.md @@ -1,4 +1,5 @@ --- +title: LED-1 controlling Govee lights description: How to use the Apollo LED-1 to control your Govee/3rd Party permanent outdoor LED lights! --- --8<-- "products/led1/examples/led-1-controlling-govee-lights.md:7:" diff --git a/docs/homey/products/led1/faq.md b/docs/homey/products/led1/faq.md index 3959c9c6d5..930551bde2 100644 --- a/docs/homey/products/led1/faq.md +++ b/docs/homey/products/led1/faq.md @@ -1,4 +1,5 @@ --- +title: LED-1 FAQ description: "Frequently asked questions about the LED-1 controller." --- --8<-- "products/led1/faq.md:5:" diff --git a/docs/homey/products/led1/introduction.md b/docs/homey/products/led1/introduction.md index 7937e204e7..3b089a34fe 100644 --- a/docs/homey/products/led1/introduction.md +++ b/docs/homey/products/led1/introduction.md @@ -1,4 +1,5 @@ --- +title: Introduction description: "Documentation for LED-1, including setup, usage, and best practices." --- --8<-- "products/led1/introduction.md:5:" diff --git a/docs/homey/products/led1/setup/getting-started-led1.md b/docs/homey/products/led1/setup/getting-started-led1.md index 2b852ba535..1fb53bc893 100644 --- a/docs/homey/products/led1/setup/getting-started-led1.md +++ b/docs/homey/products/led1/setup/getting-started-led1.md @@ -1,4 +1,5 @@ --- +title: Getting started description: "Getting started with your new LED-1!" --- --8<-- "products/led1/setup/getting-started-led1.md:5:" diff --git a/docs/homey/products/led1/setup/led1-general-tips.md b/docs/homey/products/led1/setup/led1-general-tips.md index 348a15815b..d229397feb 100644 --- a/docs/homey/products/led1/setup/led1-general-tips.md +++ b/docs/homey/products/led1/setup/led1-general-tips.md @@ -1,4 +1,5 @@ --- +title: LED-1 general tips description: "Multiple helpful tips to use your LED-1 to the fullest!" --- --8<-- "products/led1/setup/led1-general-tips.md:5:" diff --git a/docs/homey/products/led1/setup/led1-pinout-guide.md b/docs/homey/products/led1/setup/led1-pinout-guide.md index 1d837de801..fffe5a5d94 100644 --- a/docs/homey/products/led1/setup/led1-pinout-guide.md +++ b/docs/homey/products/led1/setup/led1-pinout-guide.md @@ -1,4 +1,5 @@ --- +title: LED-1 pinout guide description: "LED-1 Pinout Guide" --- --8<-- "products/led1/setup/led1-pinout-guide.md:5:" diff --git a/docs/homey/products/led1/setup/led1-replace-fuse.md b/docs/homey/products/led1/setup/led1-replace-fuse.md index 55454161e4..020f569f4a 100644 --- a/docs/homey/products/led1/setup/led1-replace-fuse.md +++ b/docs/homey/products/led1/setup/led1-replace-fuse.md @@ -1,4 +1,5 @@ --- +title: How to replace the LED-1 10 A fuse description: "Tutorial showing how to replace the 10 A Fuse on the LED-1." --- --8<-- "products/led1/setup/led1-replace-fuse.md:5:" diff --git a/docs/homey/products/led1/troubleshooting/led1-boot-mode.md b/docs/homey/products/led1/troubleshooting/led1-boot-mode.md index a3fdedc1af..93e28298ca 100644 --- a/docs/homey/products/led1/troubleshooting/led1-boot-mode.md +++ b/docs/homey/products/led1/troubleshooting/led1-boot-mode.md @@ -1,4 +1,5 @@ --- +title: Putting the LED-1 in boot mode description: "Step by step guide for putting The LED-1 In Boot Mode." --- --8<-- "products/led1/troubleshooting/led1-boot-mode.md:5:" diff --git a/docs/homey/products/led1/troubleshooting/led1-find-ip-address-and-hostname.md b/docs/homey/products/led1/troubleshooting/led1-find-ip-address-and-hostname.md index 1298a8a470..d472a2d3ce 100644 --- a/docs/homey/products/led1/troubleshooting/led1-find-ip-address-and-hostname.md +++ b/docs/homey/products/led1/troubleshooting/led1-find-ip-address-and-hostname.md @@ -1,4 +1,5 @@ --- +title: How to find the IP address and hostname of your LED-1 description: "Step by step guide for finding the IP address and the hostname of your LED-1 device." --- --8<-- "products/led1/troubleshooting/led1-find-ip-address-and-hostname.md:5:" diff --git a/docs/homey/products/led1/troubleshooting/led1-reflash.md b/docs/homey/products/led1/troubleshooting/led1-reflash.md index 93bb754ba8..032a57ff9a 100644 --- a/docs/homey/products/led1/troubleshooting/led1-reflash.md +++ b/docs/homey/products/led1/troubleshooting/led1-reflash.md @@ -1,4 +1,5 @@ --- -description: "Step by step guide for re-flashing the LED-1 back to factory firmware." +title: Factory re-flash LED-1 +description: "Step by step guide for re-flashing the LED-1 with regular WLED from your browser." --- --8<-- "products/led1/troubleshooting/led1-reflash.md:5:" diff --git a/docs/homey/products/msr2/setup/msr2-general-tips.md b/docs/homey/products/msr2/setup/msr2-general-tips.md index dc459d24cc..1be1389f1d 100755 --- a/docs/homey/products/msr2/setup/msr2-general-tips.md +++ b/docs/homey/products/msr2/setup/msr2-general-tips.md @@ -34,4 +34,4 @@ The MSR-2 can also be mounted on the ceiling if you can provide power and mount **![Table of LD2410 gates 0 to 8 with distance ranges in meters and feet and default move and still thresholds](/assets/ld2410-gate-table.png)![Radar Distance Resolution set to 0.75m with Radar End Zone 1, 2, and 3 at 50, 100, and 200 cm](/assets/gate-zones-and-rr.png)** -![Fan diagram of LD2410 gates G1 to G8, each 0.75 m deep, reaching 6 m (19.69 ft) from the sensor](/assets/ld2410-gate-map.png)![Radar gate diagram with Zones 1, 2, and 3 shaded red, blue, and green over gates G1 to G7](/assets/radar-gates-colored.png) \ No newline at end of file +![Fan diagram of LD2410 gates G1 to G8, each 0.75 m deep, reaching 6 m (19.69 ft) from the sensor](/assets/ld2410-gate-map.png)![Fan diagram of LD2410 gates G1 to G8 grouped into example zones: Zone 1 (G1 to G2) in red, Zone 2 (G3 to G5) in blue, and Zone 3 (G6 to G8) in green, reaching 6 m](/assets/radar-gates-colored.png) \ No newline at end of file diff --git a/docs/homey/products/msr2/troubleshooting/msr2-code.md b/docs/homey/products/msr2/troubleshooting/msr2-code.md index c3ba309b2c..e7f068abaa 100755 --- a/docs/homey/products/msr2/troubleshooting/msr2-code.md +++ b/docs/homey/products/msr2/troubleshooting/msr2-code.md @@ -16,17 +16,17 @@ If your device has already been added to Homey, please Apollo MSR-2 Installer. +3\. Open the Apollo MSR-2 installer. -4\. Click the big "Connect" button. +4\. Click **Connect & Install**. -![Apollo MSR-2 Installer page with the CONNECT button highlighted](/assets/msr-2-reflash-pic-1.png) +![MSR-2 page of the Apollo installer with the Connect & Install button outlined in red](/assets/installer-msr-2.png) 5\. Select the open com port then click Connect. ![Browser serial port dialog listing the USB JTAG serial debug unit with the Connect button](/assets/msr-2-reflash-pic-2.png) -6\. Click "Install MSR-2". +6\. Click **Install ApolloAutomation.MSR-2**. ![Installer Device Dashboard menu with INSTALL MSR-2 highlighted](/assets/msr-2-reflash-pic-3.png) diff --git a/docs/homey/products/mtr1/examples/how-to-use-the-apollo-gpio-header-to-control-an-led-strip.md b/docs/homey/products/mtr1/examples/how-to-use-the-apollo-gpio-header-to-control-an-led-strip.md index becdf0d1b7..c685f187e1 100755 --- a/docs/homey/products/mtr1/examples/how-to-use-the-apollo-gpio-header-to-control-an-led-strip.md +++ b/docs/homey/products/mtr1/examples/how-to-use-the-apollo-gpio-header-to-control-an-led-strip.md @@ -1,4 +1,5 @@ --- +title: Control an LED strip with the GPIO header description: "Wire a WS2812B LED strip to the Apollo GPIO Header and control it from Home Assistant." --- --8<-- "products/msr2/examples/gpio-header-control-an-led-strip.md:5:" diff --git a/docs/homey/products/mtr1/troubleshooting/mtr1-code.md b/docs/homey/products/mtr1/troubleshooting/mtr1-code.md index a168ece8d2..1794bb511d 100755 --- a/docs/homey/products/mtr1/troubleshooting/mtr1-code.md +++ b/docs/homey/products/mtr1/troubleshooting/mtr1-code.md @@ -16,17 +16,17 @@ If your device has already been added to Homey, please Apollo MTR-1 Installer. +3\. Open the Apollo MTR-1 installer. -4\. Click the big "Connect" button. +4\. Click **Connect & Install**. -![Apollo MTR-1 Installer page with the Connect button highlighted](/assets/mtr-1-reflash-pic-1.png) +![MTR-1 page of the Apollo installer with the Connect & Install button outlined in red](/assets/installer-mtr-1.png) 5\. Select the open com port then click Connect. ![Browser serial port prompt with the USB JTAG/serial debug unit selected and Connect clicked](/assets/mtr-1-reflash-pic-2.png) -6\. Click "Install MTR-1". +6\. Click **Install ApolloAutomation.MTR-1**. ![Installer Device Dashboard with the Install MTR-1 option being clicked](/assets/mtr-1-reflash-pic-3.png) diff --git a/docs/homey/products/plt1/troubleshooting/plt1-code.md b/docs/homey/products/plt1/troubleshooting/plt1-code.md index 383eb7e825..0d7ac2a9ac 100755 --- a/docs/homey/products/plt1/troubleshooting/plt1-code.md +++ b/docs/homey/products/plt1/troubleshooting/plt1-code.md @@ -16,17 +16,17 @@ Follow these steps to put your device in boot mode and install the factory firmw ![Side of the PLT-1 with the boot button opening circled](/assets/screenshot-2024-10-23-at-12-32-55-pm.png) -2\. Navigate to our installer page and click connect under Non Battery Firmware Apollo PLT-1 Installer +2\. Navigate to the Apollo PLT-1 installer and choose **USB Power** since you are using a PLT-1. -3\. Click the big "Connect" button. +3\. Click **Connect & Install**. -![Apollo PLT-1 Installer page with the Non Battery Firmware Connect button highlighted](/assets/plt-1-reflash-pic-1-1.png) +![PLT-1 page of the Apollo installer with the USB Power variant and the Connect & Install button outlined in red](/assets/installer-plt-1-usb-power.png) 4\. Select the open com port then click Connect. ![Browser serial port prompt with the USB JTAG/serial debug unit selected and Connect clicked](/assets/plt-1-reflash-pic-2-1.png) -5\. Click "Install ApolloAutomation.PLT-1". +5\. Click **Install ApolloAutomation.PLT-1**. ![Installer Device Dashboard with the Install ApolloAutomation.PLT-1 option highlighted](/assets/plt-1-reflash-pic-3.png) diff --git a/docs/homey/products/plt1b/troubleshooting/plt1b-code.md b/docs/homey/products/plt1b/troubleshooting/plt1b-code.md index 3d9c413f19..cefe510d50 100755 --- a/docs/homey/products/plt1b/troubleshooting/plt1b-code.md +++ b/docs/homey/products/plt1b/troubleshooting/plt1b-code.md @@ -21,11 +21,11 @@ Follow these steps to put your PLT-1B in boot mode and install the factory firmw ![Tool inserted into the boot button opening on the side of the closed PLT-1B case](/assets/plt-boot-mode-pic-4.jpg) -2\. Open the Apollo PLT-1B Installer. +2\. Open the Apollo PLT-1 installer. The PLT-1B uses the same page as the PLT-1. -3\. Under **Battery Firmware**, click the big **Connect** button. +3\. Choose **Battery Power**, then click **Connect & Install**. -![Apollo PLT-1 Installer page with the Battery Firmware Connect button being clicked](/assets/plt-1b-reflash-pic-1.png) +![PLT-1 page of the Apollo installer with the Battery Power variant and the Connect & Install button outlined in red](/assets/installer-plt-1-battery-power.png) 4\. Select the open COM port, then click **Connect**. diff --git a/docs/homey/products/rpro1/calibrating-co2.md b/docs/homey/products/rpro1/calibrating-co2.md index 5c6648ac0d..80c9f188d1 100644 --- a/docs/homey/products/rpro1/calibrating-co2.md +++ b/docs/homey/products/rpro1/calibrating-co2.md @@ -1,4 +1,5 @@ --- +title: CO2 calibration tutorial (quick) description: "Step by step guide for re-calibrating your SCD40 CO2 sensor" --- --8<-- "products/rpro1/calibrating-co2.md:5:" diff --git a/docs/homey/products/rpro1/faq.md b/docs/homey/products/rpro1/faq.md index 857b3dae2f..249f026a6b 100644 --- a/docs/homey/products/rpro1/faq.md +++ b/docs/homey/products/rpro1/faq.md @@ -35,7 +35,7 @@ description: "Answers to common questions about the R PRO-1 PoE mmWave sensor wi 7\. **How do I connect the R PRO-1 to Homey?** * The R PRO-1 ships with Wi-Fi firmware. Connect it to your Wi-Fi through its hotspot, then add it in Homey with the Apollo Automation app, which talks to it directly over your local network through the ESPHome native API. The app runs on Homey Pro; Homey Cloud isn't supported. See [Getting started](../../general/setup/getting-started/). -* Once it's connected, you can switch to Ethernet firmware for PoE from the sensor's own web page: in a browser, open `http://apollo-r-pro-1-w-xxxxxx.local`, where `xxxxxx` is the last 6 characters of the device's name in Homey. Choose **Ethernet** under **Firmware Type**, then press **Firmware Update**. The sensor downloads the new firmware from GitHub, so it needs internet access. You can also reflash it to Ethernet firmware with the R PRO-1 installer. +* Once it's connected, you can switch to Ethernet firmware for PoE from the sensor's own web page: in a browser, open `http://apollo-r-pro-1-w-xxxxxx.local`, where `xxxxxx` is the last 6 characters of the device's name in Homey. Choose **Ethernet** under **Firmware Type**, then press **Firmware Update**. The sensor downloads the new firmware from GitHub, so it needs internet access. You can also reflash it to Ethernet firmware from the Apollo R PRO-1 installer by choosing **Ethernet**. * Homey recognizes the R PRO-1 by its hardware address, so after the switch it stays the same device in Homey. 8\. **What kind of flows can I create with the R PRO-1?** diff --git a/docs/homey/products/rpro1/setup/zones-hlk.md b/docs/homey/products/rpro1/setup/zones-hlk.md index d826295ca3..098f4f7277 100644 --- a/docs/homey/products/rpro1/setup/zones-hlk.md +++ b/docs/homey/products/rpro1/setup/zones-hlk.md @@ -38,9 +38,7 @@ Follow these steps to turn on the LD2450's Bluetooth and set up its zones in the 1\. Open your R PRO-1's web server (see address tip above), scroll down until you see **LD2450 Bluetooth**, and toggle it on. -![Device Configuration panel with the LD2450 Bluetooth toggle switched on and highlighted](/assets/mtr-1-toggle-on-ld2450-bluetooth.png) - -*Shown on an MTR-1; the R PRO-1 has the same LD2450 Bluetooth switch.* +![R PRO-1 web page with the LD2450 Bluetooth switch turned on and highlighted](/assets/r-pro-1-toggle-on-ld2450-bluetooth.png) 2\. Open the HLKRadarTool App and select your device. diff --git a/docs/homey/products/temp1/troubleshooting/temp1-code.md b/docs/homey/products/temp1/troubleshooting/temp1-code.md index df8bdf9783..2c79607410 100755 --- a/docs/homey/products/temp1/troubleshooting/temp1-code.md +++ b/docs/homey/products/temp1/troubleshooting/temp1-code.md @@ -14,27 +14,27 @@ Follow these steps to put your device in boot mode and install the factory firmw 1\. Put your device in boot mode by holding down the boot button and then plugging in the USB cable. -2\. Navigate to the [Apollo TEMP-1 Installer](https://apolloautomation.github.io/TEMP-1/). +2\. Navigate to the [Apollo TEMP-1 installer](https://install.apolloautomation.com/#/temp-1). -3\. Click "Connect" under **Non Battery Firmware Revision 2** since you are using a TEMP-1. +3\. Choose **USB Power** since you are using a TEMP-1, then click **Connect & Install**. !!! tip "Use R2 version unless instructed to use R1 by support!" - R2 is what all of our devices use except a very small batch of TEMP-1 and TEMP-1B + The Apollo installer installs the Revision 2 (R2) firmware. R2 is what all of our devices use except a very small batch of TEMP-1 and TEMP-1B boards. If support tells you your board needs Revision 1 (R1), click **Connect** under **Non Battery Firmware Revision 1** on the [classic TEMP-1 installer](https://apolloautomation.github.io/TEMP-1/) instead. In the next steps, the firmware option is named **Install ApolloAutomation.TEMP-1**. -![Apollo TEMP-1 Installer page with the Non Battery Firmware Revision 2 Connect button clicked](/assets/temp-1-reflash-pic-1-1.png) +![TEMP-1 page of the Apollo installer with the USB Power variant and the Connect & Install button outlined in red](/assets/installer-temp-1-usb-power.png) 4\. Select the open com port then click Connect. ![Browser serial port dialog with the USB JTAG/serial debug unit port selected and the Connect button](/assets/temp-1-reflash-pic-2.png) -5\. Click "Install ApolloAutomation.TEMP-1". +5\. Click **Install Apollo.TEMP-1_R2**. -![Device Dashboard dialog with Install ApolloAutomation.TEMP-1 highlighted](/assets/temp-1-reflash-pic-3.png) +![Device Dashboard dialog with the TEMP-1 firmware install option highlighted](/assets/temp-1-reflash-pic-3.png) 6\. Click "INSTALL". -![Install ApolloAutomation.TEMP-1 confirmation dialog with the Install button highlighted](/assets/temp-1-reflash-pic-4.png) +![TEMP-1 firmware install confirmation dialog with the Install button highlighted](/assets/temp-1-reflash-pic-4.png) 7\. Once you see "Installation complete!" you are finished. Click Next then close out of the browser window. diff --git a/docs/homey/products/temp1b/troubleshooting/temp1b-code.md b/docs/homey/products/temp1b/troubleshooting/temp1b-code.md index 76f2d8d7e8..912d36693d 100755 --- a/docs/homey/products/temp1b/troubleshooting/temp1b-code.md +++ b/docs/homey/products/temp1b/troubleshooting/temp1b-code.md @@ -12,25 +12,33 @@ If your device has already been added to Homey, please Put your device in boot mode by holding down the boot button and then plugging in the USB cable. -2\. Navigate to our installer page and click connect under Battery Firmware [Apollo TEMP-1 Installer](https://apolloautomation.github.io/TEMP-1/) +2\. Navigate to the [Apollo TEMP-1 installer](https://install.apolloautomation.com/#/temp-1). The TEMP-1B uses the same page as the TEMP-1. !!! failure "Remove the battery!" This will not work properly if the battery is still supplying power to the TEMP-1B. Please remove the battery if you are having issues! -3\. Select the open com port then click Connect. +3\. Choose **Battery Power** since you are using a TEMP-1B, then click **Connect & Install**. + +![TEMP-1 page of the Apollo installer with the Battery Power variant and the Connect & Install button outlined in red](/assets/installer-temp-1-battery-power.png) + +!!! tip "Use R2 version unless instructed to use R1 by support!" + + The Apollo installer installs the Revision 2 (R2) firmware. R2 is what all of our devices use except a very small batch of TEMP-1 and TEMP-1B boards. If support tells you your board needs Revision 1 (R1), click **Connect** under **Battery Firmware Revision 1** on the [classic TEMP-1 installer](https://apolloautomation.github.io/TEMP-1/) instead. In the next steps, the firmware option is named **Install ApolloAutomation.TEMP-1B**. + +4\. Select the open com port then click Connect. ![Browser serial port dialog with the USB JTAG/serial debug unit port selected and the Connect button](/assets/temp-1b-reflash-pic-2-1.png) -4\. Click "Install ApolloAutomation.TEMP-1B". +5\. Click **Install Apollo.TEMP-1B_R2**. -![Device Dashboard dialog with Install ApolloAutomation.TEMP-1B selected](/assets/temp-1b-reflash-pic-3.png) +![Device Dashboard dialog with the TEMP-1B firmware install option selected](/assets/temp-1b-reflash-pic-3.png) -5\. Click "INSTALL". +6\. Click "INSTALL". -![Install ApolloAutomation.TEMP-1B confirmation dialog with the cursor on the Install button](/assets/temp-1b-reflash-pic-4.png) +![TEMP-1B firmware install confirmation dialog with the cursor on the Install button](/assets/temp-1b-reflash-pic-4.png) -6\. Once you see "Installation complete!" you are finished. Click Next then close out of the browser window. +7\. Once you see "Installation complete!" you are finished. Click Next then close out of the browser window. ![Web installer dialog showing Installation complete after flashing the TEMP-1B, with the Next button](/assets/temp-1b-reflash-pic-7.png) @@ -38,4 +46,4 @@ If your device has already been added to Homey, please proceed to the getting started guide and set up your sensor as a new device! \ No newline at end of file +8\. Please proceed to the getting started guide and set up your sensor as a new device! \ No newline at end of file diff --git a/docs/products/air1/troubleshooting/air1-code.md b/docs/products/air1/troubleshooting/air1-code.md index ee82ad9421..ebbfd3faba 100755 --- a/docs/products/air1/troubleshooting/air1-code.md +++ b/docs/products/air1/troubleshooting/air1-code.md @@ -13,23 +13,23 @@ If your Apollo AIR-1 becomes unresponsive and you've exhausted the other trouble ## Re-flash the factory firmware -Follow these steps to put the factory firmware back on your AIR-1 from the Apollo AIR-1 Installer. +Follow these steps to put the factory firmware back on your AIR-1 from the Apollo AIR-1 installer. 1\. Put your AIR-1 in boot mode: hold down the boot button (the right of the two buttons beside the USB-C port), then plug in the USB cable. Let go of the button once the cable is in. ![Tool pointing to the AIR-1 boot button, the right of two buttons beside the USB-C port](/assets/air-1-boot-button.jpg) -2\. Navigate to the Apollo AIR-1 Installer. +2\. Open the Apollo AIR-1 installer. -3\. Click the big **Connect** button on the installer page. +3\. Click **Connect & Install** on the installer page. -![Apollo AIR-1 Installer page with the Connect button highlighted](/assets/air-1-reflash-pic-1.png) +![AIR-1 page of the Apollo installer with the Connect & Install button outlined in red](/assets/installer-air-1.png) 4\. In the browser pop-up, select your AIR-1's open serial (COM) port, then click **Connect**. In the screenshot below, it's listed as USB JTAG/serial debug unit. ![Browser serial port dialog with the USB JTAG/serial debug unit port and the Connect button](/assets/air-1-reflash-pic-2-1.png) -5\. Click **Install AIR-1**. +5\. Click **Install ApolloAutomation.AIR-1**. ![Installer Device Dashboard with the Install AIR-1 option highlighted](/assets/air-1-reflash-pic-3.png) diff --git a/docs/products/apolloodroid/bluetoothtracking.md b/docs/products/apolloodroid/bluetoothtracking.md index c345cc2440..bf989d40b9 100755 --- a/docs/products/apolloodroid/bluetoothtracking.md +++ b/docs/products/apolloodroid/bluetoothtracking.md @@ -1,4 +1,5 @@ --- +title: Bluetooth tracker setup description: "Tutorial for how to turn your Apollo device into a BLE tracker to track an iPhone!" --- --8<-- "products/general/setup/bluetooth-tracking.md:5:" \ No newline at end of file diff --git a/docs/products/btn1/troubleshooting/btn1-reflash.md b/docs/products/btn1/troubleshooting/btn1-reflash.md index e2694e4e76..d8985dbf83 100755 --- a/docs/products/btn1/troubleshooting/btn1-reflash.md +++ b/docs/products/btn1/troubleshooting/btn1-reflash.md @@ -20,11 +20,11 @@ description: Step by step guide for reflashing The BTN-1. ![Holding the BTN-1 boot button while pressing and releasing the reset button](/assets/btn-1-boot-mode-method-2.webp) -4\. Navigate to our installer page using a chromium based browser such as Chrome or Edge and click **connect** under Apollo BTN-1 Installer. Select the open com port and click **connect**. +4\. Open the Apollo BTN-1 installer in a Chromium-based browser such as Chrome or Edge and click **Connect & Install**. Select the open com port and click **Connect**. -![Apollo BTN-1 Installer page, clicking Connect and choosing the USB JTAG serial port](/assets/btn-1-reflash-installer-connect.gif) +![BTN-1 page of the Apollo installer with the Connect & Install button outlined in red](/assets/installer-btn-1.png) -5\. Click Install **BTN-1** then click **Install** again. +5\. Click **Install ApolloAutomation.BTN-1**, then click **Install** again. ![Clicking Install ApolloAutomation.BTN-1 in the Device Dashboard, then Install to confirm](/assets/btn-1-reflash-install.gif) diff --git a/docs/products/general/calibrating-and-updating/mmwave-videos.md b/docs/products/general/calibrating-and-updating/mmwave-videos.md index 2364b68594..155920a644 100755 --- a/docs/products/general/calibrating-and-updating/mmwave-videos.md +++ b/docs/products/general/calibrating-and-updating/mmwave-videos.md @@ -38,7 +38,7 @@ To tune your sensor, you'll turn on Radar Engineering Mode and adjust the gate t 5\. The gates are different distances from the sensor. -![Radar Gates Colored](/assets/radar-gates-colored.png "Radar Gates Colored") +![Fan diagram of LD2410 gates G1 to G8 grouped into example zones: Zone 1 (G1 to G2) in red, Zone 2 (G3 to G5) in blue, and Zone 3 (G6 to G8) in green, reaching 6 m](/assets/radar-gates-colored.png) 6\. Moving the gate still and move threshold slider to the right increases the amount of energy needed to trigger the sensor. Do this if you want the gate to be less sensitive. diff --git a/docs/products/general/setup/getting-started-btn1.md b/docs/products/general/setup/getting-started-btn1.md index c595f93c01..eb7d1560e1 100755 --- a/docs/products/general/setup/getting-started-btn1.md +++ b/docs/products/general/setup/getting-started-btn1.md @@ -1,4 +1,5 @@ --- +title: Getting started description: "Generic getting started article." --- --8<-- "products/general/setup/getting-started.md:5:" \ No newline at end of file diff --git a/docs/products/h1/reflash.md b/docs/products/h1/reflash.md index bdde6a66ea..aa8d88cd14 100755 --- a/docs/products/h1/reflash.md +++ b/docs/products/h1/reflash.md @@ -15,7 +15,9 @@ Follow these steps to flash fresh firmware onto your H-1 and find it again in Ho 1\. Hold the boot button, then plug your H-1 into your computer with a quality USB-C cable that supports data transfer. Let go of the boot button once the USB cable is plugged in. -2\. Open our [H-1 install page](https://apolloautomation.github.io/H-1/) and click **Connect**. +2\. Open the [Apollo H-1 installer](https://install.apolloautomation.com/#/h-1) and click **Connect & Install**. The installer has one firmware for the H-1, the smart Wi-Fi firmware. + +![H-1 page of the Apollo installer with the Connect & Install button outlined in red](/assets/installer-h-1.png) 3\. Select your Apollo device and click **Connect**. It shows with a name similar to the one below. If you aren't sure which device it is, unplug the H-1 and see which one disappears. diff --git a/docs/products/h2/faq.md b/docs/products/h2/faq.md index 4b7722cc0f..931a39ace7 100755 --- a/docs/products/h2/faq.md +++ b/docs/products/h2/faq.md @@ -12,7 +12,7 @@ description: Frequently asked questions about the H-2. 3\. **Is the Apollo H-2 “smart” right out of the box?** -* The H-2 is pre-flashed with a simple firmware that operates independently, allowing you to play songs with the gold button without needing any additional setup. For a full “smart” experience, you can reflash the H-2 to the smart firmware then join it to Home Assistant, where you can program custom automations, change songs, and adjust LED effects. +* The H-2 is pre-flashed with a simple firmware that operates independently, allowing you to play songs with the gold button without needing any additional setup. For a full “smart” experience, you can reflash the H-2 to the smart firmware from the Apollo H-2 installer (choose **Smart (Wi-Fi)**), then join it to Home Assistant, where you can program custom automations, change songs, and adjust LED effects. 4\. **How do I activate the pre-loaded songs?** @@ -28,7 +28,7 @@ description: Frequently asked questions about the H-2. 7\. **How do I set up the Apollo H-2 with Home Assistant?** -* To integrate the H-2 with Home Assistant, reflash the sensor with smart firmware. +* To integrate the H-2 with Home Assistant, reflash it with the smart firmware: open the Apollo H-2 installer and choose **Smart (Wi-Fi)**. 8\. **Does the ornament require any additional power source?** diff --git a/docs/products/h2/setup/getting-started.md b/docs/products/h2/setup/getting-started.md index 9650bfd48b..2a395ec5a7 100755 --- a/docs/products/h2/setup/getting-started.md +++ b/docs/products/h2/setup/getting-started.md @@ -31,7 +31,7 @@ Each button plays one of these songs: 4\. **Add to Home Assistant** (Optional) -For additional customization, you will need to put the H-2 in boot mode then flash the [smart H-2 firmware](https://apolloautomation.github.io/H-2/) and finally connect to Home Assistant following the [setup guide](https://wiki.apolloautomation.com/products/general/setup/getting-started/). With Home Assistant you can add new songs, change LED effects, and create custom automations. +For additional customization, you will need to put the H-2 in boot mode then flash the smart firmware from the [Apollo H-2 installer](https://install.apolloautomation.com/#/h-2) (choose **Smart (Wi-Fi)**) and finally connect to Home Assistant following the [setup guide](https://wiki.apolloautomation.com/products/general/setup/getting-started/). With Home Assistant you can add new songs, change LED effects, and create custom automations. 5\. **Enjoy Your Ornament** diff --git a/docs/products/h2/troubleshooting/reflash.md b/docs/products/h2/troubleshooting/reflash.md index b5a65f9302..70226f28e5 100755 --- a/docs/products/h2/troubleshooting/reflash.md +++ b/docs/products/h2/troubleshooting/reflash.md @@ -16,13 +16,13 @@ description: Step by step guide for re-flashing the H-2 back to factory firmware ![Holding the boot button on the H-2 while plugging a USB-C cable into it](/assets/h-2-boot-mode-method-1-boot-button.webp) -4\. Navigate to our installer page using a chromium based browser such as Chrome or Edge and click **connect** under **H-2 Smart Wi-Fi Firmware** or **H-2 No Wi-Fi Firmware**. Select the open com port and click **connect**. +4\. Open the Apollo H-2 installer with the button below, using a Chromium-based browser such as Chrome or Edge. Under **Choose your firmware**, click **Smart (Wi-Fi)** to join your Wi-Fi and Home Assistant, or **Basic (No Wi-Fi)** to go back to the firmware the ornament ships with. Then click **Connect & Install**, select the open com port, and click **Connect**. -[Click here to head to the reflashing site!](https://apolloautomation.github.io/H-2/){ .md-button .md-button--primary } +[Apollo H-2 installer](https://install.apolloautomation.com/#/h-2){ .md-button .md-button--primary } -![Apollo H-2 Installer page: clicking Connect, picking the serial port, and the device menu opening](/assets/h-2-reflash-installer-connect.gif) +![H-2 page of the Apollo installer with the Smart (Wi-Fi) variant and the Connect & Install button outlined in red](/assets/installer-h-2-smart.png) -5\. Click Install **H-2** then click **Install** again. +5\. Click **Install ApolloAutomation.H-2** (Smart) or **Install ApolloAutomation.H-2D** (Basic), then click **Install** again. ![Clicking Install ApolloAutomation.H-2, confirming Install, and the installer erasing the device](/assets/h-2-reflash-install.gif) diff --git a/docs/products/h3/battery-sensors/wake-up-battery-sensor.md b/docs/products/h3/battery-sensors/wake-up-battery-sensor.md index 023266d9c9..80d3bfa358 100644 --- a/docs/products/h3/battery-sensors/wake-up-battery-sensor.md +++ b/docs/products/h3/battery-sensors/wake-up-battery-sensor.md @@ -1,4 +1,5 @@ --- +title: How to wake up your sensor description: "How to wake up your Apollo device which is currently sleeping." --- --8<-- "products/general/battery-sensors/wake-up-battery-sensor.md:5:" diff --git a/docs/products/h3/examples/holiday-songs.md b/docs/products/h3/examples/holiday-songs.md index d23da5af1d..532355676c 100644 --- a/docs/products/h3/examples/holiday-songs.md +++ b/docs/products/h3/examples/holiday-songs.md @@ -1,4 +1,5 @@ --- +title: Holiday songs buzzer list description: "Holiday songs you can play on the buzzer in your H-3." --- --8<-- "products/general/holiday-songs.md:7:" diff --git a/docs/products/led1/faq.md b/docs/products/led1/faq.md index e649b706af..ad45303ec2 100755 --- a/docs/products/led1/faq.md +++ b/docs/products/led1/faq.md @@ -39,6 +39,6 @@ description: Frequently asked questions about the LED-1 controller. 9\. **Can I reflash this with stock WLED firmware?** -* Yes! Our devices do not need custom compiled firmware, any esp32 8MB or technically 4MB firmware should work. +* Yes! The LED-1 runs regular WLED. Flash it with the [LED-1 reflash guide](../troubleshooting/led1-reflash/), then set the pins in WLED from the [LED-1 pinout guide](../setup/led1-pinout-guide/).   \ No newline at end of file diff --git a/docs/products/led1/troubleshooting/led1-reflash.md b/docs/products/led1/troubleshooting/led1-reflash.md index 01c82c6e4f..f624556254 100755 --- a/docs/products/led1/troubleshooting/led1-reflash.md +++ b/docs/products/led1/troubleshooting/led1-reflash.md @@ -1,10 +1,10 @@ --- title: Factory re-flash LED-1 -description: Step by step guide for re-flashing the LED-1 back to factory firmware. +description: Step by step guide for re-flashing the LED-1 with regular WLED from your browser. --- # Factory re-flash LED-1 -Follow these steps to flash your device back to its factory firmware with ESP Flasher on Windows. +Follow these steps to flash your Apollo LED-1 with regular WLED from the official WLED web installer. Use Chrome or Edge, since the installer needs a browser that can talk to the USB serial port. 1\. Plug in a USB cable that supports power and data into your computer. @@ -12,22 +12,17 @@ Follow these steps to flash your device back to its factory firmware with ESP Fl   -3\. Download the firmware .bin file from here. +3\. Open the WLED web installer. Leave **Mode** on **Basic**, keep the newest version selected in the version dropdown, and keep **Plain** selected. Basic installs a 4MB build, which works on the LED-1. -4\. Download ESP Flasher (Windows EXE) and open it. +![WLED web installer in Basic mode with version 16.0.1 in the version dropdown, Plain selected and highlighted, and the Install button highlighted](/assets/wled-installer-plain.png) -5\. Click the **Serial Port** dropdown and choose the available COM port. +4\. Click **Install**, pick your LED-1's serial port, and follow the prompts. When the installer shows that installation is complete, close it. -![ESP Flasher window with COM12 selected in the Serial port dropdown](/assets/m-1-select-open-com-port.png) +5\. The device is still in **boot mode** and needs to be power cycled. To reboot it, either unplug the power cable or press the **reset button** labeled **RST** (the left button; the boot button **BT** is on the right). -6\. Browse to the firmware file from Step 3 and select it. +6\. Set the LED-1's pins in WLED. Regular WLED doesn't know how the LED-1 is wired, so it needs the GPIO numbers from the [LED-1 pinout guide](../../setup/led1-pinout-guide/). Open your LED-1 in WLED (the [Connect to Wi-Fi](../../setup/getting-started-led1/#connect-to-wi-fi) steps show how), click **Config**, and set the pins in this order: -![ESP Flasher Firmware field showing the downloaded WLED .bin file after clicking Browse](/assets/m-1-select-firmware-you-downloaded.png) - -7\. Click **Flash ESP** and wait for the process to complete. Once it's done, it will appear as shown in the image below. - -![ESP Flasher console reading Done! Flashing is complete after the write reaches 100 percent](/assets/m-1-reflash-completed.png) - -8\. The device is still in **boot mode** and needs to be power cycled. To reboot it, either unplug the power cable or press the **reset button** labeled **RST** (the left button; the boot button **BT** is on the right). +- Under **Usermods**, in the **AudioReactive** section, set the microphone pins: SD to GPIO 12, WS to GPIO 27, and SCK to GPIO 14. Check **Reboot after save?** and click **Save**. Do this first, because WLED's default microphone settings use GPIO 15, which Output 2 needs. +- After the LED-1 restarts, open **Config → LED & Hardware**. Set the LED outputs to GPIO 13 (Output 1) and GPIO 15 (Output 2), clicking **+** to add the second output. Set the relay to GPIO 22 and the button to GPIO 0, then click **Save**. If your LEDs stay dark while WLED shows them on, check **Invert** under **Relay** and save again. [Head to the Getting Started article to set up your LED-1 as a new device!](/products/led1/setup/getting-started-led1.md){ .md-button .md-button--primary } \ No newline at end of file diff --git a/docs/products/msr1/setup/general-tips.md b/docs/products/msr1/setup/general-tips.md index dc88b4b763..69482db315 100755 --- a/docs/products/msr1/setup/general-tips.md +++ b/docs/products/msr1/setup/general-tips.md @@ -34,7 +34,7 @@ The MSR-1 can also be mounted on the ceiling if you can provide power and mount **![Table of LD2410 gates 0 to 8 with distance ranges in meters and feet and default move and still thresholds](/assets/ld2410-gate-table.png)![Home Assistant radar settings with 0.75 m distance resolution and Zone 1, 2, and 3 distances in cm](/assets/gate-zones-and-rr.png)** -![Fan diagram of LD2410 gates G1 to G8, each 0.75 m deep, reaching 6 m (19.69 ft) from the sensor](/assets/ld2410-gate-map.png)![Radar gate fan diagram with Zone 1 in red, Zone 2 in blue, and Zone 3 in green](/assets/radar-gates-colored.png) +![Fan diagram of LD2410 gates G1 to G8, each 0.75 m deep, reaching 6 m (19.69 ft) from the sensor](/assets/ld2410-gate-map.png)![Fan diagram of LD2410 gates G1 to G8 grouped into example zones: Zone 1 (G1 to G2) in red, Zone 2 (G3 to G5) in blue, and Zone 3 (G6 to G8) in green, reaching 6 m](/assets/radar-gates-colored.png) Each gate is 0.75 m deep, so the eight gates reach 6 m (19.69 ft) from the sensor. diff --git a/docs/products/msr1/troubleshooting/msr1-code.md b/docs/products/msr1/troubleshooting/msr1-code.md index 428c7ec9a2..d0cc2caca5 100755 --- a/docs/products/msr1/troubleshooting/msr1-code.md +++ b/docs/products/msr1/troubleshooting/msr1-code.md @@ -16,17 +16,17 @@ If your device has already been connected to Home Assistant please Apollo MSR-1 Installer. +3\. Open the Apollo MSR-1 installer. -4\. Click the big "Connect" button. +4\. Click **Connect & Install**. -![Apollo MSR-1 Installer page with the Connect button](/assets/msr-1-reflash-pic-1.png) +![MSR-1 page of the Apollo installer with the Connect & Install button outlined in red](/assets/installer-msr-1.png) 5\. Select the open com port then click Connect. ![Browser serial port prompt with the USB JTAG/serial debug unit selected and the Connect button](/assets/msr-1-reflash-pic-2.png) -6\. Click "Install MSR-1". +6\. Click **Install ApolloAutomation.MSR-1_Factory**. ![Device Dashboard menu with Install MSR-1 highlighted](/assets/msr-1-reflash-pic-3.png) diff --git a/docs/products/msr2/setup/msr2-general-tips.md b/docs/products/msr2/setup/msr2-general-tips.md index 1bc40664af..3dc0966bb1 100755 --- a/docs/products/msr2/setup/msr2-general-tips.md +++ b/docs/products/msr2/setup/msr2-general-tips.md @@ -34,6 +34,6 @@ The MSR-2 can also be mounted on the ceiling if you can provide power and mount **![Table of LD2410 gates 0 to 8 with distance ranges in meters and feet and default move and still thresholds](/assets/ld2410-gate-table.png)![Home Assistant radar settings with 0.75 m distance resolution and Zone 1, 2, and 3 distances in cm](/assets/gate-zones-and-rr.png)** -![Fan diagram of LD2410 gates G1 to G8, each 0.75 m deep, reaching 6 m (19.69 ft) from the sensor](/assets/ld2410-gate-map.png)![Radar gate fan diagram with Zone 1 in red, Zone 2 in blue, and Zone 3 in green](/assets/radar-gates-colored.png) +![Fan diagram of LD2410 gates G1 to G8, each 0.75 m deep, reaching 6 m (19.69 ft) from the sensor](/assets/ld2410-gate-map.png)![Fan diagram of LD2410 gates G1 to G8 grouped into example zones: Zone 1 (G1 to G2) in red, Zone 2 (G3 to G5) in blue, and Zone 3 (G6 to G8) in green, reaching 6 m](/assets/radar-gates-colored.png) ##### \ No newline at end of file diff --git a/docs/products/msr2/troubleshooting/msr2-code.md b/docs/products/msr2/troubleshooting/msr2-code.md index e136751cb5..eacaaa868b 100755 --- a/docs/products/msr2/troubleshooting/msr2-code.md +++ b/docs/products/msr2/troubleshooting/msr2-code.md @@ -16,17 +16,17 @@ If your device has already been connected to Home Assistant please Apollo MSR-2 Installer. +3\. Open the Apollo MSR-2 installer. -4\. Click the big "Connect" button. +4\. Click **Connect & Install**. -![Apollo MSR-2 Installer page with the Connect button outlined in red](/assets/msr-2-reflash-pic-1.png) +![MSR-2 page of the Apollo installer with the Connect & Install button outlined in red](/assets/installer-msr-2.png) 5\. Select the open com port then click Connect. ![Browser serial port prompt with the USB JTAG/serial debug unit selected and Connect clicked](/assets/msr-2-reflash-pic-2.png) -6\. Click "Install MSR-2". +6\. Click **Install ApolloAutomation.MSR-2**. ![Device Dashboard menu with the Install MSR-2 option selected](/assets/msr-2-reflash-pic-3.png) diff --git a/docs/products/mtr1/troubleshooting/mtr1-code.md b/docs/products/mtr1/troubleshooting/mtr1-code.md index d48267b2e1..b3055c7c50 100755 --- a/docs/products/mtr1/troubleshooting/mtr1-code.md +++ b/docs/products/mtr1/troubleshooting/mtr1-code.md @@ -18,17 +18,17 @@ Follow these steps to put your device in boot mode and install the factory firmw 2\. Push and hold the boot button. While still holding the button down, plug in a USB-C cable into the USB-C port of your MTR-1 then let go of the button. -3\. Navigate to our installer page and click connect under Apollo MTR-1 Installer. +3\. Open the Apollo MTR-1 installer. -4\. Click the big "Connect" button. +4\. Click **Connect & Install**. -![Apollo MTR-1 Installer page with the Connect button outlined in red](/assets/mtr-1-reflash-pic-1.png) +![MTR-1 page of the Apollo installer with the Connect & Install button outlined in red](/assets/installer-mtr-1.png) 5\. Select the open com port then click Connect. ![Browser serial port prompt with the USB JTAG/serial debug unit selected and Connect clicked](/assets/mtr-1-reflash-pic-2.png) -6\. Click "Install MTR-1". +6\. Click **Install ApolloAutomation.MTR-1**. ![Device Dashboard menu with the Install MTR-1 option selected](/assets/mtr-1-reflash-pic-3.png) diff --git a/docs/products/new-product-template/troubleshooting/productname-reflash.md b/docs/products/new-product-template/troubleshooting/productname-reflash.md index 7008258e70..b1e0b0e8b8 100755 --- a/docs/products/new-product-template/troubleshooting/productname-reflash.md +++ b/docs/products/new-product-template/troubleshooting/productname-reflash.md @@ -20,15 +20,15 @@ description: Step by step guide for reflashing The PUMP-1. ![Holding the PUMP-1 boot button while plugging in the USB-C cable](/assets/pump-1-hold-boot-button-video.webp) -4\. Navigate to our installer page and click connect under Apollo PUMP-1 Installer. +4\. Open the Apollo PUMP-1 installer and click **Connect & Install**. -![Apollo PUMP-1 Installer page with the cursor on the Connect button](/assets/pump-1-reflash-connect-button.png) +![PUMP-1 page of the Apollo installer with the Connect & Install button outlined in red](/assets/installer-pump-1.png) 5\. Select the open com port then click Connect. ![Browser serial port prompt with USB JTAG/serial debug unit selected and the cursor on Connect](/assets/pump-1-reflash-com-port.png) -6\. Click Install PUMP-1. +6\. Click **Install ApolloAutomation.PUMP-1**. ![Device Dashboard menu with the cursor on Install ApolloAutomation.PUMP-1](/assets/pump-1-reflash-click-install.png) diff --git a/docs/products/plt1/troubleshooting/plt1-code.md b/docs/products/plt1/troubleshooting/plt1-code.md index ff6dea55af..a6b006ba27 100755 --- a/docs/products/plt1/troubleshooting/plt1-code.md +++ b/docs/products/plt1/troubleshooting/plt1-code.md @@ -16,17 +16,17 @@ Follow these steps to put your device in boot mode and install the factory firmw ![Side of the PLT-1 case with the boot button opening circled in red](/assets/screenshot-2024-10-23-at-12-32-55-pm.png) -2\. Navigate to our installer page and click connect under Non Battery Firmware Apollo PLT-1 Installer +2\. Navigate to the Apollo PLT-1 installer and choose **USB Power** since you are using a PLT-1. -3\. Click the big "Connect" button. +3\. Click **Connect & Install**. -![Apollo PLT-1 Installer with the Non Battery Firmware Connect button highlighted](/assets/plt-1-reflash-pic-1-1.png) +![PLT-1 page of the Apollo installer with the USB Power variant and the Connect & Install button outlined in red](/assets/installer-plt-1-usb-power.png) 4\. Select the open com port then click Connect. ![Browser serial port prompt with USB JTAG/serial debug unit selected and the cursor on Connect](/assets/plt-1-reflash-pic-2-1.png) -5\. Click "Install ApolloAutomation.PLT-1". +5\. Click **Install ApolloAutomation.PLT-1**. ![Device Dashboard menu with Install ApolloAutomation.PLT-1 highlighted](/assets/plt-1-reflash-pic-3.png) diff --git a/docs/products/plt1b/troubleshooting/plt1b-code.md b/docs/products/plt1b/troubleshooting/plt1b-code.md index c02fb672ac..446461fbb4 100755 --- a/docs/products/plt1b/troubleshooting/plt1b-code.md +++ b/docs/products/plt1b/troubleshooting/plt1b-code.md @@ -19,11 +19,11 @@ If your Apollo PLT-1B becomes unresponsive and you've exhausted the other troubl ![Closed PLT-1B case with tweezers inserted into the boot button opening on the side](/assets/plt-boot-mode-pic-4.jpg) -2\. Open the Apollo PLT-1B Installer. +2\. Open the Apollo PLT-1 installer. The PLT-1B uses the same page as the PLT-1. -3\. Under **Battery Firmware**, click the big **Connect** button. +3\. Choose **Battery Power**, then click **Connect & Install**. -![Apollo PLT-1 Installer with the cursor on the Battery Firmware Connect button](/assets/plt-1b-reflash-pic-1.png) +![PLT-1 page of the Apollo installer with the Battery Power variant and the Connect & Install button outlined in red](/assets/installer-plt-1-battery-power.png) 4\. In the browser pop-up, select the open COM port (the PLT-1B's serial port, shown as USB JTAG/serial debug unit in the example below), then click **Connect**. diff --git a/docs/products/pump1/troubleshooting/pump1-reflash.md b/docs/products/pump1/troubleshooting/pump1-reflash.md index 7008258e70..b1e0b0e8b8 100755 --- a/docs/products/pump1/troubleshooting/pump1-reflash.md +++ b/docs/products/pump1/troubleshooting/pump1-reflash.md @@ -20,15 +20,15 @@ description: Step by step guide for reflashing The PUMP-1. ![Holding the PUMP-1 boot button while plugging in the USB-C cable](/assets/pump-1-hold-boot-button-video.webp) -4\. Navigate to our installer page and click connect under Apollo PUMP-1 Installer. +4\. Open the Apollo PUMP-1 installer and click **Connect & Install**. -![Apollo PUMP-1 Installer page with the cursor on the Connect button](/assets/pump-1-reflash-connect-button.png) +![PUMP-1 page of the Apollo installer with the Connect & Install button outlined in red](/assets/installer-pump-1.png) 5\. Select the open com port then click Connect. ![Browser serial port prompt with USB JTAG/serial debug unit selected and the cursor on Connect](/assets/pump-1-reflash-com-port.png) -6\. Click Install PUMP-1. +6\. Click **Install ApolloAutomation.PUMP-1**. ![Device Dashboard menu with the cursor on Install ApolloAutomation.PUMP-1](/assets/pump-1-reflash-click-install.png) diff --git a/docs/products/rpro1/faq.md b/docs/products/rpro1/faq.md index 823848da06..76836888c0 100755 --- a/docs/products/rpro1/faq.md +++ b/docs/products/rpro1/faq.md @@ -32,7 +32,7 @@ description: Frequently asked questions about the R PRO-1 PoE mmWave sensor. 7\. **How do I connect the R PRO-1 to Home Assistant?** -* The R PRO-1 connects to your Home Assistant instance through ESPHome using Wi-Fi. Once connected, you can switch to using the ethernet firmware. You can also reflash it to Ethernet firmware here. +* The R PRO-1 connects to your Home Assistant instance through ESPHome using Wi-Fi. Once connected, you can switch to using the ethernet firmware. You can also reflash it to Ethernet firmware from the Apollo R PRO-1 installer by choosing **Ethernet**. 8\. **What kind of automations can I create with the R PRO-1?** diff --git a/docs/products/rpro1/troubleshooting/rpro1-code.md b/docs/products/rpro1/troubleshooting/rpro1-code.md index 5e75181716..1ed1bd0e48 100755 --- a/docs/products/rpro1/troubleshooting/rpro1-code.md +++ b/docs/products/rpro1/troubleshooting/rpro1-code.md @@ -21,17 +21,17 @@ With the board out of the case: - While still holding the button down, plug a USB-C cable into the USB-C port of your R PRO-1. - Let go of the button. -2\. Open the Apollo R PRO-1 Installer. +2\. Open the Apollo R PRO-1 installer. -3\. Click the big **Connect** button. +3\. Under **Choose your firmware**, pick **WiFi** if your R PRO-1 connects over Wi-Fi, or **Ethernet** if it connects over PoE or Ethernet. Then click **Connect & Install**. -![Apollo R PRO-1 Installer page with the Ethernet Firmware CONNECT button highlighted](/assets/r-pro-1-reflash-connect-button.png) +![R PRO-1 page of the Apollo installer with the WiFi variant and the Connect & Install button outlined in red](/assets/installer-r-pro-1-wifi.png) 4\. In the browser pop-up, select the open COM port (the R PRO-1's serial port, shown as USB JTAG/serial debug unit in the example below), then click **Connect**. ![Browser serial port prompt with the USB JTAG serial debug unit COM port and Connect button](/assets/r-pro-1-reflash-connect-comp-port.png) -5\. Click **Install R PRO-1**. +5\. Click **Install ApolloAutomation.R-PRO-1-W** if you chose **WiFi**, or **Install ApolloAutomation.R-PRO-1-ETH** if you chose **Ethernet**. ![Installer Device Dashboard with the install R PRO-1 Ethernet firmware option highlighted](/assets/r-pro-1-reflash-click-install.png) diff --git a/docs/products/temp1/troubleshooting/temp1-code.md b/docs/products/temp1/troubleshooting/temp1-code.md index c146df6365..fc29afd9e0 100755 --- a/docs/products/temp1/troubleshooting/temp1-code.md +++ b/docs/products/temp1/troubleshooting/temp1-code.md @@ -15,27 +15,27 @@ Follow these steps to put your TEMP-1 in boot mode, flash the factory firmware f 1\. Put your TEMP-1 in boot mode: hold down the boot button, then plug in the USB cable. -2\. Open the [Apollo TEMP-1 Installer](https://apolloautomation.github.io/TEMP-1/) page. +2\. Open the [Apollo TEMP-1 installer](https://install.apolloautomation.com/#/temp-1) page. -3\. Under the **Non Battery Firmware** option, click **Connect** for Revision 2 (R2). Non Battery Firmware is the right choice because you're using a TEMP-1. +3\. Choose **USB Power**, then click **Connect & Install**. USB Power is the right choice because you're using a TEMP-1. -![Apollo TEMP-1 Installer page with the Non Battery Firmware Revision 2 Connect button clicked](/assets/temp-1-reflash-pic-1-1.png) +![TEMP-1 page of the Apollo installer with the USB Power variant and the Connect & Install button outlined in red](/assets/installer-temp-1-usb-power.png) !!! tip "Use R2 unless support tells you to use R1" - R2 is what all of our devices use, except a very small batch of TEMP-1 and TEMP-1B boards. Support will tell you if yours needs R1. + The Apollo installer installs the Revision 2 (R2) firmware. R2 is what all of our devices use, except a very small batch of TEMP-1 and TEMP-1B boards. Support will tell you if yours needs Revision 1 (R1). If it does, click **Connect** under **Non Battery Firmware Revision 1** on the [classic TEMP-1 installer](https://apolloautomation.github.io/TEMP-1/) instead. In the next steps, the firmware option is named **Install ApolloAutomation.TEMP-1**. 4\. In the browser's serial port pop-up, select the open COM port (**USB JTAG/serial debug unit** in the screenshot below), then click **Connect**. ![Browser serial port dialog with the USB JTAG/serial debug unit port selected and Connect clicked](/assets/temp-1-reflash-pic-2.png) -5\. Click **Install ApolloAutomation.TEMP-1**. +5\. Click **Install Apollo.TEMP-1_R2**. -![Device Dashboard dialog with Install ApolloAutomation.TEMP-1 highlighted](/assets/temp-1-reflash-pic-3.png) +![Device Dashboard dialog with the TEMP-1 firmware install option highlighted](/assets/temp-1-reflash-pic-3.png) 6\. Click **INSTALL**. -![Install ApolloAutomation.TEMP-1 confirmation dialog with the Install button highlighted](/assets/temp-1-reflash-pic-4.png) +![TEMP-1 firmware install confirmation dialog with the Install button highlighted](/assets/temp-1-reflash-pic-4.png) 7\. When the installer shows **Installation complete!**, the flash is finished. Click **Next**, then close the browser window. diff --git a/docs/products/temp1b/troubleshooting/temp1b-code.md b/docs/products/temp1b/troubleshooting/temp1b-code.md index c830b7fd7a..b5d90f0202 100755 --- a/docs/products/temp1b/troubleshooting/temp1b-code.md +++ b/docs/products/temp1b/troubleshooting/temp1b-code.md @@ -14,31 +14,31 @@ Follow these steps to put your device in boot mode and install the factory firmw 1\. Put your device in boot mode by holding down the boot button and then plugging in the USB cable. -2\. Navigate to our installer page and click connect under Battery Firmware [Apollo TEMP-1 Installer](https://apolloautomation.github.io/TEMP-1/) +2\. Navigate to the [Apollo TEMP-1 installer](https://install.apolloautomation.com/#/temp-1). The TEMP-1B uses the same page as the TEMP-1. !!! failure "Remove the battery!" This will not work properly if the battery is still supplying power to the TEMP-1B. Please remove the battery if you are having issues! -3\. Click "Connect" under the Battery Firmware option since you are using a TEMP-1B. +3\. Choose **Battery Power** since you are using a TEMP-1B, then click **Connect & Install**. -![Apollo TEMP-1 Installer with Connect clicked under Battery Firmware Revision 2](/assets/temp-1b-reflash-pic-1.png) +![TEMP-1 page of the Apollo installer with the Battery Power variant and the Connect & Install button outlined in red](/assets/installer-temp-1-battery-power.png) !!! tip "Use R2 version unless instructed to use R1 by support!" - R2 is what all of our devices use except a very small batch of TEMP-1 and TEMP-1B + The Apollo installer installs the Revision 2 (R2) firmware. R2 is what all of our devices use except a very small batch of TEMP-1 and TEMP-1B boards. If support tells you your board needs Revision 1 (R1), click **Connect** under **Battery Firmware Revision 1** on the [classic TEMP-1 installer](https://apolloautomation.github.io/TEMP-1/) instead. In the next steps, the firmware option is named **Install ApolloAutomation.TEMP-1B**. 4\. Select the open com port then click Connect. ![Browser serial port dialog with the USB JTAG/serial debug unit port selected](/assets/temp-1b-reflash-pic-2-1.png) -5\. Click "Install ApolloAutomation.TEMP-1B". +5\. Click **Install Apollo.TEMP-1B_R2**. -![Device Dashboard dialog with Install ApolloAutomation.TEMP-1B selected](/assets/temp-1b-reflash-pic-3.png) +![Device Dashboard dialog with the TEMP-1B firmware install option selected](/assets/temp-1b-reflash-pic-3.png) 6\. Click "INSTALL". -![Install ApolloAutomation.TEMP-1B confirmation dialog with the cursor on Install](/assets/temp-1b-reflash-pic-4.png) +![TEMP-1B firmware install confirmation dialog with the cursor on Install](/assets/temp-1b-reflash-pic-4.png) 7\. Once you see "Installation complete!" you are finished. Click Next then close out of the browser window. diff --git a/docs/products/temppro1/faq.md b/docs/products/temppro1/faq.md index 0740171ac7..bccbf5ab7e 100755 --- a/docs/products/temppro1/faq.md +++ b/docs/products/temppro1/faq.md @@ -6,7 +6,7 @@ description: Frequently asked questions about the TEMP Pro-1 temperature sensor. 1\. **How is the TEMP Pro-1 powered?** -* PoE (IEEE 802.3-compliant) powered or... +* PoE (802.3af compliant) powered or... * USB-C at 5 volts using less than 1 amp of power. 2\. **What are the Optional Probe Addons?** diff --git a/tools/docs-checks/README.md b/tools/docs-checks/README.md new file mode 100644 index 0000000000..44f5a40a2d --- /dev/null +++ b/tools/docs-checks/README.md @@ -0,0 +1,34 @@ +# Docs checks + +These scripts run on every pull request into `dev` or `main` +(`.github/workflows/docs-checks.yml`). Problems show up as comments on the +changed lines in the PR. Fix them and push again; the checks re-run. + +| Check | Fails the PR on | How to fix | +| --- | --- | --- | +| `check_markdown.py` | Missing front matter `title:` or `description:`, heading levels that skip (`##` to `####`), more than one `#` H1, images without alt text, snippet includes that point at a missing file or start inside the included page's front matter | Add the field, use the next heading level, describe the image inside `![...]`, or start the include after the included page's closing `---` | +| `check_secrets.py` | ESPHome API encryption keys, generated OTA passwords, passwords typed into YAML, and access tokens | Use `!secret` (or a placeholder like `your-wifi-password`). If the value was real, change it on the device or account too | +| `check_images.py` | Photos with GPS location data (phones add it by default) | `exiftool -gps:all= -overwrite_original docs/assets/` | +| `check_links.py` | Broken links, links to a missing `#anchor`, filename case mismatches (GitHub Pages is case-sensitive), and images without alt text, checked on the built site | Fix the link target or anchor; match the file name's case exactly | + +Warnings (shown, but they don't fail the PR): em dashes and the filler words +the style guide bans, and images or recordings over 1.5 MB that the PR adds +or changes. + +The checks can't read text inside screenshots or recordings. Before adding +one, look through it for passwords, API keys, email addresses, and other +personal details, and crop or trim them out (see the style guide). + +## Run them locally + +```bash +pip install -r requirements.txt +python tools/docs-checks/check_markdown.py docs +python tools/docs-checks/check_secrets.py docs +python tools/docs-checks/check_images.py docs/assets +mkdocs build -d site +python tools/docs-checks/check_links.py site docs +``` + +`check_images.py` needs exiftool (`brew install exiftool` on macOS, +`sudo apt install libimage-exiftool-perl` on Debian or Ubuntu). diff --git a/tools/docs-checks/check_images.py b/tools/docs-checks/check_images.py new file mode 100644 index 0000000000..70ed526391 --- /dev/null +++ b/tools/docs-checks/check_images.py @@ -0,0 +1,48 @@ +"""Image checks for Apollo Docs pull requests. + +Usage: python tools/docs-checks/check_images.py [assets_dir] + +Fails on: photos that carry GPS location metadata (phones add it by +default, and it publishes where the photo was taken). +Warns on: images over 1.5 MB, which slow pages down. Set CHANGED_FILES +(newline-separated paths) to limit this warning to the files a PR changes. + +Needs exiftool (apt install libimage-exiftool-perl, brew install exiftool). +To fix a GPS error: exiftool -gps:all= -overwrite_original +""" +import os +import shutil +import subprocess +import sys + +ASSETS = sys.argv[1] if len(sys.argv) > 1 else "docs/assets" +EXTS = (".jpg", ".jpeg", ".png", ".webp", ".heic", ".tif", ".tiff") +LIMIT = 1.5 * 1024 * 1024 + +if not shutil.which("exiftool"): + print("::error::exiftool is not installed, so GPS metadata can't be checked.") + sys.exit(1) + +r = subprocess.run( + ["exiftool", "-q", "-q", "-r", "-if", "$GPSLatitude or $GPSLongitude", "-p", "$Directory/$FileName", + *sum((["-ext", e.lstrip(".")] for e in EXTS), []), ASSETS], + capture_output=True, text=True, +) +gps = [l for l in r.stdout.splitlines() if l.strip()] +for path in gps: + print(f"::error file={path}::Photo contains GPS location data. Remove it with: exiftool -gps:all= -overwrite_original \"{path}\"") + +changed = os.environ.get("CHANGED_FILES") +only = {os.path.normpath(f) for f in changed.split()} if changed is not None else None +big = 0 +for root, _, files in os.walk(ASSETS): + for name in files: + p = os.path.join(root, name) + if only is not None and os.path.normpath(p) not in only: + continue + if os.path.getsize(p) > LIMIT and name.lower().endswith(EXTS + (".gif", ".mp4")): + big += 1 + print(f"::warning file={p}::{os.path.getsize(p) / 1048576:.1f} MB. Consider resizing (750 px wide is plenty for most images) or compressing.") + +print(f"check_images: {len(gps)} image(s) with GPS data, {big} large file warning(s)") +sys.exit(1 if gps else 0) diff --git a/tools/docs-checks/check_links.py b/tools/docs-checks/check_links.py new file mode 100644 index 0000000000..20198d3412 --- /dev/null +++ b/tools/docs-checks/check_links.py @@ -0,0 +1,143 @@ +"""Check internal links, anchors, and images in the built Apollo Docs site. + +Usage: mkdocs build -d site && python tools/docs-checks/check_links.py site docs + +MkDocs only validates links written as .md files. The wiki uses site-style +links (../page/, https://wiki.apolloautomation.com/...), so this checks every +link, #anchor, image, and video in page content against the built site. +Filename case must match exactly, because GitHub Pages is case-sensitive. +Fails on any broken link, missing anchor, or image without alt text. +""" +import os, sys, posixpath +from html.parser import HTMLParser +from urllib.parse import urlsplit, unquote + +SITE = sys.argv[1] if len(sys.argv) > 1 else "site" +DOCS = sys.argv[2] if len(sys.argv) > 2 else "docs" +OWN_HOSTS = {"wiki.apolloautomation.com"} + + +class Page(HTMLParser): + def __init__(self): + super().__init__(convert_charrefs=True) + self.ids, self.refs = set(), [] + self.in_article, self.stack = False, 0 + + def handle_starttag(self, tag, attrs): + a = dict(attrs) + if "id" in a: + self.ids.add(a["id"]) + if tag == "a" and "name" in a: + self.ids.add(a["name"]) + if tag == "article" and "md-content__inner" in (a.get("class") or ""): + self.in_article, self.stack = True, 0 + if not self.in_article: + return + if tag == "article": + self.stack += 1 + if tag == "a" and a.get("href") is not None and "headerlink" not in (a.get("class") or ""): + self.refs.append(("a", a["href"], None)) + elif tag == "img": + self.refs.append(("img", a.get("src", ""), a.get("alt"))) + elif tag in ("video", "source", "audio") and a.get("src"): + self.refs.append((tag, a["src"], None)) + if tag == "video" and a.get("poster"): + self.refs.append(("poster", a["poster"], None)) + + def handle_endtag(self, tag): + if self.in_article and tag == "article": + self.stack -= 1 + if self.stack <= 0: + self.in_article = False + + +ALL = set() +for r, _, fs in os.walk(SITE): + for f in fs: + ALL.add("/" + os.path.relpath(os.path.join(r, f), SITE).replace(os.sep, "/")) +LOWER = {f.lower(): f for f in ALL} + +pages = {} +for f in ALL: + if not f.endswith(".html") or f.startswith(("/assets/", "/search/")) or f == "/404.html": + continue + html = open(SITE + f, encoding="utf-8", errors="replace").read() + if 'http-equiv="refresh"' in html[:2000] and "md-content" not in html: + continue + p = Page() + p.feed(html) + pages[f] = p + + +def resolve(base, ref): + sp = urlsplit(ref) + if sp.scheme in ("mailto", "tel", "javascript", "data"): + return None + if sp.scheme in ("http", "https"): + if sp.netloc.lower() not in OWN_HOSTS: + return None + path = sp.path or "/" + elif sp.scheme or sp.netloc: + return None + elif not sp.path: + return base, unquote(sp.fragment) + elif sp.path.startswith("/"): + path = sp.path + else: + path = posixpath.normpath(posixpath.join(posixpath.dirname(base), sp.path)) + if sp.path.endswith("/") and not path.endswith("/"): + path += "/" + return unquote(path), unquote(sp.fragment) + + +case_mismatch = [] + + +def exists(path): + p = "/" + path.lstrip("/") + cands = [p + "index.html"] if p.endswith("/") else [p, p + "/index.html"] + for c in cands: + if c in ALL: + return c + for c in cands: + if c.lower() in LOWER: + case_mismatch.append((path, LOWER[c.lower()])) + return None + + +def src_md(url): + rel = url.lstrip("/") + rel = rel[: -len("/index.html")] if rel.endswith("/index.html") else rel + for cand in (rel + ".md", rel + "/index.md"): + if os.path.isfile(os.path.join(DOCS, cand)): + return "docs/" + cand + return "?" + url + + +broken, bad_anchor, missing_alt = [], [], [] +for url, pr in pages.items(): + for kind, ref, alt in pr.refs: + if kind == "img" and (alt is None or not alt.strip()): + missing_alt.append({"page": src_md(url), "src": ref}) + r = resolve(url, ref) + if r is None: + continue + path, frag = r + t = exists(path) + if not t: + broken.append({"page": src_md(url), "kind": kind, "ref": ref}) + continue + if frag and kind == "a" and t in pages and frag not in pages[t].ids: + bad_anchor.append({"page": src_md(url), "ref": ref}) + +for b in broken: + print(f"::error file={b['page']}::Broken {b['kind']} link: {b['ref']}") +for a in bad_anchor: + print(f"::error file={a['page']}::Link to a missing #anchor: {a['ref']}") +for m in missing_alt: + print(f"::error file={m['page']}::Image without alt text: {m['src']}") +for wrong, right in sorted(set(case_mismatch)): + print(f"::error::Link case doesn't match the file (GitHub Pages is case-sensitive): {wrong} should be {right}") +total = len(broken) + len(bad_anchor) + len(missing_alt) + len(set(case_mismatch)) +print(f"check_links: {len(pages)} pages, {len(broken)} broken, {len(bad_anchor)} bad anchors, {len(missing_alt)} missing alt, {len(set(case_mismatch))} case mismatches") +sys.exit(1 if total else 0) diff --git a/tools/docs-checks/check_markdown.py b/tools/docs-checks/check_markdown.py new file mode 100644 index 0000000000..886dff77ae --- /dev/null +++ b/tools/docs-checks/check_markdown.py @@ -0,0 +1,115 @@ +"""Markdown checks for Apollo Docs pull requests. + +Usage: python tools/docs-checks/check_markdown.py [docs_dir] + +Errors (fail the check): + - front matter missing, or missing title or description + - heading levels that skip (## straight to ####) or more than one H1 + - images without alt text (![](...) or with no alt) + - snippet includes whose target is missing or whose line offset starts + inside the target's front matter (it would render as page text) +Warnings (shown on the PR, do not fail): + - em dashes in prose and the filler words the style guide bans + +Output uses GitHub Actions annotations, so problems show up on the +changed lines in the PR. +""" +import os +import re +import sys + +DOCS = sys.argv[1] if len(sys.argv) > 1 else "docs" +FILLER = re.compile(r"\b(simply|seamlessly|powerful)\b", re.I) +errors = warnings = 0 + + +def note(kind, path, line, msg): + global errors, warnings + if kind == "error": + errors += 1 + else: + warnings += 1 + print(f"::{kind} file={path},line={line}::{msg}") + + +def front_matter_end(lines): + if not lines or lines[0].strip() != "---": + return None + for i in range(1, len(lines)): + if lines[i].strip() == "---": + return i + return None + + +for root, _, files in os.walk(DOCS): + for name in sorted(files): + if not name.endswith(".md"): + continue + path = os.path.join(root, name) + is_snippet = "/_snippets" in path.replace(os.sep, "/") + lines = open(path, encoding="utf-8", errors="replace").read().split("\n") + end = front_matter_end(lines) + + if not is_snippet: + if end is None: + note("error", path, 1, "Missing front matter. Add title: and description: between --- lines.") + else: + fm = "\n".join(lines[1:end]) + if not re.search(r"^title:\s*\S", fm, re.M): + note("error", path, 1, "Front matter is missing title:.") + if not re.search(r"^description:\s*\S", fm, re.M): + note("error", path, 1, "Front matter is missing description:.") + + start = (end + 1) if end is not None else 0 + fence = None + last_level = 0 + h1_count = 0 + for n, line in enumerate(lines[start:], start=start + 1): + m = re.match(r"^\s*(`{3,}|~{3,})", line) + if m: + tok = m.group(1) + if fence is None: + fence = tok + elif tok[0] == fence[0] and len(tok) >= len(fence) and line.strip() == tok: + fence = None + continue + if fence: + continue + + h = re.match(r"^(#{1,6})\s", line) + if h: + level = len(h.group(1)) + h1_count += level == 1 + if last_level and level > last_level + 1: + note("error", path, n, f"Heading jumps from level {last_level} to {level}. Use level {last_level + 1}.") + last_level = level + + for img in re.finditer(r"!\[\s*\]\(([^)\s]+)", line): + note("error", path, n, f"Image has no alt text: {img.group(1)}. Describe what it shows inside the brackets.") + for tag in re.finditer(r"]*>", line, re.I): + if not re.search(r'\balt\s*=\s*"[^"]+"', tag.group(0)): + note("error", path, n, " tag has no alt text. Add alt=\"...\" describing the image.") + + inc = re.search(r'--8<--\s+"([^":]+)((?::\d*){0,2})"', line) + if inc: + target = os.path.join(DOCS, inc.group(1)) + if not os.path.exists(target): + note("error", path, n, f"Snippet include target not found: {inc.group(1)}") + else: + tlines = open(target, encoding="utf-8", errors="replace").read().split("\n") + tend = front_matter_end(tlines) + nums = re.findall(r":(\d*)", inc.group(2)) + first = int(nums[0]) if nums and nums[0] else 1 + if tend is not None and first <= tend + 1: + note("error", path, n, f"Include starts at line {first}, inside {inc.group(1)}'s front matter (ends at line {tend + 1}). Start at line {tend + 2} or later.") + + if "—" in line and not line.lstrip().startswith("|"): + note("warning", path, n, "Em dash in prose. The style guide asks for a comma, period, colon, or parentheses instead.") + if FILLER.search(line): + note("warning", path, n, f"Filler word '{FILLER.search(line).group(0)}'. The style guide asks to drop it or say what it does.") + + if h1_count > 1: + note("error", path, 1, f"{h1_count} H1 headings. A page should have one.") + +print(f"check_markdown: {errors} error(s), {warnings} warning(s)") +sys.exit(1 if errors else 0) diff --git a/tools/docs-checks/check_secrets.py b/tools/docs-checks/check_secrets.py new file mode 100644 index 0000000000..13b3531513 --- /dev/null +++ b/tools/docs-checks/check_secrets.py @@ -0,0 +1,51 @@ +"""Scan docs text for credentials that should never be published. + +Usage: python tools/docs-checks/check_secrets.py [docs_dir] + +Fails on: + - ESPHome API encryption keys (a 44-character base64 key after key:) + - OTA passwords that look generated (32 hex characters) + - Wi-Fi or other passwords typed in YAML instead of !secret + - common access token formats (GitHub, Slack, AWS, JWT, long bearer tokens) + +Placeholders are allowed: !secret references, values containing words like +your/example/password/changeme/xxx, and known public defaults (for example +WLED's own hotspot password). Screenshots can't be scanned automatically; +check those by eye before adding them. +""" +import os +import re +import sys + +DOCS = sys.argv[1] if len(sys.argv) > 1 else "docs" +EXTS = (".md", ".html", ".htm", ".yaml", ".yml", ".txt", ".json") +PLACEHOLDER = re.compile(r"(?i)your|example|password|passw|changeme|change_me|placeholder|secret|xxx|<|>|\$\{|_here|abc123|12345678|wled1234") +PATTERNS = [ + ("ESPHome API encryption key", re.compile(r"""\bkey:\s*["']?([A-Za-z0-9+/]{43}=)["']?""")), + ("generated OTA password", re.compile(r"""\bpassword:\s*["']?([0-9a-f]{32})["']?\s*$""", re.I)), + ("password typed in YAML", re.compile(r"""^\s*(?:password|ap_password|wifi_password):\s*["']([^"'\n]{6,})["']""", re.I)), + ("GitHub token", re.compile(r"\b(gh[pousr]_[A-Za-z0-9]{30,}|github_pat_[A-Za-z0-9_]{40,})\b")), + ("Slack token", re.compile(r"\b(xox[abposr]-[A-Za-z0-9-]{10,})\b")), + ("AWS access key", re.compile(r"\b(AKIA[0-9A-Z]{16})\b")), + ("JSON Web Token", re.compile(r"\b(eyJ[A-Za-z0-9_-]{15,}\.eyJ[A-Za-z0-9_-]{15,}\.[A-Za-z0-9_-]{15,})")), + ("bearer token", re.compile(r"(?i)\bbearer\s+([A-Za-z0-9._~+/-]{32,}=*)")), +] + +found = 0 +for root, _, files in os.walk(DOCS): + for name in sorted(files): + if not name.endswith(EXTS): + continue + path = os.path.join(root, name) + for n, line in enumerate(open(path, encoding="utf-8", errors="replace"), 1): + for label, pat in PATTERNS: + for m in pat.finditer(line): + value = m.group(1) + if "!secret" in line or PLACEHOLDER.search(value): + continue + found += 1 + shown = value[:4] + "..." if len(value) > 8 else "..." + print(f"::error file={path},line={n}::Possible {label} ({shown}). Replace it with !secret or a placeholder, and rotate it if it was real.") + +print(f"check_secrets: {found} possible secret(s)") +sys.exit(1 if found else 0)