TeHyBug
This F.A.Q. covers the latest TeHyBug firmware and features.

Frequently Asked Questions

TeHyBug is an IoT environmental monitoring system that tracks temperature, humidity, pressure, and other sensor data. It consists of ESP8266/ESP8285-based hardware devices and a cloud platform for data visualization and management.

Key features include:

  • Real-time environmental monitoring
  • WiFi connectivity
  • Multiple sensor support
  • Cloud data storage and visualization
  • Low power consumption with deep sleep mode
  • Easy OTA (Over-The-Air) firmware updates

The latest TeHyBug firmware is a complete rewrite in C/C++ (previous versions were partially written in Lua).

Key Features:
  • Fully written in C/C++ for better performance
  • Easy OTA (Over-The-Air) updates via web interface
  • Enhanced stability and reliability
  • Improved power management

The firmware is compatible with TeHyBug Universal boards (without display):

  • TeHyBug 18650 Universal v1 (ESP-01 based)
  • TeHyBug 18650 Universal v2 (ESP-M based)
  • Mini TeHyBug
  • Gumboard
  • Other TeHyBug boards with audio jack connector for sensors
Note: The firmware also works with generic ESP8266/ESP8285 dev boards (Wemos, Lolin, NodeMCU, etc.), but the indicator LED and deep sleep power saving mode may not function properly.

TeHyBug has two buttons:

  • RESET Button: Forces TeHyBug to reboot/restart
  • MODE Button: Activates configuration mode after reset during device boot

Live Mode

Device is configured to serve data (via HTTP/MQTT) with power-saving deep sleep enabled and config mode deactivated in system settings.

  • LED blinks rapidly
  • Device sends data at configured intervals
  • Enters deep sleep between measurements
Config Mode

TeHyBug serves a web interface at http://tehybug.local where you can configure everything.

  • LED is solid blue
  • Device acts as configuration portal
  • All settings can be modified
To return to Config mode from Live mode:
  1. Press the RESET button
  2. Push and hold the MODE button until LED turns blue
  3. Release the MODE button

Port B (green audio jack) supports the following sensors:

  • BME680 - Temperature, humidity, pressure, and gas sensor
  • BME280/BMP280 - Temperature, humidity, and pressure sensor
  • DHT21/DHT22/AM2032 - Temperature and humidity (in DHT simulation mode)
  • AHT20 - Temperature and humidity sensor
  • MAX44009 - Ambient light sensor
  • DS18B20 - Digital temperature sensor
  • Other I2C and OneWire sensors (requires code modification)

Pin Mapping: See the Port B pinmapping documentation for detailed connection information.

Port A (black audio jack) supports the following sensors:

  • DHT21/DHT22/AM2032 - Temperature and humidity (in DHT simulation mode)
  • DS18B20 - Digital temperature sensor
  • ADC Soil Moisture Sensor - Analog soil moisture measurement
  • Other ADC and OneWire sensors (requires code modification)

Pin Mapping: See the Port A pinmapping documentation for detailed connection information.

Configuration First Steps:
  1. Connect an external sensor to the board's 3.5mm audio jack connector
  2. Connect power supply to micro USB port
  3. TeHyBug will boot with solid blue LED
  4. Connect to TeHyBug WiFi network (Password: TeHyBug123)
  5. Open http://192.168.4.1/ in your browser and click configuration button
  6. Provide your WiFi network credentials and save
  7. TeHyBug will connect to your network and boot in configuration mode
  8. Open http://tehybug.local/ in your browser
  9. Follow the instructions on the configuration page
If http://tehybug.local/ doesn't work, find the device IP from your router and use that instead.

Demo Configuration Page: View Demo

You can update the firmware using the built-in OTA (Over-The-Air) feature:

  1. Connect to your TeHyBug device's configuration portal
  2. Navigate to the "Firmware Update" section
  3. Select the firmware file (.bin) you want to flash
  4. Click "Update Firmware"
  5. Wait for the update process to complete (device will reboot automatically)
Make sure your device is connected to power during the update process to avoid corruption.

The OTA update page is at http://tehybug.local/update (or http://<device-ip>/update). It is protected — Username: TeHyBug, Password: FreshAirMakesSense.

The TeHyBug family covers several WiFi environmental devices, all based on ESP8266/ESP8285:

  • TeHyBug 18650 Universal (v1 ESP-01, v2 ESP-M) & Mini TeHyBug — temperature / humidity / pressure / air-quality loggers with audio-jack sensor ports
  • GumBoard — TeHyBug sensor board
  • CO2 sensor (FreshAirMakesSense) — SCD4X or Senseair S8 CO2 with OLED display
  • CO2 Desk monitor — SCD4X CO2 with an E-Paper display and RGB air-quality LEDs
  • Indicator board — 15 WS2812B RGB LEDs, buzzer, PIR motion + reed (open-door) sensor, on-board AHT20
  • Display / Clock
  • TeHyButton — battery-powered WiFi button / water-leak / open-door sensor

Devices can be ordered from Tindie, and 3D-printable enclosures are on Thingiverse.

The CO2 sensor (FreshAirMakesSense) measures CO2 with an SCD4X or Senseair S8 sensor, plus optional temperature/humidity/pressure via external AHT10/BMx280. Features:

  • OLED (or E-Paper, on the Desk model) display
  • RGB air-quality indication: green = normal, yellow = medium, red = high CO2
  • Home Assistant MQTT auto-discovery (just enter your MQTT broker IP)
  • Web server for OTA updates and JSON sensor data
  • Offline display-only mode (no WiFi)
Calibration:
  • SCD4X auto-calibrates and usually needs no manual calibration.
  • To force calibration, take the device outside to fresh air, wait ~5 minutes, then hold the calibration button (RIGHT/IO_14/IO_4 depending on model) — about 1 second on the CO2 sensor, or 15 seconds on the Desk. Wait ~5–15 minutes without moving it until calibration finishes (LED turns green). Outdoor air ≈ 400 ppm is used as the reference.
  • The Senseair S8 needs occasional manual calibration the same way.

The CO2 Desk monitor shows temperature, humidity, CO2 (ppm), optional PM2.5 (µg/m³) and pressure (hPa) on its E-Paper display, with two RGB LEDs for air quality at a glance.

CO2 levels (ppm):

  • < 1000 — good / normal indoor air
  • 1000–1500 — getting stuffy, open a window
  • > 1500 — ventilate immediately

PM2.5 levels (µg/m³): < 12 good, 12–35 moderate, > 35 unhealthy.

Outdoor air ≈ 400 ppm; a well-ventilated room is 400–800 ppm. If no PM2.5 sensor is fitted, both LEDs show CO2.

The TeHyButton is a battery-powered, latching WiFi button on an ESP8285. Pressing it powers the device on, it joins WiFi, reports the press, then cuts its own power — so there is no standby battery drain between presses.

  • Reports single click, double click and long press (via the %state% placeholder)
  • Sends the event by HTTP GET, HTTP POST and/or MQTT
  • Each device has a unique key (%key%) for use with tehybug.com or your own server
  • WiFi setup via captive portal, configured through a built-in web dashboard, with OTA firmware updates

It also works as a WiFi water-leakage sensor or open-door sensor.

Yes — with a DS3231 RTC + I²C EEPROM module attached, the TeHyBug Universal/Mini (ESP8285 build) stores timestamped readings on the device itself, with no server, broker or network. Configure and read it on the Data Log page of the web interface.

  • One file per day, a full month retained (32 KB EEPROM split into 32 ~1 KB slots); the oldest day is recycled when full.
  • Switch to per-hour logging for a finer rolling 24 hours. Changing the period wipes the log so it starts clean.
  • Log what you want via a placeholder template (e.g. %temp% %humi%); a compact format fits more entries.
  • The log interval is independent of data-serving; in offline mode it also sets the deep-sleep interval, with WiFi fully off.

To read the data while in offline mode, press RESET then hold MODE until the LED turns blue to re-enter Config mode.

Most updates are done over-the-air (see "How do I update the firmware?"). To flash manually over USB, first boot the device into flash mode: hold the MODE button and press RESET, release RESET first, then release MODE (the LEDs go off).

Then flash the .esp8285.bin (or .esp8266.bin) file with any of:

  • BugZapper — the bundled flasher with a built-in serial monitor (no separate PyFlasher/CoolTerm needed). Run ./bugzapper.sh (GUI) or ./flash.sh (CLI).
  • Arduino IDE — select a generic ESP8285 board (flash size "2MB FS:64KB OTA:~992KB", Basic SSL ciphers).
  • esptool or other ESP flashing tools.

Factory reset / WiFi reset: press the RESET button, then shortly after push and hold the MODE button for 15+ seconds. This erases the WiFi configuration and all settings, and the device returns to its setup access point.

Don't keep MODE held down during power-on/boot — that enters firmware-flash mode, not a factory reset. Tap RESET first, then push and hold MODE.

Just changing settings/WiFi (without a full reset): press RESET, then hold MODE until the LED turns blue to re-enter Config mode, reconnect to the device's WiFi network and adjust the configuration.

Battery-powered TeHyBugs save power with a deep-sleep mode between measurements. To enable it:

  • Set the data frequency to 6 minutes or more. Below 6 minutes the device stays connected to WiFi and consumes much more power (not recommended on battery).
  • 15 minutes or more is recommended for battery operation. The maximum value is shown on the device's node-info page.
  • For the absolute lowest draw, use offline mode with an RTC+EEPROM module (no WiFi at all).
Don't try to remove the black glue on the ESP-01 module — it protects a tiny wire that enables deep sleep.

  • No reverse polarity. TeHyBug is not protected against it — connecting power backwards to the screw terminal will damage the device.
  • Voltage range: min 3.4 V, max 12 V (5 V recommended). With a 9 V battery, make sure real voltage stays below 10 V.
  • Never use a battery and the Micro USB supply at the same time — it will damage the device.

Note: the MODE button is on GPIO0, so holding it during reset boots the ESP into firmware-flash mode. To enter Config mode, press MODE after the device has booted, not while holding RESET.

Yes. The CO2, CO2 Desk and Indicator firmwares support Home Assistant MQTT auto-discovery: enter your MQTT broker IP in the device configuration and the device appears automatically in Home Assistant.

All current devices also run a small web server that serves live readings as JSON (e.g. http://tehybug.local/), and there's an iOS Scriptable widget available too.

Yes — two ways, depending on what you want:

Quick-launch app icon (iOS & Android)

Open tehybug.com in your phone's browser and choose Add to Home Screen (Safari: Share → Add to Home Screen; Chrome: ⋮ → Add to Home screen). You'll get a TeHyBug app icon that opens straight into your live Overview of all devices.

A live home-screen widget (iOS)

For an at-a-glance widget that shows a reading without opening anything, use the free Scriptable app. There are two scripts depending on how you want to reach the device:

A) On your home WiFi — works with any device (incl. CO2 sensors)

The device serves its own readings locally, so no account or public key is needed — your phone just has to be on the same network. Use the local TeHyBug widget script (it reads http://tehybug.local/).

B) From anywhere — for cloud-connected devices (Universal / Mini)

  1. Enable public access on the device (device → Settings) and copy its public key (the part after /bugs/public/ in the share link).
  2. Install Scriptable, create a new script, and paste in our cloud TeHyBug widget script.
  3. Add a Scriptable widget to your home screen, then long-press it → Edit Widget → set Parameter to your public key (optionally with a value), e.g. yourkey, yourkey,co2, or yourkey,h (values: t temp, h humidity, p pressure, co2, v battery).
Android: there's no simple equivalent of Scriptable, so the Add to Home Screen shortcut above is the easiest option. For a live widget, a builder like KWGT (web-fetch) or an automation app like Tasker can pull from our JSON feed at tehybug.com/api/public/bug/<public-key>/latest.