# methyx/visioconf-rence-pour-ehpad architecture

> Architecture diagram of the GitHub repository methyx/visioconf-rence-pour-ehpad, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/methyx/visioconf-rence-pour-ehpad
- Repository: https://github.com/methyx/visioconf-rence-pour-ehpad

## Overview

1. This repository is a Raspberry Pi appliance project, not a typical server or web app. The core product is a “Keep In Touch Box” for EHPADs: a TV-connected box that automates Google Duo calls, optionally acts as a photo frame, and is controlled through physical buttons and GPIO peripherals.

2. The main runtime is a single Python application, `KIT_Box_V10.py`. It is the orchestration layer for almost everything: startup mode selection, call handling, photo-frame behavior, menu dialogs, GPIO button/LED handling, TV control, fan control, logging, and USB photo import.

3. The user interface is intentionally minimal and mixed-modal:
   - physical buttons on the box drive actions,
   - Chromium/Google Duo provides the call UI,
   - the program watches the screen and simulates clicks/keypresses,
   - in remote maintenance mode, keyboard shortcuts emulate the hardware buttons.
   This means the architecture depends heavily on screen state rather than on a Duo API.

4. The call-handling subsystem is built around screen scraping and automation. Every few seconds the program captures the screen area where Duo notifications appear, performs character recognition on that capture, and uses the result to detect incoming calls, ongoing calls, and call end. It then accepts or rejects calls by simulating UI actions.

5. The hardware boundary is the Raspberry Pi GPIO layer plus Grove accessories. The box uses three LED buttons:
   - red: reject / block calls / menu access,
   - blue: navigation / system menu,
   - yellow: validation.
   These inputs are paired with LED outputs for user feedback. The README also maps the fan, IR receiver, and IR emitter to fixed GPIO pins, so the Python app is the single controller across all attached peripherals.

6. TV control is a distinct subsystem with two modes:
   - “photo frame” mode, where the connected TV is automatically turned on/off on schedule and shows a slideshow;
   - “TV” mode, where the box works with the user’s existing TV and switches to/from the HDMI input as needed.
   The app first tries HDMI-CEC for TV power/input actions, and falls back to IR commands when CEC is unreliable. That makes TV control an abstraction with two transport paths: CEC and IR.

7. The photo-frame subsystem is file-based. During active hours it can:
   - display a randomized slideshow of JPG files from a configured directory,
   - scale images automatically,
   - import photos from a USB key by letting the user browse a folder with the buttons and then copy it into the Raspberry Pi photo store.
   This is separate from Duo call handling, but shares the same wake/sleep and TV control logic.

8. There is a time-based scheduler governing the appliance. The box only behaves fully during configured “wake” hours, and outside those hours it can sleep the display/TV. The same schedule determines when incoming calls are accepted, when the photo frame runs, and when menu interactions are available.

9. The call-blocking feature is another stateful subsystem. A press on the red button can open a dialog to block calls for 15, 30, 45, or 60 minutes. During that period the box rejects incoming calls and keeps the red LED on. This is a temporary override layered on top of the normal call-accept behavior.

10. Logging is treated as a first-class function. The system records:
   - call log: received/accepted/refused calls and duration,
   - system log: operational events, reset on each startup but preserved as the previous version.
   These logs are an important output boundary for caregivers or maintenance.

11. Thermal management is handled independently from call logic. The fan is activated or stopped based on CPU temperature, which implies the Python process is also periodically reading system telemetry and driving a GPIO output accordingly.

12. `Parametres.txt` is the main configuration boundary. It is required in `/home/pi/Documents/` and controls startup mode, schedules, photo paths, TV behavior, IR command names, durations, and other operational settings. The app is therefore designed to be deployed as a configurable appliance rather than as a compiled binary.

13. `enregistrer_telecommande.sh` supports one specific integration path: learning IR remote commands using `irrecord`. This indicates the project expects real-world TV heterogeneity and includes a tooling boundary for capturing device-specific IR codes.

14. The repository also contains deployment and hardware artifacts rather than application code:
   - 3D printable box STL files,
   - installation guides in PDF/RTF,
   - screenshots/photos zip archives.
   These support physical assembly and operator setup, but the execution architecture remains centered on the Raspberry Pi, Chromium/Google Duo, GPIO hardware, and screen automation.

Main entry points: [`KIT_Box_V10.py`](https://github.com/methyx/visioconf-rence-pour-ehpad/blob/main/KIT_Box_V10.py) (KIT_Box_V10.py), [`Parametres.txt`](https://github.com/methyx/visioconf-rence-pour-ehpad/blob/main/Parametres.txt) (Parametres.txt), [`enregistrer_telecommande.sh`](https://github.com/methyx/visioconf-rence-pour-ehpad/blob/main/enregistrer_telecommande.sh) (IR Learning)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_app["KIT_Box_V10.py<br/>orchestrator<br/>[KIT_Box_V10.py]"]
  node_scheduler(("Wake Schedule<br/>time control"))
  node_callauto["Call Automation<br/>screen automation"]
  node_screenocr["Screen OCR<br/>vision step"]
  node_duoui["Chromium Duo<br/>external UI"]
  node_photoframe["Photo Frame<br/>slideshow"]
  node_usbimport["USB Import<br/>file import"]
  node_callblock(("Call Block<br/>state override"))
end

subgraph group_hardware["Hardware"]
  node_buttons["Button Logic<br/>input handling"]
  node_leds(("LED Feedback<br/>gpio output"))
  node_gpiolayer["GPIO Peripherals<br/>hardware boundary"]
  node_tvctrl["TV Control<br/>device control"]
  node_cec(("HDMI-CEC<br/>transport"))
  node_irctrl(("IR Control<br/>transport"))
  node_fan(("Fan Control<br/>thermal control"))
end

subgraph group_ops["Ops"]
  node_cfg["Parametres.txt<br/>config<br/>[Parametres.txt]"]
  node_logs["Call Logs<br/>audit log"]
  node_syslog["System Log<br/>operational log"]
  node_remote["IR Learning<br/>tooling"]
  node_artifacts["Physical Artifacts<br/>deployment assets"]
end

node_app -->|"reads"| node_cfg
node_app -->|"drives"| node_scheduler
node_app -->|"runs"| node_callauto
node_callauto -->|"captures"| node_screenocr
node_callauto -->|"acts on"| node_duoui
node_app -->|"handles"| node_buttons
node_buttons -->|"uses"| node_gpiolayer
node_app -->|"updates"| node_leds
node_leds -->|"uses"| node_gpiolayer
node_app -->|"controls"| node_tvctrl
node_tvctrl -->|"tries first"| node_cec
node_tvctrl -->|"falls back to"| node_irctrl
node_app -->|"runs"| node_photoframe
node_photoframe -->|"imports via"| node_usbimport
node_app -->|"opens"| node_callblock
node_callblock -->|"overrides"| node_callauto
node_app -->|"records"| node_logs
node_app -->|"records"| node_syslog
node_app -->|"monitors"| node_fan
node_app -->|"supports"| node_remote
node_app -.->|"ships with"| node_artifacts
node_cfg -->|"configures"| node_tvctrl
node_cfg -->|"configures"| node_photoframe
node_cfg -->|"configures"| node_scheduler

click node_app "https://github.com/methyx/visioconf-rence-pour-ehpad/blob/main/KIT_Box_V10.py"
click node_cfg "https://github.com/methyx/visioconf-rence-pour-ehpad/blob/main/Parametres.txt"
click node_remote "https://github.com/methyx/visioconf-rence-pour-ehpad/blob/main/enregistrer_telecommande.sh"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_scheduler,node_callauto,node_screenocr,node_duoui,node_photoframe,node_usbimport,node_callblock toneBlue
class node_buttons,node_leds,node_gpiolayer,node_tvctrl,node_cec,node_irctrl,node_fan toneAmber
class node_cfg,node_logs,node_syslog,node_remote,node_artifacts toneMint
```

## Components

### Runtime

Core appliance software and its main control flow

- [KIT_Box_V10.py](https://github.com/methyx/visioconf-rence-pour-ehpad/blob/main/KIT_Box_V10.py): orchestrator · Main Python appliance runtime coordinating startup, screen automation, GPIO, TV, photo frame, logging, and scheduling · `KIT_Box_V10.py`
- **Wake Schedule**: time control · Controls active hours, sleep behavior, and when calls or photo frame actions are allowed
- **Call Automation**: screen automation · Detects Duo call state from screen captures and drives accept/reject actions through simulated input
- **Screen OCR**: vision step · Captures the Duo notification area and extracts text to infer incoming, ongoing, or ended calls
- **Chromium Duo**: external UI · Google Duo running in Chromium as the call interface used by the box
- **Photo Frame**: slideshow · Displays scheduled image slideshows and handles photo import into the local store
- **USB Import**: file import · Lets the user browse a USB folder and copy photos into the Raspberry Pi photo library
- **Call Block**: state override · Temporary do-not-disturb mode that rejects calls for a selected duration

### Hardware

GPIO, TV, and peripheral control

- **Button Logic**: input handling · Maps red, blue, and yellow physical buttons plus maintenance shortcuts to appliance actions
- **LED Feedback**: gpio output · Drives button LEDs and status indication for calls, blocking, and menus
- **GPIO Peripherals**: hardware boundary · Raspberry Pi GPIO layer connecting buttons, LEDs, fan, IR receiver, and IR emitter
- **TV Control**: device control · Abstracts TV power and input switching for photo-frame and normal TV modes
- **HDMI-CEC**: transport · Primary transport for TV power and input control when supported
- **IR Control**: transport · Fallback transport using learned infrared commands when HDMI-CEC is unreliable
- **Fan Control**: thermal control · Monitors CPU temperature and switches the cooling fan on or off

### Ops

Configuration, deployment, and physical artifacts

- [Parametres.txt](https://github.com/methyx/visioconf-rence-pour-ehpad/blob/main/Parametres.txt): config · Primary operational configuration for modes, schedules, paths, durations, and device settings · `Parametres.txt`
- **Call Logs**: audit log · Records received, accepted, refused, and duration information for calls
- **System Log**: operational log · Tracks startup and runtime events and preserves the previous boot's log state
- [IR Learning](https://github.com/methyx/visioconf-rence-pour-ehpad/blob/main/enregistrer_telecommande.sh): tooling · Shell script for recording TV remote commands with irrecord · `enregistrer_telecommande.sh`
- **Physical Artifacts**: deployment assets · Box STL files, installation guides, screenshots, and other operator-facing materials

## Connections

- KIT_Box_V10.py → Parametres.txt: reads · Loads appliance settings at startup and during operation
- KIT_Box_V10.py → Wake Schedule: drives · Uses configured hours to decide wake, sleep, and menu availability
- KIT_Box_V10.py → Call Automation: runs · Coordinates call detection and acceptance or rejection behavior
- Call Automation → Screen OCR: captures · Screenscrapes the Duo notification area and interprets state
- Call Automation → Chromium Duo: acts on · Simulates clicks and keypresses in the Chromium Duo UI
- KIT_Box_V10.py → Button Logic: handles · Maps physical and maintenance inputs to box actions
- Button Logic → GPIO Peripherals: uses · Reads button states through the GPIO boundary
- KIT_Box_V10.py → LED Feedback: updates · Sets LED feedback for calls, blocking, and menu states
- LED Feedback → GPIO Peripherals: uses · Drives GPIO outputs for indicator lights
- KIT_Box_V10.py → TV Control: controls · Manages TV power, input, and display state
- TV Control → HDMI-CEC: tries first · Uses HDMI-CEC when available for TV control
- TV Control → IR Control: falls back to · Uses infrared commands when HDMI-CEC is unreliable
- KIT_Box_V10.py → Photo Frame: runs · Starts slideshow mode during configured active periods
- Photo Frame → USB Import: imports via · Copies user-selected photos from USB storage into the local store
- KIT_Box_V10.py → Call Block: opens · Provides temporary call rejection durations from the red button flow
- Call Block → Call Automation: overrides · Forces incoming calls to be refused during the block window
- KIT_Box_V10.py → Call Logs: records · Writes call outcomes and durations for caregiver review
- KIT_Box_V10.py → System Log: records · Appends operational events and startup state changes
- KIT_Box_V10.py → Fan Control: monitors · Reads temperature and drives cooling decisions
- KIT_Box_V10.py → IR Learning: supports · Provides a tool for learning device-specific IR remote commands
- KIT_Box_V10.py → Physical Artifacts: ships with · Repository includes assembly, installation, and physical build materials
- Parametres.txt → TV Control: configures · Defines TV behavior, command names, and mode selection
- Parametres.txt → Photo Frame: configures · Defines photo paths, slideshow behavior, and import locations
- Parametres.txt → Wake Schedule: configures · Supplies wake and sleep times used by the appliance
