Initial implementation

Author: blacktm

LICENSE.md

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2018 Tom Black ([blacktm.com](http://www.blacktm.com))
+Copyright © 2018 Tom Black ([blacktm.com](http://www.blacktm.com))
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 

README.md

@@ -1,3 +1,232 @@
-# Tello Ruby gem
+# Fly Tello with Ruby!
 
-🚧 In development 🚧
+This gem will let you fly the [Tello drone](https://www.ryzerobotics.com/tello) using Ruby.
+
+## Your first flight
+
+If you don't already have one, get a Tello drone! A [number of retailers](https://www.ryzerobotics.com/where-to-buy) carry them for $99 USD. (You _can_ also use the [test server](#test-server) packaged with this gem to simulate commands, but that's not nearly as fun.)
+
+Install the Ruby gem:
+
+```
+$ gem install tello
+```
+
+The gem comes with a command-line utility, also named `tello`. We can use it to launch an interactive console (IRB, or [Pry](http://pryrepl.org) if installed) and send commands to the drone. Go ahead and start the console:
+
+```
+$ tello console
+```
+
+Now, set the drone on the ground clear of any objects (including yourself) and press the button to turn it on. Wait for it to boot up, until the status light is blinking yellow.
+
+**Linux and Windows users:** Connect to the drone's Wi-Fi manually (the network name should start with `TELLO-`). For macOS users, this will happen automatically with the next command.
+
+In your interactive console, connect to the drone like so (the `>` here is just to note it's a Ruby prompt — don't type that):
+
+```ruby
+> connect
+```
+
+If you've successfully connected to the drone, you should see a "ready to fly" message. You're now ready to take flight!
+
+```ruby
+> takeoff
+```
+
+The drone should now be hovering. At this point, you can run all sorts of flight commands, described in the next section. Before we learn about all of them, let's have some fun. Stand clear of the drone and do a back flip:
+
+```ruby
+> flip :backward
+```
+
+Nice! For now, let's land the drone and learn about what else it can do.
+
+```ruby
+> land
+```
+
+## Flight commands
+
+This gem comes packed with commands you can send to the Tello drone. Let's go through each one.
+
+### `connect`
+
+The first command you'll run is `connect`. This will establish a network connection to the drone and prepare it for further commands. If already connected, `connect` will try to re-establish a connection (helpful for troubleshooting). If you need to, you can also use the `disconnect` command to break the connection.
+
+### `takeoff`
+
+Use this command to take flight! The drone will soon hover in place.
+
+### `land`
+
+Slowly descend to the ground and stop all rotors.
+
+### `stop`
+
+Immediately stop all rotors. This is like the "kill switch" for the drone, useful in emergencies. Be careful: the drone will fall from the sky and could get damaged.
+
+### `up`, `down`, `left`, `right`, `forward`, `backward`
+
+These are essential movement commands. Each one takes the distance the drone should move as a parameter, from 20 to 500 cm, for example:
+
+```ruby
+up 50  # ascend 50 cm
+down 100  # descend 1 meter
+left 250  # fly to the left 250 cm
+right 75  # fly to the right 75 cm
+forward 500  # fly forwards 5 m
+backward 200  # fly backwards 2 m
+```
+
+### `cw`, `ccw`
+
+These commands rotate the drone clockwise or counterclockwise, from 1 to 3600 degrees, for example:
+
+```ruby
+cw 90  # turn toward the right
+cw 360  # turn toward the right in a full circle
+ccw 180  # turn toward the left, facing in the opposite direction
+ccw 3600  # spin around 10 times
+```
+
+### `flip`
+
+Make the drone do a flip in a given direction, for example:
+
+```ruby
+flip :left
+flip :right
+flip :forward
+flip :backward
+
+# Or use this shorthand for the direction
+flip :l
+flip :r
+flip :f
+flip :b
+```
+
+### `speed`
+
+Get or set the speed of the drone, in cm/s (centimeters per second). Without parameters, it will simply return the speed. To set the speed used during movement commands, provide a value from 10 to 100 as a parameter, for example:
+
+```ruby
+speed  # get the current speed in cm/s
+speed 75  # set the drone speed to 75 cm/s
+
+speed 100  # set speed to 1 m/s
+forward 300  # fly forwards 3 meters in 3 seconds
+```
+
+### `go`
+
+The drone can also be given a precise location to move, based on a 3D coordinate system. The `go` command tells the drone to move to an _x, y, z_ position at a given speed. The coordinate values must be between 20 and 500 cm, while the speed must be between 10 and 100 cm/s, for example:
+
+```ruby
+# Parameters: x, y, z, speed
+go 100, 200, 50, 10
+```
+
+### `curve`
+
+Fly in a curve, where the coordinates are between 20 and 500 cm, and speed is between 10 and 100 cm/s, for example:
+
+```ruby
+# Parameters: x1, y1, z1, x2, y2, z2, speed
+curve 50, 100, 100, 25, 50, 75, 25
+```
+
+### `rc`
+
+Send remote controller values via four channels, each between -100 and 100, for example:
+
+```ruby
+# Parameters: left/right, forward/backward, up/down, yaw
+rc 0, 50, -25, 100
+```
+
+### `height`
+
+Get the height of the drone in cm.
+
+### `attitude`
+
+Get the [inertial measurement unit (IMU)](https://en.wikipedia.org/wiki/Inertial_measurement_unit) attitude data. Example response: `"pitch:-8;roll:3;yaw:2;"`
+
+### `acceleration`
+
+Get the IMU angular acceleration data. Example response: `"agx:-138.00;agy:-51.00;agz:-989.00;"`
+
+### `baro`
+
+Get the barometer value.
+
+### `tof`
+
+Get the distance from the [time-of-flight (TOF) camera](https://en.wikipedia.org/wiki/Time-of-flight_camera).
+
+### `time`
+
+Get the flight time.
+
+### `battery`
+
+Get the battery level.
+
+### `temp`
+
+Get the temperature range of the drone in celsius.
+
+### `wifi`
+
+Get the Wi-Fi signal-to-noise ratio (SNR). Provide parameters to set the SSID and password, for example:
+
+```ruby
+# Get the SNR
+wifi
+
+# Set the SSID with password
+wifi ssid: 'my-drone', pass: '12345'
+```
+
+### `state`
+
+Get the state of the entire drone represented as a hash. Select a specific value by using one of the following keys: `:pitch`, `:roll`, `:yaw`, `:vgx`, `:vgy`, `:vgz`, `:templ`, `:temph`, `:tof`, `:h`, `:bat`, `:baro`, `:time`, `:agx`, `:agy`, `:agz`
+
+### `send`
+
+Finally, you can send raw command strings to the Tello drone (this is what we use internally for all the commands above). Refer to the [Tello SDK documentation](https://www.ryzerobotics.com/tello/downloads) for a listing of available commands. For example:
+
+```ruby
+send 'command'
+send 'height?'
+send 'up 50'
+```
+
+## Test server
+
+You can simulate a connection to a Tello by running a test server at the command line, like so:
+
+```
+$ tello server
+```
+
+Then, open a new terminal window and run:
+
+```
+$ tello console --test
+```
+
+Now, run Tello commands just like you would when connected to a real drone.
+
+## Gem development
+
+Run `rake` to build this gem and install locally.
+
+To release a new version:
+
+1. Update the version number in [`version.rb`](lib/tello/version.rb), commit changes
+2. Create a [new release](https://github.com/blacktm/tello/releases) in GitHub, with tag in the form `v#.#.#`
+3. Run `rake` to build the gem, then push it to [rubygems.org](https://rubygems.org) with `gem push tello-#.#.#.gem`
+4. 🎉

Rakefile

@@ -0,0 +1,42 @@
+require_relative 'lib/tello/colorize'
+require_relative 'lib/tello/version'
+
+# Helpers
+
+def print_task(task)
+  print "\n", "==> ".blue, task.bold, "\n\n"
+end
+
+def run_cmd(cmd)
+  puts "==> #{cmd}\n"
+  system cmd
+end
+
+# Tasks
+
+task default: 'all'
+
+desc "Uninstall gem"
+task :uninstall do
+  print_task "Uninstalling"
+  run_cmd "gem uninstall tello --executables"
+end
+
+desc "Build gem"
+task :build do
+  print_task "Building"
+  run_cmd "gem build tello.gemspec --verbose"
+end
+
+desc "Install gem"
+task :install do
+  print_task "Installing"
+  run_cmd "gem install tello-#{Tello::VERSION}.gem --local --verbose"
+end
+
+desc "Uninstall, build, install, and test"
+task :all do
+  Rake::Task['uninstall'].invoke
+  Rake::Task['build'].invoke
+  Rake::Task['install'].invoke
+end

bin/tello

@@ -0,0 +1,28 @@
+#!/usr/bin/env ruby
+require 'tello/colorize'
+require 'tello/version'
+
+# Check Command-line Arguments #################################################
+
+usage = "Fly the Tello drone with Ruby!".bold + "\n
+Usage: tello <command> <options>
+             [-v|--version]
+
+Summary of commands and options:
+  console       Open an interactive Tello console
+    --test        Start the console in test mode
+  server        Start the test server
+  -v|--version  Prints the installed version\n\n"
+
+if ARGV.delete '--test' then $tello_testing = true end
+
+case ARGV[0]
+when 'console'
+  require 'tello/cli/console'
+when 'server'
+  require 'tello/cli/server'
+when '-v', '--version'
+  puts Tello::VERSION
+else
+  puts usage
+end

lib/tello.rb

@@ -0,0 +1,29 @@
+# Tello module and requires
+
+module Tello
+  # Flag for testing
+  attr_accessor :testing, :os, :ip, :port
+
+  def self.testing; @testing end
+  def self.testing=(t); @testing=(t) end
+  def self.os; @os end
+
+  # Set the operating system
+  case RUBY_PLATFORM
+  when /darwin/
+    @os = :macos
+  when /linux/
+    @os = :linux
+  when /mingw/
+    @os = :windows
+  end
+end
+
+require 'tello/colorize'
+require 'tello/state'
+require 'tello/wifi'
+require 'tello/client'
+require 'tello/dsl'
+
+# Add DSL
+extend Tello::DSL

lib/tello/cli/console.rb

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+
+if $tello_testing
+  puts "⚠️  Test mode enabled"
+  r_module = 'tello/cli/testing'
+else
+  r_module = 'tello'
+end
+
+puts "Ready to receive Tello commands. Type \"exit\" to quit."
+
+if system('pry -v &>/dev/null')
+  system("pry -r #{r_module}")
+else
+  system("irb -r #{r_module}")
+end