The Reality of Vendor Apps

Why build a custom watch app?

The hardware from LilyGO was great, but the software story was a dead end. The official companion phone app provided by the manufacturer was so severely outdated that it completely failed to install and run on modern phones. Without a functioning controller, the hardware was essentially a brick. Instead of giving up, I decided to dive into their firmware, reverse-engineer the UDP packet structures they were using, and build my own dedicated, tactile Wear OS smartwatch controller from scratch to bring the thruster back to life.

Network Discovery

Subnet Scanning & Multicast.

Once I understood the protocol, the first hurdle was simply finding the boat on the network. The LilyGO hardware creates an ad-hoc Wi-Fi network, but the smartwatch has no idea what the target device's IP address is. Hardcoding an IP makes the system brittle; broadcasting blindly wastes battery and congests the network.

Discovery Layer

Safe-Payload Pinging

The app implements an aggressive, mathematically constrained subnet scanner. It iterates from subnet.1 to subnet.254, firing a specifically crafted "zero-throttle" UDP payload. This guarantees that if it hits the thruster, the motors will not physically fire during discovery.

Telemetry Acknowledgment

UDP Port 2390

The watch listens concurrently on UDP Port 2390. When the hardware receives the safe ping, it immediately returns a telemetry packet containing signal strength (RSSI) and battery voltage. The watch captures the sender's IP address and locks onto it, instantly completing the dynamic handshake.

Reverse-Engineering Hurdles

Physical Protocol Negotiation.

Writing software for undocumented hardware introduces catastrophic failure states that don't exist in pure web development. During testing, I discovered that different iterations of the LilyGo control boards interpreted the throttle bytes completely differently.

The LilyGo Classic (V1) Short: On older hardware revisions, the PWM driver was designed such that sending a raw 0 integer caused the H-Bridge to electrically short, risking permanent damage to the silicon. The valid range was 1 to 128, where 1 was absolute zero throttle. In contrast, the newer V2 hardware uses a standard 0 to 255 range.

To prevent hardware destruction, the ThrusterController.kt engine implements strict mathematical coercion. Before firing any UDP packet, the joystick's 0.0 to 1.0 float vector is passed through a deterministic protocol filter. If V1 is selected, 0.0 is strictly clamped to 1, mathematically guaranteeing the silicon will never receive a short-circuit command.

UI Engineering

Kinematic Jetpack Compose

Controlling differential thrust on a 1.4-inch circular smartwatch screen requires absolute precision. A standard square bounding box would result in dead zones at the corners of the round display.

Atan2 Geometry

Radial Bounding

The custom Compose Canvas joystick tracks drag gestures using Pythagorean distance checks. If the user drags outside the permitted circle, the app uses atan2() to calculate the exact angle and mathematically clamps the thumbpad to the extreme edge of the radius.

Tactile Feedback

Haptic Edge-Limits

Operators driving the thruster cannot constantly stare at their wrist. When the mathematical drag vector crosses the maximum boundary radius, the Compose layer instantly triggers the watch's internal Vibrator motor, providing a physical "click" that confirms maximum throttle has been reached without looking.