Tekko BDSimSimulator

Connect Arduino & ESP32 to Tekko Sim and AI

Turn a real knob, let Arduino send its reading to the browser and map it to a simulator slider. With permission, your AI can inspect the reading. This is an experimental device bridge, not an industrial control system. Physical validation on your board is required.

Your AIClaude / Codex ↔MCP Tekko SimYour browser ↔USB / WSS Real deviceArduino / ESP32
Device readings do not pass through a Tekko server. Sharing with AI and sending commands require separate permissions.

Plain words first

Compatibility and drivers

Not every IoT device works just by plugging it in. Starter sketches target Arduino Uno and classic ESP32. Other boards may need different pinouts, voltages and USB settings. Sensors normally connect to a board; custom firmware must read them and speak the Tekko protocol. Receiving a reading does not create a simulator model for an unsupported component.

The sketches have been compiler-tested; physical testing on your board is still required. If no port appears, check the data cable and USB port, then the manufacturer’s driver for your USB chip. Arduino IDE may also need the correct board package. This release is a browser and local connector, not an Electron installer.

Arduino board detection help · Browser serial support

1. Start with board and USB only

Use a known Uno or ESP32, a USB data cable and a desktop computer. Disconnect motors, relays, battery packs and mains-connected equipment. Begin with USB power only. Some boards reset when the port opens.

  1. Choose the correct Board and Port in Arduino IDE. Install a manufacturer driver only if needed.
  2. Download your sketch: Arduino Uno · Classic ESP32. Match the folder name to the sketch filename and open it in the IDE.
  3. Choose Upload, then close Serial Monitor; two apps cannot use the same port simultaneously.
  4. Open an editable circuit in Tekko Sim → Real device → Connect USB and select your board. Start with desktop Chrome/Edge; the panel reports when Web Serial is unavailable.
  5. Check that uptime_ms increases and led_state is 0. If readings are absent, check 115200 baud, cable and firmware.

Analog input starts disabled, so a floating pin is not shown as a meaningful reading. The ESP32 example uses GPIO34; check C3/S2/S3 pinouts and USB settings first. If no built-in LED pin is known, the sketch rejects LED commands rather than guessing.

2. Approve a command yourself

  1. Enable Allow commands after my approval, enter PING under Command and choose Review command. This only shows a preview.
  2. Send once sends once. acknowledged means firmware replied, not that physical action was observed.
  3. Send LED ON and observe the physical built-in LED. It turns off after three seconds. Also test LED OFF.
  4. Reject sends nothing. Pending requests expire after 30 seconds. A missing acknowledgement means unknown; inspect the device before retrying.

Disconnect closes the link; it does not cut power. Your firmware and hardware must handle communication loss independently. Do not use this prototype for safety-critical actuators.

3. Map a real knob to the simulator

Unplug USB before wiring a 10 kΩ potentiometer. Its middle pin is the wiper; the ends connect to supply and ground. Verify the pinout. Never apply 5V to an ESP32 input.

BoardEndsWiperRange
Arduino Uno5V, GNDA00–1023
Classic ESP323V3, GNDGPIO340–4095
  1. Change TEKKO_READ_KNOB 0 to TEKKO_READ_KNOB 1, upload, close Serial Monitor and reconnect.
  2. Turn the knob and record actual low/middle/high readings. If it does not reach the range endpoints, check calibration and ADC behavior.
  3. Add a Potentiometer in the sim. Open Real device → Feed a reading into the simulator.
  4. Set Sensor reading to knob and Simulator input to potentiometer Turn. Use minimum 0 and maximum 1023 for Uno or 4095 for ESP32, then Use reading.
  5. Turning the real knob changes the simulated input. This maps an input; it does not upload the entire circuit to hardware. Unplugging pauses mapped simulation; five seconds without data marks readings stale. Press Run after fresh data returns.

4. AI, simulator and device together

AI setup guide — connect the device in the separate window opened by the first Tekko tool call. AI cannot see a device connected in another ordinary tab.

  1. With Share readings with AI off, ask for readings; they must be withheld. Enable it and ask: “Use tekko_hardware_status, explain the real readings and distinguish them from simulation.”
  2. With write permission off, AI command requests must fail. Enable it and ask: “Propose PING, but wait for my approval.” Check the pending request; nothing is sent without Send once.
  3. Revoking sharing blocks future readings and, while real input is mapped, simulator status too. Previously sent data cannot be recalled from your AI provider; share only data you intend to send.

5. Work offline after preparation

While online, download and extract the connector. In its mcp-src folder run npm ci and npx playwright install chromium. Prepare Arduino IDE, any driver and board packages too, separately on each computer/OS.

node offline.mjs

Disconnect internet and run this command. Test local circuit editing, Arduino/MicroPython simulation and USB. External browser requests are blocked. Cloud AI, external MCP, public sharing and internet gateways are unavailable. For a previously configured compatible local AI client/model, use the stdio connector with TEKKO_OFFLINE=1. Visiting the website once is not offline preparation.

Report your physical test results

For Saleh or any tester: mark every row PASS / FAIL / NOT TESTED. Include board model, OS, browser, sketch version, AI app, exact errors and reproduction steps. Add screenshots/video without passwords or tokens. Software test success does not prove physical validation.

TestExpected resultResult
USB connect and reconnectCorrect board; uptime increases; permissions OFF on reconnect____
PING / LED ON / LED OFFMatching ack; observe physical LED and three-second auto-off____
Reject / wait 30 seconds / revoke writesNo unapproved command sent____
Knob low / middle / highRecord three real values; mapped input follows____
Unplug / stop telemetryDisconnected or stale; mapped simulation pauses____
AI sharing and PING requestReadings only with consent; one send after approval____
Open another projectDevice disconnects and permissions reset____
Offline / wrong cable / busy port / wrong baudLocal work runs offline; failures do not claim success____

Developers: custom firmware and Wi-Fi gateways

The USB starter flow has software tests; physical verification is separate. You can also connect your own secure gateway at wss://… or a local bridge at ws://localhost. Insecure LAN WebSockets are not accepted from the HTTPS site. Gateways need suitable authentication, Origin checks and the same protocol. No Tekko relay or MQTT credentials are involved; the simulator MQTT broker remains virtual.

{"protocol":"tekko-bridge-v1","type":"telemetry","values":{"knob":512}}
TK request-id PING
{"protocol":"tekko-bridge-v1","type":"ack","id":"request-id","ok":true}

Send one JSON record per serial line or one text record per WebSocket message. Limits: 4096 characters per line, 32 finite numeric fields and 160 printable characters per command. Map only fresh in-range readings. Ack request IDs must match; a completed write or timeout does not prove physical execution. Add device watchdogs and hardware interlocks before extending beyond the starter LED.

Chrome Web Serial · Espressif Arduino Serial API

Open Tekko Sim