Skip to content

Hardware Reference

Current hardware (documented here)

This dev documentation intentionally focuses on the currently used hardware:

  • Board: Heltec WiFi LoRa 32 (V3.2) / HTIT‑WB32LA V3.2 (ESP32‑S3 + SX1262)
  • IAS sensor: TE Connectivity MS4525DO (I2C differential pressure sensor)

Datasheets (local assets)

Because docs/dev/docs/assets is a symlink to docs/assets, these PDFs are available as local MkDocs assets:

Firmware touchpoints (repo-relative)

  • Radio (SX1262): main/radio/
  • Sensor stack: main/sensors/
  • OLED UI: main/display/
  • Winch WS2812 LED strip: main/winch/owts_winch_led.*

MS4525DO (PX4AirspeedV1.1) wiring (5V module + level shifter)

The common PX4AirspeedV1.1 breakout is a 5V MS4525DO module. The ESP32‑S3 GPIOs are 3.3V only, so wire SDA/SCL through a bi-directional level shifter.

OWTS defaults for the sensor bus use header-accessible GPIOs:

  • SDA: GPIO4
  • SCL: GPIO5

Complete wiring diagram (text)

                           ┌───────────────────────────────────────────────┐
                           │        Heltec HTIT‑WB32LA V3.2 (ESP32‑S3)     │
                           │                                               │
                           │  5V   o────────────────┐                      │
                           │  3V3  o────────┐       │                      │
                           │  GND  o────┐   │       │                      │
                           │            │   │       │                      │
                           │ GPIO4 o────┼───┼─────────────── SDA (LV side) │
                           │ GPIO5 o────┼───┼─────────────── SCL (LV side) │
                           │            │   │                              │
                           └────────────┼───┼──────────────────────────────┘
                                        │   │
                                        │   │
                                        │   │
                    ┌───────────────────▼───▼─────────────────────┐
                    │        4‑channel bi-directional shifter     │
                    │                                             │
                    │  HV  o───────────────(to ESP 5V)            │
                    │ GND  o───────────────(to ESP GND)           │
                    │                                             │
                    │  LV  o───────────────(to ESP 3V3)           │
                    │ GND  o───────────────(to ESP GND)           │
                    │                                             │
                    │ HV1 o─────────────── Sensor SDA (5V side)   │
                    │ LV1 o─────────────── ESP GPIO4 (SDA)        │
                    │                                             │
                    │ HV2 o─────────────── Sensor SCL (5V side)   │
                    │ LV2 o─────────────── ESP GPIO5 (SCL)        │
                    └─────────────────────────────────────────────┘

                    ┌─────────────────────────────────────────────┐
                    │          MS4525DO 5V module (PX4Airspeed)   │
                    │                                             │
                    │  5V  (red)   o─────────────── to ESP 5V     │
                    │  GND (black) o─────────────── to ESP GND    │
                    │  SDA (yellow)o─────────────── to HV1        │
                    │  SCL (green) o─────────────── to HV2        │
                    └─────────────────────────────────────────────┘

Notes

  • Ground must be common: ESP GND, shifter GND, sensor GND all tied together.
  • HV vs LV: HV side is the 5V domain (sensor), LV side is the 3.3V domain (ESP).
  • Sanity check: with power on and everything connected, SDA/SCL idle-high on the ESP side should read ~3.3V, not 5V.

Winch mode: WS2812 / WS2812B LED strip wiring (5V power + 3.3V data)

In winch mode, OWTS can drive an addressable LED strip (WS2812/WS2812B) as a VU-style speed indicator using the same blue→green→red scheme as the frontend.

Power + data domains

  • Power: use the board 5V output for the strip (small strips only; see notes).
  • Data: the ESP32‑S3 GPIO is 3.3V. For short wiring and small LED counts this often works directly. A 5V level shifter can improve margin but is optional.

Recommended wiring (text)

                           ┌───────────────────────────────────────────────┐
                           │        Heltec HTIT‑WB32LA V3.2 (ESP32‑S3)     │
                           │                                               │
                           │  5V   o──────────────┐                        │
                           │  GND  o───────────┐  │                        │
                           │                   │  │                        │
                           │ GPIOxx o───[330Ω]─┼──┼──────────────► DI      │
                           │         (series)  │  │                        │
                           └───────────────────┼──┼────────────────────────┘
                                               │  │
                                               │  │
                    ┌──────────────────────────▼──▼─────────────────────────┐
                    │                 WS2812 / WS2812B strip                │
                    │                                                       │
                    │  +5V  o────────────────────── to ESP 5V               │
                    │  GND  o────────────────────── to ESP GND              │
                    │  DI   o────────────────────── from ESP GPIOxx         │
                    └───────────────────────────────────────────────────────┘
  • Common ground: ESP GND and strip GND must be tied together.
  • Two GND wires: some WS2812 pigtails expose both power GND and digital GND (e.g. blue + white). Tie both to the board ground (or tie together at the strip input).
  • Series resistor on data: ~330–470 Ω close to the ESP output helps reduce ringing.
  • Bulk capacitor on 5V: e.g. \(≥ 470 µF\) (often 1000 µF) across strip +5V/GND near the strip input helps with inrush/current spikes.

Optional: re-use the existing I2C level shifter

If you already have the typical BSS138 bi-directional MOSFET level shifter installed for the MS4525DO wiring, you can route the WS2812 data line through one channel — but it’s not ideal for the WS2812’s fast one-wire timing. Direct 3.3V often works better for short runs.

If you want a “proper” shifter, use a 74AHCT125 / 74HCT14 (powered from 5V) for a clean 3.3V→5V data signal.

Optional resistor (pull-down)

If your strip’s DI line tends to float during boot (random colors), add a pull-down ~10 kΩ from DI to GND on the strip side. A pull-up is usually not desired; OWTS wants the line low when idle/off.

Firmware configuration touchpoints

  • Enable driver: CONFIG_OWTS_WINCH_USE_WS2812
  • Select data pin: CONFIG_OWTS_WINCH_WS2812_GPIO

Runtime settings (count, brightness, dim-below factor, reverse, color order) are persisted in NVS and can be updated via GET/PATCH /api/winch/led.

Power budget note

Board 5V is fine for small strips (e.g. 10 LEDs). For larger n or full-brightness white, use an external 5V supply sized for the strip and keep grounds common.