Documentation ¶
Overview ¶
Package tello provides an unofficial, easy-to-use, standalone API for the Ryze Tello® drone.
Disclaimer ¶
Tello is a registered trademark of Ryze Tech. The author(s) of this package is/are in no way affiliated with Ryze, DJI, or Intel. The package has been developed by gathering together information from a variety of sources on the Internet (especially the generous contributors at https://tellopilots.com), and by examining data packets sent to/from the Tello. The package will probably be extended as more knowledge of the drone's protocol is obtained.
Use this package at your own risk. The author(s) is/are in no way responsible for any damage caused either to or by the drone when using this software.
Features ¶
The following features have been implemented...
- Stick-based flight control, ie. for joystick, game-, or flight-controller
- Drone built-in flight commands, eg. Takeoff(), PalmLand()
- Macro-level flight control, eg. Forward(), Up()
- Autopilot commands, eg. AutoFlyToHeight(), AutoTurnToYaw()
- Enriched flight data (some log data is added) for real-time telemetry
- Video stream support
- Picture taking/saving
- Multiple drone support - Untested
An example application using this package is available at http://github.com/SMerrony/telloterm
This documentation should be consulted alongside https://github.com/SMerrony/tello/blob/master/ImplementationChart.md
Concepts ¶
Connection Types ¶
The drone provides two types of connection: a 'control' connection which handles all commands to and from the drone including flight, status and (still) pictures, and a 'video' connection which provides an H.264 video stream from the forward-facing camera. You must establish a control connection to use the drone, but the video connection is optional and cannot be started unless a control connection is running.
Funcs vs. Channels
Certain functionality is made available in two forms: single-shot function calls and streaming (channel) data flows. Eg. GetFlightData() vs. StreamFlightData(), and UpdateSticks() vs. StartStickListener().
Use whichever paradigm you prefer, but be aware that the channel-based calls should return immediately (the channels are buffered) whereas the function-based options could conceivably cause your application to pause very briefly if the Tello is very busy. (In practice, the author has not found this to be an issue.)
Index ¶
- Constants
- func QuatToEulerDeg(qX, qY, qZ, qW float32) (pitch, roll, yaw int)
- type FlightData
- type FlipType
- type IMUData
- type MVOData
- type StickMessage
- type SvCmd
- type Tello
- func (tello *Tello) Anticlockwise(pct int)
- func (tello *Tello) AutoFlyToHeight(dm int16) (done chan bool, err error)
- func (tello *Tello) AutoFlyToXY(targetX, targetY float32) (done chan bool, err error)
- func (tello *Tello) AutoTurnByDeg(delta int16) (done chan bool, err error)
- func (tello *Tello) AutoTurnToYaw(targetYaw int16) (done chan bool, err error)
- func (tello *Tello) BackFlip()
- func (tello *Tello) BackLeftFlip()
- func (tello *Tello) BackRightFlip()
- func (tello *Tello) Backward(pct int)
- func (tello *Tello) Bounce()
- func (tello *Tello) CancelAutoFlyToHeight()
- func (tello *Tello) CancelAutoFlyToXY()
- func (tello *Tello) CancelAutoTurn()
- func (tello *Tello) Clockwise(pct int)
- func (tello *Tello) ControlConnect(udpAddr string, droneUDPPort int, localUDPPort int) (err error)
- func (tello *Tello) ControlConnectDefault() (err error)
- func (tello *Tello) ControlConnected() (c bool)
- func (tello *Tello) ControlDisconnect()
- func (tello *Tello) CounterClockwise(pct int)
- func (tello *Tello) Down(pct int)
- func (tello *Tello) Flip(dir FlipType)
- func (tello *Tello) Forward(pct int)
- func (tello *Tello) ForwardFlip()
- func (tello *Tello) ForwardLeftFlip()
- func (tello *Tello) ForwardRightFlip()
- func (tello *Tello) GetFlightData() FlightData
- func (tello *Tello) GetLowBatteryThreshold()
- func (tello *Tello) GetMaxHeight()
- func (tello *Tello) GetSSID()
- func (tello *Tello) GetVersion()
- func (tello *Tello) GetVideoBitrate()
- func (tello *Tello) GetVideoSpsPps()
- func (tello *Tello) Hover()
- func (tello *Tello) IsAutoTurning() (set bool)
- func (tello *Tello) IsAutoXY() (set bool)
- func (tello *Tello) IsHomeSet() (set bool)
- func (tello *Tello) Land()
- func (tello *Tello) Left(pct int)
- func (tello *Tello) LeftFlip()
- func (tello *Tello) NumPics() (np int)
- func (tello *Tello) PalmLand()
- func (tello *Tello) Right(pct int)
- func (tello *Tello) RightFlip()
- func (tello *Tello) SaveAllPics(prefix string) (np int, err error)
- func (tello *Tello) SendOfficialCommand(commandString string)
- func (tello *Tello) SetFastMode()
- func (tello *Tello) SetHome() (err error)
- func (tello *Tello) SetLowBatteryThreshold(thr uint8)
- func (tello *Tello) SetSlowMode()
- func (tello *Tello) SetSportsMode(sports bool)
- func (tello *Tello) SetVideoBitrate(vbr VBR)
- func (tello *Tello) SetVideoNormal()
- func (tello *Tello) SetVideoWide()
- func (tello *Tello) StartSmartVideo(cmd SvCmd)
- func (tello *Tello) StartStickListener() (sChan chan<- StickMessage, err error)
- func (tello *Tello) StopLanding()
- func (tello *Tello) StopSmartVideo(cmd SvCmd)
- func (tello *Tello) StopStickListener()
- func (tello *Tello) StreamFlightData(asAvailable bool, periodMs time.Duration) (<-chan FlightData, error)
- func (tello *Tello) TakeOff()
- func (tello *Tello) TakePicture() (err error)
- func (tello *Tello) ThrowTakeOff()
- func (tello *Tello) TurnLeft(pct int)
- func (tello *Tello) TurnRight(pct int)
- func (tello *Tello) Up(pct int)
- func (tello *Tello) UpdateSticks(sm StickMessage)
- func (tello *Tello) VideoConnect(udpAddr string, droneUDPPort int) (<-chan []byte, error)
- func (tello *Tello) VideoConnectDefault() (<-chan []byte, error)
- func (tello *Tello) VideoDisconnect()
- type VBR
Constants ¶
const ( // autoPilotSpeedVSlow = 8192 // AutoHeightLimitDm is the maximum vertical displacement allowed for AutoFlyToHeight() etc. in decimetres. AutoHeightLimitDm = 300 // AutoXYLimitM is the maximum horizontal displacement allowed for AutoFlyToXY() etc. in metres. AutoXYLimitM = 200 // 200m // AutoXYToleranceM is the maximum accuracy we try to attain in XY navigation in metres AutoXYToleranceM = 0.3 // AutoXYNearTargetM is how close to the target we slow down for finer navigation AutoXYNearTargetM = 3.0 )
const ( Sv360 SvCmd = 1 << 2 // Slowly rotate around 360 degrees. SvCircle = 2 << 2 // Circle around a point in front of the drone. SvUpOut = 3 << 2 // Perform the 'Up and Out' manouvre. )
Smart Video flight commands...
const TelloPackageVersion = "v0.9.5" // TODO Update with each release
TelloPackageVersion holds the semver of this package release.
Variables ¶
This section is empty.
Functions ¶
func QuatToEulerDeg ¶ added in v0.5.0
QuatToEulerDeg converts a quaternion set into pitch, roll & yaw expressed in degrees
Types ¶
type FlightData ¶
type FlightData struct { BatteryCritical bool BatteryLow bool BatteryMilliVolts int16 BatteryPercentage int8 BatteryState bool CameraState uint8 DownVisualState bool DroneFlyTimeLeft int16 DroneHover bool EastSpeed int16 ElectricalMachineryState uint8 EmOpen bool ErrorState bool FactoryMode bool Flying bool FlyMode uint8 FlyTime int16 FrontIn bool FrontLSC bool FrontOut bool GravityState bool GroundSpeed int16 Height int16 // seems to be in decimetres IMU IMUData ImuCalibrationState int8 ImuState bool LightStrength uint8 LightStrengthUpdated time.Time LowBatteryThreshold uint8 MaxHeight uint8 MVO MVOData NorthSpeed int16 OnGround bool OutageRecording bool PowerState bool PressureState bool SmartVideoExitMode int16 SSID string ThrowFlyTimer int8 Version string VerticalSpeed int16 VideoBitrate VBR WifiInterference uint8 WifiStrength uint8 WindState bool }
FlightData holds our current knowledge of the drone's state. This data is not all sent at once from the drone, different fields may be updated at varying rates.
type IMUData ¶ added in v0.4.0
type IMUData struct { QuaternionW, QuaternionX, QuaternionY, QuaternionZ float32 Temperature int16 Yaw int16 // derived from Quat fields, -180 > degrees > +180 }
IMUData comes from the flight log messages
type MVOData ¶ added in v0.4.0
type MVOData struct {
PositionX, PositionY, PositionZ float32
VelocityX, VelocityY, VelocityZ int16
}
MVOData comes from the flight log messages
type StickMessage ¶
type StickMessage struct {
Rx, Ry, Lx, Ly int16
}
StickMessage holds the signed 16-bit values of a joystick update. Each value can range from -32768 to 32767
type Tello ¶
type Tello struct {
// contains filtered or unexported fields
}
Tello holds the current state of a connection to a Tello drone.
func (*Tello) Anticlockwise ¶
Anticlockwise tells the drone to start rotating Anticlockwise at a given speed between 0 and 100.
func (*Tello) AutoFlyToHeight ¶ added in v0.7.0
AutoFlyToHeight starts vertical movement to the specified height in decimetres (so a value of 10 means 1m). The func returns immediately and a Goroutine handles the navigation until either it is complete or cancelled via CancelAutoFlyToHeight(). The caller may optionally listen on the 'done' channel for a signal that the navigation is complete (or has been cancelled).
func (*Tello) AutoFlyToXY ¶ added in v0.8.0
AutoFlyToXY starts horizontal movement to the specified (X, Y) location expressed in metres from the home point (which must have been previously set). The func returns immediately and a Goroutine handles the navigation until either it is complete or cancelled via CancelFlyToXY(). The caller may optionally listen on the 'done' channel for a signal that the navigation is complete (or has been cancelled).
func (*Tello) AutoTurnByDeg ¶ added in v0.7.0
AutoTurnByDeg starts rotational movement by the specified amount degrees. The amount should be between -180 and +180 degrees, where negative values cause an anticlockwise rotation and vice-versa. The func returns immediately and a Goroutine handles the navigation. The caller may optionally listen on the 'done' channel for a signal that the navigation is complete (may have been cancelled). You may explicitly cancel this operation via CancelAutoTurn().
func (*Tello) AutoTurnToYaw ¶ added in v0.7.0
AutoTurnToYaw starts rotational movement to the specified yaw in degrees. The yaw should be between -180 and +180 degrees. The func returns immediately and a Goroutine handles the navigation. The caller may optionally listen on the 'done' channel for a signal that the navigation is complete (may have been cancelled). You may explicitly cancel this operation via CancelAutoTurn().
func (*Tello) BackLeftFlip ¶
func (tello *Tello) BackLeftFlip()
BackLeftFlip - flip backwards and to the left.
func (*Tello) BackRightFlip ¶
func (tello *Tello) BackRightFlip()
BackRightFlip - flip backwards and to the right.
func (*Tello) Backward ¶
Backward tells the drone to start moving Backward at a given speed between 0 and 100.
func (*Tello) CancelAutoFlyToHeight ¶ added in v0.7.0
func (tello *Tello) CancelAutoFlyToHeight()
CancelAutoFlyToHeight stops any in-flight AutoFlyToHeight navigation. The drone should stop moving vertically.
func (*Tello) CancelAutoFlyToXY ¶ added in v0.8.0
func (tello *Tello) CancelAutoFlyToXY()
CancelAutoFlyToXY stops any in-flight AutoFlyToXY navigation. The drone should stop.
func (*Tello) CancelAutoTurn ¶ added in v0.7.0
func (tello *Tello) CancelAutoTurn()
CancelAutoTurn stops any in-flight AutoTurnToYaw or AutoTurnByDeg navigation. The drone should stop rotating.
func (*Tello) Clockwise ¶
Clockwise tells the drone to start rotating Clockwise at a given speed between 0 and 100.
func (*Tello) ControlConnect ¶
ControlConnect attempts to connect to a Tello at the provided network addr. It then starts listening for responses on the control channel and processes them in a Goroutine.
func (*Tello) ControlConnectDefault ¶
ControlConnectDefault attempts to connect to a Tello on the default network addresses. It then starts listening for responses on the control channel and processes them in a Goroutine.
func (*Tello) ControlConnected ¶
ControlConnected returns true if we are currently connected.
func (*Tello) ControlDisconnect ¶
func (tello *Tello) ControlDisconnect()
ControlDisconnect stops the control channel listener and closes the connection to a Tello.
func (*Tello) CounterClockwise ¶
CounterClockwise is an alias for Anticlockwise().
func (*Tello) Forward ¶
Forward tells the drone to start moving forward at a given speed between 0 and 100.
func (*Tello) ForwardLeftFlip ¶
func (tello *Tello) ForwardLeftFlip()
ForwardLeftFlip - flip forward and to the left.
func (*Tello) ForwardRightFlip ¶
func (tello *Tello) ForwardRightFlip()
ForwardRightFlip - flip forwardsand to the right.
func (*Tello) GetFlightData ¶
func (tello *Tello) GetFlightData() FlightData
GetFlightData returns the current known state of the Tello.
func (*Tello) GetLowBatteryThreshold ¶ added in v0.2.0
func (tello *Tello) GetLowBatteryThreshold()
GetLowBatteryThreshold requests the threshold from the Tello which is stored in FlightData.LowBatteryThreshold as an integer percentage, i.e. from 0 to 100.
func (*Tello) GetMaxHeight ¶ added in v0.2.0
func (tello *Tello) GetMaxHeight()
GetMaxHeight asks the Tello to send us its current maximum permitted height.
func (*Tello) GetSSID ¶ added in v0.2.0
func (tello *Tello) GetSSID()
GetSSID asks the Tello to send us its current Wifi AP ID.
func (*Tello) GetVersion ¶ added in v0.2.0
func (tello *Tello) GetVersion()
GetVersion asks the Tello to send us its Version string
func (*Tello) GetVideoBitrate ¶ added in v0.2.0
func (tello *Tello) GetVideoBitrate()
GetVideoBitrate requests the current video Mbps from the Tello.
func (*Tello) GetVideoSpsPps ¶ added in v0.9.0
func (tello *Tello) GetVideoSpsPps()
GetVideoSpsPps asks the Tello to send SPS and PPS in video stream. Calling this more often decreases video bandwidth, calling less often results in video artifacts. Every 0.5 to 2.0 seconds seems a reasonable range.
func (*Tello) Hover ¶
func (tello *Tello) Hover()
Hover simply sets the sticks to zero which should halt all motion - useful as a panic action!
func (*Tello) IsAutoTurning ¶ added in v0.9.3
IsAutoTurning tests whether we are currently auto-navigating rotationally
func (*Tello) IsAutoXY ¶ added in v0.9.3
IsAutoXY tests whether we are currently navigating horizontally
func (*Tello) IsHomeSet ¶ added in v0.8.0
IsHomeSet tests whether the home point used for the travelling AutoFly... funcs is set.
func (*Tello) Right ¶
Right tells the drone to start moving Right at a given speed between 0 and 100.
func (*Tello) SaveAllPics ¶
SaveAllPics writes all JPEG pictures to disk using the given prefix and a generated index number. It returns the number of pictures written &/or an error. If there is no error, the pictures are removed from memory.
func (*Tello) SendOfficialCommand ¶ added in v0.9.7
func (*Tello) SetFastMode ¶
func (tello *Tello) SetFastMode()
SetFastMode sets the 'fast' or 'sports' mode of flight.
func (*Tello) SetHome ¶ added in v0.8.0
SetHome establishes the current MVO position and IMU yaw as the home point for autopilot operations. It could be called after takeoff to establish a home coordinate, or during (non-autopilot) flight to set a waypoint.
func (*Tello) SetLowBatteryThreshold ¶ added in v0.2.0
SetLowBatteryThreshold set the warning threshold to a percentage value (0-100). N.B. It can take a few seconds for the Tello to change this value internally.
func (*Tello) SetSlowMode ¶
func (tello *Tello) SetSlowMode()
SetSlowMode sets the 'slow' or 'normal' mode of flight.
func (*Tello) SetSportsMode ¶
SetSportsMode sets the sports mode of flight to the given value.
func (*Tello) SetVideoBitrate ¶
SetVideoBitrate ask the Tello to use the specified bitrate (or auto) for video encoding.
func (*Tello) SetVideoNormal ¶ added in v0.2.0
func (tello *Tello) SetVideoNormal()
SetVideoNormal requests video format to be (native) ~4:3 ratio.
func (*Tello) SetVideoWide ¶ added in v0.2.0
func (tello *Tello) SetVideoWide()
SetVideoWide requests video format to be (cropped) 16:9 ratio.
func (*Tello) StartSmartVideo ¶ added in v0.5.0
StartSmartVideo begins a preprogrammed 'smart video' flight action.
func (*Tello) StartStickListener ¶
func (tello *Tello) StartStickListener() (sChan chan<- StickMessage, err error)
StartStickListener starts a Goroutine which listens for StickMessages on a channel and applies them to the Tello. All four axes are updated on each message recieved.
func (*Tello) StopSmartVideo ¶ added in v0.5.0
StopSmartVideo begins a preprogrammed 'smart video' flight action.
func (*Tello) StopStickListener ¶ added in v0.9.0
func (tello *Tello) StopStickListener()
StopStickListener stops a Goroutine started by StartStickListener().
func (*Tello) StreamFlightData ¶
func (tello *Tello) StreamFlightData(asAvailable bool, periodMs time.Duration) (<-chan FlightData, error)
StreamFlightData starts a Goroutine which sends FlightData to a channel.
If asAvailable is true then updates are sent whenever fresh data arrives from the Tello and periodMs is ignored. TODO. If asAvailable is false then updates are sent every periodMs N.B. This streamer does not block on the channel, so unconsumed updates are lost.
func (*Tello) TakeOff ¶
func (tello *Tello) TakeOff()
TakeOff sends a normal takeoff request to the Tello. Any previously set origin is invalidated.
func (*Tello) TakePicture ¶
TakePicture requests the Tello to take a JPEG snapshot. The process takes a little while to complete and the video may freeze during photography. Sometime the Tello does not honour the request. The pictures are stored in the tello struct until saved by eg. SaveAllPics().
func (*Tello) ThrowTakeOff ¶
func (tello *Tello) ThrowTakeOff()
ThrowTakeOff initiates a 'throw and go' launch. Any previously set origin is invalidated.
func (*Tello) UpdateSticks ¶
func (tello *Tello) UpdateSticks(sm StickMessage)
UpdateSticks does a one-off update of the stick values which are then sent to the Tello. N.B. All four axes are updated on every call to this func.
func (*Tello) VideoConnect ¶
VideoConnect attempts to connect to a Tello video channel at the provided addr and starts a listener. A channel of raw H.264 video frames is returned along with any error. The channel will be closed if the connection is lost.
func (*Tello) VideoConnectDefault ¶
VideoConnectDefault attempts to connect to a Tello video channel using default addresses, then starts a listener. A channel of raw H.264 video frames is returned along with any error.
func (*Tello) VideoDisconnect ¶
func (tello *Tello) VideoDisconnect()
VideoDisconnect closes the connection to the video channel.