Skip to content

feat: add protected headless provisioning workflow#178

Open
JeremyWhittaker wants to merge 1 commit into
infinition:mainfrom
JeremyWhittaker:feature/headless-provisioning
Open

feat: add protected headless provisioning workflow#178
JeremyWhittaker wants to merge 1 commit into
infinition:mainfrom
JeremyWhittaker:feature/headless-provisioning

Conversation

@JeremyWhittaker

Copy link
Copy Markdown

Summary

This PR adds a protected headless provisioning workflow for Bjorn.

When Bjorn cannot join Wi-Fi, it can now expose a temporary setup path for phone-based recovery instead of requiring SSH or direct file edits. The primary recovery path is a fallback setup AP with a small setup page. A secondary Bluetooth PAN path is also exposed for Android phones, but the AP remains the preferred offline-management path.

What Changed

  • added bjorn-connectivity.service to manage connectivity state
  • added a fallback bjorn-setup access point for offline provisioning
  • added a dedicated /setup.html onboarding page and a matching setup script
  • added a simple setup-access gate using a 6-digit code shown on the e-paper display
  • moved Wi-Fi connect/scan flow to nmcli / NetworkManager-based handling
  • added a lock to prevent setup AP recovery from racing with in-progress Wi-Fi joins
  • added port 80 redirect support for simpler phone access to the web UI
  • hardened local setup endpoints and file download/restore paths
  • updated installation and troubleshooting documentation for the new provisioning flow

Why

Today, Bjorn is difficult to recover when it is headless and offline:

  • there is no universal phone-friendly recovery path when saved Wi-Fi is unavailable
  • changing Wi-Fi credentials requires SSH or manual file edits
  • temporary provisioning flows are easy to interrupt during network transitions

This PR adds a practical recovery path for new installs and field use without changing the default operating model when Bjorn is already on normal Wi-Fi.

Scope

Primary path:

  • setup AP on 192.168.4.1
  • protected setup UI for entering Wi-Fi credentials
  • on-screen setup code and setup-password hints

Secondary path:

  • Bluetooth PAN on 172.22.0.1
  • Android-oriented local management path
  • explicit UI guidance that Bluetooth PAN is secondary and may require disabling Wi-Fi/mobile data on the phone

Testing

Tested manually on Raspberry Pi Zero / Raspberry Pi OS with NetworkManager and BlueZ:

  • verified bjorn-connectivity.service lifecycle
  • verified setup AP startup and protected setup page access
  • verified setup code unlock flow from a phone browser
  • verified Wi-Fi scan and connect flow from the setup UI
  • verified failed Wi-Fi join recovers cleanly without fighting the setup manager
  • verified Bluetooth PAN comes up on Android and serves the setup UI from 172.22.0.1:8000
  • verified phone-facing setup copy and display overlays on the e-paper screen

Notes

  • the setup AP is the primary offline provisioning path
  • Bluetooth PAN is kept as a secondary Android-only convenience path
  • this PR intentionally leaves the existing normal web UI unchanged when Bjorn is already on Wi-Fi
  • this PR complements feat: add optional Bluetooth pairing display workflow #177 but is intended to stand on its own from a user-workflow perspective

@gitguardian

gitguardian Bot commented Mar 13, 2026

Copy link
Copy Markdown

⚠️ GitGuardian has uncovered 1 secret following the scan of your pull request.

Please consider investigating the findings and remediating the incidents. Failure to do so may lead to compromising the associated services or software components.

Since your pull request originates from a forked repository, GitGuardian is not able to associate the secrets uncovered with secret incidents on your GitGuardian dashboard.
Skipping this check run and merging your pull request will create secret incidents on your GitGuardian dashboard.

🔎 Detected hardcoded secret in your pull request
GitGuardian id GitGuardian status Secret Commit Filename
- - Generic Password c43e2a0 connectivity_manager.py View secret
🛠 Guidelines to remediate hardcoded secrets
  1. Understand the implications of revoking this secret by investigating where it is used in your code.
  2. Replace and store your secret safely. Learn here the best practices.
  3. Revoke and rotate this secret.
  4. If possible, rewrite git history. Rewriting git history is not a trivial act. You might completely break other contributing developers' workflow and you risk accidentally deleting legitimate data.

To avoid such incidents in the future consider


🦉 GitGuardian detects secrets in your source code to help developers and security teams secure the modern development process. You are seeing this because you or someone else with access to this repository has authorized GitGuardian to scan your pull request.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant