Troubleshooting

Build or programming failure

• Run pio run -e stratolink from firmware, where the custom board definition and environment live.
• Check that include/secrets.h exists and the dependencies match the source revision. Do not upgrade every library to work around one build error.
• If J-Link cannot connect, check target power, voltage reference, common ground, SWDIO, SWCLK, reset, and connector orientation.
• The payload is programmed over SWD. A USB serial cable alone cannot replace the programmer.

Keep the first build error or J-Link connection error. Later messages are often consequences of that first failure.

No join in TTN

1. Confirm you are looking at the right application, device, and cluster.
2. Check that DevEUI, JoinEUI, and AppKey match the firmware without byte reversal or separators.
3. Check the frequency plan, regional parameters, antenna, and gateway coverage.
4. Give the payload a clear sky view and enough power for GPS. Current development firmware may stay silent until it has regional authority.
5. If the gateway sees a join request but the device never completes the join, inspect TTN’s join errors and downlink delivery. An uplink-only connection is insufficient for OTAA.

Do not reset frame counters, discard nonce history, or reuse another device’s identity as a troubleshooting shortcut.

Packets without a usable position

Inspect raw telemetry and GPS fields separately. The receiver needs a fresh fix, not just serial activity or a repeated position. Move outdoors, give the GPS antenna a clear sky view, and check power during acquisition.

A packet with unavailable GPS should still carry whatever other readings the firmware could obtain. Do not substitute the receiving gateway’s coordinates for the payload coordinates. Repeated historical GPS values can be stale even when packet timestamps advance.

Some San Francisco positions are deliberately approximate. This is a privacy treatment, not GPS accuracy.

TTN receives packets but the dashboard is empty

1. In TTN Live data, note the exact application, device ID, DevEUI, packet time, frame counter, fPort, and raw payload length.
2. Open Your balloons in the dashboard. Confirm the corresponding network is listed. If it is not, complete Connect TTN; the initial registration alone does not forward packets.
3. Check the custom webhook in the same TTN cluster and application. Use its complete dashboard URL, enable uplink messages, and copy the Authorization header exactly.
4. Check the delivery status. After using Reconnect, update TTN with the new header. The previous credential no longer works.
5. Leave event-data filters empty. A decoder error can omit decoded_payload, but the raw frm_payload and identity fields must still be forwarded.
6. Send a new packet and check Last received. Then clear fleet filters, enable inactive balloons, and scrub to that reception time.

If TTN reports an invalid payload, check that the installed decoder matches the firmware’s packet version and port. If the globe is blank but cards load, check WebGL support and the Mapbox configuration.

Unexpected power or sensor readings

Compare voltage telemetry with a meter at the same time and rail. VSTOR is the storage rail, not the regulated 3.3 V rail. A reading during transmission may differ from an idle reading.

Check a missing sensor on the I²C bus and verify its power state. The expected addresses are LIS2DH12 0x18, TMP117 0x48, LTR-390UV 0x53, and MS5611 0x76.

Recheck sleep current with the debugger disconnected. Then test the finished energy store through darkness and recovery. A power-supply bench run does not measure the leakage or balance of the final capacitor assembly.

For help, send contact@stratolink.org the board and firmware revision, device ID, packet timestamp, and the relevant error. Remove keys and private location data from screenshots and logs.