feat: Implement Generic IoT Data Simulator CLI

This commit introduces a command-line tool to simulate various types of
IoT sensor data (temperature, humidity, GPS, boolean status, counter)
and send it to the console or an HTTP POST endpoint.

Features:
- Configurable device profiles (ID and sensor types) via CLI strings or JSON.
- Simulates temperature, humidity, GPS (with random walk), boolean status,
  and an incrementing counter.
- Outputs data as JSON to console or via HTTP POST.
- User-defined interval between messages and total message count.
- Includes `iot_simulator_requirements.txt` (for `requests` library).
- Comprehensive `README_iot_simulator.md` with setup, usage, and examples.

Author: google-labs-jules[bot]

README_iot_simulator.md

@@ -0,0 +1,138 @@
+# Generic IoT Data Simulator
+
+This Python CLI tool simulates various types of IoT sensor data and sends it to configurable endpoints (console or HTTP POST). It's designed to help developers test IoT backends, data ingestion pipelines, dashboards, and other components without needing physical hardware.
+
+## Features
+
+*   **Multiple Sensor Types:** Simulate data for:
+    *   Temperature (°C)
+    *   Humidity (%)
+    *   GPS Location (latitude, longitude - with random walk)
+    *   Boolean Status (e.g., on/off, open/closed)
+    *   Incrementing Counter
+*   **Configurable Device Profiles:** Define multiple simulated devices, each with its own set of sensors. Device IDs can be specified or auto-generated.
+*   **Flexible Output:**
+    *   **Console:** Print generated data as structured JSON to the standard output.
+    *   **HTTP POST:** Send data as a JSON payload to a specified HTTP(S) endpoint.
+*   **Customizable Simulation:**
+    *   Control the interval between messages.
+    *   Set the total number of messages to send (or run indefinitely).
+*   **Standardized Data Format:** Output includes `deviceId`, `timestamp` (ISO 8601 UTC), and sensor readings.
+*   **Stateful Sensors:** GPS coordinates evolve with a random walk, and counters increment per device.
+
+## Prerequisites
+
+*   Python 3.6+
+*   `requests` library (for HTTP output).
+
+## Installation
+
+1.  **Clone the repository or download the files.**
+    Ensure you have `iot_sim_main.py`, the `iot_simulator` directory (containing `generators.py`, `publishers.py`, `__init__.py`), and the `iot_simulator_requirements.txt` file.
+
+2.  **Create a virtual environment (recommended):**
+    ```bash
+    python3 -m venv venv
+    source venv/bin/activate  # On Windows: venv\Scripts\activate
+    ```
+
+3.  **Install dependencies:**
+    Navigate to the directory containing `iot_simulator_requirements.txt` and run:
+    ```bash
+    pip install -r iot_simulator_requirements.txt
+    ```
+
+## Usage
+
+The tool is run from the command line using `python3 iot_sim_main.py`.
+
+### Command-Line Arguments
+
+*   `-p, --profiles PROFILES [PROFILES ...]`: **(Required)**
+    *   Defines one or more device profiles.
+    *   Each profile can be a string in the format `"device_id:sensor1,sensor2,..."`.
+    *   If `device_id:` is omitted (e.g., `"sensor1,sensor2"`), a unique device ID will be auto-generated.
+    *   Alternatively, you can provide a single argument which is a JSON string representing a list of profiles: `'[{"id":"dev1","sensors":["temp","hum"]}, {"id":"dev2","sensors":["gps"]}]'`
+    *   **Supported sensor types:** `temperature`, `humidity`, `gps`, `status`, `counter`.
+*   `-i, --interval INTERVAL`: (Optional) Interval in seconds between sending message batches (default: 5.0 seconds).
+*   `-n, --num_messages NUM_MESSAGES`: (Optional) Number of message batches to send. A batch includes data from all defined profiles. Set to `0` for an infinite simulation (stop with Ctrl+C) (default: 10).
+*   `-o, --output {console,http}`: (Optional) Output target. Defaults to `console`.
+*   `--http_url HTTP_URL`: (Optional) Target URL for HTTP POST output. **Required if `--output=http` is chosen.**
+*   `-h, --help`: Show help message and exit.
+
+### JSON Payload Format
+
+The data is sent/printed as a JSON object with the following structure:
+```json
+{
+  "deviceId": "your_device_id",
+  "timestamp": "YYYY-MM-DDTHH:MM:SS.ffffffZ", // ISO 8601 UTC
+  // Sensor fields appear here based on profile
+  "temperature_celsius": 23.7,
+  "humidity_percent": 45.8,
+  "location": {
+    "latitude": 34.052200,
+    "longitude": -118.243700
+  },
+  "active_status": true,
+  "event_count": 123
+}
+```
+*Note: Not all sensor fields will be present in every message; only those configured for the specific device profile.*
+
+### Examples
+
+1.  **Simulate one device with temperature and humidity, output to console (10 messages, 5s interval):**
+    ```bash
+    python3 iot_sim_main.py --profiles "device001:temperature,humidity"
+    ```
+
+2.  **Simulate two devices, 5 messages, 2s interval, output to console:**
+    ```bash
+    python3 iot_sim_main.py \
+        --profiles "thermostat1:temperature" "gps_tracker:gps,counter" \
+        --num_messages 5 \
+        --interval 2
+    ```
+
+3.  **Simulate one device (auto-generated ID) with all sensor types, run indefinitely, output to console every 10s:**
+    ```bash
+    python3 iot_sim_main.py \
+        --profiles "temperature,humidity,gps,status,counter" \
+        --num_messages 0 \
+        --interval 10
+    ```
+
+4.  **Simulate devices defined in a JSON string, output to an HTTP endpoint:**
+    ```bash
+    python3 iot_sim_main.py \
+        --profiles '[{"id":"factory_sensor_A","sensors":["temperature","counter"]},{"id":"asset_tracker_B","sensors":["gps"]}]' \
+        --output http \
+        --http_url "http://localhost:8080/api/data" \
+        --interval 2 \
+        --num_messages 100
+    ```
+    *(Ensure you have an HTTP server listening at the specified `--http_url` if testing HTTP output.)*
+
+## File Structure
+```
+.
+├── iot_simulator/
+│   ├── __init__.py     # Makes 'iot_simulator' a Python package
+│   ├── generators.py   # Logic for generating sensor data
+│   └── publishers.py   # Logic for formatting and sending data (console, HTTP)
+├── iot_sim_main.py       # CLI entry point and main simulation loop
+├── iot_simulator_requirements.txt # Python dependencies (requests)
+└── README_iot_simulator.md        # This documentation file
+```
+
+## Sensor Details
+
+*   **temperature:** Random float, default range -10.0 to 40.0 °C. Output key: `temperature_celsius`.
+*   **humidity:** Random float, default range 20.0 to 80.0 %. Output key: `humidity_percent`.
+*   **gps:** Simulates GPS coordinates (latitude, longitude) starting from a base point and performing a small random walk with each update. Output key: `location` (an object with `latitude` and `longitude`).
+*   **status:** Random boolean (True/False). Output key: `active_status`.
+*   **counter:** Integer that increments by 1 for each message from that specific device. Output key: `event_count`.
+
+Sensor data generation (ranges, GPS step) is defined in `iot_simulator/generators.py` and can be customized there if needed.
+```

iot_sim_main.py

@@ -0,0 +1,197 @@
+import argparse
+import time
+import json # For parsing device_profiles if given as JSON string
+import uuid
+from iot_simulator.generators import generate_sensor_data, generate_timestamp, DEVICE_STATES
+from iot_simulator.publishers import format_payload, print_to_console, send_http_post
+
+def parse_device_profiles(profiles_str_list):
+    """
+    Parses device profile strings.
+    Each string can be "device_id:sensor1,sensor2" or just "sensor1,sensor2" (auto-gen ID).
+    Or, it can be a JSON string representing a list of more complex profiles.
+    """
+    profiles = []
+    if not profiles_str_list:
+        return profiles
+
+    # Check if the input is a single string that might be JSON
+    if len(profiles_str_list) == 1 and (profiles_str_list[0].startswith('[') or profiles_str_list[0].startswith('{')):
+        try:
+            parsed_json = json.loads(profiles_str_list[0])
+            if isinstance(parsed_json, list):
+                # Expecting list of {"id": "dev1", "sensors": ["temp", "hum"]}
+                for p_item in parsed_json:
+                    if isinstance(p_item, dict) and "id" in p_item and "sensors" in p_item:
+                        profiles.append({"id": p_item["id"], "sensors": p_item["sensors"]})
+                    else:
+                        print(f"Warning: Invalid JSON profile item format: {p_item}. Skipping.")
+                return profiles
+            elif isinstance(parsed_json, dict): # Single profile as JSON object
+                 if "id" in parsed_json and "sensors" in parsed_json:
+                    profiles.append({"id": parsed_json["id"], "sensors": parsed_json["sensors"]})
+                    return profiles
+                 else:
+                    print(f"Warning: Invalid JSON profile object format: {parsed_json}. Skipping.")
+                    return [] # Or handle as error
+        except json.JSONDecodeError as e:
+            print(f"Warning: Could not parse profile string as JSON '{profiles_str_list[0]}': {e}. Proceeding with string parsing.")
+            # Fall through to string parsing if JSON attempt fails for a single ambiguous string
+
+    # String parsing for "device_id:sensor1,sensor2" or "sensor1,sensor2"
+    for profile_str in profiles_str_list:
+        parts = profile_str.split(':', 1)
+        device_id = ""
+        sensors_str = ""
+
+        if len(parts) == 2:
+            device_id = parts[0].strip()
+            sensors_str = parts[1].strip()
+        elif len(parts) == 1:
+            sensors_str = parts[0].strip()
+            # No device_id provided, will auto-generate
+        else:
+            print(f"Warning: Invalid profile string format '{profile_str}'. Skipping.")
+            continue
+
+        if not device_id:
+            device_id = f"sim-{uuid.uuid4().hex[:8]}"
+            print(f"Auto-generated device ID: {device_id} for sensors: {sensors_str}")
+
+        sensor_types = [s.strip() for s in sensors_str.split(',') if s.strip()]
+        if not sensor_types:
+            print(f"Warning: No sensor types specified for device ID '{device_id}' in profile '{profile_str}'. Skipping.")
+            continue
+
+        profiles.append({"id": device_id, "sensors": sensor_types})
+
+    return profiles
+
+
+def main_loop(profiles, interval_seconds, num_messages, output_target, http_url=None):
+    """
+    Main simulation loop.
+    """
+    if not profiles:
+        print("No valid device profiles configured. Exiting.")
+        return
+
+    print(f"\nStarting IoT simulation...")
+    print(f"Device Profiles: {profiles}")
+    print(f"Interval: {interval_seconds}s")
+    print(f"Messages per run (per profile): {num_messages if num_messages > 0 else 'Infinite'}")
+    print(f"Output Target: {output_target}")
+    if output_target == 'http' and http_url:
+        print(f"HTTP Target URL: {http_url}")
+
+    # Reset global device states for a fresh run if needed, or manage them per profile run.
+    # For simplicity, DEVICE_STATES in generators.py is global.
+    # If we want truly independent runs for counters/GPS per main_loop call, clear it here.
+    # DEVICE_STATES.clear() # Uncomment if each run of main_loop should reset all device states
+
+    try:
+        msg_count = 0
+        while True:
+            if num_messages > 0 and msg_count >= num_messages:
+                print(f"\nReached target message count ({num_messages}). Simulation finished for this run.")
+                break
+
+            current_ts = generate_timestamp()
+
+            for profile in profiles:
+                device_id = profile["id"]
+                sensor_types = profile["sensors"]
+
+                # This list will hold data from multiple sensors for this device for this timestamp
+                all_sensor_readings_for_device = []
+
+                for sensor_type in sensor_types:
+                    # generate_sensor_data from generators.py manages state per device_id
+                    reading = generate_sensor_data(device_id, sensor_type)
+                    if reading:
+                        all_sensor_readings_for_device.append(reading)
+
+                if not all_sensor_readings_for_device:
+                    print(f"Warning: No sensor data generated for device {device_id} at {current_ts}. Skipping.")
+                    continue
+
+                # Format the payload with all readings for this device
+                payload = format_payload(device_id, current_ts, all_sensor_readings_for_device)
+
+                if output_target == 'console':
+                    print_to_console(payload)
+                elif output_target == 'http':
+                    if http_url:
+                        send_http_post(http_url, payload)
+                    else:
+                        print("Error: HTTP output specified but no URL provided. Skipping send.")
+
+            msg_count += 1
+            if num_messages == 0 or msg_count < num_messages : # Only sleep if not the last message of a finite run
+                print(f"--- Sent message batch #{msg_count}. Waiting {interval_seconds}s... ---")
+                time.sleep(interval_seconds)
+
+    except KeyboardInterrupt:
+        print("\nSimulation stopped by user (Ctrl+C).")
+    except Exception as e:
+        print(f"\nAn unexpected error occurred during simulation: {e}")
+    finally:
+        print("IoT Simulation ended.")
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Generic IoT Data Simulator.")
+
+    parser.add_argument(
+        "-p", "--profiles",
+        nargs='+',
+        required=True,
+        help='Device profiles. Each profile as "device_id:sensor1,sensor2,..." or "sensor1,sensor2" (ID auto-generated). '
+             'Alternatively, a single argument which is a JSON string: \'[{"id":"dev1","sensors":["temp","hum"]}]\' '
+             'Supported sensors: temperature, humidity, gps, status, counter.'
+    )
+    parser.add_argument(
+        "-i", "--interval",
+        type=float,
+        default=5.0,
+        help="Interval in seconds between sending messages (default: 5.0s)."
+    )
+    parser.add_argument(
+        "-n", "--num_messages",
+        type=int,
+        default=10,
+        help="Number of messages to send per simulation run (0 for infinite) (default: 10)."
+    )
+    parser.add_argument(
+        "-o", "--output",
+        choices=['console', 'http'],
+        default='console',
+        help="Output target: 'console' or 'http' (default: console)."
+    )
+    parser.add_argument(
+        "--http_url",
+        help="Target URL for HTTP POST output (required if --output=http)."
+    )
+
+    args = parser.parse_args()
+
+    if args.output == 'http' and not args.http_url:
+        parser.error("--http_url is required when --output is 'http'.")
+
+    parsed_profiles = parse_device_profiles(args.profiles)
+    if not parsed_profiles:
+        print("Error: No valid device profiles could be parsed. Please check your --profiles argument.")
+        print("Examples: --profiles \"myDevice:temperature,humidity\" \"another:gps,counter\"")
+        print("      or: --profiles '[{\"id\":\"dev1\",\"sensors\":[\"temperature\",\"status\"]}, {\"id\":\"dev2\",\"sensors\":[\"gps\"]}]'")
+        return
+
+    main_loop(
+        profiles=parsed_profiles,
+        interval_seconds=args.interval,
+        num_messages=args.num_messages,
+        output_target=args.output,
+        http_url=args.http_url
+    )
+
+if __name__ == "__main__":
+    main()

iot_simulator/__init__.py

@@ -0,0 +1,15 @@
+# This file makes 'iot_simulator' a Python package.
+
+from .generators import (
+    generate_temperature,
+    generate_humidity,
+    generate_gps_coordinates,
+    generate_boolean_status,
+    generate_counter_value,
+    generate_timestamp,
+    generate_device_id,
+    generate_sensor_data,
+    DEVICE_STATES # Exposing for potential external state management if ever needed, or reset
+)
+
+from .publishers import format_payload, print_to_console, send_http_post