# simonwalkersamuel/wifilocation architecture

> Architecture diagram of the GitHub repository simonwalkersamuel/wifilocation, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/simonwalkersamuel/wifilocation
- Repository: https://github.com/simonwalkersamuel/wifilocation

## Overview

##### Project Type and Purpose
- This is a proof-of-principle HomeAssistant "custom component" (a sensor platform) plus an Android Tasker automation.
- Purpose: sample Wi-Fi signal strengths via an Android phone, use machine learning on a HomeAssistant server to detect which room the user is in, and expose that as a HomeAssistant sensor.

##### File Structure Analysis
- Top level:
- wifilocation.py – HomeAssistant custom sensor component.
- Wifi_Location.prj.xml – Tasker project file for Android calibration & runtime scanning.
- README.md – installation & usage instructions.
- LICENSE / .gitignore – ancillary.
- No separate “frontend” or “backend” folders; the server side is embedded in HomeAssistant via wifilocation.py, while the client side resides in Tasker.

##### Key Components
a. Android Device (Tasker)
- Tasker Project (Wifi_Location.prj.xml)
- Modules: Wi-Fi Scanner → collects SSID/BSSID + RSSI → tags samples with WIFI_ROOM variable during calibration or live scanning
- REST Client → sends HTTP GET/POST to HomeAssistant API endpoint
b. Wi-Fi Infrastructure
- Wi-Fi Routers (at least 3) as external RF signal sources
c. HomeAssistant Server
- Custom Component: wifilocation.py
- REST API endpoint (/api/wifilocation)
- ML Pipeline:
– Calibration file loader (wifilocation_calibration.txt)
– Model training (numpy, scikit, Keras, TensorFlow)
– Inference module (real-time RSSI → room prediction)
- Sensor Entity → updates HomeAssistant state machine
- Configuration: configuration.yaml entry for sensor platform
- File Store: stores calibration text file, model artifacts
d. User Interface
- HomeAssistant Dashboard → displays “current room” sensor

##### Relationships and Data Flows
- Calibration Phase:
1. User runs Tasker “Sample Wifi” task in each room → Tasker writes per-sample entries with WIFI_ROOM label to calibration file.
2. User transfers calibration file from Android to HomeAssistant server (manual or via sync).
3. HomeAssistant custom component loads file, trains ML model.
- Runtime (Inference) Phase:
1. Tasker periodically scans Wi-Fi RSSI → encodes data into HTTP request.
2. Android Tasker sends request to HomeAssistant REST endpoint with RSSI payload.
3. wifilocation.py parses payload, runs inference, updates sensor state.
4. HomeAssistant UI / automations react to sensor value.

##### Architectural Patterns and Design Principles
- Layered design:
- Device Layer (Android Tasker)
- Transport Layer (HTTP REST)
- Server Layer (HomeAssistant custom component + ML library stack)
- Presentation Layer (HomeAssistant UI)
- Separation of concerns: capture vs. processing vs. presentation
- Extensibility: ML framework can be swapped or extended; Tasker project can be modified for other sensors

- Clear labels on each block (e.g., “Tasker Wifi Scanner,” “ML Inference Module”).
- Notes on technologies at each component (e.g., “TensorFlow, Keras” at ML block).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Device Layer"
        Android["Android Tasker"]:::edge
        subgraph Tasker
            Scanner["Wi-Fi Scanner"]:::edge
            Client["REST Client"]:::edge
        end
    end

    Routers["Wi-Fi Routers"]:::external

    subgraph "Server Layer"
        HA_Server["HomeAssistant Server"]:::compute
        subgraph "Custom Component"
            API["REST API Endpoint\n/api/wifilocation"]:::compute
            ML["ML Pipeline\n(TensorFlow, Keras)"]:::compute
            Inference["Inference Module"]:::compute
            Sensor["Sensor Entity"]:::compute
        end
        subgraph "Data Stores"
            CalFile["Calibration File\n(wifilocation_calibration.txt)"]:::storage
            ModelFile["Trained Model"]:::storage
            Config["configuration.yaml"]:::storage
        end
    end

    subgraph "Presentation Layer"
        Dashboard[(HomeAssistant Dashboard)]:::ui
    end

    %% Data Flows - Calibration Phase
    Scanner -->|"samples with WIFI_ROOM label"| CalFile
    CalFile -->|"load calibration"| ML
    ML -->|"train model"| ModelFile

    %% Data Flows - Runtime Phase
    Routers -->|"RSSI signals"| Scanner
    Scanner -->|"RSSI data"| Client
    Client -->|"RSSI JSON payload over HTTPS"| API
    API -->|"parse payload"| Inference
    ModelFile -->|"provide model"| Inference
    Inference -->|"predict room"| Sensor
    Sensor -->|"state update"| Dashboard

    %% Click Events
    click Android "https://github.com/simonwalkersamuel/wifilocation/blob/master/Wifi_Location.prj.xml"
    click API "https://github.com/simonwalkersamuel/wifilocation/blob/master/wifilocation.py"
    click Scanner "https://github.com/simonwalkersamuel/wifilocation/blob/master/Wifi_Location.prj.xml"
    click Client "https://github.com/simonwalkersamuel/wifilocation/blob/master/Wifi_Location.prj.xml"
    click CalFile "https://github.com/simonwalkersamuel/wifilocation/blob/master/wifilocation.py"
    click ModelFile "https://github.com/simonwalkersamuel/wifilocation/blob/master/wifilocation.py"
    click Sensor "https://github.com/simonwalkersamuel/wifilocation/blob/master/wifilocation.py"
    click Dashboard "https://github.com/simonwalkersamuel/wifilocation/blob/master/README.md"
    click HA_Server "https://github.com/simonwalkersamuel/wifilocation/blob/master/README.md"
    click Config "https://github.com/simonwalkersamuel/wifilocation/blob/master/wifilocation.py"
    click CalFile "https://github.com/simonwalkersamuel/wifilocation/blob/master/wifilocation.py"
    click ModelFile "https://github.com/simonwalkersamuel/wifilocation/blob/master/wifilocation.py"
    click README["README.md"] "README.md"
    click LICENSE["LICENSE"] ".gitignore"
    click GI[".gitignore"] ".gitignore"

    %% Styles
    classDef edge fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef compute fill:#90EE90,stroke:#000,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#000,stroke-width:1px
    classDef storage fill:#FFA500,stroke:#000,stroke-width:1px
    classDef ui fill:#DDA0DD,stroke:#000,stroke-width:1px
    classDef docs fill:#FFFFE0,stroke:#000,stroke-width:1px
```
