BamPocket

BamPocket — client iOS natif (open source) pour Bambuddy, l'outil auto-hébergé de gestion d'imprimantes 3D Bambu Lab. Projet tiers, non affilié à Bambuddy ni à Bambu Lab. « Bambuddy » et « Bambu Lab » sont des marques de leurs détenteurs ; la relecture/clearance pré-publication reste du ressort de l'utilisateur. Contexte : docs/adr/0004-nommage.md. Le dépôt GitHub conserve le slug historique bambuddy-pocket.

Qu'est-ce que c'est

Un client mobile iPhone + iPad (iOS 18+) qui se connecte à une ou plusieurs instances Bambuddy auto-hébergées et expose, dans une expérience native SwiftUI, l'essentiel de la gestion d'un parc d'imprimantes Bambu Lab : suivi temps réel, contrôles, file d'attente, archives, caméra, bibliothèque/projets, lancement d'impression et découpe. Ce n'est pas un clone de l'interface web : l'app exploite l'API au mieux pour une UX mobile soignée.

État du projet

v0.1 — périmètre applicatif complet. L'app couvre les parcours principaux de bout en bout ; elle reste en lecture seule vis-à-vis des imprimantes réelles pendant le développement (les écritures se testent sur une instance Docker de dev). Le dépôt est public pour bénéficier de l'intégration continue GitHub Actions. Restent volontairement hors v0.1 (Spoolman connecté, metrics Prometheus), un petit reste codable (rattachement d'un job de file à un projet) et les étapes de distribution liées à un compte Apple Developer. État détaillé : PROGRESS.md ; phases : ROADMAP.md.

⚠️ Avant toute publication de l'app (App Store) : la vérification de marque « Bambuddy » et la relecture juridique AGPL/exception restent à la charge de l'utilisateur (cf. en-tête et docs/adr/).

Fonctionnalités

• Temps réel : statut des imprimantes par WebSocket (fusion des deltas) avec repli REST automatique ; multi-imprimantes, badge de connexion.
• Multi-serveurs : plusieurs instances Bambuddy ajoutées par URL ; bascule rapide.
• Authentification : clé d'API, login utilisateur/mot de passe + 2FA par email, Cloudflare Access (service token) ; secrets au Keychain.
• Détail imprimante : températures (buse(s)/plateau/chambre), progression (couches, temps restant), ventilateurs détaillés, AMS (variantes standard/Lite/HT), erreurs HMS, profils K (lecture), capacités adaptatives par modèle.
• Contrôles : pause/reprise/stop, vitesse, lumière de chambre, clear HMS, AMS load/unload/reset/séchage, skip-objects, clear/home/calibration, bed-jog, airduct, connect, etc.
• File d'attente : liste + réordonnancement, ajout, start/stop/cancel/delete, édition d'item, lots (batches), mise à jour en lot, distribution automatique (temps réel).
• Historique & archives : liste paginée, détail (durée, filament, coût/énergie, timelapse), recherche serveur, favoris, édition, suppression, réimpression, rattachement à un projet.
• Lancement d'impression & découpe : lancer une impression depuis une archive ou un fichier de bibliothèque ; slicing d'un modèle en fichier imprimable via le sidecar serveur.
• Bibliothèque, projets & inventaire : arbre de dossiers, déplacement, corbeille, upload ; projets (nomenclature/BOM, chronologie, archives) ; inventaire filaments (consommation, reset).
• Caméra : snapshot + flux MJPEG, détection de plateau vide, flux/snapshot/vignette authentifiés via jeton (?token=).
• Viewer 3D embarqué (hors-ligne, Three.js) : STL / 3MF en maillage et G-code en parcours d'outil.
• Cloud & écosystème : compte Bambu Cloud, import MakerWorld, catalogue firmware (lecture), prises connectées, maintenance, catalogue de filaments, liens externes.
• Sauvegardes : locales (état/liste/déclenchement) et distantes Git (config/journal/run).
• Réglages & état serveur : langue, devise, imprimante par défaut, coûts ; /system/info + /system/health, clés d'API, journal d'impression, support/diagnostic.
• Expérience : iPad (barre latérale adaptative), thèmes clair/sombre, design system (Inter, Dynamic Type), i18n FR/EN/ES/DE, accessibilité VoiceOver.

Captures : docs/appstore/screenshots/. Installation sur appareil sans compte payant : docs/SIDELOAD.md.

Pile technique

• Swift + SwiftUI, architecture MVVM, async/await, injection de dépendances.
• Séparation nette réseau / domaine / UI.
• Dépendances tierces minimales (SPM), sinon maison.
• Tests unitaires + UI sur les chemins critiques ; SwiftLint + SwiftFormat ; build sans warning.
• CI GitHub Actions (build + tests + lint).

Connexion à un serveur Bambuddy

L'app gère plusieurs serveurs ajoutés par URL (schéma + hôte + port). Méthodes d'accès : LAN HTTP (exception ATS documentée + réseau local iOS), Tailscale/VPN, reverse proxy HTTPS, et Cloudflare Access par service token (en-têtes CF-Access-Client-Id / CF-Access-Client-Secret sur toutes les requêtes, y compris le WebSocket). Tous les secrets/tokens sont stockés au Keychain, jamais en clair ni dans le dépôt.

Développement

Pré-requis

• macOS + Xcode 26+ (iOS 18 SDK ou supérieur).
• Docker (pour l'instance Bambuddy de dev).

ℹ️ Si xcodebuild se plaint des Command Line Tools, Xcode est installé mais non sélectionné. Soit sudo xcode-select -s /Applications/Xcode.app/Contents/Developer, soit exporter DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer (utilisé par les scripts/CI locaux).

Backend de dev (Docker, macOS)

Docker Desktop ne gère pas network_mode: host : dans docker-compose.yml commenter network_mode: host, décommenter ports: (au moins 8000). La découverte d'imprimantes ne marche pas → ajout par IP manuel.

docker compose up -d
curl -s http://localhost:8000/health            # {"status":"healthy"}
open http://localhost:8000/docs                  # Swagger

La démo https://bambuddy.cool sert de référence en lecture seule (jamais d'écriture).

Projet iOS (génération & build)

Le projet Xcode est généré depuis project.yml via XcodeGen (brew install xcodegen) — le .xcodeproj n'est pas versionné (source de vérité = project.yml).

xcodegen generate         # crée BamPocket.xcodeproj
open BamPocket.xcodeproj  # ouvrir dans Xcode, ou builder en CLI ↓
xcodebuild -project BamPocket.xcodeproj -scheme BamPocket \
  -destination 'platform=iOS Simulator,name=iPhone 17' build test
(cd Packages/BambuddyPocketKit && swift test)   # tests du paquet SPM

Le code est organisé en : cible app BamPocket (SwiftUI) + paquet SPM local BambuddyPocketKit (modules …Domain, …Networking, …DesignSystem — noms internes conservés). Cf. docs/adr/0002-architecture.md.

Documentation

• docs/bambuddy-api.md — contrat d'API (REST + WebSocket + modèles).
• docs/api/openapi.json — spec OpenAPI brute (source machine).
• docs/api/rest-endpoints.md — catalogue exhaustif des 621 endpoints.
• docs/adr/ — décisions d'architecture (ADR).
• docs/SIDELOAD.md — installer l'app sur votre iPhone (free provisioning, sans compte développeur payant).
• CONTRIBUTING.md — guide de contribution.

Licence

GNU AGPL-3.0-or-later (voir LICENSE) — aligné sur Bambuddy (lui-même AGPL-3.0), avec une permission additionnelle (AGPLv3 §7) autorisant la distribution via l'App Store et les plateformes analogues (voir LICENSE-APP-STORE-EXCEPTION.md). Contexte et alternatives écartées : docs/adr/0001-licence.md. En-têtes de fichiers : SPDX-License-Identifier: AGPL-3.0-or-later.