birdcage/docs/ble-bridge-wiring.md

BLE Bridge Wiring — ESP32-S3 + 2× MAX485

Transparent BLE-to-RS422 bridge for the Winegard Carryout G2 satellite dish, with optional IMU and barometric sensors for orientation and refraction correction.

Parts

Bridge (required):

• ESP32-S3-DevKitC-1-N16R8
• 2× MAX485 TTL-to-RS485 module
• 1× SparkFun Bidirectional Logic Level Converter (BOB-12009, BSS138-based)
• RJ-12 6P6C straight-wired cable with breakout
• Hookup wire / jumpers

Sensors (optional):

• 1× GY-9250 (MPU-9250) — 9-axis IMU (accelerometer + gyroscope + magnetometer)
• 1× BMP388 — barometric pressure + temperature
• 1× RYS352A GPS module — observer location + PPS timing

Schematic

                          SparkFun Level Converter (BOB-12009)
                         ┌──────────────────────────────────────┐
                         │                                      │
ESP32 3V3 ──────────────►│ LV                            HV │◄── ESP32 5V
ESP32 GND ──────────────►│ GND                          GND │◄── (shared)
                         │                                      │
ESP32 GPIO17 (TX) ──────►│ LV1                          HV1 │──────► MAX485₁ DI
ESP32 GPIO18 (RX) ◄──────│ LV2                          HV2 │◄────── MAX485₂ RO
                         │                                      │
                         │  LV3  (spare)          HV3  (spare)  │
                         │  LV4  (spare)          HV4  (spare)  │
                         └──────────────────────────────────────┘


    MAX485 Board 1 (TX only)              MAX485 Board 2 (RX only)
    ┌────────────────────────┐            ┌────────────────────────┐
    │  VCC ◄── 5V            │            │  VCC ◄── 5V            │
    │  GND ◄── GND           │            │  GND ◄── GND           │
    │                        │            │                        │
    │  DI  ◄── HV1           │            │  RO  ──► HV2           │
    │  RO     (unused)       │            │  DI     (unused)       │
    │                        │            │                        │
    │  DE  ◄── 5V ┐ locked   │            │  DE  ◄── GND ┐ locked  │
    │  RE  ◄── 5V ┘ TX mode  │            │  RE  ◄── GND ┘ RX mode │
    │                        │            │                        │
    │  A  ───────────────────┼──► pin 2   │  A  ◄──────────────────┼── pin 4
    │  B  ───────────────────┼──► pin 3   │  B  ◄──────────────────┼── pin 5
    └────────────────────────┘            └────────────────────────┘

                        RJ-12 to Carryout G2
                    ┌───────────────────────────┐
                    │  Pin 1 (White)  ── GND     │◄── ESP32 GND
                    │  Pin 2 (Red)    ── TX+/TA  │◄── A₁
                    │  Pin 3 (Black)  ── TX-/TB  │◄── B₁
                    │  Pin 4 (Yellow) ── RX+/RA  │──► A₂
                    │  Pin 5 (Green)  ── RX-/RB  │──► B₂
                    │  Pin 6 (Blue)   ── N/C     │
                    └───────────────────────────┘

Power Rails

ESP32 5V ──┬── Level Converter HV
           ├── MAX485₁ VCC
           ├── MAX485₁ DE + RE (tied high = TX mode)
           └── MAX485₂ VCC

ESP32 3V3 ─── Level Converter LV

ESP32 GND ─┬── Level Converter GND
           ├── MAX485₁ GND
           ├── MAX485₂ GND
           ├── MAX485₂ DE + RE (tied low = RX mode)
           └── RJ-12 Pin 1

RJ-12 Cable Notes

Straight-wired 6P6C. Pin 1 is leftmost when looking at the jack with the clip facing away from you (tab down). Wire colors per the standard flat cable:

Pin	Color	Function	Connects to
1	White	GND	Common ground
2	Red	TX+ (TA)	MAX485₁ A
3	Black	TX- (TB)	MAX485₁ B
4	Yellow	RX+ (RA)	MAX485₂ A
5	Green	RX- (RB)	MAX485₂ B
6	Blue	N/C	—

If crimping your own cable, verify pin-to-color with a multimeter before connecting to the dish. RJ-12 crimps are easy to get reversed (pins mirror if the connector is flipped). A wrong connection won't damage anything (differential signals are current-limited) but communication won't work.

How It Works

The Carryout G2 uses RS-422 full-duplex: two separate differential pairs, one for each direction. The MAX485 is a half-duplex RS-485 transceiver with a shared A/B pair and direction control pins (DE/RE). By hardwiring DE/RE, each board is locked into a single direction:

• Board 1 (TX): DE=HIGH, RE=HIGH → driver always enabled, receiver disabled. ESP32 UART1 TX → level shifter → DI → differential A/B → G2 serial RX.

• Board 2 (RX): DE=LOW, RE=LOW → driver disabled, receiver always enabled. G2 serial TX → differential A/B → RO → level shifter → ESP32 UART1 RX.

The SparkFun level converter translates between 3.3V (ESP32) and 5V (MAX485) on both data lines. The two spare channels (LV3/HV3, LV4/HV4) are available if DE/RE ever need GPIO control for a half-duplex variant.

Firmware

See firmware/ble-bridge/ — transparent BLE Nordic UART Service (NUS) bridge. The firmware is the same regardless of whether the RS-422 transceiver is a MAX490 (single full-duplex chip) or two MAX485s (locked half-duplex pair). It only sees UART TX/RX on GPIO17/18.

Sensors — I2C Bus

The MPU-9250 and BMP388 share a single I2C bus on GPIO8 (SDA) / GPIO9 (SCL). Both run at 3.3V directly from the ESP32, no level shifting needed.

                    I2C Bus (3.3V, 400kHz)
                    ─────────────────────

ESP32 3V3 ──┬──────────────────┬─── MPU-9250 VCC
             │                  └─── BMP388 VCC
             │
             ├── 4.7KΩ ── SDA bus ──┬── MPU-9250 SDA
             │                      └── BMP388 SDI
             │
             └── 4.7KΩ ── SCL bus ──┬── MPU-9250 SCL
                                    └── BMP388 SCK

ESP32 GPIO8  (SDA) ──── SDA bus
ESP32 GPIO9  (SCL) ──── SCL bus

ESP32 GND ──┬── MPU-9250 GND
             └── BMP388 GND (SDO to GND = addr 0x76)

MPU-9250 AD0 ── GND  (I2C address = 0x68)
BMP388   SDO ── GND  (I2C address = 0x76)

The 4.7KΩ pull-ups are shared — one pair for the whole bus. Many breakout boards include onboard pull-ups already; if both the GY-9250 and BMP388 boards have them, the combined parallel resistance (~2.3KΩ) is still fine for 400kHz I2C at 3.3V. Only add external pull-ups if neither board has them.

MPU-9250 (GY-9250) — 9-Axis IMU

I2C Address	0x68 (AD0 → GND)
VCC	3-5V (onboard LDO)
Interface	I2C (up to 400kHz) or SPI

What it provides for satellite tracking:

• Magnetometer (AK8963): Compass heading for automatic north alignment. Eliminates manual alignment of dish base "BACK" marking to true north. Apply local magnetic declination to convert magnetic north → true north.
• Accelerometer: Gravity vector → tilt angle = elevation. Independent verification of the dish firmware's reported EL position.
• Gyroscope: Angular rate during slews. Detect oscillation, overshoot, and vibration for tuning the leapfrog overshoot compensation algorithm.

Mounting considerations: The magnetometer is extremely sensitive to nearby ferrous metals and electromagnetic interference from motors. Mount on the fixed base plate, away from motor housings, with a known axis aligned to the dish's reference direction. Rigid mounting — any flex between sensor and dish structure introduces measurement error.

BMP388 — Barometric Pressure + Temperature

I2C Address	0x76 (SDO → GND)
VCC	3.3V
Pressure range	300-1250 hPa
Pressure resolution	±0.01 hPa (±8 cm altitude)
Temperature accuracy	±0.5°C
Interface	I2C (up to 3.4MHz) or SPI

What it provides for satellite tracking:

• Atmospheric refraction correction. Radio signals bend as they pass through the atmosphere, especially at low elevation angles. The amount of bending depends on air pressure and temperature. At 15° elevation (the Trav'ler's minimum), refraction shifts apparent position by ~0.2°. Standard refraction models (Bennett, Saemundsson) take pressure and temperature as inputs — the BMP388 provides both in real time.
• Temperature monitoring. Ambient temperature at the dish for thermal drift awareness and electronics health monitoring.

Refraction formula (simplified Bennett):

R = 1/tan(el + 7.31/(el + 4.4)) × (P/1010) × (283/(273 + T))

Where R is refraction in arcminutes, el is apparent elevation in degrees, P is pressure in hPa, T is temperature in °C. At el=15°, P=1013, T=20°C: R ≈ 3.4 arcmin ≈ 0.057°. Small but meaningful for narrow-beam antennas.

GPS — RYS352A

The RYS352A is a compact GPS module with PPS output. It connects via UART2 and provides observer location for satellite pass prediction and a 1Hz PPS pulse for precise UTC time synchronization.

ESP32 GPIO5 (UART2 RX) ◄── RYS352A TX  (NMEA sentences out)
ESP32 GPIO6 (UART2 TX) ──► RYS352A RX  (config commands in, optional)
ESP32 GPIO7             ◄── RYS352A PPS (1Hz rising edge, ~100ns jitter)
ESP32 3V3               ──► RYS352A VCC
ESP32 GND               ──► RYS352A GND

Module Pin	ESP32 Pin	Function
VCC	3V3	3.3V power (onboard LDO on most breakouts)
GND	GND	Ground
TX	GPIO5 (UART2 RX)	NMEA sentence output at 115200 baud
RX	GPIO6 (UART2 TX)	PAIR/NMEA config input (optional)
PPS	GPIO7	1Hz pulse synchronized to GPS time

PPS (Pulse Per Second): The RYS352A outputs a precise 1Hz pulse on the rising edge, synchronized to UTC via GPS constellation. The firmware captures this edge via interrupt (micros() timestamp) for correlating satellite events with sub-microsecond precision relative to the GPS epoch. The module's RTC battery backup enables warm starts (~5s) after initial cold start fix (~30-60s).

UART notes: The RYS352A defaults to 115200 baud NMEA output with GN talker ID (multi-constellation). The TX line (GPIO6) is used at boot to send $PAIR proprietary commands (Airoha AG3352 engine) that configure the GPS module for satellite tracking use. See docs/RYS352x_PAIR_Command_Guide.md for the full command reference.

Boot-time PAIR init sequence: The firmware sends $PAIR062 commands at startup to filter NMEA output — only GGA (position/quality), GSA (fix mode/DOP), RMC (time/date/speed), and GSV (satellite visibility, every 5th fix) are enabled. Redundant sentences (GLL, VTG, ZDA, GRS, GST, GNS) are disabled to reduce parser load and latency. A $PAIR752 command configures PPS to pulse only on 2D/3D fix with 100ms pulse width. Each command waits for $PAIR001 ACK; failures are logged but non-fatal — the GPS works with defaults if PAIR commands are unsupported.

The firmware uses TinyGPS++ v1.1+ with custom field extractors (TinyGPSCustom) to read GGA quality (field 6: SPS/DGPS/RTK) and GSA nav mode (field 2: 2D/3D) directly from the NMEA stream, replacing the earlier heuristic that inferred fix type from altitude validity. Both GN and GP talker ID variants are registered for compatibility across constellation configurations.

Full GPIO Map

GPIO	Function	Interface	Notes
5	GPS RX	UART2 RX	← RYS352A TX (NMEA out)
6	GPS TX	UART2 TX	→ RYS352A RX (config in)
7	GPS PPS	GPIO interrupt	1Hz rising edge
8	I2C SDA	I2C	MPU-9250 + BMP388 (shared bus)
9	I2C SCL	I2C	MPU-9250 + BMP388 (shared bus)
17	RS-422 TX	UART1 TX	→ Level shifter → MAX485₁ DI
18	RS-422 RX	UART1 RX	← Level shifter ← MAX485₂ RO
38	RGB LED	WS2812	Onboard NeoPixel (DevKitC V1.1)
43	USB Console TX	UART0	CH343 USB-serial (untouched)
44	USB Console RX	UART0	CH343 USB-serial (untouched)

Loopback Test (no dish)

Before connecting to the G2, verify the bridge by shorting MAX485₁ A to MAX485₂ A, and MAX485₁ B to MAX485₂ B (loop TX back into RX). Anything sent via BLE or USB serial should echo back.