Device Simulator

A comprehensive IoT device simulator that connects to Azure IoT Hub and IoT Platform servers. This simulator can provision devices, monitor device twins, send telemetry data, and handle commands according to device type schemas.

Features

🔧 Device Configuration

• Local Configuration: Load device configuration from local files if already configured
• Interactive CLI Setup: Command-line interface for device configuration and management
• OAuth2 Authentication: Secure authentication with IoT Platform server
• Device Provisioning: Automatic device creation in IoT Hub
• Configuration Management: Get and set device configurations through IoT Hub
• Schema Management: Download and cache device type schemas locally

🔌 Connectivity

• Azure IoT Hub Integration: Connect to IoT Hub using device connection strings
• Gateway Support: Connect through configured gateways
• SAS Token Authentication: Secure device authentication

📊 Device Twin Monitoring

• Desired Properties: Listen for twin configuration changes from IoT Hub
• Reported Properties: Update device status and configurations to IoT Hub only if reported section of the device is empty
• Default Configurations: Apply schema-based default values and sync with IoT Hub

📡 Telemetry (D2C Messages)

• Message Types:
  • 🚨 Events: Critical notifications and warnings
  • 📈 Measurements: Sensor readings and metrics
  • ⚡ Status: Device health and operational status
  • 🔧 FW Debug: Firmware debugging and diagnostic information
• Scheduled Transmission: Configurable intervals for each message type, on each trigger all the messages of this type will be sent (all events/meausrement/etc)
• Schema Compliance: Values generated according to device type schema
• Data Continuity: Coordinated values based on previous messages

🎯 Command Handling (C2D)

• Command Reception: Process commands from IoT Platform
• Schema Validation: Verify commands against device type schema
• Response Generation: Automatic success responses when required

📅 Historical Telemetry Generation

You can generate and send historical telemetry data for a device over a custom date range. This is useful for backfilling data or simulating device history.

Example usage:

python -m simulator.main --generate-history --start-date 2026-01-01 --end-date 2026-01-30 --message-count 1000

Arguments:

• --generate-history: Enable historical data generation mode
• --start-date: Start date (supports YYYY-MM-DD )
• --end-date: End date (supports YYYY-MM-DD )
• --message-count: Number of message sets to generate (each set includes all enabled message types)

If no device is configured, you will be prompted to set one up before generating historical data.

Prerequisites

• Python 3.9 or higher (supports Python 3.9-3.13)
• pip package manager
• Virtual environment
• Azure IoT Hub instance
• IoT Platform server with OAuth2 support
• Device type schemas in IoT Platform server

Installation

Quick Setup (Recommended)

# Clone the repository
git clone <repository-url>
cd tandem-platform-simulator

# Run setup script
# Windows:
setup.bat
# Linux/macOS:
bash setup.sh

The setup script will:

1. Create a virtual environment
2. Install the package in development mode with all dependencies
3. Copy configuration template
4. Set up logging directory

Manual Installation

# Create virtual environment
python -m venv venv

# Activate virtual environment
# Windows:
venv\Scripts\activate
# Linux/macOS:
source venv/bin/activate

# Install package in development mode with all dependencies
pip install -e ".[dev]"

# Copy configuration template
copy simulator\config\templates\config.template.json config\config.json  # Windows
# cp simulator/config/templates/config.template.json config/config.json  # Linux/macOS

Configuration

Local Device Configuration

If you have existing device configuration, create these files:

config/device-config.json

{
  "deviceId": "your-device-id",
  "gatewayId": "your-gateway-id",
  "deviceType": "your-device-type",
  "lastUpdated": "2025-08-24T10:30:00Z"
}

schemas/device-type-schema.json

Application Configuration

config/config.json

{
  "iotPlatform": {
    "baseUrl": "https://your-iot-platform.com/api",
    "oauth2": {
      "clientId": "your-client-id",
      "authorization_endpoint": "https://your-authority.your-region.cloudapp.azure.com/application/o/authorize/",
      "token_endpoint": "https://your-authority.your-region.cloudapp.azure.com/application/o/token/"
    }
  },
  "provisioner": {
    "baseUrl": "https://your-provisioner-app.azurewebsites.net"
  },
  "iotHub": {
    "hostName": "your-iot-hub-name.azure-devices.net"
  },
  "messaging": {
    "intervals": {
      "measurement": 60,
      "sw_logs": 180,
      "state": 120,
      "events": 300
    },
    "enabled": {
      "measurement": true,
      "sw_logs": false,
      "state": true,
      "events": true
    }
  },
  "logging": {
    "level": "INFO",
    "file": "logs/simulator.log"
  }
}

Message Type Configuration

The messaging configuration has two sections:

• intervals: How often each message type is sent (in seconds)
• enabled: Whether each message type should be sent at all

Message Types:

• measurement: Sensor readings and metrics
• 🔧 sw_logs: Software logs and debugging information
• 🔄 state: Device state and operational status
• ⚠️ events: Event notifications and alerts

Default Settings:

• All message types are enabled by default except sw_logs (disabled)
• You can disable any message type by setting its enabled value to false
• Disabled message types will not generate telemetry tasks, saving resources

Usage

1. Start the Simulator

# Activate virtual environment first (if not already active)
# Windows:
venv\Scripts\activate
# Linux/macOS:
source venv/bin/activate

# Start the simulator (recommended way)
iot-simulator

# Initialize configuration if needed
iot-simulator --init

# Alternative way (direct module execution)
python -m simulator.main

2. Device Configuration Flow

Option A: Pre-configured Device

If config/device-config.json and corresponding schema exist:

• ✅ Device automatically starts tracking
• 🔗 Connects to IoT Hub using stored connection string
• 📊 Begins twin monitoring and telemetry transmission

Option B: New Device Setup

If no local configuration exists:

1. 🌐 CLI-based Authorization

   • Follow OAuth2 login prompts in terminal
   • Authenticate with IoT Platform credentials via browser
   • Grant device management permissions

2. ⚙️ Device Configuration via CLI

   • New Device Creation:

     • Enter Device ID through command prompts
     • Select from available Managed Groups (displayed in terminal)
     • Choose Device Type from server list (interactive menu)
     • Provision new device in IoT Hub
     • Set initial configurations in IoT Hub device twin

   • OR Choose Existing Device:

     • Select from available devices list displayed in terminal
     • Get device configurations from IoT Hub device twin
     • Get selected device data from server: id, gateway id, managed-group, type.

3. 💾 Schema Download

   • Device type schema downloaded from IoT Platform
   • Configuration saved locally for future use

3. Runtime Operations

Twin Configuration Monitoring

[TWIN] Listening for desired property changes from IoT Hub...
[TWIN] Generated default configs from schema
[TWIN] Desired property updated from IoT Hub: {'telemetryInterval': 45}
[TWIN] Patched reported property: {'telemetryInterval': 45}

Telemetry Transmission

[D2C] Sending measurement: {"temperature": 23.5, "humidity": 65.2}
[D2C] Sending state: {"batteryLevel": 85, "signalStrength": -67}
[D2C] Sending events: {"type": "highTemperature", "value": 78.2}
[D2C] Sending sw_logs: {"firmware_version": "1.2.3", "memory_usage": 65, "cpu_temp": 42}

Command Handling

[C2D] Received command: reboot
[C2D] Command validated against schema
[C2D] Sending response: {"status": "success", "timestamp": "2025-10-26T10:30:00Z"}

Project Structure

tandem-platform-simulator/
├── pyproject.toml            # Modern Python packaging configuration
├── setup.bat/setup.sh        # Setup scripts for development environment
├── simulator/               # Main package
│   ├── main.py             # Primary application entry point
│   ├── api/                # Platform API clients
│   │   ├── device_creation_metadata_api.py
│   │   └── firmware_version_api.py
│   ├── auth/               # OAuth2 authentication
│   │   ├── oauth_flow.py
│   │   └── oauth2_client.py
│   ├── config/             # Configuration management
│   │   ├── config_manager.py
│   │   ├── schemas.py
│   │   └── templates/
│   │       └── config.template.json
│   ├── connectivity/       # IoT Hub client
│   │   └── iot_hub_client.py
│   ├── device_setup/       # CLI-based device configuration
│   │   ├── setup_coordinator.py
│   │   ├── configuration_ui.py
│   │   └── device_selector.py
│   ├── provisioning/       # Device provisioning
│   │   └── device_provisioner.py
│   ├── telemetry/          # D2C message generation
│   │   ├── sender.py
│   │   ├── telemetry_generator.py
│   │   └── message_generators/
│   │       ├── measurement_generator.py
│   │       ├── state_generator.py
│   │       ├── alerts_generator.py
│   │       └── fw_debug_generator.py
│   ├── twin/               # Device twin manager
│   │   ├── twin_manager.py
│   │   ├── default_config_applier.py
│   │   ├── firmware_reporter.py
│   │   └── reported_store.py
│   ├── commands/           # C2D command processing
│   │   └── command_handler.py
│   └── utils/              # Utilities and logging
│       ├── logger.py
│       ├── version_parser.py
│       └── schema/
│           ├── schema_generator.py
│           ├── schema_reference_resolver.py
│           └── schema_value_generator.py
├── config/                 # Configuration files
│   ├── config.json         # Application configuration (created from template)
│   ├── device-config.json  # Device-specific config (auto-generated)
│   └── auth-tokens.json    # OAuth tokens (auto-generated)
├── schemas/                # Device type schemas (downloaded)
├── certificates/           # Device certificates (if using)
├── twin_schemas/          # Twin schemas
├── tests/                  # Test suite
│   └── commands/
├── logs/                   # Application logs
└── README.md

Logging

The simulator provides detailed logging for all operations:

• 🔐 Authentication: OAuth2 flow, token management
• ⚙️ Configuration: Device setup, schema downloads
• 🔗 Connectivity: IoT Hub connections, reconnection attempts
• 👥 Twin Operations: Desired/reported property changes
• 📡 Telemetry: Message generation and transmission
• 🎯 Commands: Command reception and response generation

Logs are written to both console and logs/simulator.log file.

Error Handling

Common Issues

Configuration Missing

# Initialize configuration if not exists
iot-simulator --init
# Edit the generated config/config.json with your settings

Authentication Failures

# Clear stored tokens and re-authenticate
del config\auth-tokens.json  # Windows
# rm config/auth-tokens.json  # Linux/macOS
iot-simulator

Connection Issues

# Check IoT Hub connectivity and device configuration
# Verify config/config.json settings
# Check config/device-config.json exists and is valid

Schema Validation Errors

# Re-run setup to download fresh schema
# Delete old schema files and device config
del schemas\*-schema.json config\device-config.json  # Windows
# rm schemas/*-schema.json config/device-config.json  # Linux/macOS
iot-simulator

Development

Development Setup

The project uses modern Python packaging with pyproject.toml. Development dependencies are automatically installed with the [dev] extra.

Package name: tgiot-device-simulator

# Install in development mode with all tools
pip install -e ".[dev]"

Available Development Commands

# Code formatting
black .                    # Format all Python files
isort .                   # Sort imports

# Linting
ruff check .              # Fast Python linter
mypy .                    # Type checking

# Testing
pytest                    # Run all tests
pytest tests/ -v          # Verbose test output
pytest --cov=simulator    # Run tests with coverage

# Build and install
pip install -e .          # Install package locally
pip install -e ".[dev]"   # Install with dev dependencies

# Package build (for distribution)
python -m build           # Build wheel and source distribution

Project Structure

├── pyproject.toml        # Modern Python packaging configuration
├── simulator/           # Main package
│   ├── main.py         # Primary application entry point
│   ├── api/            # Platform API clients
│   ├── auth/           # OAuth2 authentication
│   ├── config/         # Configuration management
│   ├── connectivity/   # IoT Hub client
│   ├── device_setup/   # CLI-based device configuration
│   ├── provisioning/   # Device provisioning logic
│   ├── telemetry/      # Telemetry sender
│   │   └── message_generators/  # Message type generators
│   ├── twin/           # Device twin manager
│   ├── commands/       # C2D command processing
│   └── utils/          # Utilities and logging
│       └── schema/     # Schema utilities
├── config/             # Configuration files
├── tests/              # Test suite
├── schemas/            # Device type schemas
├── certificates/       # Device certificates
├── twin_schemas/       # Twin schemas
└── logs/               # Application logs

Entry Points:

• iot-simulator - Console command (recommended)
• iot-simulator --init - Initialize configuration
• python -m simulator.main - Direct module execution

Tandem Platform Device Simulator - Bridging the gap between IoT devices and cloud platforms with intelligent simulation and monitoring capabilities.