SensorSim

A web-based sensor simulator for VirtualChameleon. Simulates the physical sensors on the remote end of the MQTT connection — ADC inputs, digital inputs, and digital output indicators — all controllable from a browser UI.

Requirements

• Linux
• Python 3.11+
• An MQTT broker (e.g. Mosquitto)

Installation

cd sensorsim
python3.11 -m venv .venv
.venv/bin/pip install -e .

Running

.venv/bin/sensorsim

Command Line Options

Flag	Default	Description
--config	config.yaml	Path to config YAML
--port	from config (8080)	Override web port
--host	0.0.0.0	Bind address

Open your browser to http://<host>:8080 to access the simulator UI.

Configuration

Edit config.yaml directly or use the web UI settings panel (gear icon).

mqtt:
  host: localhost
  port: 1883
  username: null    # optional
  password: null    # optional

device:
  id: cham-1        # VirtualChameleon device ID
  web_port: 8080

channels: []        # configured via web UI

layout_order: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18]

Channel Configuration

Channels are configured through the web UI by clicking on any unconfigured (grayed out) channel slot. Each channel supports:

ADC Input (pins 1-8 only):

• Name, unit label (e.g. "Volts", "Amps", "RPM")
• Min/max range (mapped linearly to 0-255 ADC value)
• Default value
• Widget style: slider or rotary knob

Digital Input (pins 9-18 for inp, pins 1-18 for in):

• Name, state labels (e.g. "Open"/"Closed")
• Which label maps to 0 vs 1
• Default state

Digital Output (pins 1-18):

• Name, state labels
• Indicator color or unlit state for each value (e.g. red/green, green/off)

Pin constraints match the real uChameleon hardware:

• inadc — only pins 1-8
• inp — only pins 9-18
• in / out — any pin 1-18

MQTT Topics

Published by SensorSim (inbound to VirtualChameleon)

Topic	Payload	Description
physical/{device_id}/pin/{N}/adc	0-255	ADC reading from simulated analog input
physical/{device_id}/pin/{N}/state	0 or 1	Digital input state
physical/{device_id}/status	online or offline	Simulator device status

Subscribed by SensorSim (outbound from VirtualChameleon)

Topic	Payload	Description
vchameleon/{device_id}/pin/{N}/output	0 or 1	Output pin state set by application

Publishing Behavior

• All configured pin values are published every 5 seconds
• Values are also published immediately on change
• When the device is toggled offline, publishing stops
• On MQTT reconnect, all current values are republished immediately

Web UI Features

• 18-channel grid (6x3, responsive)
• Drag-and-drop channel reordering (persisted)
• Real-time WebSocket updates
• MQTT connection status indicator
• Online/Offline toggle
• Settings panel for MQTT and device configuration
• All configuration persists to YAML

How It Works

SensorSim acts as the "physical world" that VirtualChameleon expects on the other end of MQTT. When you move a slider representing battery voltage (0-15V), SensorSim scales the value to 0-255 and publishes it to physical/cham-1/pin/1/adc. VirtualChameleon receives this and presents it to the application over the virtual serial port as if a real ADC were reporting.

For digital outputs, when the application sets a pin high via VirtualChameleon, it publishes to vchameleon/cham-1/pin/14/output. SensorSim subscribes to this and updates the indicator light on the UI.

sensorsim

sensorsim