tello

package module
v0.9.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 23, 2019 License: MIT Imports: 13 Imported by: 9

README

tello Go Package

This tello package provides an unofficial, easy-to-use, standalone API for the Ryze Tello® drone.

Disclaimer

Tello is a registered trademark of Ryze Tech. The author of this package is 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 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 flight control, eg. AutoFlyToHeight(), AutoFlyToXY()
  • Video stream support
  • Enriched flight-data (some log data is added)
  • Picture taking/saving support
  • Multiple drone support - Untested

See ImplementationChart.md for full details of what functions are currently implemented.

Documentation should be available locally via godoc, or via godoc.org.

An example application using this package is available at telloterm.

Here is an example of just about the simplest use of the package...

package main
import (
  "log"
  "time"
  "github.com/SMerrony/tello"
)

func main() {
  	drone := new(tello.Tello)
  err := drone.ControlConnectDefault()
  if err != nil {
    log.Fatalf("%v", err) 
  }

  drone.TakeOff()
  time.Sleep(10 * time.Second)
  drone.Land()
  drone.ControlDisconnect()
}

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.

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

View Source 
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
)
View Source 
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...

View Source 
const TelloPackageVersion = "v0.9.3" // 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 

func QuatToEulerDeg(qX, qY, qZ, qW float32) (pitch, roll, yaw int)

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 FlipType 

type FlipType int

FlipType represents a flip direction. 

const (
	FlipForward FlipType = iota
	FlipLeft
	FlipBackward
	FlipRight
	FlipForwardLeft
	FlipBackwardLeft
	FlipBackwardRight
	FlipForwardRight
)

Flip types...

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 SvCmd 

type SvCmd byte

SvCmd is Smart Video flight command.

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 

func (tello *Tello) Anticlockwise(pct int)

Anticlockwise tells the drone to start rotating Anticlockwise at a given speed between 0 and 100.

func (*Tello) AutoFlyToHeight added in v0.7.0 

func (tello *Tello) AutoFlyToHeight(dm int16) (done chan bool, err error)

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 

func (tello *Tello) AutoFlyToXY(targetX, targetY float32) (done chan bool, err error)

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 

func (tello *Tello) AutoTurnByDeg(delta int16) (done chan bool, err error)

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 

func (tello *Tello) AutoTurnToYaw(targetYaw int16) (done chan bool, err error)

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) BackFlip 

func (tello *Tello) BackFlip()

BackFlip - flip backwards.

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 

func (tello *Tello) Backward(pct int)

Backward tells the drone to start moving Backward at a given speed between 0 and 100.

func (*Tello) Bounce 

func (tello *Tello) Bounce()

Bounce toggles the bouncing mode of the Tello.

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 

func (tello *Tello) Clockwise(pct int)

Clockwise tells the drone to start rotating Clockwise at a given speed between 0 and 100.

func (*Tello) ControlConnect 

func (tello *Tello) ControlConnect(udpAddr string, droneUDPPort int, localUDPPort int) (err error)

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 

func (tello *Tello) ControlConnectDefault() (err error)

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 

func (tello *Tello) ControlConnected() (c bool)

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 

func (tello *Tello) CounterClockwise(pct int)

CounterClockwise is an alias for Anticlockwise().

func (*Tello) Down 

func (tello *Tello) Down(pct int)

Down tells the drone to start moving Down at a given speed between 0 and 100.

func (*Tello) Flip 

func (tello *Tello) Flip(dir FlipType)

Flip sends a flip flight command to the Tello.

func (*Tello) Forward 

func (tello *Tello) Forward(pct int)

Forward tells the drone to start moving forward at a given speed between 0 and 100.

func (*Tello) ForwardFlip 

func (tello *Tello) ForwardFlip()

ForwardFlip - flip forwards.

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 

func (tello *Tello) IsAutoTurning() (set bool)

IsAutoTurning tests whether we are currently auto-navigating rotationally

func (*Tello) IsAutoXY added in v0.9.3 

func (tello *Tello) IsAutoXY() (set bool)

IsAutoXY tests whether we are currently navigating horizontally

func (*Tello) IsHomeSet added in v0.8.0 

func (tello *Tello) IsHomeSet() (set bool)

IsHomeSet tests whether the home point used for the travelling AutoFly... funcs is set.

func (*Tello) Land 

func (tello *Tello) Land()

Land sends a normal Land request to the Tello.

func (*Tello) Left 

func (tello *Tello) Left(pct int)

Left tells the drone to start moving Left at a given speed between 0 and 100.

func (*Tello) LeftFlip 

func (tello *Tello) LeftFlip()

LeftFlip - flip to the left.

func (*Tello) NumPics 

func (tello *Tello) NumPics() (np int)

NumPics returns the number of JPEG pictures we are storing in memory

func (*Tello) PalmLand 

func (tello *Tello) PalmLand()

PalmLand initiates a Palm Landing.

func (*Tello) Right 

func (tello *Tello) Right(pct int)

Right tells the drone to start moving Right at a given speed between 0 and 100.

func (*Tello) RightFlip 

func (tello *Tello) RightFlip()

RightFlip - flip to the right.

func (*Tello) SaveAllPics 

func (tello *Tello) SaveAllPics(prefix string) (np int, err error)

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) SetFastMode 

func (tello *Tello) SetFastMode()

SetFastMode sets the 'fast' or 'sports' mode of flight.

func (*Tello) SetHome added in v0.8.0 

func (tello *Tello) SetHome() (err error)

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 

func (tello *Tello) SetLowBatteryThreshold(thr uint8)

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 

func (tello *Tello) SetSportsMode(sports bool)

SetSportsMode sets the sports mode of flight to the given value.

func (*Tello) SetVideoBitrate 

func (tello *Tello) SetVideoBitrate(vbr VBR)

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 

func (tello *Tello) StartSmartVideo(cmd SvCmd)

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) StopLanding 

func (tello *Tello) StopLanding()

StopLanding cancels a land command.

func (*Tello) StopSmartVideo added in v0.5.0 

func (tello *Tello) StopSmartVideo(cmd SvCmd)

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 

func (tello *Tello) TakePicture() (err error)

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) TurnLeft 

func (tello *Tello) TurnLeft(pct int)

TurnLeft is an alias for Anticlockwise().

func (*Tello) TurnRight 

func (tello *Tello) TurnRight(pct int)

TurnRight is an alias for Clockwise().

func (*Tello) Up 

func (tello *Tello) Up(pct int)

Up tells the drone to start moving Up at a given speed between 0 and 100.

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 

func (tello *Tello) VideoConnect(udpAddr string, droneUDPPort int) (<-chan []byte, error)

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 

func (tello *Tello) VideoConnectDefault() (<-chan []byte, error)

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.

type VBR 

type VBR byte

VBR is a Video Bit Rate, the int value is meaningless. 

const (
	VbrAuto VBR = iota // let the Tello choose the best for the current connection
	Vbr1M              // Set the VBR to 1Mbps
	Vbr1M5             // Set the VBR to 1.5Mbps
	Vbr2M              // Set the VBR to 2Mbps
	Vbr3M              // Set the VBR to 3Mbps
	Vbr4M              // Set the VBR to 4mbps
)

VBR settings...

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.