Tello SDK Research

Overview

The DJI Tello and Tello EDU drones expose a Wi-Fi UDP text-based command protocol for control and telemetry queries. This document covers the protocol details relevant to building an Elixir adapter.

Protocol Basics

• Transport: UDP
• Drone IP: 192.168.10.1 (default, when connected to drone's Wi-Fi)
• Command Port: 8889 (default)
• Local Command Socket: configurable (Tello SDK typically uses 8889 as well)
• Encoding: Plain ASCII text commands, newline-terminated
• Response: Plain ASCII text responses (ok, error, numeric values)

Connection Sequence

1. Connect to drone's Wi-Fi access point (SSID: TELLO-XXXXXX)
2. Open UDP socket on local port (default 8889)
3. Send command to enter SDK mode
4. Receive ok or error response
5. Drone is now ready to accept commands

The Tello EDU supports station mode where the drone connects to your network, but the primary connection model is direct Wi-Fi.

SDK Mode Activation

Send:    "command"
Receive: "ok"

This must be sent before any other command. Without it, the drone ignores UDP packets.

Movement Commands

All movement commands are blocking from the drone's perspective. The drone sends the response only after completing the movement.

Movement Constraints

• Minimum distance: 20 cm, maximum: 500 cm
• Minimum rotation: 1 degree, maximum: 3600 degrees
• Speed range: 10-100 cm/s
• The drone hovers between commands -- there is no "continue moving" mode in the text SDK
• Commands are queued: sending a new command while one is executing will queue it

Query Commands

Query commands return numeric values instead of ok.

Response Format

• Success: ok (for commands) or numeric string (for queries)
• Error: error (generic error)
• Timeout: No response within the configured timeout period
• Not in SDK mode: No response at all

Timing and Throttling

• Default command timeout: varies by implementation, typically 5-15 seconds
• Movement commands block until the drone completes the action
• Queries are fast (sub-second)
• The SDK documentation recommends sending commands at a reasonable rate
• Sending commands too rapidly can cause dropped packets (UDP has no backpressure)
• The drone has an internal command queue with limited capacity

State Machine

[Idle] --command--> [SDK Mode] --takeoff--> [Flying]
  ^                    |                      |  |
  |                    |                      |  |
  +--------------------+--land/emergency------+--+

• In Idle, the drone ignores all UDP commands except command
• In SDK Mode, the drone accepts commands but is not flying
• In Flying, movement and query commands work
• land returns to SDK Mode
• emergency returns to Idle (motors stop, need command again)

UDP Considerations

• UDP is connectionless -- there is no handshake
• Packet loss is possible, especially over Wi-Fi
• The drone does not guarantee command delivery
• Commands may arrive out of order if sent rapidly
• No built-in acknowledgment beyond the text response
• Socket should be bound to a specific local port and reused for the session

Tello EDU vs Tello (Standard)

The Tello EDU's station mode is essential for swarm control: it allows the drone to join a Wi-Fi network rather than creating its own access point.

Safety Considerations

• emergency must always be available and bypass all normal safety checks
• takeoff and land are single-command actions that move the drone through critical state transitions
• Movement commands take time to complete -- retrying them automatically is dangerous
• The drone has no collision avoidance in the text SDK
• Battery state is only available via polling -- there is no push notification
• Wi-Fi range limitation means commands may silently fail
• The drone will auto-land at low battery regardless of commands

Design Implications for ex_drone

1. One UDP socket per drone: Each drone connection needs its own :gen_udp socket bound to a local port.
2. Sequential command model: Commands must be sent one at a time, waiting for the response before sending the next. This maps naturally to a GenServer's sequential message processing.
3. Timeout handling: Every command needs a configurable timeout. Movement commands need longer timeouts than queries.
4. No retry policy for movement: Per the prompt, movement commands must not be automatically retried. Only query commands may be retried.
5. State tracking required: Since the drone only responds with ok/error/numeric, the Elixir side must track position state for safety validation.
6. Emergency bypass: The emergency command must bypass all safety checks and be sent regardless of current state.
7. Command encoding is trivial: Commands are simple ASCII strings. The main complexity is in timing, safety, and state management, not in protocol encoding.

See also

• Guide: Tello
• Further reading: Tello and classroom hardware