chore : update env defaults and make targets

2026-01-10 11:36:34 +01:00
parent d9eda4746a
commit 3292dfbede
6 changed files with 241 additions and 86 deletions
--- a/README.md
+++ b/README.md
@@ -1,15 +1,15 @@
-# Pont Bascule Connector (Raspberry Pi) — FastAPI + Serial + Tailscale
+# Pont Bascule Connector — FastAPI + Serial + (optionnel) Tailscale

-API HTTP (FastAPI) qui pilote un pont bascule connecté en USB (port série) sur Raspberry Pi.
+API HTTP (FastAPI) qui pilote un pont bascule connecté en USB (port série) sur Raspberry Pi ou Linux.

-**Objectif :** permettre à une application/serveur distant d'interroger le pont bascule via réseau (Tailscale), avec une contrainte stricte : **1 requête série à la fois**.
+**Objectif :** permettre à une application/serveur distant d'interroger le pont bascule via réseau, avec une contrainte stricte : **1 requête série à la fois**.

 ---

 ## Fonctionnement global

 ```
-Client (PC / serveur / app) --HTTP--> Raspberry Pi (FastAPI)
+Client (PC / serveur / app) --HTTP--> Machine (FastAPI)
                                      |
                                      | 1 appel à la fois (lock)
                                      v
@@ -19,58 +19,78 @@ Client (PC / serveur / app) --HTTP--> Raspberry Pi (FastAPI)
                                 Pont bascule
 ```

-**Accès distant :**
+**Accès distant (optionnel) :**
 - via IP Tailscale `100.x.x.x` (VPN mesh)
- optionnellement via `tailscale serve` pour exposer l'API sur le port 80 sans `:8000`
+- ou autre VPN / reverse-proxy selon votre infra

 ---

 ## Prérequis

-### Raspberry Pi
- Raspberry Pi OS (Lite recommandé)
- Python 3
- Accès SSH
- Tailscale installé et connecté
-
 ### Matériel
 - Pont bascule branché en USB (ou via adaptateur USB↔RS232/RS485 selon le matériel)

+### Système
+- Raspberry Pi OS / Debian / Ubuntu (autres Linux OK)
+- Python 3.9+ recommandé
+- Accès SSH
+- (optionnel) Tailscale installé et connecté
+
 ---

-## Installation (Raspberry Pi)
+## Installation

 ### 1) Récupérer le projet

 ```bash
 cd ~
-git clone <URL_DE_TON_REPO> pont-bascule-connector
+git clone gitea@gitea.malio.fr:MALIO-DEV/pont-bascule-connector.git
 cd pont-bascule-connector
 ```

-### 2) Environnement Python
-
-Deux options :
-
-#### Option A : venv global (recommandé si déjà en place)
+### 2) Installer les dépendances système (Debian/Ubuntu/Raspberry Pi OS)

 ```bash
-python3 -m venv /home/malio/venv
-source /home/malio/venv/bin/activate
+sudo apt update
+sudo apt install -y python3 python3-venv python3-pip git
+```
+
+Si vous êtes sur un autre OS, installez Python 3 + pip + venv via votre gestionnaire de paquets.
+
+### 3) Installer les dépendances Python
+
+```bash
+python3 -m venv ./.venv
+source ./.venv/bin/activate
 pip install --upgrade pip
 pip install -r requirements.txt
 ```

-#### Option B : venv dans le projet
+---
+
+## Hook git (commit-msg)
+
+Le repo contient un hook pour valider le format des messages de commit.
+
+Activation :

 ```bash
-python3 -m venv ./venv
-source ./venv/bin/activate
-pip install --upgrade pip
-pip install -r requirements.txt
+git config core.hooksPath .githooks
 ```

-### 3) Configuration série (.env)
+Format attendu :
+
+```text
+<type>(<scope optionnel>) : <message>
+```
+
+Types autorisés : `build`, `chore`, `ci`, `docs`, `feat`, `fix`, `perf`, `refactor`, `revert`, `style`, `test`.
+
+---
+
+## Configuration série (.env)
+
+Le fichier `.env` est chargé automatiquement au démarrage (via `python-dotenv`).

 Créer un fichier `.env` à la racine du projet :

@@ -79,9 +99,12 @@ cd ~/pont-bascule-connector
 nano .env
 ```

-Exemple :
+Exemple (mode reel / port serie) :

 ```env
+APP_MODE=serial
+APP_HOST=0.0.0.0
+APP_PORT=8000
 SERIAL_PORT=/dev/ttyUSB0
 SERIAL_BAUDRATE=9600
 SERIAL_TIMEOUT_S=1.0
@@ -89,16 +112,28 @@ SERIAL_OPEN_DELAY_S=2.0
 SERIAL_POST_WRITE_DELAY_S=0.5
 ```

+Exemple (mode mock pour dev, sans port serie) :
+
+```env
+APP_MODE=mock
+APP_HOST=0.0.0.0
+APP_PORT=8000
+```
+
 **Notes importantes :**

+- `APP_MODE=serial` (defaut) utilise le port serie ; `APP_MODE=mock` simule les reponses pour le dev.
+- `APP_HOST` et `APP_PORT` permettent de changer l'interface d'ecoute et le port HTTP.
 - `SERIAL_OPEN_DELAY_S=2.0` et `SERIAL_POST_WRITE_DELAY_S=0.5` reproduisent le comportement du script Tkinter historique :
  - attente 2s après ouverture du port
  - envoi trame
  - attente 0.5s
  - lecture une seule fois de `in_waiting`
- Si ton port est `/dev/ttyACM0`, adapte `SERIAL_PORT`
+- Si votre port est `/dev/ttyACM0`, adaptez `SERIAL_PORT`

-### 4) Droits port série (dialout)
+---
+
+## Droits port série (dialout)

 Vérifier les devices :

@@ -108,19 +143,21 @@ ls /dev/ttyACM* 2>/dev/null || true
 dmesg | tail -n 30
 ```

-Ajouter l'utilisateur au groupe `dialout` :
+Ajouter l'utilisateur courant au groupe `dialout` :

 ```bash
-sudo usermod -aG dialout malio
-sudo reboot
+sudo usermod -aG dialout "$USER"
+newgrp dialout
 ```

+Si besoin, reconnectez-vous (ou redémarrez) pour que les droits prennent effet.
+
 ---

 ## Lancer l'API (mode manuel)

 ```bash
-source /home/malio/venv/bin/activate   # ou ./venv/bin/activate
+source ./.venv/bin/activate
 uvicorn app.main:app --host 0.0.0.0 --port 8000
 ```

@@ -140,19 +177,19 @@ curl http://127.0.0.1:8000/health
 sudo nano /etc/systemd/system/pont-bascule-api.service
 ```

-Contenu (adapter les chemins si nécessaire) :
+Contenu (adapter les chemins et l'utilisateur) :

 ```ini
 [Unit]
 Description=Pont bascule API (FastAPI)
-After=network-online.target tailscaled.service
+After=network-online.target
 Wants=network-online.target

 [Service]
-User=malio
-WorkingDirectory=/home/malio/pont-bascule-connector
-EnvironmentFile=/home/malio/pont-bascule-connector/.env
-ExecStart=/home/malio/venv/bin/uvicorn app.main:app --host 0.0.0.0 --port 8000
+User=<votre_user>
+WorkingDirectory=/home/<votre_user>/pont-bascule-connector
+EnvironmentFile=/home/<votre_user>/pont-bascule-connector/.env
+ExecStart=/home/<votre_user>/pont-bascule-connector/.venv/bin/uvicorn app.main:app --host 0.0.0.0 --port 8000
 Restart=always
 RestartSec=2

@@ -255,18 +292,18 @@ Si une requête est déjà en cours, l'API renvoie :

 ---

-## Accès à distance via Tailscale
+## Accès à distance via Tailscale (optionnel)

 ### 1) Vérifier Tailscale

-Sur le Raspberry :
+Sur la machine :

 ```bash
 tailscale status
 tailscale ip -4
 ```

-Exemple : IP Tailscale du Pi `100.122.43.54`.
+Exemple : IP Tailscale `100.122.43.54`.

 ### 2) Appeler l'API via Tailscale (simple)

@@ -277,7 +314,7 @@ curl -X POST http://100.122.43.54:8000/send/esclave

 ### 3) Option recommandée : exposer sans port avec `tailscale serve`

-Sur le Raspberry :
+Sur la machine :

 ```bash
 sudo tailscale serve --http=80 localhost:8000
@@ -291,12 +328,6 @@ curl http://100.122.43.54/health
 curl -X POST http://100.122.43.54/send/esclave
 ```

-### 4) SSH via Tailscale
-
-```bash
-tailscale ssh malio@raspberrypi
-```
-
 ---

 ## Dépannage rapide
@@ -330,7 +361,7 @@ groups

 ---

-## Sécurité recommandée (à faire)
+## Sécurité recommandée (optionnel)

 1. **Exposer l'API uniquement via Tailscale :**
   - faire écouter uvicorn en local seulement (`--host 127.0.0.1`)
@@ -342,29 +373,8 @@ groups

 ---

-## Autres recommandations (vraiment utiles)
+## Recommandations utiles

-### 1) Sécuriser l'API
+### Port série stable (udev)

-Aujourd'hui tu exposes `0.0.0.0:8000` → accessible depuis le LAN.
-
-Si tu veux "Tailscale only" (recommandé) :
- Dans systemd : `--host 127.0.0.1`
- Et tu actives `tailscale serve --http=80 localhost:8000`
-
-### 2) Ajouter une route `/weight`
-
-Tu m'envoies 1 exemple de `response_ascii` (exact) et je te code un parseur robuste qui sort :
-
-```json
-{
-  "weight": 12.34,
-  "unit": "kg",
-  "ticket": "000123",
-  "raw": "..."
-}
-```
-
-### 3) Port série stable (udev)
-
-Si ton port passe parfois de `/dev/ttyUSB0` à `/dev/ttyUSB1`, on peut créer une règle udev pour avoir un nom fixe, genre `/dev/pontbascule`.
+Si votre port passe parfois de `/dev/ttyUSB0` à `/dev/ttyUSB1`, on peut créer une règle udev pour avoir un nom fixe (ex: `/dev/pontbascule`).