Domoticz Mobile - Application de contrôle pour Domoticz

📌 Table des Matières

1. Domoticz Mobile
2. Prérequis
3. Installation
4. Variables d'Environnement
5. Configuration SSL/TLS
6. Scripts npm
7. Build & Déploiement
8. Architecture & Patterns
9. Fonctionnalités
10. Tests
11. Contribution
12. Maintenance
13. Licence

---

Domoticz Mobile

Application mobile pour piloter les équipements Domoticz. Développée avec React Native et Expo, elle cible principalement Android et le web.

📋 Prérequis

Avant de commencer, assurez-vous d'avoir :

• Node.js 24 — version figée via .nvmrc et engines.node: ">=24" dans package.json. Utilisez nvm use pour aligner automatiquement votre environnement local sur la version attendue par la CI.
• npm 6 ou supérieur (inclus avec Node.js)
• Expo CLI via npx expo (guide officiel)

# Aligner Node.js sur la version du projet (si nvm installé)
nvm use

# Vérifier les versions
node --version   # v24.x.x ou supérieur
npm --version    # v6.0.0 ou supérieur

# Vérifier Expo CLI (via npx)
npx expo --version

Plateforme cible : Android et Web (React Native via Expo)

Stack technologique :

• Expo SDK ~56.0.13
• React 19.2.3
• React Native 0.85.3
• TypeScript strict mode
• expo-router ~56.2.12
• Jest + jest-expo (tests)
• ESLint 9.39.1 (flat config, eslint.config.js — seule source de vérité)

🚀 Installation

Étape 1 : Cloner le dépôt

git clone https://github.com/vzwingma/domotique-mobile.git
cd domotique-mobile

Étape 2 : Installer les dépendances

npm install

Cette commande installe toutes les dépendances listées dans package.json, y compris React Native, Expo, TypeScript, Jest et ESLint.

🔑 Variables d'Environnement

La configuration de l'application passe exclusivement par des variables d'environnement préfixées EXPO_PUBLIC_, qui sont disponibles au build time.

Configuration de Base

Créez un fichier .env.local à la racine du projet (non versionné) :

# URL du serveur Domoticz (inclure le port si nécessaire)
# Format: http://HOST:PORT/ ou https://HOST:PORT/
EXPO_PUBLIC_DOMOTICZ_URL=http://192.168.1.x:8080/

# Authentification Basic Auth encodée en Base64
# Format: "login:password" encodé en Base64
EXPO_PUBLIC_DOMOTICZ_AUTH=<Base64 de login:password>

# Environnement courant (optionnel, par défaut: "production")
# Valeurs: development, staging, production
EXPO_PUBLIC_MY_ENVIRONMENT=development

# Domaine du serveur Domoticz pour la configuration SSL
# Format: IP ou FQDN SANS protocole ni port (ex: 192.168.1.100 ou domotique.home.local)
# Requis pour le support HTTPS avec certificat auto-signé
EXPO_PUBLIC_DOMOTICZ_DOMAIN=192.168.1.x

Générer la valeur Base64

Pour encoder vos identifiants :

# macOS/Linux
echo -n "monlogin:monmotdepasse" | base64

# Windows (PowerShell)
[Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes("monlogin:monmotdepasse"))

Variables Disponibles

Variable	Requis	Description
EXPO_PUBLIC_DOMOTICZ_URL	✅ Oui	URL serveur Domoticz avec protocole et port
EXPO_PUBLIC_DOMOTICZ_AUTH	✅ Oui	Identifiants Basic Auth encodés en Base64
EXPO_PUBLIC_DOMOTICZ_DOMAIN	⚠️ Si HTTPS + certificat auto-signé	Domaine pour configuration SSL
EXPO_PUBLIC_MY_ENVIRONMENT	❌ Non	Environnement d'exécution (debug info)

🔐 Configuration SSL/TLS

Si votre serveur Domoticz utilise HTTPS avec un certificat auto-signé, suivez ces étapes :

1. Exporter le certificat depuis votre serveur

openssl s_client -connect <HOST>:<PORT> -showcerts </dev/null 2>/dev/null \
  | openssl x509 -outform PEM > domoticz.crt
# Exemple :
openssl s_client -connect 192.168.1.100:8443 -showcerts </dev/null 2>/dev/null \
  | openssl x509 -outform PEM > domoticz.crt

Ou via un navigateur : cadenas → Certificat → Exporter au format PEM/Base64.

2. Placer le certificat dans le projet

assets/
  certificates/
    domoticz.crt   ← votre certificat ici (format PEM)

3. Configurer l'URL dans .env.local

EXPO_PUBLIC_DOMOTICZ_URL=https://domatique.freeboxos.fr:38243/

Le domaine est configuré directement dans app.json en option du plugin (pas via variable d'environnement).

4. Lancer le build natif

Le plugin SSL ne s'applique pas avec npm start (Expo Go). Il faut un build natif :

Commande	Contexte	SSL
npm start	Expo Go — développement rapide	❌
npm run android	Build local Android (nécessite SDK + JDK)	✅
npm run android:clean	Build local force-clean (plugin garanti)	✅
npm run start:dev-client	Dev-client déjà buildé (EAS development)	✅
eas build --profile previewV	APK distribution interne	✅

Pour développer localement avec SSL :

npm run android          # prebuild + compile + installe sur l'appareil/émulateur

Les modifications JS sont ensuite rechargées à chaud sans recompiler.

Si le premier build ne résout pas le problème (fichiers natifs en cache) :

npm run android:clean    # force un prebuild complet

Note Web : Pour le navigateur, acceptez l'exception de sécurité en naviguant manuellement vers l'URL HTTPS de Domoticz une première fois.

Scripts npm

npm start                                           # Serveur Metro (Expo Go — sans SSL)
npm run start:dev-client                            # Serveur Metro pour expo-dev-client (avec SSL)
npm run android                                     # Build natif Android + lancement (avec SSL)
npm run android:clean                               # Build natif Android force-clean (avec SSL)
npm run web                                         # Lancer dans le navigateur
npm test                                            # Tests Jest en mode watch
npm test -- path/to/file.test.tsx                   # Un fichier de test précis
npm test -- --testNamePattern="nom du test"         # Tests filtrés par nom
npm run lint                                        # ESLint via Expo
npm run validate:expo                               # Expo Doctor (environnement + cohérence Expo)

Builds EAS (distribution APK Android) :

npm run eas:build:development       # Dev-client (à utiliser avec npm run start:dev-client)
npm run eas:build:production        # Build de production
npm run eas:submit                  # Soumission du build de production vers le store

Les builds previewV/previewC sont déclenchés automatiquement à chaque push sur main via un EAS Workflow natif (.eas/workflows/android-build-main-workflow.yml) — aucune commande manuelle requise pour ce cas. Détails complets : docs/DEPLOIEMENT.md.

🚢 Build & Déploiement

Le déploiement Android combine build automatique et scripts manuels :

• Preview automatique : previewV → previewC construits à chaque push sur main (EAS Workflow natif).
• Development/Production/Submit : scripts npm dédiés (eas:build:development, eas:build:production, eas:submit), déclenchés manuellement.
• Keystore de production : géré exclusivement via eas credentials (EAS Credentials), jamais par un fichier committé dans le repo.

Procédure complète (y compris la gestion opérationnelle non-sensible du keystore) : docs/DEPLOIEMENT.md.

🏗️ Architecture & Patterns

Pour une documentation complète de l'architecture, des patterns utilisés, de la structure des dossiers, et de la gestion d'état globale, consultez docs/ARCHITECTURE.md.

Points clés :

• Flux de données : UI → Controller → Services → Serveur Domoticz
• État global : React Context API via DomoticzContextProvider
• Routage : Expo Router avec file-based routing
• HTTP : Centralisé dans ClientHTTP.service.ts avec Basic Auth
• Patterns : Controllers, Services, Models (avec TypeScript strict)

✅ Tests

L'application utilise Jest avec le preset react-native pour les tests unitaires et snapshot testing. Pour une validation locale/pré-PR, les tests unitaires seuls ne suffisent plus : expo-doctor est désormais un gate obligatoire via npm run validate:expo.

# Lancer les tests en mode watch
npm test

# Tester un fichier spécifique
npm test -- path/to/file.test.tsx

# Tests filtrés par nom
npm test -- --testNamePattern="mon pattern"

# Linter le code
npm run lint

# Vérifier la santé Expo (obligatoire avant PR)
npm run validate:expo

Politique de couverture :

• Objectifs cibles par couche : controllers 100%, services ≥90%, composants ≥70%, modèles ≥85%.
• Dans .github/workflows/ci.yml, l'étape nyc --check-coverage (job test) est informative uniquement (continue-on-error: true) — elle ne bloque pas la CI en cas de seuil non atteint.
• Le blocage réel est délégué au Quality Gate SonarCloud (sonar.qualitygate.wait=true), qui échoue la CI si la couverture ou la qualité du code régresse. Détail de cette décision : ADR-009 — Seuil de couverture CI.
• Pas de tests E2E/intégration actuellement.
• Snapshot tests pour les composants UI.

Pour plus de détails sur le setup Jest, les conventions de test, et les meilleures pratiques, consultez docs/TESTING.md.

Fonctionnalités

• Navigation par 5 onglets (Favoris, Lumières, Volets, Températures, Maison) avec header unifié (icône d'onglet + titre + badge de connexion)
• Badge de connexion unifié sur tous les onglets avec 4 états UI canoniques : Connecté, Synchronisation, Déconnecté, Erreur
• Écran Favoris orienté actions rapides : cartes 1 tap (action principale + bouton), slider conditionnel disponible en mode previewC, limité aux 7 favoris actifs les plus utilisés
• Affichage et contrôle des lumières (on/off, variateur) avec labels métier "Allumé"/"Éteint" et état synthétique pour les groupes ("Éteintes" / "Allumées" / "Mixte" / niveau%)
• Gestion des volets/stores (ouverture/fermeture via slider et clic icône) avec labels "Ouvert"/"Fermé" ; confirmation modale pour les actions sur groupe de volets (nom contenant "Tous")
• Consultation des capteurs de température avec indicateurs "Déconnecté"/"Inconnu" pour les capteurs inactifs
• Contrôle des thermostats (point de consigne ajustable par paliers de ±0,5°C, affichage distinct Mesure / Consigne)
• Gestion des groupes d'équipements (indicateur "Mixte" pour niveaux incohérents)
• Écran Maison : paramètres interactifs (présence, phase) via chips segmentés + section "À propos" (version app, version serveur Domoticz, statut connexion)

Composants UI principaux

Composant	Fichier	Rôle
DeviceComponent	app/components/device.component.tsx	Orchestrateur : délègue à ViewLightDevice ou ViewBlindDevice selon le type
ViewLightDevice	app/components/lightDevice.component.tsx	Affichage et contrôle d'une lumière individuelle ou groupe (on/off, variateur)
ViewBlindDevice	app/components/blindDevice.component.tsx	Affichage et contrôle d'un volet individuel ou groupe (slider, résumé groupe)
DeviceCard	app/components/deviceCard.component.tsx	Carte générique réutilisée par ViewLightDevice et ViewBlindDevice
FavoriteCard	app/components/favoriteCard.component.tsx	Carte favori "action rapide" (1 tap) ; slider conditionnel en mode previewC
PrimaryIconAction	app/components/primaryIconAction.component.tsx	Bouton icône principal utilisé dans les cartes d'équipements et favoris
DisconnectedState	app/components/disconnectedState.component.tsx	Indicateur visuel "Déconnecté" pour les équipements inactifs
TemperatureComponent	app/components/temperature.component.tsx	Card compacte pour un capteur de température
ThermostatComponent	app/components/thermostat.component.tsx	Contrôle de consigne thermostat avec boutons ±0,5°C
ParamListComponent	app/components/paramList.component.tsx	Paramètres interactifs (présence, phase) via chips segmentés

🤝 Contribution

Pour contribuer à ce projet :

1. Consultez le guide complet : CONTRIBUTING.md
2. Points clés :
   • Fork le dépôt
   • Créez une branche feature/ ou fix/ explicite
   • Respectez les conventions TypeScript et Expo du projet
   • Lancez npm test, npm run lint et npm run validate:expo avant de soumettre
   • Soumettez une Pull Request avec une description claire

En savoir plus :

• Git workflow (main/develop/feature)
• Setup local dev environment
• Code style & linting conventions
• Commit message format

Consultez CONTRIBUTING.md pour tous les détails.

🔭 Maintenance

• Veille des versions majeures (Expo SDK, React, React Native) : revue trimestrielle + alerte automatisée mensuelle, basées sur le Dependency Dashboard Renovate. Processus détaillé : docs/PROCESS-VEILLE-VERSIONS.md (voir ADR-007).
• Renovate : patches en automerge, montées de version majeures créées en PR draft (jamais automergées) — revue manuelle requise, cf. document de veille ci-dessus.

📄 Licence

Ce projet est sous licence MIT. Consultez le fichier LICENSE pour plus d'informations.