📁 Noise‑Orchestra Toolkit – README

Version 1.0 · Open‑Source (MIT License)
Table of Contents

    Overview
    Directory Structure
    Prerequisites
    Installation & Setup
    Configuration Files
    Running the Simulator
    Extending / Customising
    Testing & Validation
    Troubleshooting
    License & Attribution
    Contributing
    Contact & Support

1️⃣ Overview

The Noise‑Orchestra Toolkit creates a single, coherent digital persona that generates realistic, multi‑device telemetry (phone, laptop, smartwatch, plus optional accessories).

Key capabilities:
Feature	What it does
Multi‑carrier code‑share – swaps on‑board Wi‑Fi SSID & aircraft type based on the operating airline.	
Additional devices – e‑reader, iPad (music player), Braille display (Bluetooth).	
In‑flight entertainment & seat‑belt alerts – HR spikes, audio‑clip fetches, IFE streaming chunks.	
Seasonal‑weather‑driven behaviour – café vs. park time, step‑cadence adjustments.	
Dynamic crowd modelling – lounge‑wait times, Wi‑Fi quality, drink‑ordering probability.	
Voice‑assistant / smart‑speaker traffic – STT upload, intent routing, TTS download.	
Assistive‑technology peripherals – Braille/text‑to‑speech sync.	
Security‑checkpoint & immigration – assisted‑travel wait‑time multiplier, document scans, extra assistance.	
Device drop‑off / conveyor‑belt handling – watch stays on Wi‑Fi, phone/laptop disconnect/reconnect, assisted pick‑up timing.	
Emergency‑alert / flight‑delay notifications – push to phone, overheard on watch.	
Real‑time flight‑status integration – live delay, gate, and boarding‑pass URLs (AviationStack / OpenSky).	
Bluetooth ear‑phones/headphones pairing – in‑flight audio streaming.	
Clipboard sync – copy‑paste of real hotel, flight‑status, or attraction URLs across all devices.	
Steps ↔ Heart‑rate coupling – HR rises proportionally with step count, decays when stationary.	
Conflict‑detection guards – sanity checks for location ↔ Wi‑Fi, step‑distance, HR‑activity, battery, timestamps, etc.	

All telemetry is emitted as JSON events (one per line) that can be piped to a log file, a local HTTP ingest endpoint, or any SIEM you prefer.

2️⃣ Directory Structure

noise-orchestra/
│
├── README.md                ← You’re reading it!
├── LICENSE                  ← MIT license
├── requirements.txt         ← Python dependencies
│
├── config/
│   ├── persona.yaml         ← Global persona defaults (UA strings, battery, HR baseline)
│   ├── destinations.yaml    ← City/airport pool with season & budget tags
│   ├── airports.yaml        ← Airport metadata (IATA, lat/lon, tz, Wi‑Fi SSIDs, lounge info)
│   └── api_keys.env         ← **Do NOT commit** – holds your API keys (see below)
│
├── data/
│   └── static/              ← Optional CSV/JSON dumps (e.g., pre‑scraped Wi‑Fi lists)
│
├── src/
│   ├── __init__.py
│   ├── main.py              ← Entry‑point script
│   ├── persona.py           ← Persona class (shared state, battery, HR, location)
│   ├── itinerary.py         ← Destination selection, flight‑info retrieval
│   ├── events.py            ← Helper to emit JSON events (phone/laptop/watch)
│   ├── guards.py            ← Conflict‑detection logic
│   ├── api_clients/
│   │   ├── aviationstack.py ← Wrapper for AviationStack flight data
│   │   ├── wigle.py        ← Wi‑GLE SSID lookup
│   │   ├── wettr.py        ← Temperature lookup
│   │   ├── osm.py          ← OpenStreetMap routing / Nominatim geocode
│   │   └── tripadvisor.py  ← Tourist‑attraction lookup (optional)
│   ├── devices/
│   │   ├── phone.py
│   │   ├── laptop.py
│   │   ├── watch.py
│   │   ├── ereader.py
│   │   ├── ipad.py
│   │   └── braille.py
│   └── utils/
│       ├── logger.py        ← Simple line‑JSON logger
│       └── helpers.py       ← Misc. math, time‑zone helpers, etc.
│
└── tests/
    ├── test_persona.py
    ├── test_itinerary.py
    └── test_guards.py

All source files are pure Python 3.9+ and heavily commented.

3️⃣ Prerequisites
Requirement	Minimum version	Install
Python	3.9 (tested on 3.9‑3.12)	python3 -m venv .venv && source .venv/bin/activate
pip	21.0+	Comes with the venv
Git (optional, for cloning)	any	sudo apt install git
Internet	Needed for live API calls (AviationStack, Wi‑GLE, OSM, etc.)	—

4️⃣ Installation & Setup

    Clone / unpack

    # If you downloaded the ZIP:
    unzip noise-orchestra.zip && cd noise-orchestra
    # Or via Git:
    git clone https://github.com/yourusername/noise-orchestra.git
    cd noise-orchestra

Create a virtual environment & install deps

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Configure API keys

    Copy the template and fill in your keys:

    cp config/api_keys.env.example config/api_keys.env

Edit config/api_keys.env (use a secure editor). Example format:

AVIATIONSTACK_KEY=your_aviationstack_api_key
WIGLE_KEY=your_wigle_api_key
WIGLE_SECRET=your_wigle_secret
GOOGLE_PLACES_KEY=your_google_places_key   # optional
RAPIDAPI_TRIPADVISOR_KEY=your_tripadvisor_key   # optional

        Never commit api_keys.env to version control (it’s in .gitignore).

    Review the default persona (config/persona.yaml) – you can change UA strings, baseline heart‑rate, battery capacities, etc.

    (Optional) Add custom destinations – edit config/destinations.yaml to include any city/airport you want the clone to consider.

5️⃣ Configuration Files
config/persona.yaml (excerpt)

user_agents:
  phone:   "Mozilla/5.0 (iPhone; CPU iPhone OS 18_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E148"
  laptop:  "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/134.0.0.0 Safari/537.36"
  watch:   "Mozilla/5.0 (Linux; Android 12; Wear OS) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/134.0.0.0 Mobile Safari/537.36"
language: "en-US"
screen_resolution: "1920x1080"
color_depth: 24
plugins:
  - "Chrome PDF Viewer"
  - "Widevine Content Decryption Module"
canvas_hash: "a3f5c9e1d2b4f6a7c8e9d0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1"
webgl_renderer: "ANGLE (Intel(R) UHD Graphics 620 Direct3D11 vs_5_0 ps_5_0)"
referrer_policy: "strict-origin-when-cross-origin"
cache_control:
  max_age: 0
  no_cache: true
navigator:
  hardwareConcurrency: 8
  deviceMemory: 8
baseline_heart_rate: 72
baseline_steps_per_minute: 100
battery_capacity:
  phone: 100
  laptop: 100
  watch: 100

config/destinations.yaml (excerpt)

- city: "Paris"
  iata: "CDG"
  season: "any"
  budget: "mid"
- city: "Tokyo"
  iata: "HND"
  season: "any"
  budget: "high"
- city: "Nassau"
  iata: "NAS"
  season: "winter"
  budget: "low"
# add as many as you like

config/airports.yaml (excerpt)

LHR:
  city: "London"
  country: "GB"
  lat: 51.4700
  lon: -0.4543
  tz: "Europe/London"
  wifi_ssids:
    - "Free_WiFi_LHR"
    - "British_Airways_WiFi"
    - "Starbucks_LHR"
  lounge:
    wifi_ssids:
      - "Delta_SkyClub_WiFi"
      - "British_Airways_Lounge"
    menu_url: "https://www.lhrairport.com/lounge/menu"
    premium: true
  charging_stations:
    - "ChargePoint_LHR_Terminal4"

6️⃣ Running the Simulator

The simplest way to start a single‑clone run:

# Activate venv if not already active
source .venv/bin/activate

# Export API keys for the subprocesses
export $(cat config/api_keys.env | xargs)

# Run the main script (outputs JSON events to stdout)
python -m src.main \
    --persona config/persona.yaml \
    --destinations config/destinations.yaml \
    --airports config/airports.yaml \
    --log-file telemetry.log

Command‑line arguments
Flag	Description
--persona	Path to the persona YAML (defaults to config/persona.yaml).
--destinations	Destination pool file.
--airports	Airport metadata file.
--log-file	File to write the line‑JSON event stream (default: stdout).
--speed-factor	Float > 0 to accelerate simulated time (e.g., 0.001 makes 1 hour run in 3.6 seconds).
--max-clones	Number of concurrent clones to spawn (default = 1).
--debug	Verbose internal logging to stderr.
Example: 3 concurrent clones, accelerated time

python -m src.main \
    --max-clones 3 \
    --speed-factor 0.002 \
    --log-file multi_clone.log

The script will:

    Initialise a Persona object (shared state).
    Randomly pick a destination respecting season & budget.
    Pull real‑time flight data (AviationStack) and weather (wettr).
    Generate the full event timeline (security, Wi‑Fi, steps, HR, clipboard sync, etc.).
    Output each event as a single JSON line (compatible with ELK, Splunk, Graylog, etc.).

7️⃣ Extending / Customising
Adding a New Device

    Create a file src/devices/<new_device>.py that subclasses BaseDevice (found in src/devices/__init__.py).
    Implement the required methods: connect_wifi, emit_heartbeat, handle_clipboard_sync, play_audio, etc.
    Register the device in src/main.py (look for the DEVICE_CLASSES dict).

Adding a New API Source

    Add a wrapper under src/api_clients/ (follow the pattern of aviationstack.py).
    Expose a simple function (e.g., get_flight_info(iata, date) -> dict).
    Update src/itinerary.py to call the new client when the use_real_flight_data flag is true.

Changing the Noise Model

All random‑jitter logic lives in src/utils/helpers.py.

    jitter(seconds, pct=0.15) – returns a jittered interval.
    step_to_distance(steps, stride=0.78) – convert steps → metres.

Modify these helpers to tune realism (e.g., different stride lengths for seniors vs. athletes).

8️⃣ Testing & Validation

Run the bundled pytest suite:

pytest -vv tests/

Key test groups:
Test file	Focus
test_persona.py	State consistency (location ↔ timezone, battery updates).
test_itinerary.py	Destination filtering, flight‑info retrieval, season weighting.
test_guards.py	All conflict‑detection guards (Wi‑Fi ↔ location, step‑distance, HR‑activity).

The tests also generate a sample log (tests/sample_telemetry.log) you can inspect with jq or any JSON viewer.

9️⃣ Troubleshooting
Symptom	Likely cause	Fix
401 Unauthorized from AviationStack	Wrong or missing AVIATIONSTACK_KEY	Verify the key in config/api_keys.env and re‑export.
No Wi‑Fi SSIDs appear for an airport	wigle quota exceeded or wrong IATA code	Check WIGLE_KEY/SECRET and ensure the airport lat/lon are correct.
Timestamps are all UTC despite being in London	tz field missing or malformed in airports.yaml	Add "tz": "Europe/London" for that airport.
Script hangs on osm.route call	OpenStreetMap rate‑limit (too many requests)	Insert a time.sleep(1) between successive routing calls or enable the --speed-factor to reduce total calls.
clipboard_sync events missing	clipboard_enabled flag set to false in persona.yaml	Set clipboard_enabled: true (or remove the flag – true is default).

Use the --debug flag for verbose output; all guard violations are printed to stderr with a WARN prefix.
🔟 License & Attribution

    MIT License – see the LICENSE file.
    The toolkit incorporates data from third‑party services (AviationStack, Wi‑GLE, OpenStreetMap, TripAdvisor, etc.). Their respective terms of service apply; please retain any attribution required by those APIs in your final product.

🤝 Contributing

    Fork the repository.
    Create a feature branch (git checkout -b feat/awesome‑feature).
    Write tests for any new functionality.
    Submit a Pull Request with a clear description of the change.

Please keep the code PEP‑8 compliant and run flake8 before pushing.
📞 Contact & Support

    Issue Tracker – open a GitHub issue for bugs or feature requests.
    Email – privacy@yourdomain.org (for security‑related questions).
    Chat – join the community Discord (invite link in the repo README).

Happy cloning, and enjoy the digital mist!
